快速开始
登录后创建独立 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 密钥。
可调用功能
目录与服务端配置同步;积分是本站计价,不是上游价格。高级功能是否可用取决于账户授权及素材传输配置。
| 功能 | tool | kind | 基础积分 |
|---|
每个工具的 required 列表可通过 capabilities 查询。蒙版需与原图同尺寸;本地裁切、压缩和格式转换不属于付费云 API。完整 options 参数与约束见 OpenAPI 文件。
接口列表
| Method | Path | 权限 |
|---|---|---|
| GET | /capabilities | catalog:read |
| POST | /assets | assets:write |
| POST | /tasks | tasks:write |
| POST | /tasks/batch | tasks:write |
| GET | /tasks | tasks:read |
| GET | /tasks/{task} | tasks:read |
| GET | /assets/{asset} | tasks:read |
| GET | /usage | tasks: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,排查时提供该编号及任务号;调用记录不保存密钥、图片内容或提示词。