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

# Grok Imagine 2.0 Ext generación de imágenes

>  - Texto a imagen asíncrono; consulte con task_id
- 1–12 imágenes por solicitud; cobro por imagen entregada con éxito ($0.08 cada una)
- Salida solo en URL; sin imagen a imagen / streaming
- Las URL de imagen expiran en 72 horas 

<Info>
  **Texto a imagen · tareas asíncronas.** Envíe `POST /v1/images/generations` y, a continuación, consulte [Obtener estado de la tarea](/es/api-reference/tasks/status).\
  El nombre del modelo es fijo: `grok-imagine-2.0-ext`. **No admitido**: imágenes de referencia, `stream` ni valores de `response_format` distintos de `url`.
</Info>

<Warning>
  No ponga claves de API en bundles del navegador (`VITE_*` / `NEXT_PUBLIC_*`, LocalStorage, etc.). Prefiera llamar a su propio BFF desde el navegador; mantenga la clave de APIMart en el servidor.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
    --header 'X-APIMart-Response-Version: 2026-07-27' \
    --data '{
      "model": "grok-imagine-2.0-ext",
      "prompt": "A red apple on a white ceramic plate, clean studio product photo",
      "n": 1,
      "size": "1:1",
      "resolution": "quality",
      "response_format": "url"
    }'
  ```

  ```python Python theme={null}
  import requests
  import uuid

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "grok-imagine-2.0-ext",
      "prompt": "A red apple on a white ceramic plate, clean studio product photo",
      "n": 1,
      "size": "1:1",
      "resolution": "quality",
      "response_format": "url",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
      "Accept": "application/json",
      "Idempotency-Key": str(uuid.uuid4()),
      "X-APIMart-Response-Version": "2026-07-27",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.status_code, response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "grok-imagine-2.0-ext",
    prompt: "A red apple on a white ceramic plate, clean studio product photo",
    n: 1,
    size: "1:1",
    resolution: "quality",
    response_format: "url",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
    Accept: "application/json",
    "Idempotency-Key": crypto.randomUUID(),
    "X-APIMart-Response-Version": "2026-07-27",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then(async (response) => {
      console.log(response.status, await response.json());
    })
    .catch((error) => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "code": 202,
    "request_id": "2026081111342261665927mpb4IPDb",
    "data": {
      "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
      "object": "generation.task",
      "type": "image",
      "status": "pending",
      "progress": 0,
      "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "request_id": "20260811...",
    "error": {
      "message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
      "type": "invalid_response_format",
      "param": "",
      "code": "invalid_response_format"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed. Please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance. Please top up and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests. Please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Capacidades y límites

| Dimensión    | Contrato                                                                          |
| ------------ | --------------------------------------------------------------------------------- |
| Modelo       | Fijo `grok-imagine-2.0-ext`                                                       |
| Capacidad    | **Solo texto a imagen**                                                           |
| Modo         | Tarea asíncrona                                                                   |
| Cantidad `n` | `1`–`12`, valor predeterminado `1`                                                |
| `size`       | 7 relaciones de aspecto + 5 alias de píxeles (abajo)                              |
| Salida       | Solo `response_format=url` (también el valor predeterminado)                      |
| Calidad      | Campo público `resolution`; valor verificado `quality`                            |
| No admitido  | Imagen a imagen, `stream=true`, `quality` público, `style`, `b64_json` / `base64` |
| Facturación  | Precio unitario fijo; se cobra por imágenes **entregadas con éxito**              |

## Autenticación y headers recomendados

<ParamField header="Authorization" type="string" required>
  Token Bearer. Obtenga una clave en la [página de API Key](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

| Header                       | Notas                                                                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`               | `application/json` (envío)                                                                                                                    |
| `Accept`                     | `application/json`                                                                                                                            |
| `Idempotency-Key`            | Muy recomendado. Nuevo UUID por generación confirmada por el usuario; los reintentos de red **deben reutilizar** la misma key y el mismo body |
| `X-APIMart-Response-Version` | Prefiera `2026-07-27` para una forma de envío estable (`data.id`)                                                                             |

## Parámetros de la solicitud

<ParamField body="model" type="string" required>
  Valor fijo: `grok-imagine-2.0-ext`
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt. Debe ser no vacío tras el trim. Haga trim antes de enviar.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Cantidad de imágenes: `1`–`12`. Un `0` explícito produce error. Omítalo para `1`.
</ParamField>

<ParamField body="size" type="string">
  Relación de aspecto. **Prefiera cadenas de proporción** (la UI solo debe mostrar proporciones):

  | `size` | Orientación | Uso típico                     |
  | ------ | ----------- | ------------------------------ |
  | `1:1`  | Cuadrado    | Producto, avatar               |
  | `2:3`  | Vertical    | Póster, cuerpo entero          |
  | `3:2`  | Horizontal  | Foto, escena amplia            |
  | `3:4`  | Vertical    | Comercio electrónico, personas |
  | `4:3`  | Horizontal  | Arte de visualización          |
  | `9:16` | Vertical    | Portada de Story / video corto |
  | `16:9` | Ancho       | Banner, portada de video       |

  Alias de píxeles: `1024x1024` (1:1), `1024x1792` (2:3), `1792x1024` (3:2), `720x1280` (9:16), `1280x720` (16:9).

  Los valores fuera de la lista blanca devuelven `400 invalid_size` (p. ej. `1:2`, `2:1`, `4:5`, `auto`).

  <Note>
    Los píxeles reales de una proporción pueden diferir de la tabla de alias (p. ej. `1:1` puede devolver 1408×1408). Confíe en la imagen devuelta; no reescriba `size` a partir de los píxeles medidos.
  </Note>
</ParamField>

<ParamField body="resolution" type="string">
  Campo de modo de calidad. Valor verificado: `quality`.

  * Omítalo (el modelo es modo calidad por defecto), o
  * Pase `resolution: "quality"` de forma explícita

  **No** es un nivel de píxeles `1K` / `2K` / `4K`; el encuadre lo controla `size`.

  <Warning>
    No envíe el campo público `quality` — recibirá `400 invalid_quality`. Use `resolution`.
  </Warning>
</ParamField>

<ParamField body="response_format" type="string" default="url">
  Solo se permite `url`. Puede omitirse. `b64_json` / `base64` → `400 invalid_response_format`.
</ParamField>

<ParamField body="webhook" type="string">
  **URL base** HTTPS pública opcional. En estado terminal, la plataforma hace POST a `{webhook}/callback`. Solo en el servidor — vea [Webhook](#webhook-opcional).
</ParamField>

### Parámetros no admitidos

| Parámetro                                  | Comportamiento                           |
| ------------------------------------------ | ---------------------------------------- |
| `quality`                                  | `400 invalid_quality` → use `resolution` |
| `style`                                    | `400 invalid_style`                      |
| `image_urls` / `image_with_roles`          | `400 invalid_image_input`                |
| `stream: true`                             | `400 invalid_stream`                     |
| `response_format: "b64_json"` / `"base64"` | `400 invalid_response_format`            |

Construya las solicitudes con una lista blanca; no reenvíe un objeto de formulario genérico de otros modelos de imagen.

## Ejemplos de solicitud

### Mínimo

```json theme={null}
{
  "model": "grok-imagine-2.0-ext",
  "prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
```

### Recomendado

```json theme={null}
{
  "model": "grok-imagine-2.0-ext",
  "prompt": "A red apple on a white ceramic plate, clean studio product photo",
  "n": 1,
  "size": "1:1",
  "resolution": "quality",
  "response_format": "url"
}
```

## Respuesta de envío

Prefiera `X-APIMart-Response-Version: 2026-07-27`. El éxito es HTTP **`202`**; el id de la tarea es **`data.id`** (no dependa del legado `data[0].task_id`).

Conserve:

* `data.id` para el sondeo (polling)
* `request_id` para depuración en el gateway
* el `Idempotency-Key` para reintentos seguros cuando el resultado sea desconocido
* los parámetros originales de la solicitud para UI / soporte

## Idempotencia y reintentos seguros

La generación de imágenes es facturable — se **recomienda encarecidamente** `Idempotency-Key` (1–191 caracteres ASCII imprimibles; UUID es lo más sencillo; se retiene \~24 horas).

| Escenario                            | Comportamiento                                | Acción                                                  |
| ------------------------------------ | --------------------------------------------- | ------------------------------------------------------- |
| Misma key + mismo body ya completado | Replay; header `Idempotency-Replayed: true`   | Use el mismo id de tarea                                |
| Misma key aún en curso               | `409 idempotency_in_progress` + `Retry-After` | Espere y reintente con la **misma key y el mismo body** |
| Misma key, body distinto             | `409 idempotency_key_reused`                  | Una nueva tarea lógica necesita una key nueva           |
| Resultado indeterminado              | `409 idempotency_result_indeterminate`        | No cree una key nueva; investigue con la antigua        |

En un timeout de red del POST cuando no pueda saber si el servidor aceptó la tarea, **no cree de inmediato una key nueva** — reintente con la misma key / body / versión de respuesta.

## Consultar tareas

```http theme={null}
GET /v1/tasks/{task_id}?language=en
Authorization: Bearer YOUR_API_KEY
Accept: application/json
```

`language` opcional: `zh` / `en` / `ko` / `ja` (solo localización de mensajes de error). Vea [Obtener estado de la tarea](/es/api-reference/tasks/status).

### Estados

| `status`                 | Terminal | Tratamiento                                                              |
| ------------------------ | :------: | ------------------------------------------------------------------------ |
| `pending` / `processing` |    No    | Siga consultando (`result` puede estar ausente — no es un fallo)         |
| `completed`              |    Sí    | Analice `result.images`                                                  |
| `failed`                 |    Sí    | Muestre `error.message`; `cost` es `0` (pre-cargo reembolsado)           |
| `unknown`                |    No    | Reintentos cortos; si persiste, contacte a soporte con el id de la tarea |

Consulte aproximadamente cada **2 segundos**; tope cerca de **10 minutos** o **120** intentos. Respete `Retry-After` en `429`. Las tareas se conservan \~3 días por defecto — guarde el id de la tarea si el cliente agota el tiempo de espera.

### Ejemplo completado

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
    "status": "completed",
    "progress": 100,
    "created": 1786419262,
    "completed": 1786419275,
    "actual_time": 13,
    "estimated_time": 100,
    "cost": 0.08,
    "credits_cost": 0.8,
    "result": {
      "images": [
        {
          "expires_at": 1786505675,
          "url": [
            "https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
          ],
          "image_ids": [
            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          ]
        }
      ]
    }
  }
}
```

### Análisis de `url` e `image_ids`

```text theme={null}
result.images[]
  ├─ url[]          ← authoritative display/download field (array)
  ├─ image_ids[]    ← optional opaque IDs
  └─ expires_at     ← Unix seconds; multiply by 1000 for JS Date
```

1. Use `url[]` para la visualización; cuando `n>1`, recorra todas las entradas
2. Empareje por índice solo si `image_ids.length === url.length`
3. Si faltan `image_ids`, la visualización sigue siendo posible
4. Los enlaces duran **72 horas** — descargue con prontitud; confíe también en `expires_at`

## Facturación

Precio base **\$0.08 por imagen** (entregas exitosas):

| `n` | Base estimada |
| --: | ------------: |
|   1 |        \$0.08 |
|   4 |        \$0.32 |
|   8 |        \$0.64 |
|  12 |        \$0.96 |

* La UI previa al envío debe decir “estimación”; el USD final es **`data.cost`**
* **`data.credits_cost`** es la vista en créditos (actualmente \~ USD × 10)
* Pre-cargo por la cantidad solicitada; liquidación por la cantidad exitosa (reembolsos parciales si hay fallo parcial)
* Fallo total: `cost=0`, pre-cargo reembolsado
* No construya claves de precio a partir de `resolution`; este modelo tiene precio fijo por imagen

## Webhook (opcional)

```json theme={null}
{
  "webhook": "https://your-service.example.com/apimart"
}
```

* Proporcione una **URL base**; la plataforma llama a `{base}/callback`
* Debe ser pública y pasar las comprobaciones SSRF
* Si se define `webhook_secret`, la firma es `hex(HMAC-SHA256(secret, raw_body))` sobre los bytes en bruto
* El cuerpo del callback coincide con el `data` de la consulta de tarea (sin envoltorio extra `{code,data}`)
* Mantenga igualmente un sondeo de baja frecuencia como respaldo

## Errores comunes

| HTTP | `error.code`              | Causa                           | Acción                                        |
| ---: | ------------------------- | ------------------------------- | --------------------------------------------- |
|  400 | `invalid_request`         | Prompt vacío / JSON no válido   | Valide la entrada                             |
|  400 | `invalid_n`               | `n` fuera de 1–12               | Limite la cantidad                            |
|  400 | `invalid_size`            | Size no está en la lista blanca | Opciones fijas de selección                   |
|  400 | `invalid_response_format` | No es `url`                     | Corrija u omita                               |
|  400 | `invalid_quality`         | Se envió el `quality` público   | Use `resolution`                              |
|  400 | `invalid_style`           | Se envió `style`                | Elimine                                       |
|  400 | `invalid_image_input`     | Imágenes de referencia          | Cambie de modelo                              |
|  400 | `invalid_stream`          | `stream=true`                   | Elimine                                       |
|  400 | `invalid_idempotency_key` | Key no válida                   | Use UUID                                      |
|  401 | Fallo de autenticación    | Key no válida                   | Corrija las credenciales del servidor         |
|  402 | Pago requerido            | Saldo bajo                      | Recargue                                      |
|  409 | `idempotency_*`           | Conflicto de idempotencia       | Vea la tabla anterior                         |
|  429 | Límite de tasa            | Demasiado rápido                | Respete `Retry-After`                         |
|  5xx | Error del servidor        | —                               | Conserve el Idempotency-Key; no rote a ciegas |

Prefiera `error.message` en la UI. No exponga detalles internos de autenticación a los usuarios finales.

## Diferencias respecto a 1.5 (resumen)

| Elemento         | Grok Imagine 1.5                 | 2.0 Ext                                           |
| ---------------- | -------------------------------- | ------------------------------------------------- |
| Modelo           | `grok-imagine-1.5-apimart`, etc. | `grok-imagine-2.0-ext`                            |
| Imagen a imagen  | Admitido (vea docs 1.5)          | **No admitido**                                   |
| Cantidad         | Vea docs 1.5                     | **1–12**                                          |
| Campo de calidad | Vea docs 1.5                     | `resolution` (`quality`); nunca `quality` público |
| Salida           | Vea docs 1.5                     | **Solo URL**                                      |
| TTL de la URL    | Vea docs 1.5 (a menudo 24h)      | **72 horas**                                      |
| Precio unitario  | Vea docs 1.5                     | **\$0.08 / imagen**                               |