# Grok Imagine Image — /images/generations

Generación de imágenes (asíncrona, por trabajos) con xAI Grok Imagine Image, nivel Standard. Para texto a imagen basta el prompt; para editar, pon las referencias en image o images (URL, data: URI o base64) o llama a /v1/images/edits. Al enviar recibes al instante un id de trabajo (HTTP 202); consulta GET /v1/images/jobs/{id} para obtener la imagen. Siete proporciones y dos resoluciones, 1K y 2K (envía resolution: "2K" o un tamaño de clase 2048 para 2K; no hay 4K y se rechaza al enviar); en 1K suele tardar 5-10 segundos. En el nivel Standard la edición conserva la proporción de la imagen original y otra proporción se recorta al centro. 1K y 2K cuestan lo mismo; las solicitudes fallidas no se cobran.

**Endpoint:** `POST https://nezhagate.com/v1/images/generations`

## Autenticación
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Cuerpo de la petición
| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `model` | string | Sí | ID del modelo; aquí grok-imagine-image. |
| `prompt` | string | Sí | Prompt de texto que describe la imagen. |
| `size` | string | No | Relación de aspecto de salida. Recomendado: pasa una relación (1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9) y el modelo renderiza de forma nativa con esa proporción, sin recortar el sujeto. También se aceptan tamaños en píxeles (p. ej. 1024x1024, 1024x1536, 1536x1024). Por defecto 1:1 (cuadrada). |
| `n` | integer | No | Número de imágenes; por defecto 1. |
| `image` | string | No | Imagen a imagen: una imagen de referencia como URL pública, data: URI o base64 en bruto. Si está presente, la petición ejecuta una verdadera transformación imagen a imagen que preserva la identidad en el tamaño y la proporción elegidos, equivalente a llamar a /v1/images/edits. |
| `images` | array | No | Referencia con varias imágenes (hasta 8; se recomiendan ≤4 para mantener la coherencia del sujeto): pasa un array de cadenas o un array de objetos [{"image_url": "..."}]; cada elemento puede ser una URL pública, un data: URI o base64. Ejecuta imagen a imagen con múltiples referencias (fusionando los sujetos y el estilo de varias), equivalente a la entrada multiimagen de /v1/images/edits. Para una sola referencia también sirve el campo image de arriba. |
| `resolution` | string | No | Resolución: 1K (por defecto) o 2K, al mismo precio. Un tamaño en píxeles de clase 2048 en size también selecciona 2K. No hay 4K y se rechaza. |

## Ejemplo de petición
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## Respuesta
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "grok-imagine-image"
}
```

## Imagen a imagen
Imagen a imagen: pon la referencia en `image` (una URL pública, un data: URI o base64 en bruto) para ejecutar una verdadera transformación que preserva la identidad: el modelo regenera a partir de ella con el tamaño y la proporción elegidos. Equivale a llamar a /v1/images/edits.

```bash
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "grok-imagine-image", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## Trabajos de imagen (enviar → consultar el resultado)
Renderizar una imagen suele tardar entre 1 y 3 minutos, así que los endpoints de imagen funcionan solo por trabajos: al enviar una petición recibes al instante un id de trabajo (HTTP 202) y consultas el resultado con ese id. El servidor sigue renderizando aunque se reinicie, así que la imagen nunca se pierde. Funciona igual para texto a imagen y para imagen a imagen. (El antiguo campo "async": true ya no hace falta; se acepta pero se ignora.)

```bash
# Paso 1 · Envía el trabajo (devuelve un id de inmediato, HTTP 202)
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image", "prompt": "an ink-wash poster", "size": "3:4"}'
# Paso 2 · Consulta el resultado (cada 2-3 s hasta que status sea succeeded)
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

status es queued / processing / succeeded / failed. Si tiene éxito, la respuesta lleva data[].url. Un trabajo solo lo puede consultar la cuenta que lo creó. Los endpoints de imagen son siempre asíncronos: al enviar recibes un id de trabajo; "async": true se acepta únicamente por compatibilidad y se ignora.