GPT Image 2

Authentication

Authenticate with your Platform API key in the Authorization header.

Your key needs models:generate and requests:read permissions. Only the following parameters are supported. Unsupported fields return 400 without a charge.

Submit a task

Submit model parameters directly; no estimate request is required. Save data.id to retrieve status, results and the final charge.

Use a unique Idempotency-Key per task. Retry an uncertain submission with the same key and request. Python / JavaScript save input and idempotency key before submission in REQUEST_STATE (default .topview-request.json); keep this file private. Restart with the same file to recover, or set TASK_ID for GET-only recovery. Use a new state path for a new task. Polling retries network errors, 429 and 5xx with bounded backoff and Retry-After; after the retry limit or 30 minutes, resume the saved task ID.

Result Guide

Submit asynchronously and poll for results.

1. Save the task IDSave data.id after submission. HTTP 200 does not mean generation has completed.
2. Check progressCall GET with the original creating API key, requests:read and the corresponding mode permission. A new or rotated key cannot read the old key’s tasks. View Playground tasks in signed-in web history; authorized workspace members can also use web history after the original key expires or is revoked. Poll every 2–5 seconds and back off for long tasks or 429 / 5xx responses.
3. Read the resultKeep polling created / processing tasks. On completed, read data.outputs. On failed, read data.error and stop polling.
4. Handle pending paymentpayment_required means settlement needs more funds. amount_due_usd is the actual cost, additional_charge_usd is the amount above the original hold, and shortfall_usd is the eligible balance shortage. Top up the same workspace; settlement retries automatically without resubmitting. SynLink image tasks use the quoted maxChargeUsd as a spending ceiling; usage above it requires review and is not automatically collected. Other metered tasks may settle additional actual usage above the original hold from eligible balance.
5. Save files and verify chargesRead charged_usd and billing_state for settlement. Save results promptly because media URLs may expire. After a timeout, query the original task rather than creating a duplicate.

Replace REQUEST_ID with data.id. Poll data.status until completed or failed; successful results are in data.outputs.

data.charged_usd is the actual task cost in USD, returned as an exact decimal string. data.billing_state: RESERVED holds funds, CAPTURED settles the charge, and RELEASED returns the hold.

Schema

Request and response schemas for the selected mode.

Submit requests using official field names. The API path selects the model; no model identifier is needed in the request body. Required fields, defaults and mode-specific constraints are defined below.

• Standard is billed by resolution without a quality selector; official quality tiers are price benchmarks only. Per-image display prices are estimates. The displayed discount is maintained by operators and does not describe real-time supplier cost. Submit directly. Settlement uses actual consumption on the selected channel and releases unused funds. Read data.charged_usd for the actual USD charge; this is not fixed per-image billing.
• APIMart standard: n=1, up to 15 references; no quality, mask_url, moderation, output_compression or non-PNG output controls.
• APIMart Official is currently disabled. Supported parameters depend on enabled routes and the schema below. Results are asynchronous; stream, partial_images and b64_json responses are unavailable.
• Topview image channel: n=1–4, up to 16 references, masks, quality, format, compression and moderation. Pixel sizes must be multiples of 16, at most 3840 per edge, within a 3:1 ratio and 655,360–8,294,400 pixels. Results are returned as asynchronous URLs.
• Topview image channel: n=1–4, up to 16 references, masks, quality, format, compression and moderation. Pixel sizes must be multiples of 16, at most 3840 per edge, within a 3:1 ratio and 655,360–8,294,400 pixels. Results are returned as asynchronous URLs.
• size accepts ratios, auto and pixel dimensions. Pixel sizes use the published 4k price; quality=auto is forwarded unchanged and priced as high. URL references are forwarded directly; inline references retain the Platform 6 MB aggregate limit. These are Platform pricing/request policies, not missing supplier fields.

If data.execution_state is REVIEW_REQUIRED, the upstream result or charge needs reconciliation and status may remain processing. Keep the task ID and contact support; do not resubmit with a new Idempotency-Key. Funds may remain RESERVED until reconciliation; a hold is not a completed charge.

Input schema

