> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Crear imagen
> Crea una imagen a partir de un prompt
## Resumen
Para agentes de código, descubre primero la lista corta recomendada de imágenes con `GET /v1/models?recommended_for=image`, y luego envía explícitamente el `model` elegido a este endpoint.
`gpt-image-2` es un modelo GPT Image con facturación por tokens. TokenLab sigue el desglose oficial de `usage` de OpenAI para liquidar tokens de entrada de texto, entrada de imagen, entrada en caché cuando se reporta, y salida de imagen; no se factura como un precio fijo por imagen.
Para generación de imágenes con `gpt-image-2`, los parámetros públicos admitidos son `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` o `compression`, `moderation` y `user`. Si omites `size` o `quality`, TokenLab usa `auto`; los valores personalizados de `size` deben usar el contrato flexible `WIDTHxHEIGHT` documentado abajo.
`input_fidelity` no forma parte del campos admitidos actual de TokenLab para `gpt-image-2`; omítelo o la solicitud devolverá `400 unsupported_parameter`.
### Notas de comportamiento del modelo
Google Gemini no comparten el mismo contrato de selección:
* `gemini-3.1-flash-image`, `gemini-3-pro-image` y `nano-banana-pro` admiten `aspect_ratio` junto con `resolution` (`1k`, `2k`, `4k`) para sus operaciones públicas de texto a imagen e image-edit/image-to-image.
* `nano-banana-2` admite `aspect_ratio` junto con `resolution` (`1k`, `2k`, `4k`) solo para texto a imagen en el contrato actual de TokenLab.
* `gemini-2.5-flash-image`, `nano-banana` y `nano-banana-edit` admiten `aspect_ratio`, pero no exponen selección pública de `resolution`.
* Para solicitudes Nano Banana con imagen de referencia, usa `nano-banana-edit` o `nano-banana-pro` en este endpoint (`/v1/images/generations`) con `operation: "image-to-image"` e `image_urls`. No envíes solicitudes de referencia Nano Banana a `/v1/images/edits`.
* En solicitudes Nano Banana image-to-image, `nano-banana-pro` puede incluir `resolution` (`1k`, `2k`, `4k`); `nano-banana-edit` debe omitirlo. `nano-banana` y `nano-banana-2` son modelos de texto a imagen en el detalles del modelo actual.
* Las imágenes de referencia en este endpoint pueden enviarse como JSON `image_url` / `image_urls`, o como archivo multipart `image`. `/v1/images/generations` no acepta `images[]` ni `file_id`; las referencias de `/v1/files` solo aplican a modelos de `/v1/images/edits` que documentan `images[].file_id`.
Para las familias de imágenes de Google, prefiere `aspect_ratio` y envía `resolution` solo cuando el modelo lo admita explícitamente.
Los modelos de imagen xAI Grok Imagine (`grok-imagine-image`, `grok-imagine-image-quality` y el legacy `grok-imagine-image-pro`) admiten `aspect_ratio` junto con `resolution` (`1k`, `2k`). `grok-imagine-image-pro` se conserva como ID de compatibilidad para `grok-imagine-image-quality`.
## Cuerpo de la solicitud
**Tiempo de espera de solicitudes síncronas:** algunas solicitudes de imagen devuelven la imagen final inline y esperan a que termine la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, así que configura el timeout de tu cliente HTTP en al menos `120s`. Si la respuesta de creación incluye `status: "pending"`, `task_id` o `poll_url`, sigue el `poll_url` devuelto en su lugar.
Modelo a usar (por ejemplo, `gpt-image-2`, `flux-pro`, `qwen-image-plus` o `nano-banana-pro`). Consulta `GET /v1/models?recommended_for=image` para la lista recomendada actual.
Descripción textual de la imagen deseada.
URL HTTPS pública de imagen de referencia para generación image-to-image. En solicitudes Nano Banana con imagen de referencia, establece `operation` en `image-to-image`; `nano-banana-pro` puede incluir `resolution`, mientras que `nano-banana-edit` debe omitirlo.
URLs HTTPS públicas de imágenes de referencia. Úsalo para una o más imágenes de referencia en solicitudes JSON. Este endpoint no admite `file_id` ni `images[]`.
URLs adicionales de referencia específicas del modelo para proveedores que distinguen imágenes de entrada principales y referencias.
Archivo multipart de imagen de referencia para generación image-to-image. Úsalo cuando la imagen fuente sea privada o requiera cabeceras. No es un `file_id` de /v1/files; este endpoint no acepta `file_id`.
Número de imágenes a generar (1-10, según el modelo).
Tamaño de la imagen. Úsalo para familias de imágenes al estilo OpenAI y otros modelos que aceptan tamaños exactos en píxeles.
Para `gpt-image-2`, `size` acepta `auto` o `WIDTHxHEIGHT`. Las dimensiones personalizadas deben ser múltiplos de 16 en ambos lados, el lado más largo debe ser como máximo `3840px`, la proporción lado largo/lado corto debe ser como máximo `3:1`, y el total de píxeles debe estar entre `655,360` y `8,294,400`. `aspect_ratio` y `resolution` no forman parte del detalles del modelo actual de TokenLab para `gpt-image-2`.
Para las familias de imágenes de Google Gemini, `size` actúa como un alias de compatibilidad que se mapea al detalles del modelo de `aspect_ratio` y, cuando está disponible, `resolution`. Para esos modelos, prefiere enviar `aspect_ratio` directamente.
Selector de relación de aspecto dependiente del modelo.
Los valores comunes en familias de imágenes de Google incluyen `1:1`, `16:9`, `9:16`, `3:2` y `2:3`.
Selector de resolución de salida dependiente del modelo.
Se admite en `gemini-3.1-flash-image` y `gemini-3-pro-image` para texto a imagen e image-edit, en `nano-banana-pro` para texto a imagen e image-to-image, y en `nano-banana-2` solo para texto a imagen. Los valores típicos son `1k`, `2k` y `4k`. No envíes este parámetro a familias de imagen Gemini que solo aceptan proporción salvo que el modelo lo documente explícitamente. Para los modelos de imagen xAI Grok Imagine, usa `1k` o `2k`.
Calidad de imagen. Los modelos GPT Image como `gpt-image-2` usan `auto`, `low`, `medium` o `high`. Otras familias de imagen pueden usar valores específicos del proveedor; revisa los metadatos del modelo antes de enviar valores no predeterminados.
Formato de respuesta: `url` o `b64_json`. El valor predeterminado es `url`.
Para solicitudes `gpt-image-2` de Azure Official o compatibles con Azure, TokenLab recibe los datos de imagen como `b64_json`. Para solicitudes `url`, TokenLab sube cada imagen al CDN y devuelve `data[].url`. Si el almacenamiento CDN no está disponible o la subida falla, la solicitud falla en lugar de convertirse en una respuesta Base64. Para `b64_json`, devuelve el Base64 sin procesar.
Establécelo en `true` con `gpt-image-2` o modelos de imagen oficiales FLUX/BFL para crear una tarea primero. Las tareas asíncronas completadas devuelven URL sin importar el `response_format` solicitado; usa solicitudes síncronas si necesitas `b64_json`.
Selector de estilo opcional. Envíalo solo cuando el modelo seleccionado lo documente explícitamente; omítelo para `gpt-image-2` salvo que los metadatos del modelo indiquen lo contrario.
Un identificador único para el usuario final.
## Respuesta
### Respuesta en línea
Marca de tiempo Unix de creación.
Array de imágenes generadas.
Cada objeto contiene:
* `url` (string): URL de la imagen generada
* `b64_json` (string): Imagen codificada en Base64, si se solicita
* `revised_prompt` (string): Revisión opcional del prompt cuando el modelo seleccionado la devuelve
### Respuesta de tarea asíncrona
Usa `async: true` con `gpt-image-2` o modelos de imagen oficiales FLUX/BFL para crear una tarea en lugar de esperar la imagen final en la solicitud de creación. La respuesta incluye `status: "pending"`, `task_id` y `poll_url`. Consulta `/v1/tasks/{task_id}` hasta que la tarea llegue a `completed` o `failed`.
Las tareas asíncronas de imagen solo devuelven las URL finales. Si necesitas datos de imagen `b64_json` sin procesar, usa una solicitud síncrona.
Al crear la tarea puede reservarse el importe estimado. Las tareas completadas se cobran por uso real; las fallidas o vencidas liberan o reembolsan la reserva.
Marca de tiempo Unix de creación.
Identificador único de la tarea para el sondeo.
Estado inicial: `pending`.
URL relativa para sondear resultados, por ejemplo `/v1/tasks/{id}`.
Vacío mientras la tarea está pendiente. Las tareas de imagen completadas devuelven las URL de imágenes generadas en `data[].url`.
Cuando recibas `status: "pending"`, usa `poll_url` o `GET /v1/tasks/{task_id}` para recuperar el resultado.
```bash cURL theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
"aspect_ratio": "16:9",
"resolution": "2k",
"n": 1
}'
```
```python Python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
aspect_ratio="16:9",
resolution="2k",
n=1
)
print(response.data[0].url)
```
```javascript JavaScript theme={null}
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.images.generate({
model: 'gemini-3-pro-image',
prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
aspect_ratio: '16:9',
resolution: '2k',
n: 1
});
console.log(response.data[0].url);
```
```php PHP theme={null}
true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gemini-3-pro-image',
'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
'aspect_ratio' => '16:9',
'resolution' => '2k',
'n' => 1
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
```
Ejemplo para familias que solo aceptan proporción: para `gemini-2.5-flash-image`, `nano-banana` o `nano-banana-edit`, envía `aspect_ratio` pero omite `resolution`:
```json theme={null}
{
"model": "gemini-2.5-flash-image",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}
```
Ejemplo de Nano Banana Pro con imagen de referencia: envía la solicitud a `/v1/images/generations`, no a `/v1/images/edits`. `resolution` es opcional y puede ser `1k`, `2k` o `4k`:
```json theme={null}
{
"model": "nano-banana-pro",
"prompt": "Create a clean cinematic character image based on the reference images",
"operation": "image-to-image",
"image_urls": ["https://example.com/reference-1.png"],
"aspect_ratio": "1:1",
"resolution": "2k"
}
```
Para imágenes fuente privadas o locales, usa una subida multipart directa. No envíes `file_id` a `/v1/images/generations`:
```bash theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=nano-banana-pro" \
-F "prompt=Create a clean cinematic character image based on this reference" \
-F "operation=image-to-image" \
-F "image=@reference.png" \
-F "aspect_ratio=1:1" \
-F "resolution=2k"
```
```json Inline Response theme={null}
{
"created": 1706000000,
"data": [
{
"url": "https://...",
"revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
}
]
}
```
```json Async Task Response theme={null}
{
"created": 1706000000,
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"data": []
}
```
## Modelos disponibles
Estos son ejemplos actuales, no un catálogo fijo. Consulta `GET /v1/models?recommended_for=image` o la página Models para ver disponibilidad y precios actualizados.
| Modelo | Tipo | Funciones |
| -------------------- | ------------------------- | -------------------------------------------------------------- |
| `gpt-image-2` | Inline o basado en tareas | Modelo GPT Image con precio por token y tamaños flexibles |
| `flux-pro` | A menudo basado en tareas | Fotorrealista, alta calidad |
| `qwen-image-plus` | A menudo basado en tareas | Buen renderizado de texto y seguimiento del prompt |
| `nano-banana-pro` | A menudo basado en tareas | Flujos con imágenes de referencia y salida de alta resolución |
| `grok-imagine-image` | A menudo basado en tareas | Generación de imagen xAI con selección de aspecto y resolución |
| `ideogram-v3` | A menudo basado en tareas | Buen renderizado de texto |
No codifiques un modelo como si fuera siempre síncrono o siempre asíncrono. Si la respuesta de creación devuelve `status: "pending"`, sigue `poll_url` y haz polling hasta que termine.
## Manejo de respuestas basadas en tareas
Para los modelos de imagen, comprueba siempre si la respuesta contiene `status: "pending"`:
```python theme={null}
import requests
import time
def generate_image(prompt, model="flux-pro"):
# Create image request
response = requests.post(
"https://api.tokenlab.sh/v1/images/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={"model": model, "prompt": prompt}
)
data = response.json()
# Check if task-based
if data.get("status") == "pending":
task_id = data["task_id"]
poll_url = data.get("poll_url")
print(f"Image task started: {task_id}")
# Poll for result
while True:
status_resp = requests.get(
f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
headers={"Authorization": "Bearer sk-your-api-key"}
)
status_data = status_resp.json()
if status_data["status"] == "completed":
return status_data["data"][0]["url"]
elif status_data["status"] == "failed":
raise Exception(status_data.get("error", "Generation failed"))
time.sleep(3)
else:
# Inline response
return data["data"][0]["url"]
# Usage
url = generate_image("a beautiful sunset over mountains", model="flux-pro")
print(f"Generated image: {url}")
```