Retrieve an image task

Overview

Retrieval only reads an existing task; it does not resubmit or charge again. queued, running, succeeded, and failed use the same task projection. A result URL remains valid only until result_expires_at.

Authentication: Bearer API key

Request

Path parameters

Name	Type	Description
`task_id`required	string	Immutable task ID returned by task creation.

Response

JSON endpoints use the standard response envelope. HTTP status represents the request outcome; business errors are not disguised as HTTP 200.

HTTP	Meaning
`200`	Request succeeded
`401`	Missing or invalid API key
`403`	API key disabled or access forbidden
`404`	Resource not found or signature invalid
`410`	Task result or signed asset expired
`422`	Request-structure validation failed
`500`	Internal service error

Complete success example (optional fields vary by state)

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_01JEXAMPLE",
    "status": "succeeded",
    "terminal_reason": null,
    "model": "gpt-image-2",
    "operation": "generation",
    "size": "1024x1024",
    "size_tier": null,
    "quality": "standard",
    "response_format": "url",
    "input_count": 0,
    "has_mask": false,
    "response_mode": "async",
    "auto_async_on_timeout": null,
    "requested_count": 1,
    "result": {
      "requested_count": 1,
      "completed_count": 1,
      "partial": false,
      "partial_reason": null,
      "partial_reason_message": null,
      "images": [
        {
          "asset_id": "asset_01JEXAMPLE",
          "mime_type": "image/png",
          "width": 1024,
          "height": 1024,
          "byte_size": 824311,
          "expires_at": "2026-08-10T03:00:30Z",
          "url": "/api/v1/assets/asset_01JEXAMPLE/content?expires=...&representation=url&signature=...",
          "b64_json": null
        }
      ]
    },
    "result_expires_at": "2026-08-10T03:00:30Z",
    "result_expired": false,
    "poll_url": "/api/v1/tasks/task_01JEXAMPLE",
    "retry_after_seconds": null,
    "channel": {
      "channel_row_id": "gpt-image-2-generations-economy-a",
      "platform_name": "Channel 001",
      "request_price": {
        "resolved_size": "1024x1024",
        "resolved_quality": "standard",
        "currency": "USD",
        "unit": "request",
        "request_price": "0.023000",
        "effective_at": "2026-08-10T00:00:00Z"
      },
      "refund_policy": {
        "code": "rpf_rrr",
        "zero_delivery": "refund_all",
        "policy_violation": "refund_all",
        "unrecoverable": "refund_all",
        "description": {
          "zh-CN": "三类终态均全额退款。",
          "en-US": "All three terminal classes receive a full refund."
        }
      },
      "size_semantics": "approximate_tier",
      "billing_basis": "per_request"
    },
    "routing": {
      "strategy": "stable_first",
      "total_attempts": 1,
      "switch_count": 0,
      "attempts": [
        {
          "attempt_number": 1,
          "channel_row_id": "gpt-image-2-generations-economy-a",
          "channel_name": "Channel 001",
          "action": "initial",
          "outcome": "accepted",
          "reason_code": "accepted_stop",
          "reason": "accepted",
          "occurred_at": "2026-08-10T00:00:01Z"
        }
      ]
    },
    "error": null,
    "billing": {
      "status": "charged",
      "currency": "USD",
      "reserved_amount": "0.023000",
      "charged_amount": "0.023000",
      "refunded_amount": "0.000000",
      "released_amount": "0.000000",
      "balance_after_settlement": "12.477000"
    },
    "created_at": "2026-08-10T00:00:00Z",
    "updated_at": "2026-08-10T00:00:30Z",
    "completed_at": "2026-08-10T00:00:30Z"
  },
  "request_id": "8f25b42f-2ed1-4ad7-99de-61d7f779bc7b",
  "timestamp": "2026-08-10T00:00:00Z"
}

Important boundaries

The explorer never auto-polls; every retrieval requires an explicit click.
A failed task's terminal_reason, error, and billing come from one final snapshot.

Open the machine-readable OpenAPI