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

# OpenAI-Compatible Image Generation API: GPT Image 2 Guide

> Generate images from text with GPT Image 2 and BetterToken's OpenAI-compatible API: API Key, Base URL, parameters, Python, JavaScript, and errors.

`POST /v1/images/generations`

The text-to-image endpoint uses an `application/json` request body. Submit a prompt, keep the HTTP request open, and read the generated image from `data[0].b64_json` in the same response.

<Note>
  Use `https://www.bettertoken.ai/v1` as the `Base URL`. Pass your BetterToken API Key through `Authorization: Bearer YOUR_API_KEY`.
</Note>

<Tip>
  You can enter `Authorization` and the request body in the Playground on the right side of the page, then send the request directly to `https://www.bettertoken.ai/v1/images/generations`.
</Tip>

<Warning>
  Do not put API keys in frontend browser code, Git repositories, tickets, screenshots, or logs. For server-side proxy calls, store API keys only in server environment variables or a secret manager.
</Warning>

## Quick start with curl

Use `https://www.bettertoken.ai/v1` as the Base URL and send a request to `https://www.bettertoken.ai/v1/images/generations`:

```bash theme={null}
curl -X POST "https://www.bettertoken.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A product photo of a green ceramic mug on a studio table",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json",
    "output_format": "png"
  }'
```

## Recommended values

Send these fields explicitly in every request:

```json theme={null}
{
  "model": "gpt-image-2",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
```

| Parameter         | What to send             | Purpose                                                                                         |
| ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `model`           | `gpt-image-2`            | Selects the image model.                                                                        |
| `prompt`          | A text description       | Required image description. Include the subject, style, composition, and important constraints. |
| `size`            | For example, `1024x1024` | Selects the output size and aspect ratio.                                                       |
| `n`               | `1`                      | Image count for one request. Send separate requests for multiple images.                        |
| `response_format` | `b64_json`               | Returns image content as base64 in `data[0].b64_json`.                                          |
| `output_format`   | `png`                    | Lets you save the result as PNG.                                                                |

Generate multiple images by sending multiple independent requests. Do not rely on a single request with `n > 1`.

## Recommended sizes

| `size`      | Ratio  | Use case                                                    |
| ----------- | ------ | ----------------------------------------------------------- |
| `auto`      | Auto   | Automatic size selection                                    |
| `1024x1024` | `1:1`  | Square images, avatars, covers, assets                      |
| `1536x1024` | `3:2`  | Landscape posters, banners, scenes                          |
| `1024x1536` | `2:3`  | Portrait mobile covers and posters                          |
| `1536x1152` | `4:3`  | Standard landscape images, product images, content graphics |
| `1152x1536` | `3:4`  | Standard portrait images, mobile covers, vertical posters   |
| `2048x2048` | `1:1`  | High-resolution square images                               |
| `2048x1152` | `16:9` | High-resolution landscape images                            |
| `3840x2160` | `16:9` | 4K landscape images                                         |
| `2160x3840` | `9:16` | 4K portrait images                                          |

`size` represents the expected aspect ratio and size tier. The actual returned pixels may be mapped or adjusted by the server. Use the decoded image dimensions instead of forcibly cropping the output to the requested value.

## Save the image

A successful response follows the OpenAI-compatible image response shape:

```json theme={null}
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}
```

Read `data[0].b64_json` and save it as base64 image content. The response may include extra fields such as `revised_prompt`; allow these fields in your client.

Always set `output_format: "png"`. Then save the decoded image as `.png` without inspecting file headers.

```python theme={null}
import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8"))
b64_json = response["data"][0]["b64_json"]

if "," in b64_json and "base64" in b64_json.split(",", 1)[0]:
    b64_json = b64_json.split(",", 1)[1]

image_bytes = base64.b64decode(b64_json)
Path("output.png").write_bytes(image_bytes)
```

### JavaScript example (Node.js)

```js theme={null}
import { writeFile } from "node:fs/promises";

const response = await fetch("https://www.bettertoken.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "A green ceramic mug on a studio table",
    size: "1024x1024",
    n: 1,
    response_format: "b64_json",
    output_format: "png",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { data } = await response.json();
const b64Json = data[0].b64_json.replace(/^data:.*;base64,/, "");
await writeFile("output.png", Buffer.from(b64Json, "base64"));
```

<Warning>
  Do not rely on `output_format: "jpeg"` or `output_format: "webp"` to directly receive JPEG or WebP files. The current endpoint may still return PNG image content. If your product needs JPEG or WebP, receive PNG first and convert it in your own code.
</Warning>

## Response flow

This endpoint is synchronous. After sending `POST /images/generations`, keep the current HTTP request open until the server responds. When generation succeeds, the image content is returned in `data[0].b64_json`.

The endpoint does not return a `task_id`, and there is no separate status query or result download endpoint.

## Timeouts and retries

* Set HTTP client timeouts to several minutes.
* Retry transport errors, `408`, `409`, `425`, `429`, and `5xx`.
* Do not retry `400`, `401`, missing parameters, or malformed requests automatically.
* Use exponential backoff such as `3s`, `8s`, and `15s`.
* If duplicate images are unacceptable, record your own request ID before retrying.

## Error handling

Errors usually return JSON. When showing an error, read `error.message` first, then `message`, then the HTTP status text.

