Media / API

Chevereto API V1.1 接入说明

整理上传接口的核心调用方式、鉴权头、参数规则与响应格式，去掉旧导出文档里的冗余样式和失真内容，方便在站内直接查阅。

默认端点 /api/1/upload

推荐方法 POST

鉴权方式 X-API-Key

接口概览

Chevereto API V1.1 支持访客上传和用户 API Key 上传，兼容常见的 ImgBB 风格客户端。正式接入时，请将域名替换为你当前站点的实际地址，并使用用户后台生成的 API Key。

示例 API Key

chv_example_user_api_key

请求地址

https://your-domain.example/api/1/upload

支持 GET 和 POST，但上传图片时建议始终使用 POST，这样更利于处理大文件、二进制内容和授权头。

授权头

X-API-Key: chv_example_user_api_key

最小调用示例

curl -X POST "https://your-domain.example/api/1/upload" \
  -H "X-API-Key: chv_example_user_api_key" \
  -F "[email protected]" \
  -F "format=json"

参数说明

参数	说明	必填
`source`	图片 URL、base64 字符串，或通过 `FILES[source]` 传入的文件。	是
`title`	图片标题。	否
`description`	图片描述。	否
`album_id`	归属于当前用户的相册 ID。	否
`category_id`	分类 ID，整数值。	否
`width`	目标缩放宽度，高度按比例自动计算。	否
`expiration`	过期时间，例如 `PT5M`、`P1D`、`P1W`、`P1Y`。	否
`nsfw`	是否标记为敏感内容，`0` 或 `1`。	否
`format`	返回格式，可选 `json`、`txt`、`redirect`。	否

过期时间速查

PT5M / 5 分钟
PT15M / 15 分钟
PT30M / 30 分钟
PT1H / 1 小时
PT6H / 6 小时
P1D / 1 天
P1W / 1 周
P1M / 1 个月
P1Y / 1 年

响应格式

json：返回完整图片对象与状态信息。
txt：返回图片直链，适合脚本快速取值。
redirect：直接跳转到查看页。

JSON 响应示例

{
  "status_code": 200,
  "status_txt": "OK",
  "success": {
    "message": "image uploaded",
    "code": 200
  },
  "image": {
    "id_encoded": "vZxn",
    "filename": "demo-image.jpeg",
    "mime": "image/jpeg",
    "width": 1920,
    "height": 1280,
    "size": 296362,
    "url": "https://your-domain.example/images/2024/03/20/demo-image.jpeg",
    "url_viewer": "https://your-domain.example/image/demo-image.vZxn",
    "delete_url": "https://your-domain.example/image/vZxn/delete/example-token"
  }
}

TXT 响应示例

https://your-domain.example/images/2024/03/20/demo-image.png

兼容性说明

如果你已有对 ImgBB API 的调用脚本，通常只需要替换域名、确认授权头和参数名即可接入 Chevereto V1.1。建议在上线前增加上传大小限制、文件类型校验和服务端鉴权日志，便于定位请求失败原因。