开发者

API 接入

创建密钥，通过 HTTP 接口上传和查询图片。

创建密钥与鉴权#

在工作台「开发者」页面创建 API Key。完整密钥只显示一次，服务端仅保存哈希；请将密钥存放在服务端环境变量中，不要写入前端代码或公开仓库。

创建或撤销访问密钥

向 POST /api/media/assets 发送 multipart/form-data。file 为必填文件，folder 为可选文件夹名称。示例里的站点地址使用当前域名。

首次上传成功返回 201。可以传入 UUID 格式的 Idempotency-Key；相同标识、文件、名称及文件夹的重试返回 200，不会重复保存。

Shell

curl -X POST "https://your-domain.example/api/media/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "folder=博客配图"

参数	说明
page / pageSize	页码默认 1；每页默认 40，最多 100
q / folder	按名称搜索 / 按文件夹筛选
status	all / ready / pending / blocked 等资源状态
sort	newest / oldest / name / size

Shell

curl "https://your-domain.example/api/media/assets?page=1&pageSize=40" \
  -H "Authorization: Bearer YOUR_API_KEY"

上传结果包含 id、url、thumbnail、bytes、width、height、status。未审核通过时 url 和 thumbnail 为空；只有 ready 状态才提供图片地址和预览，地址可能包含站点配置的媒体域名。