Poll a gpt-image-2 API render to completion and pull the hosted PNG URL. Paginate past renders by cursor. Single-task and list responses documented end to end.

Retrieve tasks

After POST /api/v1/images/generate returns a task_id, the task runs asynchronously (~45–60 seconds end-to-end). Poll this endpoint to receive the final state and image URL.

Retrieve a single task

GET /api/v1/images/task/{id}

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <YOUR_API_KEY>`

Path parameters

Parameter	Description
`id`	The `task_id` returned by `POST /api/v1/images/generate`, e.g. `gpt-image-2-kUtpnus8fXpDKkuEjayG3`

Response

200 OK — processing

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "processing",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": null,
    "images": null,
    "error": null,
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:12:03.456Z"
  }
}

200 OK — completed

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "completed",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
    "images": [
      {
        "url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
        "content_type": "image/png"
      }
    ],
    "error": null,
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:13:02.789Z"
  }
}

When n > 1, images contains the full generated set in order. The media_url field remains the first image in the array as a convenient primary URL.

200 OK — failed

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "failed",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": null,
    "images": null,
    "error": "Generation failed",
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:13:10.123Z"
  }
}

Credits for a failed task are refunded automatically by the background worker — the credit_transaction log shows a matching refund entry.

404 NOT_FOUND

Returned when:

The task ID does not exist
The task belongs to a different account
The task was created through the web Studio rather than the API

The same 404 is returned in all three cases — no information is leaked about which case applies.

Status values

`status`	Meaning
`processing`	Task accepted, running on the upstream generator
`completed`	Completed successfully. `media_url` / `images` are set.
`failed`	Generation failed. Credits have been refunded. `error` is set.

Status transitions are monotonic — once completed or failed, the value won't change.

Polling cadence

Generation typically takes 45–60 seconds. Recommended pattern:

Wait 10 seconds after submission before the first poll
Poll every 5–10 seconds while status is processing
Stop after 10 minutes if the task is still not terminal (treat as stuck and contact support with the task_id)

while true; do
  resp=$(curl -s -H "Authorization: Bearer $GPTIMG_API_KEY" \
    "https://gptimg.co/api/v1/images/task/$TASK_ID")
  status=$(echo "$resp" | jq -r .data.status)
  case "$status" in
    completed)
      echo "Done"
      echo "$resp" | jq -r .data.media_url
      break
      ;;
    failed)
      echo "Failed (credits refunded)"
      echo "$resp" | jq -r .data.error
      exit 1
      ;;
    *)
      echo "Status: $status"
      sleep 5
      ;;
  esac
done

List your tasks

GET /api/v1/images/task

Returns a paginated list of the authenticated user's API-sourced gpt-image-2 tasks, newest first. Tasks created through the web Studio are intentionally excluded — API and Studio are separate surfaces.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Page size, 1–100
`cursor`	string	—	Opaque cursor from a previous response's `next_cursor`. Omit on the first page.

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "kUtpnus8fXpDKkuEjayG3",
        "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
        "status": "completed",
        "provider": "gpt-image-2",
        "model": "gpt-image-2",
        "type": "text-to-image",
        "media_url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
        "images": [{ "url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png", "content_type": "image/png" }],
        "error": null,
        "created_at": "2026-04-22T00:12:03.456Z",
        "updated_at": "2026-04-22T00:13:02.789Z"
      }
    ],
    "next_cursor": "2026-04-22T00:12:03.456Z"
  }
}

Field	Description
`data.items`	Array of task objects (same shape as the single-task response)
`data.next_cursor`	Pass as `?cursor=...` on the next request. `null` when there are no more pages.

Pagination example

# First page
curl -H "Authorization: Bearer $GPTIMG_API_KEY" \
  "https://gptimg.co/api/v1/images/task?limit=50"

# Next page
curl -H "Authorization: Bearer $GPTIMG_API_KEY" \
  "https://gptimg.co/api/v1/images/task?limit=50&cursor=2026-04-22T00:12:03.456Z"

Retrieve tasks

After POST /api/v1/images/generate returns a task_id, the task runs asynchronously (~45–60 seconds end-to-end). Poll this endpoint to receive the final state and image URL.

Retrieve a single task

GET /api/v1/images/task/{id}

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <YOUR_API_KEY>`

