API reference
Task & download
Every tool returns a task id. Poll it until the run completes, then stream the result.
GET
/api/ai-tasks/{taskId}GET
/api/ai-creations/{taskId}/downloadPoll a task
GET /api/ai-tasks/{taskId} returns the task state:
| Parameter | Values | Notes |
|---|---|---|
| status | pending · running · completed · failed | Failed tasks refund automatically — see refunded. |
| stage | string or null | Coarse progress inside a run (e.g. upscale stages), when reported; null otherwise. |
| widthPx, heightPx, dpi | numbers or null | Result pixel size and print DPI, once completed. |
| thumbnailUrl | string or null | Preview of the finished file, once completed. |
| credits | number | Credits the run cost. |
| refunded | boolean | True when a failure returned the credits. |
| errorCode | string or null | Stable machine code on failure, null otherwise. |
Poll every few seconds — runs usually finish in 1–3 minutes.
Unknown task ids return 404 with {"errorCode": "not_found"}. The task must belong to the authenticated account.
Download the result
GET /api/ai-creations/{taskId}/download streams the finished file with attachment headers — hand it straight to production. DPI and physical size are written into the file.
Error responses use a plain {"error": "..."} body:401 unauthorized, 404 unknown task or no result yet, 502 upstream fetch failed, 500 internal failure. Poll until status: completed before downloading.