Saltar al contenido principal

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.

​
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, partial_images y user. Si omites size o quality, TokenLab usa auto; los valores personalizados de size deben usar el contrato flexible WIDTHxHEIGHT documentado abajo. Nota de compatibilidad: si una solicitud gpt-image-2 incluye input_fidelity, TokenLab lo elimina antes de reenviarla porque GPT Image 2 ya procesa las entradas de imagen con alta fidelidad.

​
Notas de comportamiento del modelo

Google Gemini no comparten el mismo contrato de selección:
  • gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-2 y nano-banana-pro admiten aspect_ratio junto con resolution (1k, 2k, 4k) para generación de texto a imagen.
  • gemini-2.5-flash-image, nano-banana y nano-banana-edit admiten aspect_ratio, pero no exponen selección pública de resolution.
  • gemini-2.0-flash-preview-image-generation se documenta aquí como texto a imagen solo por prompt.
  • Para solicitudes con imagen de referencia de nano-banana, nano-banana-2 y nano-banana-pro, usa 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.
  • Para solicitudes image-to-image de Nano Banana, omite resolution. nano-banana-2 y nano-banana-pro solo exponen resolution para texto a imagen, y nano-banana no lo expone.
  • 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 y se enruta upstream a grok-imagine-image-quality.

​
Cuerpo de la solicitud

Tiempo de espera de solicitudes síncronas: algunos proveedores de imagen enrutados 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.
​
model
string
predeterminado:"dall-e-3"
Modelo a usar (por ejemplo, gpt-image-2, dall-e-3, flux-pro, midjourney).
​
prompt
string
requerido
Descripción textual de la imagen deseada.
​
image_url
string
URL HTTPS pública de imagen de referencia para generación image-to-image. En modelos Nano Banana, establece operation en image-to-image y omite resolution salvo que el modelo la admita explícitamente para esa operación.
​
image_urls
string[]
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[].
​
reference_image_urls
string[]
URLs adicionales de referencia específicas del modelo para proveedores que distinguen imágenes de entrada principales y referencias.
​
image
file
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
integer
predeterminado:"1"
Número de imágenes a generar (1-10, según el modelo).
​
size
string
predeterminado:"1024x1024"
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 contrato público 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 contrato público de aspect_ratio y, cuando está disponible, resolution. Para esos modelos, prefiere enviar aspect_ratio directamente.
​
aspect_ratio
string
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.
​
resolution
string
Selector de resolución de salida dependiente del modelo.Se admite en gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-2, nano-banana-pro y familias de alta resolución similares. 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.
​
quality
string
predeterminado:"standard"
Calidad de imagen. Los modelos DALL-E usan standard o hd; los modelos GPT Image como gpt-image-2 usan auto, low, medium o high.
​
response_format
string
predeterminado:"url"
Formato de respuesta: url o b64_json. El valor predeterminado es url.Para rutas gpt-image-2 de Azure Official o compatibles con Azure, TokenLab no reenvía response_format al upstream. El gateway siempre recibe los datos de imagen upstream como b64_json; para solicitudes url, sube cada imagen al CDN y devuelve data[].url. Si el almacenamiento CDN no está disponible o la subida falla, la solicitud falla en vez de degradar a Base64. Para b64_json, devuelve el Base64 sin procesar.
​
async
boolean
predeterminado:"false"
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.
​
style
string
predeterminado:"vivid"
Estilo para DALL-E 3: vivid o natural.
​
user
string
Un identificador único para el usuario final.

​
Respuesta

​
Respuesta en línea

​
created
integer
Marca de tiempo Unix de creación.
​
data
array
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): El prompt usado (DALL-E 3)

​
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.
​
created
integer
Marca de tiempo Unix de creación.
​
task_id
string
Identificador único de la tarea para el sondeo.
​
status
string
Estado inicial: pending.
​
poll_url
string
URL relativa para sondear resultados, por ejemplo /v1/tasks/{id}.
​
data
array
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. 
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-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

{
  "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..."
    }
  ]
}

​
Modelos disponibles

ModeloTipoFunciones
dall-e-3Normalmente inlineMejor calidad, mejora de prompt
dall-e-2Normalmente inlineMás rápido, más económico
flux-proA menudo basado en tareasFotorrealista, alta calidad
flux-schnellNormalmente inlineMuy rápido
midjourneyA menudo basado en tareasEstilo artístico
ideogram-v3A menudo basado en tareasMejor renderizado de texto
stable-diffusion-3Normalmente inlineCódigo abierto, configurable
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": 
import requests
import time

def generate_image(prompt, model="midjourney"):
    # 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="midjourney")
print(f"Generated image: {url}")