> ## 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.

# API de génération d’images OpenAI compatible : guide GPT Image 2

> Générez des images à partir de texte avec GPT Image 2 et l’API OpenAI compatible de BetterToken : API Key, Base URL, paramètres, Python, JavaScript et erreurs.

`POST /v1/images/generations`

L’endpoint texte à image utilise un corps de Request `application/json`. Envoyez un prompt, gardez la Request HTTP ouverte et lisez l’image générée depuis `data[0].b64_json` dans la même réponse.

<Note>
  Utilisez `https://www.bettertoken.ai/v1` comme `Base URL`. Passez votre BetterToken API Key via `Authorization: Bearer YOUR_API_KEY`.
</Note>

<Tip>
  Vous pouvez saisir `Authorization` et le corps de Request dans le Playground à droite de la page, puis envoyer la Request directement à `https://www.bettertoken.ai/v1/images/generations`.
</Tip>

<Warning>
  Ne placez pas d’API Key dans le code navigateur frontend, les dépôts Git, tickets, captures d’écran ou journaux. Pour les appels de proxy côté serveur, stockez les API Key uniquement dans les variables d’environnement serveur ou un gestionnaire de secrets.
</Warning>

## Démarrage rapide avec curl

Utilisez `https://www.bettertoken.ai/v1` comme Base URL et envoyez une Request à `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"
  }'
```

## Valeurs recommandées

Envoyez explicitement ces champs dans chaque Request :

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

| Paramètre         | Valeur à envoyer          | Objectif                                                                                                |
| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `model`           | `gpt-image-2`             | Sélectionne le modèle d’image.                                                                          |
| `prompt`          | Une description textuelle | Description d’image requise. Incluez le sujet, le style, la composition et les contraintes importantes. |
| `size`            | Par exemple, `1024x1024`  | Sélectionne la taille de sortie et le ratio.                                                            |
| `n`               | `1`                       | Nombre d’images pour une Request. Envoyez des Request distinctes pour plusieurs images.                 |
| `response_format` | `b64_json`                | Renvoie le contenu d’image en base64 dans `data[0].b64_json`.                                           |
| `output_format`   | `png`                     | Permet d’enregistrer le résultat en PNG.                                                                |

Générez plusieurs images en envoyant plusieurs Request indépendantes. Ne vous appuyez pas sur une seule Request avec `n > 1`.

## Tailles recommandées

| `size`      | Ratio  | Cas d’utilisation                                                    |
| ----------- | ------ | -------------------------------------------------------------------- |
| `auto`      | Auto   | Sélection automatique de la taille                                   |
| `1024x1024` | `1:1`  | Images carrées, avatars, couvertures, ressources                     |
| `1536x1024` | `3:2`  | Affiches, bannières et scènes au format paysage                      |
| `1024x1536` | `2:3`  | Couvertures et affiches mobiles au format portrait                   |
| `1536x1152` | `4:3`  | Images paysage standard, images de produit, illustrations de contenu |
| `1152x1536` | `3:4`  | Images portrait standard, couvertures mobiles, affiches verticales   |
| `2048x2048` | `1:1`  | Images carrées haute résolution                                      |
| `2048x1152` | `16:9` | Images paysage haute résolution                                      |
| `3840x2160` | `16:9` | Images paysage 4K                                                    |
| `2160x3840` | `9:16` | Images portrait 4K                                                   |

`size` représente le ratio attendu et le niveau de taille. Les pixels réellement renvoyés peuvent être mappés ou ajustés par le serveur. Utilisez les dimensions de l’image décodée plutôt que de recadrer de force la sortie à la valeur demandée.

## Enregistrer l’image

Une réponse réussie suit la structure de réponse d’image OpenAI compatible :

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

Lisez `data[0].b64_json` et enregistrez-le comme contenu d’image base64. La réponse peut inclure des champs supplémentaires tels que `revised_prompt` ; autorisez ces champs dans votre client.

Définissez toujours `output_format: "png"`. Enregistrez ensuite l’image décodée sous `.png` sans inspecter les en-têtes de fichier.

```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)
```

### Exemple JavaScript (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>
  Ne vous appuyez pas sur `output_format: "jpeg"` ou `output_format: "webp"` pour recevoir directement des fichiers JPEG ou WebP. L’endpoint actuel peut toujours renvoyer du contenu image PNG. Si votre produit nécessite du JPEG ou du WebP, recevez d’abord du PNG et convertissez-le dans votre propre code.
</Warning>

## Flux de réponse

Cet endpoint est synchrone. Après l’envoi de `POST /images/generations`, gardez la Request HTTP actuelle ouverte jusqu’à la réponse du serveur. Lorsque la génération réussit, le contenu de l’image est renvoyé dans `data[0].b64_json`.

L’endpoint ne renvoie pas de `task_id`, et il n’existe pas d’endpoint distinct de requête de statut ou de téléchargement de résultat.

## Délais d’attente et tentatives

* Réglez les délais d’attente du client HTTP sur plusieurs minutes.
* Réessayez les erreurs de transport, `408`, `409`, `425`, `429` et `5xx`.
* Ne réessayez pas automatiquement `400`, `401`, les paramètres manquants ou les Request malformées.
* Utilisez un backoff exponentiel comme `3s`, `8s` et `15s`.
* Si les images dupliquées sont inacceptables, enregistrez votre propre ID de Request avant de réessayer.

## Gestion des erreurs

Les erreurs renvoient généralement du JSON. Lors de l’affichage d’une erreur, lisez d’abord `error.message`, puis `message`, puis le texte de statut HTTP.

| Statut HTTP | Signification                                                   | Action à effectuer                                                                                 |
| ----------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `400`       | JSON malformé, paramètre manquant ou taille non prise en charge | Vérifiez le corps de Request. Ne réessayez pas automatiquement.                                    |
| `401`       | API Key manquante ou non valide                                 | Vérifiez l’en-tête `Authorization: Bearer YOUR_API_KEY`.                                           |
| `402`       | Solde ou quota insuffisant                                      | Ajoutez du solde ou utilisez une Key disponible.                                                   |
| `429`       | Limite de débit, de concurrence ou amont occupé                 | Attendez et réessayez avec un backoff exponentiel.                                                 |
| `5xx`       | Échec de passerelle ou amont                                    | Réessayez la Request. Si elle échoue toujours, enregistrez l’ID de Request et le message d’erreur. |

## Checklist d’intégration

* La Base URL est `https://www.bettertoken.ai/v1`.
* L’en-tête contient `Authorization: Bearer YOUR_API_KEY`.
* La Request utilise `application/json` et `POST /images/generations`.
* `model` est `gpt-image-2`, `response_format` est `b64_json`, `output_format` est `png` et `n` est `1`.
* `size` est l’une des valeurs recommandées, par exemple `1024x1024`.
* Votre client HTTP autorise plusieurs minutes pour la génération.

## Documents associés

* [Image à image](/fr/api-reference/images-edits)
* [GPT Image 2 est disponible](/fr/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.

````