Path parameters

Parameter	Description
`id`	The `task_id` returned by `POST /api/v1/images/generate`, e.g. `gpt-image-2-kUtpnus8fXpDKkuEjayG3`

Response

200 OK — processing

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "processing",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": null,
    "images": null,
    "error": null,
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:12:03.456Z"
  }
}

200 OK — completed

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "completed",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
    "images": [
      {
        "url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
        "content_type": "image/png"
      }
    ],
    "error": null,
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:13:02.789Z"
  }
}

When n > 1, images contains the full generated set in order. The media_url field remains the first image in the array as a convenient primary URL.

200 OK — failed

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "failed",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": null,
    "images": null,
    "error": "Generation failed",
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:13:10.123Z"
  }
}

Credits for a failed task are refunded automatically by the background worker — the credit_transaction log shows a matching refund entry.

404 NOT_FOUND

Returned when:

The task ID does not exist
The task belongs to a different account
The task was created through the web Studio rather than the API

The same 404 is returned in all three cases — no information is leaked about which case applies.

Status values

`status`	Meaning
`processing`	Task accepted, running on the upstream generator
`completed`	Completed successfully. `media_url` / `images` are set.
`failed`	Generation failed. Credits have been refunded. `error` is set.

Status transitions are monotonic — once completed or failed, the value won't change.

Polling cadence

Generation typically takes 45–60 seconds. Recommended pattern:

Wait 10 seconds after submission before the first poll
Poll every 5–10 seconds while status is processing
Stop after 10 minutes if the task is still not terminal (treat as stuck and contact support with the task_id)

while true; do
  resp=$(curl -s -H "Authorization: Bearer $GPTIMG_API_KEY" \
    "https://gptimg.co/api/v1/images/task/$TASK_ID")
  status=$(echo "$resp" | jq -r .data.status)
  case "$status" in
    completed)
      echo "Done"
      echo "$resp" | jq -r .data.media_url
      break
      ;;
    failed)
      echo "Failed (credits refunded)"
      echo "$resp" | jq -r .data.error
      exit 1
      ;;
    *)
      echo "Status: $status"
      sleep 5
      ;;
  esac
done

List your tasks

GET /api/v1/images/task

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Page size, 1–100
`cursor`	string	—	Opaque cursor from a previous response's `next_cursor`. Omit on the first page.

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "kUtpnus8fXpDKkuEjayG3",
        "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
        "status": "completed",
        "provider": "gpt-image-2",
        "model": "gpt-image-2",
        "type": "text-to-image",
        "media_url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
        "images": [{ "url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png", "content_type": "image/png" }],
        "error": null,
        "created_at": "2026-04-22T00:12:03.456Z",
        "updated_at": "2026-04-22T00:13:02.789Z"
      }
    ],
    "next_cursor": "2026-04-22T00:12:03.456Z"
  }
}

Field	Description
`data.items`	Array of task objects (same shape as the single-task response)
`data.next_cursor`	Pass as `?cursor=...` on the next request. `null` when there are no more pages.

Pagination example

# First page
curl -H "Authorization: Bearer $GPTIMG_API_KEY" \
  "https://gptimg.co/api/v1/images/task?limit=50"

# Next page
curl -H "Authorization: Bearer $GPTIMG_API_KEY" \
  "https://gptimg.co/api/v1/images/task?limit=50&cursor=2026-04-22T00:12:03.456Z"

Retrieve tasks

Retrieve tasks

Retrieve a single task

Headers

Path parameters

Response

200 OK — processing

200 OK — completed

200 OK — failed

404 NOT_FOUND

Status values

Polling cadence

List your tasks

Query parameters

Response

Tabla de contenidos

Retrieve tasks

Retrieve tasks

Retrieve a single task

Headers

Path parameters

Response

200 OK — processing

200 OK — completed

200 OK — failed

404 NOT_FOUND

Status values

Polling cadence

List your tasks

Query parameters

Response

Tabla de contenidos