| HTTP status | Meaning                                                     | What to do                                                                     |
| ----------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `400`       | Malformed JSON, a missing parameter, or an unsupported size | Check the request body. Do not retry automatically.                            |
| `401`       | API Key is missing or invalid                               | Check the `Authorization: Bearer YOUR_API_KEY` header.                         |
| `402`       | Insufficient balance or quota                               | Add balance or use an available key.                                           |
| `429`       | Rate limit, concurrency limit, or busy upstream             | Wait and retry with exponential backoff.                                       |
| `5xx`       | Gateway or upstream failure                                 | Retry the request. If it still fails, record the request ID and error message. |

## Integration checklist

* The Base URL is `https://www.bettertoken.ai/v1`.
* The header contains `Authorization: Bearer YOUR_API_KEY`.
* The request uses `application/json` and `POST /images/generations`.
* `model` is `gpt-image-2`, `response_format` is `b64_json`, `output_format` is `png`, and `n` is `1`.
* `size` is one of the recommended values, such as `1024x1024`.
* Your HTTP client allows several minutes for generation.

## Related docs

* [Image to image](/en/api-reference/images-edits)
* [GPT Image 2 is live](/en/model-updates/gpt-image-2)


## OpenAPI

````yaml api-reference/openapi.json POST /v1/images/generations
openapi: 3.1.0
info:
  title: BetterToken GPT Image 2 API
  description: >-
    OpenAI-compatible image generation and image editing endpoints for
    BetterToken.
  version: 1.0.0
servers:
  - url: https://www.bettertoken.ai
security:
  - bearerAuth: []
paths:
  /v1/images/generations:
    post:
      tags:
        - GPT Image 2
      summary: 文生图（图片生成）
      description: >-
        使用 GPT Image 2 根据文本提示词生成图片。请求使用 application/json，成功响应中的图片内容位于
        data[0].b64_json。
      operationId: createImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToImageRequest'
            example:
              model: YOUR_MODEL_ID
              prompt: 一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感
              'n': 1
              size: 1024x1024
              response_format: b64_json
              output_format: png
      responses:
        '200':
          $ref: '#/components/responses/ImageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl 'https://www.bettertoken.ai/v1/images/generations' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              --data '{
                "model": "YOUR_MODEL_ID",
                "prompt": "一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感",
                "n": 1,
                "size": "1024x1024",
                "response_format": "b64_json",
                "output_format": "png"
              }'
components:
  schemas:
    TextToImageRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: 固定使用 YOUR_MODEL_ID。
          enum:
            - YOUR_MODEL_ID
          default: YOUR_MODEL_ID
          example: YOUR_MODEL_ID
        prompt:
          type: string
          description: 图片生成提示词。
          example: 一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感
        'n':
          type: integer
          description: 推荐固定为 1。多张图片建议发起多次独立请求。
          minimum: 1
          maximum: 1
          default: 1
          example: 1
        size:
          $ref: '#/components/schemas/ImageSize'
        response_format:
          type: string
          description: 推荐固定为 b64_json，便于稳定保存图片。
          enum:
            - b64_json
          default: b64_json
          example: b64_json
        output_format:
          type: string
          description: 推荐固定为 png。不要依赖 jpeg 或 webp 直接返回对应格式。
          enum:
            - png
          default: png
          example: png
      additionalProperties: false
    ImageSize:
      type: string
      description: >-
        图片尺寸和比例档位。auto 为自动；1024x1024 和 2048x2048 为 1:1；1536x1024 为 3:2；1024x1536
        为 2:3；1536x1152 为 4:3；1152x1536 为 3:4；2048x1152 和 3840x2160 为
        16:9；2160x3840 为 9:16。实际返回像素可能由服务端映射或调整，客户端应以解码后的真实图片尺寸为准。
      enum:
        - auto
        - 1024x1024
        - 1536x1024
        - 1024x1536
        - 1536x1152
        - 1152x1536
        - 2048x2048
        - 2048x1152
        - 3840x2160
        - 2160x3840
      default: 1024x1024
      example: 1024x1024
    ImageResponse:
      type: object
      description: >-
        OpenAI-compatible image response. Clients should read data[0].b64_json
        and allow additional fields such as revised_prompt.
      properties:
        created:
          type: integer
          example: 1710000000
        data:
          type: array
          items:
            type: object
            properties:
              b64_json:
                type: string
                description: Base64-encoded image content.
                example: iVBORw0KGgoAAAANSUhEUgAA...(truncated)
              revised_prompt:
                type: string
                description: Optional revised prompt.
            additionalProperties: true
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: invalid request
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: invalid_request
          additionalProperties: true
        message:
          type: string
          example: insufficient quota
      additionalProperties: true
  responses:
    ImageResponse:
      description: Image generation result.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ImageResponse'
          example:
            created: 1710000000
            data:
              - b64_json: iVBORw0KGgoAAAANSUhEUgAA...(truncated)
    BadRequest:
      description: 请求格式错误、缺少参数、JSON 或 multipart 解析失败、尺寸格式错误。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API Key 缺失或无效。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: 额度或余额不足。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 触发限速、并发限制或上游繁忙。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: 网关或上游服务异常。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: BetterToken API Key
      description: >-
        Use your BetterToken API Key as a bearer token. Do not expose API keys
        in frontend browser code, screenshots, logs, tickets, or Git
        repositories.

````