Retrieve a task

Get one task's status and result. A task is generated in the background; with a webhook you don't need to poll, and the webhook body is exactly this endpoint's response. Every response uses the { code, message, data } envelope, see Response format.

curl https://api.nanoapi.ai/v1/tasks/tk_01jb8z5q4w3e2r1t0y9u8i7o6p \
  -H "Authorization: Bearer $NANOAPI_API_KEY"

Response

On success you get 200 with the full task object as data:

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
    "model": "genjutsu-1.0",
    "status": "running",
    "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": [],
    "billing": {
      "currency": "USD",
      "frozen": "4.095",
      "charged": "0.00",
      "refunded": "0.00",
      "billed_seconds": null
    },
    "error": null,
    "webhook_url": "https://example.com/hooks/nanoapi",
    "created_at": "2026-10-22T08:30:00Z",
    "started_at": "2026-10-22T08:31:05Z",
    "finished_at": null,
    "elapsed_seconds": null
  }
}

This task is still generating: outputs is empty, finished_at and elapsed_seconds are null and nothing has been charged yet. A succeeded task is shown under The task object, a failed one under Failed tasks.

Errors

A failed request returns 4xx / 5xx. Only this one read failed; it says nothing about the task, which keeps queuing or generating as before. For example, a task that doesn't exist:

{
  "code": 404,
  "message": "Task not found.",
  "error": {
    "type": "not_found",
    "param": null,
    "details": null
  },
  "request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}

The task object

It's the data of a retrieved task, each item in a task list's data.items, and the data of a webhook (creating a task returns a short form). This is what data contains:

{
  "object": "task",
  "id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
  "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/outputs/tk_01jb8z5q4w3e2r1t0y9u8i7o6p/0.mp4",
      "preview_url": "https://file.example.com/outputs/tk_01jb8z5q4w3e2r1t0y9u8i7o6p/0_compressed.mp4"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "4.095",
    "charged": "4.095",
    "refunded": "0.00",
    "billed_seconds": 15
  },
  "error": null,
  "webhook_url": "https://example.com/hooks/nanoapi",
  "created_at": "2026-10-22T08:30:00Z",
  "started_at": "2026-10-22T08:31:05Z",
  "finished_at": "2026-10-22T08:47:12Z",
  "elapsed_seconds": 1032
}

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

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

Once the task has finished, charged + refunded = frozen. See Billing.

Failed tasks

A failed task was created and its cost frozen, but no result was generated. A failed task:

• has status: "failed". That's final: it never changes, and you can't retry the task itself.
• has an error with the reason: type for your program, message an English explanation for people. A task failure isn't a failed request, so there's no HTTP status here.
• has an empty outputs array.
• got its money back in full: billing.charged is "0.00" and billing.refunded equals billing.frozen. The frozen amount is already back in your available balance; you don't need to do anything.

A failed task looks like this in the data of a retrieved task, in a task list's data.items and in the data of a webhook. Here are three tasks that failed at different stages; they differ in error, started_at and when they finished:

{
  "object": "task",
  "id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
  "model": "genjutsu-1.0",
  "status": "failed",
  "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": [],
  "billing": {
    "currency": "USD",
    "frozen": "4.095",
    "charged": "0.00",
    "refunded": "4.095",
    "billed_seconds": null
  },
  "error": {
    "type": "invalid_media",
    "message": "A reference image could not be downloaded. Make sure every link in image_urls is publicly downloadable."
  },
  "webhook_url": "https://example.com/hooks/nanoapi",
  "created_at": "2026-10-22T08:30:00Z",
  "started_at": "2026-10-22T08:31:05Z",
  "finished_at": "2026-10-22T08:31:40Z",
  "elapsed_seconds": 100
}

Compared with a succeeded task, these fields differ:

A failed task can't be retried. To generate again, create a task with the same parameters: you get a new task ID and the cost is frozen again.

Failure reasons

New failure reasons may be added: treat any type you don't recognize as an ordinary failure instead of raising an error.

When a task can fail

Messages

message is an English explanation for developers: log it, use it to debug, or translate it for your own users. These are all the messages you can currently get:

The wording may change and new messages may be added: branch on type only.