> ## 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 geração de imagens compatível com OpenAI: guia do GPT Image 2

> Gere imagens a partir de texto com GPT Image 2 e a API compatível com OpenAI da BetterToken: API Key, Base URL, parâmetros, Python, JavaScript e erros.

`POST /v1/images/generations`

O endpoint de texto para imagem usa um corpo de solicitação `application/json`. Envie um prompt, mantenha a solicitação HTTP aberta e leia a imagem gerada em `data[0].b64_json` na mesma resposta.

<Note>
  Use `https://www.bettertoken.ai/v1` como `Base URL`. Passe sua BetterToken API Key por `Authorization: Bearer YOUR_API_KEY`.
</Note>

<Tip>
  Você pode informar `Authorization` e o corpo da solicitação no Playground à direita da página e enviar a solicitação diretamente para `https://www.bettertoken.ai/v1/images/generations`.
</Tip>

<Warning>
  Não coloque API Keys no código de frontend do navegador, em repositórios Git, tickets, capturas de tela ou logs. Para chamadas por proxy no servidor, armazene API Keys somente em variáveis de ambiente do servidor ou em um gerenciador de segredos.
</Warning>

## Início rápido com curl

Use `https://www.bettertoken.ai/v1` como Base URL e envie uma solicitação para `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"
  }'
```

## Valores recomendados

Envie estes campos explicitamente em cada solicitação:

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

| Parâmetro         | O que enviar             | Finalidade                                                                                      |
| ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `model`           | `gpt-image-2`            | Seleciona o modelo de imagem.                                                                   |
| `prompt`          | Uma descrição de texto   | Descrição obrigatória da imagem. Inclua o assunto, estilo, composição e restrições importantes. |
| `size`            | Por exemplo, `1024x1024` | Seleciona o tamanho de saída e a proporção.                                                     |
| `n`               | `1`                      | Quantidade de imagens por solicitação. Envie solicitações separadas para várias imagens.        |
| `response_format` | `b64_json`               | Retorna o conteúdo da imagem em base64 em `data[0].b64_json`.                                   |
| `output_format`   | `png`                    | Permite salvar o resultado como PNG.                                                            |

Gere várias imagens enviando várias solicitações independentes. Não dependa de uma única solicitação com `n > 1`.

## Tamanhos recomendados

| `size`      | Proporção  | Caso de uso                                                           |
| ----------- | ---------- | --------------------------------------------------------------------- |
| `auto`      | Automática | Seleção automática de tamanho                                         |
| `1024x1024` | `1:1`      | Imagens quadradas, avatares, capas e recursos                         |
| `1536x1024` | `3:2`      | Pôsteres, banners e cenas horizontais                                 |
| `1024x1536` | `2:3`      | Capas e pôsteres verticais para dispositivos móveis                   |
| `1536x1152` | `4:3`      | Imagens horizontais padrão, imagens de produto e gráficos de conteúdo |
| `1152x1536` | `3:4`      | Imagens verticais padrão, capas móveis e pôsteres verticais           |
| `2048x2048` | `1:1`      | Imagens quadradas em alta resolução                                   |
| `2048x1152` | `16:9`     | Imagens horizontais em alta resolução                                 |
| `3840x2160` | `16:9`     | Imagens horizontais 4K                                                |
| `2160x3840` | `9:16`     | Imagens verticais 4K                                                  |

`size` representa a proporção e a faixa de tamanho esperadas. Os pixels retornados podem ser mapeados ou ajustados pelo servidor. Use as dimensões da imagem decodificada em vez de recortar à força a saída para o valor solicitado.

## Salve a imagem

Uma resposta bem-sucedida segue o formato de resposta de imagem compatível com OpenAI:

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

Leia `data[0].b64_json` e salve-o como conteúdo de imagem base64. A resposta pode incluir campos extras, como `revised_prompt`; permita esses campos no cliente.

Defina sempre `output_format: "png"`. Depois salve a imagem decodificada como `.png`, sem inspecionar cabeçalhos de arquivo.

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

### Exemplo 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>
  Não dependa de `output_format: "jpeg"` ou `output_format: "webp"` para receber diretamente arquivos JPEG ou WebP. O endpoint atual ainda pode retornar conteúdo de imagem PNG. Se seu produto precisar de JPEG ou WebP, receba PNG primeiro e converta-o no seu código.
</Warning>

## Fluxo de resposta

Este endpoint é síncrono. Depois de enviar `POST /images/generations`, mantenha a solicitação HTTP atual aberta até o servidor responder. Quando a geração é bem-sucedida, o conteúdo da imagem é retornado em `data[0].b64_json`.

O endpoint não retorna `task_id`, e não há endpoint separado para consulta de status ou download do resultado.

## Timeouts e novas tentativas

* Defina timeouts do cliente HTTP para vários minutos.
* Tente novamente erros de transporte, `408`, `409`, `425`, `429` e `5xx`.
* Não tente novamente automaticamente `400`, `401`, parâmetros ausentes ou solicitações malformadas.
* Use backoff exponencial, como `3s`, `8s` e `15s`.
* Se imagens duplicadas forem inaceitáveis, registre seu próprio ID de solicitação antes de tentar novamente.

## Tratamento de erros

Os erros geralmente retornam JSON. Ao mostrar um erro, leia primeiro `error.message`, depois `message` e, por fim, o texto de status HTTP.

| Status HTTP | Significado                                                  | O que fazer                                                                                        |
| ----------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `400`       | JSON malformado, parâmetro ausente ou tamanho não compatível | Verifique o corpo da solicitação. Não tente novamente automaticamente.                             |
| `401`       | A API Key está ausente ou é inválida                         | Verifique o cabeçalho `Authorization: Bearer YOUR_API_KEY`.                                        |
| `402`       | Saldo ou cota insuficiente                                   | Adicione saldo ou use uma chave disponível.                                                        |
| `429`       | Limite de taxa, de concorrência ou upstream ocupado          | Aguarde e tente novamente com backoff exponencial.                                                 |
| `5xx`       | Falha de gateway ou upstream                                 | Tente a solicitação novamente. Se ainda falhar, registre o ID da solicitação e a mensagem de erro. |

## Checklist de integração

* A Base URL é `https://www.bettertoken.ai/v1`.
* O cabeçalho contém `Authorization: Bearer YOUR_API_KEY`.
* A solicitação usa `application/json` e `POST /images/generations`.
* `model` é `gpt-image-2`, `response_format` é `b64_json`, `output_format` é `png` e `n` é `1`.
* `size` é um dos valores recomendados, como `1024x1024`.
* Seu cliente HTTP permite vários minutos para a geração.

## Documentação relacionada

* [Imagem para imagem](/pt-br/api-reference/images-edits)
* [GPT Image 2 está disponível](/pt-br/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.

````