Tasks
Retrieve and list tasks, and every field of the task object.
Every generation is a task. Tasks are created by a model endpoint, such as POST /v1/genjutsu, and read with the endpoints below.
Retrieve a task
GET https://api.nanoapi.ai/v1/tasks/{task_id}curl https://api.nanoapi.ai/v1/tasks/tk_01jb8z5q4w3e2r1t0y9u8i7o6p \
-H "Authorization: Bearer $NANOAPI_API_KEY"Returns the task object. While the task is queued or running, the response has Retry-After: 15, the suggested polling interval. A task that doesn't exist or isn't yours returns 404 not_found.
List tasks
GET https://api.nanoapi.ai/v1/tasks| Query parameter | Description |
|---|---|
ids | Up to 20 comma-separated task IDs, to check several tasks in one request. Other filters and pagination are then ignored. |
status | queued, running, succeeded or failed. |
product | Currently only genjutsu. |
api_key_id | The key that created the task (api_key.id). |
created_after / created_before | Creation time range (ISO 8601). |
limit / starting_after | See Pagination. |
curl "https://api.nanoapi.ai/v1/tasks?ids=tk_01jb8z5q4w3e2r1t0y9u8i7o6p,tk_01jb8z7c2d4f6g8h0j2k4m6n8p" \
-H "Authorization: Bearer $NANOAPI_API_KEY"Returns { "object": "list", "data": [...], "has_more": false } with full task objects, newest first. Match results by id, not by position. Read requests are limited to 1 per second, so check all the tasks you're waiting on in one request (Rate limits).
The task object
Returned by the model endpoints and the endpoints above, and sent as data in webhooks.
{
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"product": "genjutsu",
"model": "genjutsu-1.0",
"status": "succeeded",
"input": {
"mode": "motion_control",
"image_urls": ["https://example.com/person.png"],
"video_url": "https://example.com/dance.mp4",
"prompt": "",
"resolution": "720p"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://file.example.com/…/0.mp4",
"preview_url": "https://file.example.com/…/0_compressed.mp4"
}
],
"billing": {
"currency": "USD",
"frozen": "4.095",
"charged": "4.095",
"refunded": "0.00",
"billed_seconds": 15
},
"error": null,
"metadata": { "order_id": "A1001" },
"webhook_url": "https://example.com/hooks/nanoapi",
"api_key": { "id": "ak_01jb7y2m3n4p5q6r7s8t9v0w1x", "name": "production", "prefix": "nf_8Kx2" },
"created_at": "2026-10-22T08:30:00Z",
"started_at": "2026-10-22T08:31:05Z",
"finished_at": "2026-10-22T08:47:12Z",
"elapsed_seconds": 1032
}| Field | Description |
|---|---|
id | Task ID, such as tk_01jb8z5q4w3e2r1t0y9u8i7o6p. See IDs. |
product | The product, currently genjutsu. |
model | The model version, such as genjutsu-1.0. |
status | queued, running, succeeded or failed. See Status. |
input | The model parameters from the create request. |
num_outputs | The number of results requested. |
outputs | The results, empty until the task succeeds. See Outputs. |
billing | Amounts in US dollars. See Billing fields. |
error | Why the task failed, otherwise null. See Failure codes. |
metadata | Your key-value pairs from the create request. |
webhook_url | From the create request, or null. |
api_key | The key that created the task: id, name and prefix (its first characters). Kept after the key is deleted or reset. |
created_at / started_at / finished_at | ISO 8601 times; started_at and finished_at are null until they happen. |
elapsed_seconds | Duration in seconds, from creation to the end, queueing included; null until the task finishes. |
Status
queued ──starts──→ running ──┬─→ succeeded (charged)
│ └─→ failed (frozen amount returned)
└──not started within 30 minutes──→ failed (queue_timeout)succeeded and failed are final and never change. Tasks can't be cancelled.
Outputs
| Field | Description |
|---|---|
index | Position, from 0. |
type | video for Genjutsu. |
url | The result file, as a direct download link. |
preview_url | A silent, compressed copy 600 pixels wide, for previews; null if it couldn't be made. |
Anyone with the link can open the file, so don't share links you want to keep private. Result files currently aren't deleted, but copy anything you need to keep to your own storage.
Billing fields
| Field | Description |
|---|---|
frozen | Frozen from your balance when the task was created. |
charged | Charged when the task succeeded; "0.00" until it finishes and for failed tasks. |
refunded | Returned to your available balance; "0.00" until it finishes. |
billed_seconds | Seconds billed (a number, up to 3 decimals) once the task succeeds, otherwise null. |
Once the task has finished, charged + refunded = frozen. See Billing.
Failure codes
error on a failed task, for example { "code": "queue_timeout", "message": "The task did not start within 30 minutes." }. The frozen amount is always returned in full.
code | Description |
|---|---|
queue_timeout | The task didn't start within 30 minutes of being queued. |
content_policy | The input violates the usage policy, for example a protected likeness or copyrighted content. |
invalid_request | The model didn't accept this combination of parameters. |
generation_failed | Generation failed or timed out. |
internal_error | An internal error. You can create the task again. |