Quick start
Sign in and create an API key. Store it in your server environment. Upload an image, submit a task and poll its ID.
https://ai.hanrouter.com/api/v1/publicThis is the configured backend address; use your public HTTPS API domain in production. Send 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"Replace placeholder IDs with real values. request_key must be a UUID. Keep API keys out of public browser code.
Available capabilities
This catalog follows server configuration. Credits are site pricing. Live availability depends on provider permissions and asset delivery configuration.
| Tool | tool | kind | Base credits |
|---|
Query capabilities for each tool’s required fields. Masks must match source dimensions. Local browser editors are separate from the paid cloud API. See OpenAPI for options and constraints.
Endpoints
| Method | Path | Permission |
|---|---|---|
| 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 |
Upload multipart/form-data with field file: JPEG, PNG or WebP, at most 10 MB. Task requests use JSON. Batch items accepts 1–10 tasks and one request_key; validation or balance failures roll back the batch.
{
"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"
}
]
}Tasks, credits and results
queued → processing → completed / failed / needs_review
HTTP 202 reserves credits. Reusing the same request_key returns the original task without another charge. Try-on quantity, Kling duration and each batch item affect cost. Definite failures refund once; uncertain outcomes require review, not blind resubmission.
Poll every 5–20 seconds and stop on terminal status. Read result/results for images, resultText for captions and file URLs for OCR. Private downloads require Bearer authentication; upstream links may expire in one hour. v1 uses polling without callbacks.
{
"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
}All account keys share 60 requests per minute; uploads are additionally limited to 30 per minute. API and website share account credits.
Errors and troubleshooting
401 · Invalid, expired or revoked key
403 · Missing permission or disabled account
404 · Missing resource or another account’s resource
422 · Invalid parameters, missing assets or insufficient credits
429 · Rate limited; respect Retry-After
Errors include message/errors. Responses include X-Request-ID; provide it and the task ID for support. Request logs exclude keys, image content and prompts.