> ## 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 generación de imágenes compatible con OpenAI: guía de GPT Image 2

> Genera imágenes a partir de texto con GPT Image 2 y la API de BetterToken compatible con OpenAI: API Key, Base URL, parámetros, Python, JavaScript y gestión de errores.

`POST /v1/images/generations`

El endpoint de texto a imagen usa un cuerpo de solicitud `application/json`. Envía un prompt, mantén abierta la solicitud HTTP y lee la imagen generada desde `data[0].b64_json` en la misma respuesta.

<Note>
  Usa `https://www.bettertoken.ai/v1` como `Base URL`. Envía tu BetterToken API Key mediante `Authorization: Bearer YOUR_API_KEY`.
</Note>

<Tip>
  Puedes introducir `Authorization` y el cuerpo de la solicitud en el Playground de la derecha. Después, envía la solicitud directamente a `https://www.bettertoken.ai/v1/images/generations`.
</Tip>

<Warning>
  No incluyas API Keys en código frontend del navegador, repositorios Git, tickets, capturas de pantalla ni registros. En llamadas mediante un proxy del servidor, guarda las API Keys únicamente en variables de entorno del servidor o en un gestor de secretos.
</Warning>

## Inicio rápido con curl

Usa `https://www.bettertoken.ai/v1` como Base URL y envía una solicitud a `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

Envía estos campos de forma explícita en cada solicitud:

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

| Parámetro         | Valor                    | Función                                                                                                             |
| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `model`           | `gpt-image-2`            | Selecciona el modelo de imagen.                                                                                     |
| `prompt`          | Una descripción de texto | Descripción obligatoria de la imagen. Incluye el sujeto, el estilo, la composición y las restricciones importantes. |
| `size`            | Por ejemplo, `1024x1024` | Selecciona el tamaño y la proporción de la salida.                                                                  |
| `n`               | `1`                      | Número de imágenes de una solicitud. Envía solicitudes separadas para generar varias imágenes.                      |
| `response_format` | `b64_json`               | Devuelve el contenido de la imagen como base64 en `data[0].b64_json`.                                               |
| `output_format`   | `png`                    | Permite guardar el resultado como PNG.                                                                              |

Para generar varias imágenes, envía varias solicitudes independientes. No dependas de una sola solicitud con `n > 1`.

## Tamaños recomendados

| `size`      | Proporción | Uso                                                                  |
| ----------- | ---------- | -------------------------------------------------------------------- |
| `auto`      | Automática | Selección automática del tamaño                                      |
| `1024x1024` | `1:1`      | Imágenes cuadradas, avatares, portadas y recursos                    |
| `1536x1024` | `3:2`      | Pósteres horizontales, banners y escenas                             |
| `1024x1536` | `2:3`      | Portadas móviles y pósteres verticales                               |
| `1536x1152` | `4:3`      | Imágenes horizontales estándar, productos y gráficos de contenido    |
| `1152x1536` | `3:4`      | Imágenes verticales estándar, portadas móviles y pósteres verticales |
| `2048x2048` | `1:1`      | Imágenes cuadradas de alta resolución                                |
| `2048x1152` | `16:9`     | Imágenes horizontales de alta resolución                             |
| `3840x2160` | `16:9`     | Imágenes horizontales 4K                                             |
| `2160x3840` | `9:16`     | Imágenes verticales 4K                                               |

`size` representa la proporción y el nivel de tamaño esperados. El servidor puede asignar o ajustar los píxeles devueltos. Usa las dimensiones de la imagen decodificada en lugar de recortar la salida por la fuerza al valor solicitado.

## Guarda la imagen

Una respuesta correcta sigue la estructura de imagen compatible con OpenAI:

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

Lee `data[0].b64_json` y guárdalo como contenido de imagen en base64. La respuesta puede incluir campos adicionales como `revised_prompt`; permite esos campos en tu cliente.

Define siempre `output_format: "png"`. Después, guarda la imagen decodificada como `.png` sin inspeccionar las cabeceras del archivo.

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

### Ejemplo con 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>
  No confíes en `output_format: "jpeg"` ni en `output_format: "webp"` para recibir directamente archivos JPEG o WebP. El endpoint actual puede seguir devolviendo contenido de imagen PNG. Si tu producto necesita JPEG o WebP, recibe primero el PNG y conviértelo en tu propio código.
</Warning>

## Flujo de respuesta

Este endpoint es síncrono. Después de enviar `POST /images/generations`, mantén abierta la solicitud HTTP hasta que responda el servidor. Cuando la generación se completa, el contenido de la imagen se devuelve en `data[0].b64_json`.

El endpoint no devuelve un `task_id`, y no existe un endpoint separado para consultar el estado o descargar el resultado.

## Tiempos de espera y reintentos

* Configura tiempos de espera de varios minutos en el cliente HTTP.
* Reintenta los errores de transporte, `408`, `409`, `425`, `429` y `5xx`.
* No reintentes automáticamente `400`, `401`, parámetros ausentes ni solicitudes mal formadas.
* Usa espera exponencial, por ejemplo, `3s`, `8s` y `15s`.
* Si no puedes aceptar imágenes duplicadas, registra tu propio ID de solicitud antes de reintentar.

## Gestión de errores

Los errores suelen devolver JSON. Al mostrar un error, lee primero `error.message`, después `message` y, por último, el texto del estado HTTP.

| Estado HTTP | Significado                                                              | Qué hacer                                                                                         |
| ----------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `400`       | JSON mal formado, parámetro ausente o tamaño no admitido                 | Comprueba el cuerpo de la solicitud. No reintentes automáticamente.                               |
| `401`       | Falta la API Key o no es válida                                          | Comprueba la cabecera `Authorization: Bearer YOUR_API_KEY`.                                       |
| `402`       | Saldo o cuota insuficientes                                              | Añade saldo o usa una Key disponible.                                                             |
| `429`       | Límite de frecuencia, límite de concurrencia o servicio original ocupado | Espera y reintenta con espera exponencial.                                                        |
| `5xx`       | Fallo del gateway o del servicio original                                | Reintenta la solicitud. Si vuelve a fallar, registra el ID de la solicitud y el mensaje de error. |

## Lista de integración

* La Base URL es `https://www.bettertoken.ai/v1`.
* La cabecera contiene `Authorization: Bearer YOUR_API_KEY`.
* La solicitud usa `application/json` y `POST /images/generations`.
* `model` es `gpt-image-2`, `response_format` es `b64_json`, `output_format` es `png` y `n` es `1`.
* `size` es uno de los valores recomendados, como `1024x1024`.
* Tu cliente HTTP permite varios minutos para la generación.

## Documentación relacionada

* [De imagen a imagen](/es/api-reference/images-edits)
* [GPT Image 2 ya está disponible](/es/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.

````