注册
登录

开发文档

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

快速开始

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

获取 API 密钥

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

API 接口参考

鉴权方式

所有开放 API 都需要在请求头中传递 `X-Api-Key` 和 `X-Api-Secret` 两个字段。

Header必选说明
X-Api-Key是个人中心创建的 API Key
X-Api-Secret是个人中心对应 API Key 的 API Secret

POST 图片上传接口

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

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

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

请求示例：cURL

curl -X POST 'https://api.tuchuang.cloud/v1/upload' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -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: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Api-Secret': 'YOUR_API_SECRET',
  },
  body: formData,
});

const result = await response.json();

响应示例

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

POST 图片列表接口

https://api.tuchuang.cloud/v1/image/list

支持分页查询、关键字筛选、标签筛选与排序。

请求示例：cURL

curl -X POST 'https://api.tuchuang.cloud/v1/image/list' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -d '{
    "keyword": "",
    "tag": null,
    "pageSize": 20,
    "current": 1,
    "sortBy": "createdAt",
    "order": "DESC"
  }'

请求示例：fetch

const response = await fetch('https://api.tuchuang.cloud/v1/image/list', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Api-Secret': 'YOUR_API_SECRET',
  },
  body: JSON.stringify({
    keyword: '',
    tag: null,
    pageSize: 20,
    current: 1,
    sortBy: 'createdAt',
    order: 'DESC',
  }),
});

const result = await response.json();

响应示例

{
  code: 0,
  data: {
    list: [
      {
        id: '123456789012345',
        name: 'demo.png',
        url: 'https://cdn.tuchuang.cloud/image/demo.png',
        size: 102400,
        type: 'image/png',
        viewCount: 12,
        tag: 'demo',
        createdAt: '2026-01-01T00:00:00.000Z',
        updatedAt: '2026-01-01T00:00:00.000Z'
      }
    ],
    total: 1,
    pageSize: 20,
    current: 1
  },
  message: 'success'
}

POST 图片删除接口

https://api.tuchuang.cloud/v1/image/delete

支持批量删除，`ids` 传入图片 ID 数组即可。

请求示例：cURL

curl -X POST 'https://api.tuchuang.cloud/v1/image/delete' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -d '{
    "ids": ["123456789012345", "123456789012346"]
  }'

请求示例：fetch

const response = await fetch('https://api.tuchuang.cloud/v1/image/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Api-Secret': 'YOUR_API_SECRET',
  },
  body: JSON.stringify({
    ids: ['123456789012345', '123456789012346'],
  }),
});

const result = await response.json();

响应示例

{
  code: 0,
  data: {
    deletedCount: 2
  },
  message: 'success'
}

错误代码表

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

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