Imágenes

Create Image

Crea una imagen a partir de un prompt

POST
/v1/images/generations

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 async entre sus parámetros admitidos pueden crear primero una tarea: envíe async: true, luego realice encuestas en GET /v1/tasks/{id}.
  • Los enlaces de imagen se guardan durante 30 días; consulte Retención de datos.
  • Envíe un encabezado Idempotency-Key para 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" y svg: {"model": "..."}. El modelo de imagen primero dibuja una imagen de referencia, luego el modelo autor escribe el SVG a partir de ella. svg.model es obligatorio; la lista de detalles del modelo muestra sus valores aceptados bajo parameter_options (svg.model). También puede enviar svg.reasoning.effort. SVG solo funciona en este endpoint, con n: 1, y sin partial_images o output_compression.
  • GIF: envíe output_format: "gif". frame_count (de 2 a 16, valor predeterminado 9) establece el número de fotogramas, y frame_duration_ms (de 20 a 2000, valor predeterminado 200) establece la duración de cada fotograma. size es el tamaño de un fotograma. GIF no acepta partial_images ni output_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.1 y nano-banana-pro admiten aspect_ratio además de resolution (1k, 2k, 4k) para sus operaciones públicas de texto a imagen, imagen a imagen y edición de imagen.
  • nano-banana-2 admite aspect_ratio y resolution (1k, 2k, 4k) tanto para la generación de texto a imagen como de imagen a imagen.
  • gemini-3.1-flash-lite-image y nano-banana-2-lite admiten texto a imagen, imagen a imagen y edición de imagen solo en resolución 1k.
  • nano-banana admite aspect_ratio pero no expone una selección pública de resolution.
  • Para imagen a imagen con gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image o gemini-3-pro-image, utilice este endpoint con operation: "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-lite o nano-banana-pro en este endpoint (/v1/images/generations) con operation: "image-to-image" e image_urls. Las solicitudes de edición de imagen para nano-banana-2, nano-banana-2.1, nano-banana-2-lite y nano-banana-pro también utilizan este endpoint, con operation: "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_urls en formato JSON, o como un archivo image multipart. images[] y file_id no se aceptan en /v1/images/generations; cree referencias de /v1/files solo para los modelos de /v1/images/edits que documenten images[].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.

modelstringobligatorio

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.

promptstringobligatorio

Descripción de texto de la imagen deseada, hasta 32.000 caracteres. Obligatorio para cada modelo cuya descripción enumere prompt.

operationstring

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.

image_urlstring

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.

image_urlsstring[]

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.

reference_image_urlsstring[]

URLs de imágenes de referencia adicionales, hasta 16, para modelos que distinguen las entradas principales de las referencias.

imagefile

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.

nintegerpredeterminado: 1

Número de imágenes a generar (1-10, dependiendo del modelo).

sizestring

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.

aspect_ratiostring

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.

resolutionstring

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.

qualitystring

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.

output_formatstring

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.

svgobject

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.

frame_countintegerpredeterminado: 9

Número de fotogramas GIF, de 2 a 16. Solo con output_format: "gif".

frame_duration_msintegerpredeterminado: 200

Duración de cada fotograma GIF en milisegundos, de 20 a 2000. Solo con output_format: "gif".

response_formatstring

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 en data[].url cuando TokenLab la ha almacenado. Cuando el modelo devuelve un enlace, cada imagen está en data[].url.
  • url: cada imagen aparece solo en data[].url.
  • b64_json: cada imagen aparece solo en data[].b64_json como datos Base64.

Los enlaces son URLs de resultados multimedia de TokenLab. Siguen siendo válidos durante 30 días. Consulte Retención de datos.

asyncbooleanpredeterminado: false

Establé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.

stylestring

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.

userstring

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

createdinteger

Marca de tiempo Unix de creación.

dataarray

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 cuando response_format es b64_json. Cuando se omite response_format, falta si TokenLab no pudo almacenar la imagen.
  • b64_json (string): Datos de imagen Base64. Presente cuando response_format es b64_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.
usageobject

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.

svg_usageobject

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.

createdinteger

Marca de tiempo Unix de creación.

task_idstring

Identificador único de tarea para realizar encuestas.

statusstring

Estado inicial: pending.

poll_urlstring

URL relativa para realizar encuestas de resultados, por ejemplo /v1/tasks/{id}.

dataarray

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
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"
  }'
Python
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)
JavaScript
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
<?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ódigoCausa
unsupported_parameterEl modelo no lista el campo, o stream es true
unsupported_operationEl modelo no tiene tal operation
unsupported_endpointLa operación para este modelo se encuentra en otro endpoint, como /v1/images/edits
unsupported_async_modeEl modelo no admite async: true
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_itemsUn valor está fuera de lo que el modelo acepta. El error nombra los valores aceptados
invalid_image_size_contractUn size o nivel que el modelo no admite, o uno que entra en conflicto con resolution
prompt_too_longEl prompt es más largo de lo que acepta el modelo
request_too_large, file_too_largeUna 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
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Longitud1 <= length <= 255

Cuerpo de la solicitud

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json