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

# GPT Image 2 API

> Developer guide for GPT-Image-2, covering the default-group standard route, gpt-image-2-vip parameter support, the Sora2Official mixed official API forwarding group, and the GPTImage2 Enterprise pure official-key group.

## Start With the Token Type and Group

For GPT Image 2, the route is determined by the **billing type and group selected when the token is created**, not only by the `model` field in the request body. The same `gpt-image-2` model name maps to different routes in the default group, the `Sora2Official` group, and the `GPTImage2 Enterprise` group.

<CardGroup cols={3}>
  <Card title="Per-call token: Default group" icon="rotate-cw">
    Default-group tokens use per-call billing. `gpt-image-2` and `gpt-image-2-vip` are both **\$0.03/call**; use `gpt-image-2-vip` when you need size and quality controls.
  </Card>

  <Card title="Usage-billed token: Sora2Official" icon="shield-check">
    `Sora2Official` tokens use usage-based billing. The request body still uses `model="gpt-image-2"`, and billing follows official input / output tokens.
  </Card>

  <Card title="Usage-billed token: GPTImage2 Enterprise" icon="badge-check">
    `GPTImage2 Enterprise` tokens use usage-based billing with pure official-key routing, billed at official input / output token pricing +20%.
  </Card>
</CardGroup>

<Tip>
  Check the token type first, then the model name. The default group is a per-call token; `Sora2Official` and `GPTImage2 Enterprise` are usage-billed tokens. Setting `model="gpt-image-2"` in the request body does not turn a per-call token into a usage-billed token.
</Tip>

<Info>
  July 9, 2026 update: default-group `gpt-image-2-vip` has restored `size` and `quality` support. In the latest verification, `1024x1024`, `2048x2048`, and `3840x2160` returned the requested dimensions, and `quality` supports `low`, `medium`, and `high`.
</Info>

<Warning>
  Do not put `Sora2Official` or `GPTImage2 Enterprise` in the request body's `model` field. They are token groups selected when the token is created; the request body still uses `model="gpt-image-2"`.
</Warning>

