HANSTUDIO API · v1

Image and video tools for your product

One API for private uploads, image processing, video generation and batch tasks.

Current mode: … · Demo returns samples without actual processing.

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/public

This 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.

TooltoolkindBase 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

MethodPathPermission
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

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.