> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT Image 2 Official

> Text-to-image, reference editing and masked inpainting, billed from token usage

`gpt-image-2` is the official API line for GPT Image 2. Use it for product imagery, posters, illustration, and edits based on visual references. Every operation uses the unified `POST /v1/tasks` endpoint.

<Note>
  For fixed per-image pricing, see [`gpt-image-2-rev`](/en/api-reference/image/gpt-image/gpt-image-2-rev). Both lines use the same task endpoint, but have separate model IDs, parameters, and billing. QWave never switches between them automatically.
</Note>

## Quick start

<CodeGroup>
  ```bash Generate an image theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: image-demo-001" \
    -d '{
      "model": "gpt-image-2",
      "action": "generate",
      "prompt": "A blue ceramic cup on a white table, soft natural light, product photography",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "quality": "low",
      "n": 1
    }'
  ```

  ```bash Edit a reference image theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: image-edit-001" \
    -d '{
      "model": "gpt-image-2",
      "action": "edit",
      "prompt": "Keep the subject and replace the background with a beach at sunset",
      "image_urls": ["https://cdn.example.com/source.png"],
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "quality": "low",
      "n": 1
    }'
  ```

  ```bash Inpaint with a mask theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "action": "edit",
      "prompt": "Change only the cup to dark green; preserve everything else",
      "image_urls": ["https://cdn.example.com/source.png"],
      "mask_url": "https://cdn.example.com/mask.png",
      "resolution": "1k",
      "quality": "medium"
    }'
  ```
</CodeGroup>

A successful submission returns a `task_id`. Retrieve the result with [`GET /v1/tasks/{task_id}`](/en/api-reference/task/status), wait inline with [`Prefer: wait`](/en/api-reference/task/submit#in-request-waiting-prefer-wait), or configure a webhook.

## Request parameters

<ParamField body="model" type="string" required>
  Must be `gpt-image-2`.
</ParamField>

<ParamField body="action" type="string" default="generate">
  * `generate`: create an image from text
  * `edit`: edit reference images; requires `image_urls`
</ParamField>

<ParamField body="prompt" type="string" required>
  The image description or editing instruction.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Reference image URLs. Required for `edit`; up to 16 images.
</ParamField>

<ParamField body="mask_url" type="string">
  URL of an inpainting mask. Requires `image_urls` and must match the first reference image dimensions.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="1:1">
  One of `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `3:1`, `1:3`, `21:9`, or `9:21`.
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  Output resolution: `1k`, `2k`, or `4k`.
</ParamField>

<ParamField body="quality" type="string" default="low">
  `low`, `medium`, or `high`. Higher quality usually consumes more output tokens.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images to generate. Value: `1`. Each request returns one image.
</ParamField>

<ParamField body="background" type="string" default="auto">
  `auto`, `opaque`, or `transparent`. Transparent output requires `png` or `webp`.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  `png`, `jpeg`, or `webp`.
</ParamField>

<ParamField body="output_compression" type="integer">
  JPEG/WebP compression from `0` to `100`. Set `output_format` to `jpeg` or `webp` when using it.
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  Moderation level: `auto` or `low`.
</ParamField>

See [Submit a task](/en/api-reference/task/submit) for `callback_url`, `callback_events`, `Prefer: wait`, `Idempotency-Key`, and the maximum-cost header.

The official line does not support `seed`. Any other parameter returns `400` and is not billed.

## Limits

| Condition                   | Limit                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| Per request                 | One image returned                                                                       |
| `action: "edit"`            | At least one reference image is required                                                 |
| Using `mask_url`            | `image_urls` is required, and the mask must match the first reference image's dimensions |
| `background: "transparent"` | `output_format` must be `png` or `webp`                                                  |
| Using `output_compression`  | `output_format` must be explicitly set to `jpeg` or `webp`                               |
| Reference images            | Up to 16                                                                                 |

## Pricing

The official line is **billed from actual token usage** across five dimensions: text input, cached text input, image input, cached image input and image output.

Rates are in `price_config` on `GET /v1/models` and in the console's Model Market. What a single call actually cost is the `cost` field on the task response — an integer quota at **500,000 quota = 1 USD**, not dollars.

Image input includes reference images and masks. Cached rates apply only when the upstream response reports cache usage that can be settled. Otherwise, billing uses ordinary input and image-output usage.

### Holds and settlement

Submitting a task places a hold for the estimated usage; the task then settles from actual usage and the difference is released. The estimate is built from:

* **Output** — expected output tokens, looked up by aspect ratio, resolution and quality
* **Text input** — a floor of 32 tokens
* **Reference images** — 4,096 tokens each; masks count as image input too

Output token counts vary enormously: at a given aspect ratio, `high` is estimated at roughly **36×** the tokens of `low`, and `4k` is several times `1k` again — combined, per-image cost spans two orders of magnitude. `quality` is the parameter with the largest effect on cost on this line, and it defaults to `low`. Aspect ratio matters too: at the same quality, `16:9` uses fewer output tokens than `1:1`.

The estimated output tokens for every aspect-ratio / resolution / quality combination are in `price_config.image_usage_reservation` on `GET /v1/models`.

You are only billed for a successfully generated image. Failed and cancelled tasks, and tasks that return no usable image, are refunded in full. See [Task status](/en/api-reference/task/status) for the billing fields.

## Response

```json Completed task theme={"system"}
{
  "task_id": "taski_example",
  "model": "gpt-image-2",
  "action": "edit",
  "status": "completed",
  "progress": "100%",
  "result": {
    "images": [
      {
        "url": ["https://cdn.example.com/result.png"]
      }
    ]
  },
  "billing_status": "settled",
  "cost": 6368
}
```

Generated images are returned in `result.images`. Failed and cancelled tasks release the hold in full. If an upstream success response contains no deliverable image, QWave marks the task as failed and refunds it.

## Related

* [GPT Image Series](/en/api-reference/image/gpt-image/overview)
* [GPT Image 1 and 1.5 Official](/en/api-reference/image/gpt-image/gpt-image-1)
* [GPT Image 2 Reverse](/en/api-reference/image/gpt-image/gpt-image-2-rev)
* [Submit Task](/en/api-reference/task/submit)
* [Query Task Status](/en/api-reference/task/status)
* [Task System](/en/docs/task-system)