Crear imagen

ResumenCopy Anchor Link

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. background acepta auto u opaque; transparent no es compatible. 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 de los campos admitidos actual de TokenLab para gpt-image-2; omítelo o la solicitud devolverá 400 unsupported_parameter.

Notas de comportamiento del modeloCopy Anchor Link

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 y resolution (1k, 2k, 4k) tanto para text-to-image como para image-to-image.
• 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.
• 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 solicitudCopy Anchor Link

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.

RespuestaCopy Anchor Link

Respuesta en líneaCopy Anchor Link

Respuesta de tarea asíncronaCopy Anchor Link

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.

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",
    "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'];

{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

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

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"

{
  "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 disponiblesCopy Anchor Link

Consulta GET /v1/models?recommended_for=image para ver los modelos de imagen, capacidades y precios actuales.

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 tareasCopy Anchor Link

Para los modelos de imagen, comprueba siempre si la respuesta contiene status: "pending" / status: "processing":

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # 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, "async": True},
        timeout=120
    )
    response.raise_for_status()
    data = response.json()

    # Check if task-based
    if data.get("status") in ("pending", "processing"):
        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"},
                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)
    else:
        # Inline response
        return data["data"][0]["url"]

# Usage
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}