<Card title="Online Test" icon="external-link" href="https://yingtu.ai">
  You can test the output first at [yingtu.ai](https://yingtu.ai), then move the prompt into your API integration.
</Card>

## Route Matrix

| Token group            | Token type         | Model name        | Route                       | Billing                                    | `size`                             | `quality`                          | Available endpoints             |
| ---------------------- | ------------------ | ----------------- | --------------------------- | ------------------------------------------ | ---------------------------------- | ---------------------------------- | ------------------------------- |
| Default group          | Per-call token     | `gpt-image-2`     | Default standard route      | **\$0.03/call**                            | Not supported                      | Not supported                      | Images generation, Images edits |
| Default group          | Per-call token     | `gpt-image-2-vip` | VIP route                   | **\$0.03/call**                            | Supports common 1K / 2K / 4K sizes | Supports `low` / `medium` / `high` | Images generation, Images edits |
| `Sora2Official`        | Usage-billed token | `gpt-image-2`     | Mixed AZ + official-key API | Billed by official input / output tokens   | Supported                          | Supported                          | Images generation, Images edits |
| `GPTImage2 Enterprise` | Usage-billed token | `gpt-image-2`     | Pure official-key API       | Official input / output token pricing +20% | Supported                          | Supported                          | Images generation, Images edits |

## Which Route Should You Use?

| Need                                                                        | Use                                                                                                                   |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| You want **\$0.03/call** billing                                            | Create a default-group per-call token; use `model="gpt-image-2-vip"` when you need size / quality                     |
| You want usage-based official input / output token billing                  | Create a `Sora2Official` or `GPTImage2 Enterprise` usage-billed token; keep `model="gpt-image-2"` in the request body |
| Existing default-group `gpt-image-2-vip` integration                        | This is a per-call token route; keep sending `size` / `quality`                                                       |
| Existing official OpenAI GPT Image 2 code with full parameter compatibility | Create a `Sora2Official` or `GPTImage2 Enterprise` usage-billed token, then keep `model="gpt-image-2"`                |
| Billing does not match expectations                                         | Check the token group in the console first; do not rely only on the request body's `model` value                      |

## Base Configuration

All routes use the same OpenAI-compatible gateway URL:

```bash theme={null}
export LAOZHANG_API_KEY="sk-your-token"
export BASE_URL="https://api.laozhang.ai/v1"
```

<Info>
  Do not set the base URL to a model-specific path, and do not expect the request body's `model` field to change the billing type. The actual route is determined by the token group selected at token creation plus the `model` field.
</Info>

## Parameter Support

### Default-group gpt-image-2

Default-group `gpt-image-2` is the legacy ChatGPT web route. Use it when you want the simplest integration and do not need size control.

* `size`: not supported
* `quality`: not supported
* Price: **\$0.03/call**

### Default-group gpt-image-2-vip

Default-group `gpt-image-2-vip` has restored size and quality parameters. Use it when you want per-call billing and need 1K / 2K / 4K image-size control.

* Supports `size`, including common values such as `1024x1024`, `2048x2048`, and `3840x2160`
* Supports `quality`, including `low`, `medium`, and `high`
* Returns `data[0].b64_json` by default
* Use an official-forward group when you need pure official-key routing and stricter official parameter compatibility
* Price: **\$0.03/call**

<Tip>
  `quality` has a visible effect on generation time and output token usage. Use `low` / `medium` for cheaper previews or batch tests, then use `high` for final assets.
</Tip>

### Sora2Official-group gpt-image-2

`Sora2Official` `gpt-image-2` is the mixed AZ + official-key official API forwarding route. Billing uses official input / output tokens with the same pricing as the official OpenAI GPT Image 2 API.

### GPTImage2 Enterprise-group gpt-image-2

`GPTImage2 Enterprise` `gpt-image-2` is the pure official-key API route, suitable for production calls that need higher route stability and official API compatibility. Billing is official input / output token pricing +20% to cover tax and operating cost, not profit markup.

### Shared Parameters for Official-Compatible Groups

Setup:

1. Create a new **usage-billed token** in the console.
2. Select `Sora2Official` for the mixed official route, or `GPTImage2 Enterprise` when you want the pure official-key route.
3. Keep `model="gpt-image-2"` in the request body.
4. Keep the official request body and replace only the base URL and API key.

This route supports official parameters, including `size`, `quality`, and other parameters supported by the official API.

Common `size` values:

* `1024x1024`
* `1536x1024`
* `1024x1536`
* `2048x2048`
* `2048x1152`
* `3840x2160`
* `2160x3840`
* `auto`

Available `quality` values:

* `low`
* `medium`
* `high`
* `auto`

## Endpoint Support

This page documents only the Images API integration path: use `/v1/images/generations` for text-to-image and `/v1/images/edits` for image-to-image. In SDKs, these correspond to `images.generate` and `images.edit`.

| Need           | Endpoint                 | Notes                                                   |
| -------------- | ------------------------ | ------------------------------------------------------- |
| Text-to-image  | `/v1/images/generations` | Returns `data[0].b64_json` by default, or `data[0].url` |
| Image-to-image | `/v1/images/edits`       | Multipart local image upload                            |

The `Sora2Official` and `GPTImage2 Enterprise` official-compatible routes must use official-style Images API endpoints:

| Need           | Endpoint                 | Notes                                           |
| -------------- | ------------------------ | ----------------------------------------------- |
| Text-to-image  | `/v1/images/generations` | Matches the official Images generation endpoint |
| Image-to-image | `/v1/images/edits`       | Matches the official Images edit endpoint       |

<Info>
  For the default-group route, `gpt-image-2-vip`, and the `Sora2Official` / `GPTImage2 Enterprise` official-compatible routes, this guide keeps only Images generation and Images edits as the documented integration methods.
</Info>

## Text-to-Image Examples

### Default-group gpt-image-2 (per-call token)

Do not pass `size` or `quality`.

```bash theme={null}
curl "$BASE_URL/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Create a clean product render of a white ceramic mug on a gray desk, soft natural light, minimal background"
  }'
```

### Default-group gpt-image-2-vip (per-call token)

`gpt-image-2-vip` has restored `size` and `quality` support. When you need per-call billing and explicit image dimensions, pass these fields directly in the request body.

```bash theme={null}
curl "$BASE_URL/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -d '{
    "model": "gpt-image-2-vip",
    "prompt": "Create a clean product render of a white ceramic mug on a gray desk, soft natural light, minimal background",
    "size": "2048x2048",
    "quality": "high"
  }'
```

### Sora2Official / GPTImage2 Enterprise-group gpt-image-2 (usage-billed token)

Use the official-style Images generation endpoint. You can pass `size` and `quality`.

```bash theme={null}
curl "$BASE_URL/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Create a clean product render of a white ceramic mug on a gray desk, soft natural light, minimal background",
    "size": "1536x1024",
    "quality": "high"
  }'
```

## Image-to-Image Examples

### Default-group Images Edits

```bash theme={null}
curl "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the provided image as the source. Keep the subject, composition, and text. Only change the sticker to red and add a very thin gold rim to the mug." \
  -F "image=@source.png"
```

### Default-group gpt-image-2-vip Images Edits

```bash theme={null}
curl "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2-vip" \
  -F "prompt=Use the provided image as the source. Keep the subject, composition, and text. Only change the sticker to blue." \
  -F "image=@source.png"
```

### Sora2Official / GPTImage2 Enterprise-group Images Edits

Official-compatible image editing must use `/v1/images/edits`, with official-style parameters.

```bash theme={null}
curl "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the provided image as the source. Keep the subject, composition, and text. Only change the sticker to green." \
  -F "image=@source.png" \
  -F "size=1024x1024" \
  -F "quality=high"
```

## Parse Responses

### Save Images API b64\_json

```python theme={null}
import base64

value = response["data"][0]["b64_json"]
if value.startswith("data:"):
    value = value.split(",", 1)[1]

value += "=" * ((4 - len(value) % 4) % 4)

with open("output.png", "wb") as f:
    f.write(base64.b64decode(value))
```

### Read an Images API URL

```python theme={null}
image_url = response["data"][0]["url"]
```

## FAQ

<AccordionGroup>
  <Accordion title="Why does gpt-image-2 mean different things on this page?">
    The token group decides the route. Default-group `gpt-image-2` is the per-call standard route. `Sora2Official` `gpt-image-2` is the usage-billed mixed AZ + official-key API route. `GPTImage2 Enterprise` `gpt-image-2` is the usage-billed pure official-key API route.
  </Accordion>

  <Accordion title="How do I tell per-call tokens from usage-billed tokens?">
    Check the group selected when the token was created in the console. The default group is a per-call token route: `gpt-image-2` / `gpt-image-2-vip` are billed at **\$0.03/call**. `Sora2Official` and `GPTImage2 Enterprise` are usage-billed token groups: the request body still uses `model="gpt-image-2"`, but billing follows official input / output tokens.
  </Accordion>

  <Accordion title="Can default-group gpt-image-2 accept size?">
    Default-group `gpt-image-2` is not the recommended size-control route. Use `gpt-image-2-vip` when you want default-group per-call billing with size control, or use `gpt-image-2` under `Sora2Official` / `GPTImage2 Enterprise` when you need official-key routing.
  </Accordion>

  <Accordion title="Can gpt-image-2-vip accept quality?">
    Yes. `gpt-image-2-vip` currently supports `low`, `medium`, and `high` quality tiers. Higher quality usually increases wait time and output token usage.
  </Accordion>

  <Accordion title="Can gpt-image-2-vip still use 4K sizes?">
    Yes. The current route can use 4K landscape sizes such as `3840x2160`; for portrait 4K, test `2160x3840` against your production prompt.
  </Accordion>

  <Accordion title="Which endpoints does this page support?">
    This page keeps only the Images API integration path: use `/v1/images/generations` for generation and `/v1/images/edits` for edits.
  </Accordion>

  <Accordion title="How do I migrate official OpenAI code?">
    First create a usage-billed token under the `Sora2Official` or `GPTImage2 Enterprise` group. Keep the official request body and `model="gpt-image-2"`, replace the base URL with `https://api.laozhang.ai/v1`, and replace the API key with your LaoZhang API token. Choose `GPTImage2 Enterprise` when you need the pure official-key route.
  </Accordion>

  <Accordion title="Why does b64_json decoding fail?">
    The value may include a `data:image/png;base64,` prefix, or it may need padding at the end. Remove the prefix first, then pad with `=` before decoding.
  </Accordion>
</AccordionGroup>