HANSTUDIO API · v1

把图像与视频能力接入你的产品

一套接口完成私有素材上传、图片处理、视频生成与批量任务。

当前模式: … · 演示模式返回样例,不执行真实处理。

快速开始

登录后创建独立 API 密钥,将密钥保存在你自己的服务端环境变量中。上传图片获得 asset id,创建任务后使用任务号轮询。

https://ai.hanrouter.com/api/v1/public

以上为当前配置的后端地址;部署时更换为你的公网 HTTPS API 域名。所有请求携带 Accept: application/json。

# Upload a private asset
curl "https://ai.hanrouter.com/api/v1/public/assets" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" \
  -H "Accept: application/json" -F "file=@product.png"

# Use the returned asset id, then create a task
curl "https://ai.hanrouter.com/api/v1/public/tasks" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
  "kind": "image",
  "tool": "remove-background",
  "prompt": "Remove the background from this product image.",
  "ratio": "1:1",
  "reference_id": "ASSET_UUID",
  "request_key": "NEW_REQUEST_UUID"
}'

# Poll the returned task id every 5–20 seconds
curl "https://ai.hanrouter.com/api/v1/public/tasks/TASK_UUID" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" -H "Accept: application/json"

示例中的 ASSET_UUID、NEW_REQUEST_UUID、TASK_UUID 需要替换为真实值;request_key 必须是 UUID。不要在浏览器公开 API 密钥。

可调用功能

目录与服务端配置同步;积分是本站计价,不是上游价格。高级功能是否可用取决于账户授权及素材传输配置。

功能toolkind基础积分

每个工具的 required 列表可通过 capabilities 查询。蒙版需与原图同尺寸;本地裁切、压缩和格式转换不属于付费云 API。完整 options 参数与约束见 OpenAPI 文件。

接口列表

MethodPath权限
GET/capabilitiescatalog:read
POST/assetsassets:write
POST/taskstasks:write
POST/tasks/batchtasks:write
GET/taskstasks:read
GET/tasks/{task}tasks:read
GET/assets/{asset}tasks:read
GET/usagetasks:read

图片上传为 multipart/form-data,字段 file,仅接收 JPEG、PNG、WebP,最大 10MB。其余创建请求使用 JSON。批量接口 items 为 1–10 个任务,共用一个 request_key,校验或余额不足时整批回滚。

{
  "request_key": "BATCH_REQUEST_UUID",
  "items": [
    {
      "kind": "image",
      "tool": "remove-background",
      "prompt": "Remove the background from this product image.",
      "ratio": "1:1",
      "reference_id": "ASSET_UUID"
    }
  ]
}

任务、额度与结果

queued → processing → completed / failed / needs_review

创建成功返回 HTTP 202 并预占积分。同一用户重复使用同一个 request_key 返回原任务,不重复扣费。试衣按结果数量计费,可灵按时长计费;批量每项独立计费。明确失败返还一次,不确定结果转人工核对,请勿盲目重提。

每 5–20 秒查询一次,终态停止。图片使用 result/results,文字使用 resultText,OCR 返回文件链接。本站私有文件需携带 Bearer 密钥下载,上游临时链接可能一小时过期,请及时保存。v1 使用轮询,尚不提供回调。

{
  "id": "TASK_UUID",
  "status": "completed",
  "kind": "image",
  "mode": "live",
  "progress": 100,
  "cost": 20,
  "result": "https://cdn.example/output.png",
  "results": [
    "https://cdn.example/output.png"
  ],
  "resultText": null
}

同一账户所有密钥共用每分钟 60 次请求额度;上传额外限制每分钟 30 次。积分与网站账户共用。

错误与排查

401 · 密钥无效、过期或撤销
403 · 权限不足或账户停用
404 · 资源不存在或不属于当前账户
422 · 参数不合法、素材缺失或积分不足
429 · 请求过快,按 Retry-After 等待

业务错误包含 message/errors。调用响应附带 X-Request-ID,排查时提供该编号及任务号;调用记录不保存密钥、图片内容或提示词。