> ## 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-kompatible Bildgenerierungs-API: GPT Image 2 Anleitung

> Erstelle Bilder aus Text mit GPT Image 2 und BetterTokens OpenAI-kompatibler API: API Key, Base URL, Parameter, Python, JavaScript und Fehlerbehebung.

`POST /v1/images/generations`

Der Text-zu-Bild-Endpunkt verwendet einen Request-Body im Format `application/json`. Sende einen Prompt, halte den HTTP-Request geöffnet und lies das generierte Bild aus `data[0].b64_json` in derselben Antwort.

<Note>
  Verwende `https://www.bettertoken.ai/v1` als `Base URL`. Übermittle deinen BetterToken API Key über `Authorization: Bearer YOUR_API_KEY`.
</Note>

<Tip>
  Du kannst `Authorization` und den Request-Body im Playground auf der rechten Seite eingeben und den Request dann direkt an `https://www.bettertoken.ai/v1/images/generations` senden.
</Tip>

<Warning>
  Lege API Keys nicht in Browser-Frontend-Code, Git-Repositories, Tickets, Screenshots oder Logs ab. Speichere API Keys für serverseitige Proxy-Aufrufe nur in Server-Umgebungsvariablen oder einem Secret Manager.
</Warning>

## Schnellstart mit curl

Verwende `https://www.bettertoken.ai/v1` als Base URL und sende einen Request an `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"
  }'
```

## Empfohlene Werte

Sende diese Felder in jedem Request explizit:

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

| Parameter         | Zu sendender Wert        | Zweck                                                                                        |
| ----------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `model`           | `gpt-image-2`            | Wählt das Bildmodell aus.                                                                    |
| `prompt`          | Eine Textbeschreibung    | Erforderliche Bildbeschreibung. Nenne Motiv, Stil, Komposition und wichtige Einschränkungen. |
| `size`            | Zum Beispiel `1024x1024` | Wählt Ausgabegröße und Seitenverhältnis aus.                                                 |
| `n`               | `1`                      | Bildanzahl pro Request. Sende für mehrere Bilder separate Requests.                          |
| `response_format` | `b64_json`               | Gibt Bildinhalt als Base64 in `data[0].b64_json` zurück.                                     |
| `output_format`   | `png`                    | Ermöglicht das Speichern des Ergebnisses als PNG.                                            |

Erstelle mehrere Bilder, indem du mehrere unabhängige Requests sendest. Verlasse dich nicht auf einen einzelnen Request mit `n > 1`.

## Empfohlene Größen

| `size`      | Verhältnis | Anwendungsfall                                               |
| ----------- | ---------- | ------------------------------------------------------------ |
| `auto`      | Auto       | Automatische Größenauswahl                                   |
| `1024x1024` | `1:1`      | Quadratische Bilder, Avatare, Cover, Assets                  |
| `1536x1024` | `3:2`      | Querformat-Poster, Banner, Szenen                            |
| `1024x1536` | `2:3`      | Mobile Cover und Poster im Hochformat                        |
| `1536x1152` | `4:3`      | Standardbilder im Querformat, Produktbilder, Inhaltsgrafiken |
| `1152x1536` | `3:4`      | Standardbilder im Hochformat, mobile Cover, vertikale Poster |
| `2048x2048` | `1:1`      | Quadratische Bilder mit hoher Auflösung                      |
| `2048x1152` | `16:9`     | Querformatbilder mit hoher Auflösung                         |
| `3840x2160` | `16:9`     | 4K-Querformatbilder                                          |
| `2160x3840` | `9:16`     | 4K-Hochformatbilder                                          |

`size` steht für das erwartete Seitenverhältnis und die Größenstufe. Die tatsächlich zurückgegebenen Pixel können vom Server zugeordnet oder angepasst werden. Verwende die dekodierten Bildabmessungen, statt die Ausgabe zwangsweise auf den angeforderten Wert zuzuschneiden.

## Bild speichern

Eine erfolgreiche Antwort folgt dem OpenAI-kompatiblen Bildantwortformat:

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

Lies `data[0].b64_json` und speichere es als Base64-Bildinhalt. Die Antwort kann zusätzliche Felder wie `revised_prompt` enthalten; erlaube diese Felder in deinem Client.

Setze immer `output_format: "png"`. Speichere das dekodierte Bild dann als `.png`, ohne Dateikopfzeilen zu prüfen.

```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>
  Verlasse dich nicht darauf, mit `output_format: "jpeg"` oder `output_format: "webp"` direkt JPEG- oder WebP-Dateien zu erhalten. Der aktuelle Endpunkt kann weiterhin PNG-Bildinhalt zurückgeben. Wenn dein Produkt JPEG oder WebP benötigt, empfange zuerst PNG und konvertiere es in deinem eigenen Code.
</Warning>

## Antwortablauf

Dieser Endpunkt ist synchron. Halte nach dem Senden von `POST /images/generations` den aktuellen HTTP-Request offen, bis der Server antwortet. Bei erfolgreicher Generierung wird der Bildinhalt in `data[0].b64_json` zurückgegeben.

Der Endpunkt gibt keine `task_id` zurück; es gibt keinen separaten Endpunkt für Statusabfragen oder das Herunterladen von Ergebnissen.

## Timeouts und Wiederholungen

* Setze HTTP-Client-Timeouts auf mehrere Minuten.
* Wiederhole Transportfehler, `408`, `409`, `425`, `429` und `5xx`.
* Wiederhole `400`, `401`, fehlende Parameter oder fehlerhafte Requests nicht automatisch.
* Verwende exponentielles Backoff wie `3s`, `8s` und `15s`.
* Wenn doppelte Bilder nicht akzeptabel sind, zeichne vor der Wiederholung eine eigene Request-ID auf.

## Fehlerbehandlung

Fehler geben gewöhnlich JSON zurück. Lies beim Anzeigen eines Fehlers zuerst `error.message`, dann `message` und anschließend den HTTP-Status-Text.

| HTTP-Status | Bedeutung                                                            | Vorgehen                                                                                         |
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `400`       | Fehlerhaftes JSON, fehlender Parameter oder nicht unterstützte Größe | Prüfe den Request-Body. Nicht automatisch wiederholen.                                           |
| `401`       | API Key fehlt oder ist ungültig                                      | Prüfe den Header `Authorization: Bearer YOUR_API_KEY`.                                           |
| `402`       | Unzureichendes Guthaben oder Kontingent                              | Lade Guthaben auf oder verwende einen verfügbaren Key.                                           |
| `429`       | Ratenlimit, Parallelitätslimit oder ausgelasteter Upstream           | Warte und wiederhole mit exponentiellem Backoff.                                                 |
| `5xx`       | Gateway- oder Upstream-Fehler                                        | Wiederhole den Request. Wenn er weiterhin fehlschlägt, zeichne Request-ID und Fehlermeldung auf. |

## Integrations-Checkliste

* Die Base URL lautet `https://www.bettertoken.ai/v1`.
* Der Header enthält `Authorization: Bearer YOUR_API_KEY`.
* Der Request verwendet `application/json` und `POST /images/generations`.
* `model` ist `gpt-image-2`, `response_format` ist `b64_json`, `output_format` ist `png` und `n` ist `1`.
* `size` ist einer der empfohlenen Werte, etwa `1024x1024`.
* Dein HTTP-Client erlaubt mehrere Minuten für die Generierung.

## Verwandte Dokumentation

* [Bild zu Bild](/de/api-reference/images-edits)
* [GPT Image 2 ist verfügbar](/de/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.

````