开发文档

为开发者提供 API 接入与错误处理说明

快速开始

欢迎使用图床云开放平台。通过我们的 API 和开发工具，您可以轻松地将图片托管能力集成到您的应用、博客或工作流中。

获取 API 密钥

前往个人中心 -> 开发者设置申请您的 API Key。请妥善保管，不要在前端代码中直接暴露。

API 接口参考

POST 图片上传接口

https://api.tuchuang.cloud/v1/upload

支持上传本地文件、粘贴图片或通过 URL 远程拉取。

参数名	类型	必选	描述
file	File	是	图片二进制数据
tag	String	否	图片标签，最长 30 个字符

请求示例：cURL

curl -X POST 'https://api.tuchuang.cloud/v1/upload' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/image.png' \
  -F 'tag=demo-tag'

请求示例：fetch

const formData = new FormData();
formData.append('file', file);
formData.append('tag', 'demo-tag');

const response = await fetch('https://api.tuchuang.cloud/v1/upload', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: formData,
});

const result = await response.json();

响应示例

{
  code: 0,
  data: {
    url: 'https://cdn.tuchuang.cloud/image/xxxxxxxxxxxxxxx.png',
  },
  message: 'success',
}

错误代码表

接口统一返回 `code`、`data`、`message` 三个字段。除 `0` 表示上传成功外，其余负数错误码均表示请求校验、权限或上传限制异常。

错误码	常量	含义	触发场景
0	STATUS.SUCCESS	上传成功。	文件上传到 R2 或 R2_TEMP 成功，并返回图片 URL。
-3	STATUS.SERVER_ERROR	服务端异常。	接口内部抛出未预期错误，比如数据库、存储或运行时异常。
-8	STATUS.USER_BLOCKED	用户已被封禁。	通过 apiKey 找到的用户状态为 INACTIVE。
-11	STATUS.API_KEY_REQUIRED	缺少 API Key。	请求头里没有有效的 Authorization: Bearer <API_KEY>。
-12	STATUS.API_KEY_INVALID	API Key 无效。	数据库中查不到对应的用户。
-13	STATUS.FILE_REQUIRED	缺少上传文件。	formData 中没有 file，或者 file 不是文件对象。
-14	STATUS.TAG_TOO_LONG	标签过长。	tag 长度超过 30 个字符。
-15	STATUS.DEVELOPER_PERMISSION_REQUIRED	没有开发者权限。	用户所属权限组未开启 allowDeveloper。
-16	STATUS.UPLOAD_DISABLED	没有上传权限。	用户所属权限组未开启 allowUpload。
-17	STATUS.FILE_TOO_LARGE	文件大小超限。	上传文件大小超过权限配置里的 maxImageSize。
-18	STATUS.FILE_TYPE_NOT_ALLOWED	文件格式不支持。	文件 MIME 类型不在 allowedImageFormats 允许列表中。
-19	STATUS.UPLOAD_LIMIT_EXCEEDED	上传次数超限。	用户当天上传次数达到 dailyUploadLimit 上限。
-20	STATUS.STORAGE_INSUFFICIENT	存储空间不足。	当前已用空间加本次文件大小后，超过权限配置的 spaceSize。
-21	STATUS.INVALID_CONTENT_TYPE	请求体类型错误。	请求头 Content-Type 不是 multipart/form-data。