Tasks

Generation on reAPI is asynchronous. Every submission endpoint — /api/v1/images/generations, /api/v1/videos/generations, and any future /api/v1/audio/generations — returns a task id, and you poll GET /api/v1/tasks/{id} until the task reaches a terminal state.

This page is the canonical reference for the polling endpoint. The request shape, status values, error codes, polling cadence, and refund semantics are the same regardless of which submission endpoint produced the task; only the contents of output differ by media kind.

GET /api/v1/tasks/{id}

Retrieve the current state of a task.

Request

GET /api/v1/tasks/{id}
Authorization: Bearer rk_live_xxx

{id} is the id returned by the submitting POST. Polling does not consume credits.

Response

200 OK — image task example:

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gpt-image-2",
  "status": "completed",
  "created_at": 1735000000,
  "output": {
    "image_urls": [
      "https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/0.png",
      "https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/1.png"
    ]
  },
  "error": null
}

200 OK — video task example:

{
  "id": "task_01k9s419324drezfbwnsvxyr6h",
  "model": "doubao-seedance-2.0",
  "status": "completed",
  "created_at": 1762853430,
  "output": {
    "video_urls": [
      "https://cdn.reapi.ai/media/tasks/01k9s419324drezfbwnsvxyr6h/0.mp4"
    ]
  },
  "error": null
}

Status values

Output shape

The shape of output depends on the media kind of the task:

Some video models add an extra last_frame_url (string) when the request opted into a return-last-frame capability.

URLs returned in output are rehosted to reAPI's CDN. If you need long-term archival, copy them to your own storage as soon as the task completes — bucket lifecycle policies are configured per-deployment and not guaranteed by this contract.

Errors

Polling pattern

Recommended:

attempt 1: wait 2s
attempt 2: wait 2s
...
the worker keeps a task alive up to a wall-clock cap before it self-reports
an 80002 timeout: 1 hour for image and audio, 48 hours for video. Most tasks
finish far sooner (image/audio usually under a minute, video in minutes), so
size your client-side give-up to your own tolerance, not the cap.

The polling endpoint is cached for 5 seconds while a task is in-flight, so polling faster than every 2–3 seconds returns the same state and just consumes rate-limit budget. Video tasks routinely take several minutes; pace your polling accordingly.

Refund behavior

Failed tasks are automatically refunded by the worker the moment the workflow ends in failure — the credit return happens atomically with the status flip, before any poll observes it. Refund is one-shot: re-polling a failed task never refunds twice.

A failed task surfaces the failure code under error:

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "status": "failed",
  "output": null,
  "error": {
    "code": 80006,
    "message": "Request violates content policy"
  }
}

The code here is one of the 8xxxx workflow-execution codes — see Errors → 8xxxx.