Common parameters match the Playground form. Use the API field path in request JSON; descriptions explain nested fields and media roles. — means no declared default, not null or zero.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "size": {
      "type": "string",
      "description": "Aspect ratio, auto, or WxH pixel dimensions; alias of aspect_ratio. Pixel dimensions use the published 4k price tier regardless of the resolution hint."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "1k",
        "2k",
        "4k"
      ]
    },
    "quality": {
      "type": "string",
      "enum": [
        "auto",
        "low",
        "medium",
        "high"
      ],
      "description": "Available when supported by the active image route. auto is forwarded unchanged and uses the published high quality price tier."
    },
    "n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "default": 1,
      "description": "Official: 1–4. Standard: 1. Each output is billed."
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "x-image-rules": {
          "minSide": 1,
          "maxSide": 16384,
          "maxRatio": 0,
          "maxBytes": 20971520,
          "maxPixels": 40000000,
          "formats": [
            "image/png",
            "image/jpeg",
            "image/webp"
          ],
          "rejectPngAlpha": false,
          "description": "Official: PNG/JPEG/WebP, each image under 50 MB. No additional input pixel minimum is specified. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created.",
          "source": "https://developers.openai.com/api/reference/python/resources/images/methods/edit"
        }
      },
      "maxItems": 16,
      "description": "Official: PNG/JPEG/WebP, each image under 50 MB. No additional input pixel minimum is specified. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created."
    },
    "mask_url": {
      "type": "string",
      "format": "uri",
      "description": "Mask: PNG under 4 MB with the same dimensions as the first image. The server checks matching dimensions before quoting.",
      "x-image-rules": {
        "minSide": 1,
        "maxSide": 16384,
        "maxRatio": 0,
        "maxBytes": 3999999,
        "maxPixels": 40000000,
        "formats": [
          "image/png"
        ],
        "rejectPngAlpha": false,
        "description": "Mask: PNG under 4 MB with the same dimensions as the first image. The server checks matching dimensions before quoting.",
        "source": "https://developers.openai.com/api/reference/python/resources/images/methods/edit"
      }
    },
    "output_format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg",
        "webp"
      ],
      "description": "Official channel."
    },
    "output_compression": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "description": "Official channel JPEG/WebP compression."
    },
    "nsfw_check": {
      "type": "boolean"
    },
    "moderation": {
      "type": "string",
      "enum": [
        "auto",
        "low"
      ],
      "description": "Official channel."
    }
  },
  "additionalProperties": false,
  "description": "Native request fields. The model route supplies model when omitted. Platform authentication, idempotency and asynchronous prediction responses remain unchanged. Platform pricing: pixel sizes use the 4k SKU; quality=auto uses the high SKU while forwarding auto unchanged. URL references are forwarded directly. Inline references retain the Platform 6 MB aggregate request limit. The selected supplier is pinned; automatic Official fallback is disabled.",
  "x-supplier-notes": [
    {
      "supplier": "apimart",
      "unsupported": [
        "quality",
        "mask_url",
        "moderation",
        "output_compression",
        "n > 1",
        "image_urls > 15",
        "output_format other than png"
      ],
      "reason": "These controls are provided only by the APIMart Official image endpoint."
    },
    {
      "supplier": "apimart_official",
      "unsupported": [
        "n > 4",
        "image_urls > 16"
      ],
      "reason": "Published APIMart Official limits."
    },
    {
      "supplier": "apimart / apimart_official",
      "unsupported": [
        "stream=true",
        "response_format=b64_json",
        "partial_images"
      ],
      "reason": "These supplier endpoints return an asynchronous task ID and URL results; no streaming or base64 response contract is published."
    },
    {
      "supplier": "Topview image channel",
      "unsupported": [
        "n > 4",
        "image_urls > 16",
        "pixel sizes that are not multiples of 16, exceed 3840 per edge, exceed a 3:1 ratio or fall outside 655,360-8,294,400 pixels",
        "stream=true",
        "response_format=b64_json",
        "partial_images"
      ],
      "reason": "Published limits of this channel; results are archived and returned as URLs. nsfw_check is accepted, moderation controls the content filter."
    }
  ],
  "required": [
    "prompt"
  ]
}

Output schema

Task query response. Generation results are inside data. Nested field presence depends on the parent being returned.

{
  "type": "object",
  "required": [
    "code",
    "message",
    "data"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "HTTP API envelope code. Inspect data.status for the task outcome."
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "id",
        "created_at",
        "code",
        "execution_state",
        "status",
        "outputs",
        "charged_usd",
        "billing_state",
        "error",
        "urls"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Platform task ID. Persist it before polling."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "code": {
          "type": "integer",
          "description": "0 for normal tasks; 402 when payment is required; 1403 for a failed task."
        },
        "execution_state": {
          "type": "string",
          "description": "Execution state; inspect status and billing_state before treating a task as settled."
        },
        "status": {
          "type": "string",
          "enum": [
            "created",
            "processing",
            "payment_required",
            "completed",
            "failed"
          ]
        },
        "outputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix."
        },
        "amount_due_usd": {
          "type": "string",
          "description": "Full actual cost in USD, present when status is payment_required."
        },
        "additional_charge_usd": {
          "type": "string",
          "description": "Actual cost minus the original reservation; present when payment is required."
        },
        "shortfall_usd": {
          "type": "string",
          "description": "Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed."
        },
        "charged_usd": {
          "type": "string",
          "description": "Actual USD charge as an exact decimal string, not the reserved amount.",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "example": "0.040000000000"
        },
        "billing_state": {
          "type": "string",
          "description": "RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.",
          "enum": [
            "RESERVED",
            "CAPTURED",
            "RELEASED"
          ]
        },
        "error": {
          "type": "string",
          "description": "Failure or payment-required description, otherwise an empty string."
        },
        "urls": {
          "type": "object",
          "required": [
            "get"
          ],
          "properties": {
            "get": {
              "type": "string",
              "format": "uri",
              "description": "Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission."
            }
          }
        },
        "last_frame_url": {
          "type": "string",
          "format": "uri",
          "description": "Last-frame image URL when requested and returned, available only after settlement."
        }
      }
    }
  }
}

Errors

HTTP success does not guarantee generation success. Inspect data.status, data.error and billing_state.