Imágenes
Create Image
Crea una imagen a partir de un prompt
Descripción general
Utilice GET /v1/models?recommended_for=image para obtener los modelos de imagen actuales, luego envíe explícitamente el model seleccionado.
Cada modelo acepta sus propias operaciones y campos. GET /v1/models/{model} (Obtener modelo) proporciona el endpoint para cada operación en tokenlab.request_format_summary.request_endpoint_by_operation, así como los campos, valores y límites aceptados para cada operación en tokenlab.request_format_details.operation_constraints. Un campo que el modelo no enumere puede devolver 400 unsupported_parameter. Una operación enviada al endpoint incorrecto devuelve 400 unsupported_endpoint.
Tareas y resultados de imagen:
- Los modelos que enumeran
asyncentre sus parámetros admitidos pueden crear primero una tarea: envíeasync: true, luego realice encuestas enGET /v1/tasks/{id}. - Los enlaces de imagen se guardan durante 30 días; consulte Retención de datos.
- Envíe un encabezado
Idempotency-Keypara reintentar una solicitud de creación de forma segura después de un tiempo de espera; consulte Reintentar de forma segura con una clave de idempotencia.
gpt-image-2 es un modelo GPT Image con precios basados en tokens. TokenLab sigue el desglose de uso oficial de OpenAI para tokens de entrada de texto, entrada de imagen, entrada almacenada en caché reportada y salida de imagen; no se factura como un modelo de precio fijo por imagen.
Para la 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. background acepta auto u opaque; transparent no es compatible. Omita size o quality para permitir que TokenLab utilice auto; los valores de size personalizados deben utilizar el contrato flexible WIDTHxHEIGHT documentado a continuación.
input_fidelity no forma parte de los campos compatibles actuales de TokenLab para gpt-image-2; omítalo o la solicitud devolverá 400 unsupported_parameter.
Salida SVG y GIF
gpt-image-2.6-flare y gpt-image-2.6-sunburst pueden devolver un SVG o un GIF animado en lugar de una imagen ráster. Otros modelos rechazan estos formatos.
- SVG: envíe
output_format: "svg"ysvg: {"model": "..."}. El modelo de imagen primero dibuja una imagen de referencia, luego el modelo autor escribe el SVG a partir de ella.svg.modeles obligatorio; la lista de detalles del modelo muestra sus valores aceptados bajoparameter_options(svg.model). También puede enviarsvg.reasoning.effort. SVG solo funciona en este endpoint, conn: 1, y sinpartial_imagesooutput_compression. - GIF: envíe
output_format: "gif".frame_count(de 2 a 16, valor predeterminado 9) establece el número de fotogramas, yframe_duration_ms(de 20 a 2000, valor predeterminado 200) establece la duración de cada fotograma.sizees el tamaño de un fotograma. GIF no aceptapartial_imagesnioutput_compression.
El resultado se encuentra en data[].b64_json o data[].url, igual que otras imágenes. Decodifique un SVG como texto XML UTF-8 y guárdelo como .svg; guarde un GIF como .gif.
Facturación: los tokens de imagen se facturan según los precios de token del modelo, y los fotogramas GIF son tokens de salida de imagen. Una solicitud SVG también factura los tokens del modelo autor, los cuales se reportan en la respuesta bajo svg_usage, a los precios de creación de SVG que se muestran en la página del modelo.
Notas sobre el comportamiento del modelo
Los modelos de la familia de imágenes Google Gemini no comparten el mismo contrato de selector:
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3-pro-image,nano-banana-2.1ynano-banana-proadmitenaspect_ratioademás deresolution(1k,2k,4k) para sus operaciones públicas de texto a imagen, imagen a imagen y edición de imagen.nano-banana-2admiteaspect_ratioyresolution(1k,2k,4k) tanto para la generación de texto a imagen como de imagen a imagen.gemini-3.1-flash-lite-imageynano-banana-2-liteadmiten texto a imagen, imagen a imagen y edición de imagen solo en resolución1k.nano-bananaadmiteaspect_ratiopero no expone una selección pública deresolution.- Para imagen a imagen con
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-imageogemini-3-pro-image, utilice este endpoint conoperation: "image-to-image"y las imágenes de referencia. Envíe las solicitudes de edición de imagen para estos modelos a/v1/images/edits. - Para solicitudes de imagen de referencia de Nano Banana, utilice
nano-banana-2,nano-banana-2.1,nano-banana-2-liteonano-banana-proen este endpoint (/v1/images/generations) conoperation: "image-to-image"eimage_urls. Las solicitudes de edición de imagen paranano-banana-2,nano-banana-2.1,nano-banana-2-liteynano-banana-protambién utilizan este endpoint, conoperation: "image-edit". No envíe solicitudes de imagen de referencia de Nano Banana a/v1/images/edits. - Las imágenes de referencia en este endpoint pueden suministrarse como
image_url/image_urlsen formato JSON, o como un archivoimagemultipart.images[]yfile_idno se aceptan en/v1/images/generations; cree referencias de/v1/filessolo para los modelos de/v1/images/editsque documentenimages[].file_id.
Para las familias de imágenes de Google, prefiera aspect_ratio y envíe resolution solo cuando el modelo la admita explícitamente.
Los modelos de imagen xAI Grok Imagine (grok-imagine-image y grok-imagine-image-2.0) admiten aspect_ratio además de resolution (1k, 2k). Texto a imagen utiliza este endpoint. Sus solicitudes de imagen a imagen y edición de imagen utilizan /v1/images/edits.
hy-image-v3.5-preview crea una imagen de 1024x1024 por solicitud a partir de texto en este endpoint y solo admite response_format: "url". Edita imágenes de referencia en /v1/images/edits.
Cuerpo de la solicitud
Tiempo de espera de solicitud síncrona: Algunas solicitudes de imagen devuelven la imagen final en línea y esperan a que finalice la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, por lo que debe establecer el tiempo de espera de su cliente HTTP en al menos 120s. Si la respuesta de creación incluye status: "pending", task_id o poll_url, realice encuestas en GET /v1/tasks/{task_id} en su lugar.
Modelo a utilizar (por ejemplo, gpt-image-2, flux-pro-1.1 o nano-banana-pro). Consulte GET /v1/models?recommended_for=image para obtener la lista recomendada actual.
Descripción de texto de la imagen deseada, hasta 32.000 caracteres. Obligatorio para cada modelo cuya descripción enumere prompt.
text-to-image, image-to-image o image-edit. Cuando se omite, es image-to-image si la solicitud tiene una imagen de referencia; de lo contrario, es text-to-image. Establezca image-edit para modelos cuya operación de edición se encuentre en este endpoint, como nano-banana-pro. text-to-image con una imagen de referencia devuelve 400 invalid_parameter.
URL pública de la imagen para la generación de imagen a imagen. Para solicitudes de imagen de referencia de Nano Banana, establezca operation en image-to-image; nano-banana-pro puede incluir resolution.
URLs públicas de imágenes de referencia, hasta 16. Utilícelo para una o más imágenes de referencia en solicitudes JSON. file_id e images[] no son compatibles en este endpoint.
URLs de imágenes de referencia adicionales, hasta 16, para modelos que distinguen las entradas principales de las referencias.
Archivo de imagen de referencia multipart para la generación de imagen a imagen. Utilícelo cuando la imagen de origen sea privada o esté protegida por encabezados. Esto es diferente de un file_id de /v1/files, que no se acepta en este endpoint.
1Número de imágenes a generar (1-10, dependiendo del modelo).
Tamaño de la imagen. Utilícelo para las familias de imágenes al estilo OpenAI y otros modelos que aceptan tamaños de píxel exactos.
Para gpt-image-2, size acepta auto o WIDTHxHEIGHT. Las dimensiones personalizadas deben ser múltiplos de 16, el borde más largo debe ser como máximo 3840px, la relación largo/ancho 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 de los detalles actuales del modelo TokenLab para gpt-image-2.
Para los modelos de imagen de Google con niveles de resolución (gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image, nano-banana-2, nano-banana-2.1 y nano-banana-pro), size acepta un tamaño de salida de la tabla de tamaños del modelo, como 1376x768 (16:9 a 1K), o un nivel de resolución: 1K, 2K o 4K. TokenLab envía un nivel como resolution, por lo que la solicitud y su precio son los mismos que con resolution. Un nivel que el modelo no admita (por ejemplo, 2K en gemini-3.1-flash-lite-image), o un nivel diferente de resolution, devuelve 400 con el código invalid_image_size_contract y los valores allowed_resolutions del modelo. Para estos modelos, la forma recomendada es aspect_ratio con resolution.
Selector de relación de aspecto dependiente del modelo.
Los valores comunes de la familia de imágenes de Google incluyen 1:1, 16:9, 9:16, 3:2 y 2:3.
Resolución de salida dependiente del modelo. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1 y nano-banana-pro admiten 1k, 2k y 4k; los modelos de imagen Grok Imagine admiten 1k y 2k. Omita este campo a menos que el modelo y la operación seleccionados lo admitan explícitamente.
Calidad de la imagen. Los modelos GPT Image como gpt-image-2 usan auto, low, medium o high. Otros modelos pueden usar valores diferentes; compruebe los detalles del modelo antes de enviar un valor no predeterminado.
Formato de archivo de la imagen: png, jpeg o webp. gpt-image-2.6-flare y gpt-image-2.6-sunburst también aceptan svg y gif; consulte Salida SVG y GIF.
Configuración de SVG, solo con output_format: "svg". model (obligatorio) selecciona el modelo de autor que escribe el SVG. reasoning.effort establece opcionalmente su esfuerzo de razonamiento.
9Número de fotogramas GIF, de 2 a 16. Solo con output_format: "gif".
200Duración de cada fotograma GIF en milisegundos, de 20 a 2000. Solo con output_format: "gif".
Cómo se devuelven las imágenes: url o b64_json.
- Omitido: cuando el modelo devuelve bytes de imagen, cada imagen está en
data[].b64_json, y también endata[].urlcuando TokenLab la ha almacenado. Cuando el modelo devuelve un enlace, cada imagen está endata[].url. url: cada imagen aparece solo endata[].url.b64_json: cada imagen aparece solo endata[].b64_jsoncomo datos Base64.
Los enlaces son URLs de resultados multimedia de TokenLab. Siguen siendo válidos durante 30 días. Consulte Retención de datos.
falseEstablécelo en true para crear una tarea primero. Solo los modelos que incluyen async entre sus parámetros admitidos lo aceptan, por ejemplo gpt-image-2, flux-pro-1.1, nano-banana-pro y seedream-5.0-lite; para cualquier otro modelo, la solicitud devuelve 400 unsupported_async_mode. Las tareas de imagen asíncronas completadas devuelven URLs independientemente del response_format solicitado; utiliza solicitudes síncronas cuando necesites b64_json.
Selector de estilo opcional. Envíelo solo cuando el modelo seleccionado lo documente explícitamente; omítalo para gpt-image-2 a menos que los metadatos del modelo indiquen lo contrario.
Un identificador único para el usuario final.
Algunos modelos también aceptan campos como negative_prompt, seed, width, height, steps, guidance_scale o mask_url. Envíelos solo cuando los detalles del modelo los listen. stream: true no es compatible y devuelve 400 unsupported_parameter.
Respuesta
Respuesta en línea
Marca de tiempo Unix de creación.
Matriz de imágenes generadas.
Cada objeto contiene:
url(string): URL de resultado multimedia de TokenLab de la imagen, válida por 30 días. No presente cuandoresponse_formatesb64_json. Cuando se omiteresponse_format, falta si TokenLab no pudo almacenar la imagen.b64_json(string): Datos de imagen Base64. Presente cuandoresponse_formatesb64_json, o cuando se omite y el modelo devuelve bytes de imagen.revised_prompt(string): Revisión opcional del prompt, cuando el modelo seleccionado devuelve una.
Recuento de tokens (input_tokens, output_tokens, total_tokens y sus detalles) para modelos con precios basados en tokens como gpt-image-2, cuando estén disponibles.
Recuento de tokens del modelo de creación de SVG (model, input_tokens, output_tokens, reasoning_tokens, total_tokens). Presente solo para salidas SVG. Estos tokens no se incluyen en usage y se facturan según las tarifas de creación de SVG.
Respuesta de tarea asíncrona
Establezca async: true en un modelo que lo admita 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. Realice encuestas en /v1/tasks/{task_id} hasta que la tarea alcance completed o failed.
Las tareas de imagen asíncronas devuelven solo URLs de imagen final. Si necesita datos de imagen en b64_json sin procesar, utilice una solicitud síncrona.
La facturación puede reservar el monto estimado cuando se crea la tarea. Las tareas completadas se facturan según el uso real, y las tareas fallidas o que excedieron el tiempo de espera se liberan o reembolsan.
Marca de tiempo Unix de creación.
Identificador único de tarea para realizar encuestas.
Estado inicial: pending.
URL relativa para realizar encuestas de resultados, por ejemplo /v1/tasks/{id}.
Vacío mientras la tarea está pendiente. Las tareas de imagen completadas devuelven las URLs de las imágenes generadas en data[].url.
Cuando reciba status: "pending", llame a GET /v1/tasks/{task_id} para recuperar el resultado.
Solicitud
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"
}'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",
extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)
print(response.data[0].url)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'
});
console.log(response.data[0].url);<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => 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'
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];Ejemplo de familia de imágenes solo con relación de aspecto: para nano-banana, envíe aspect_ratio pero omita resolution:
{
"model": "nano-banana",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}Ejemplo de imagen de referencia de Nano Banana Pro: envíe la solicitud a /v1/images/generations, no a /v1/images/edits. resolution es opcional y puede establecerse en 1k, 2k o 4k:
{
"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"
}Ejemplo de carga multipart directa para imágenes de origen privadas o locales. No pase un file_id a /v1/images/generations:
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"Respuesta
{
"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..."
}
]
}Errores
Los errores de solicitud devuelven 400 (413 para cargas de gran tamaño) con un error.code. Códigos comunes para solicitudes de imagen:
| Código | Causa |
|---|---|
unsupported_parameter | El modelo no lista el campo, o stream es true |
unsupported_operation | El modelo no tiene tal operation |
unsupported_endpoint | La operación para este modelo se encuentra en otro endpoint, como /v1/images/edits |
unsupported_async_mode | El modelo no admite async: true |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | Un valor está fuera de lo que el modelo acepta. El error nombra los valores aceptados |
invalid_image_size_contract | Un size o nivel que el modelo no admite, o uno que entra en conflicto con resolution |
prompt_too_long | El prompt es más largo de lo que acepta el modelo |
request_too_large, file_too_large | Una carga supera el límite de tamaño (50 MiB por archivo, 200 MiB para todas las entradas) |
Para saldo (402), límite de tasa (429) y reglas de reintento, consulte Manejo de errores.
Elegir un modelo
Consulte GET /v1/models?recommended_for=image o utilice la página de modelos para conocer la disponibilidad, capacidades y precios actuales.
No codifique de forma rígida un modelo como siempre síncrono o siempre asíncrono. Una solicitud sin async: true aún puede devolver status: "pending"; siempre que la respuesta de creación contenga status: "pending" o status: "processing", realice encuestas en GET /v1/tasks/{task_id} hasta que finalice.
Manejo de respuestas basadas en tareas
Para modelos de imagen, verifique siempre si la respuesta contiene status: "pending" / status: "processing":
import requests
import time
def generate_image(prompt, model="gpt-image-2"):
# Crear solicitud de imagen
response = requests.post(
"https://api.tokenlab.sh/v1/images/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={"model": model, "prompt": prompt, "async": True},
timeout=120
)
response.raise_for_status()
data = response.json()
# Comprobar si está basada en tareas
if data.get("status") in ("pending", "processing"):
task_id = data["task_id"]
print(f"Image task started: {task_id}")
# Realizar encuestas para obtener el resultado
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
f"https://api.tokenlab.sh/v1/tasks/{task_id}",
headers={"Authorization": "Bearer sk-your-api-key"},
timeout=30
)
status_resp.raise_for_status()
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)
raise TimeoutError(f"Image task {task_id} did not finish in time")
else:
# Respuesta en línea
return data["data"][0]["url"]
# Uso
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")Ejemplo de Hy Image 3.5 Preview. Solo acepta size 1024x1024 y n 1:
{
"model": "hy-image-v3.5-preview",
"prompt": "A yellow lemon on a white table",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Autorización
BearerAuth Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.
Valores permitidos
- "auto"
- "verified"
- "official"
Clave opcional que hace que una solicitud de imagen sea segura para reintentar si la solicitud creó una tarea. Envíe un nuevo valor único, como un UUID, para cada solicitud. Un reintento con la misma clave y el mismo cuerpo devuelve entonces esa tarea y no crea, envía ni cobra una segunda tarea. Para una solicitud que devuelve la imagen directamente, un reintento con la misma clave puede devolver un estado de tarea en lugar de la imagen, o 409 con idempotent_response_not_replayable. Un cuerpo diferente con una clave que ya fue aceptada se rechaza; el código de estado y el código de error para ese caso no están garantizados. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.
1 <= length <= 255Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json