Crear imagen

Descripción generalCopy Anchor Link

Utilice GET /v1/models?recommended_for=image para obtener los modelos de imagen actuales, luego envíe el model seleccionado explícitamente.

gpt-image-2 es un modelo de imagen GPT con precio basado en tokens. TokenLab sigue el desglose de uso oficial de OpenAI para tokens de entrada de texto, entrada de imagen, entrada almacenada en caché y salida de imagen; no se factura como un modelo 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 personalizados de size deben utilizar el contrato flexible WIDTHxHEIGHT documentado a continuación.

input_fidelity no forma parte de los campos admitidos actualmente por TokenLab para gpt-image-2; omítalo o la solicitud devolverá 400 unsupported_parameter.

Notas sobre el comportamiento del modeloCopy Anchor Link

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 la 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" y 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 proporcionarse como image_url / image_urls en 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 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 lo admita explícitamente.

Los modelos de imagen xAI Grok Imagine (grok-imagine-image, grok-imagine-image-2.0 y el legado grok-imagine-image-pro) admiten aspect_ratio además de resolution (1k, 2k). grok-imagine-image-pro se mantiene como un ID de compatibilidad para grok-imagine-image-2.0.

Cuerpo de la solicitudCopy Anchor Link

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, así que configure 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, siga la poll_url devuelta en su lugar.

RespuestaCopy Anchor Link

Respuesta en líneaCopy Anchor Link

Respuesta de tarea asíncronaCopy Anchor Link

Establezca 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. Realice el sondeo de /v1/tasks/{task_id} hasta que la tarea llegue a completed o failed.

Las tareas de imagen asíncronas devuelven solo URLs de imágenes finales. Si necesita datos de imagen 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.

Cuando reciba status: "pending", utilice 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": "nano-banana",
  "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..."
    }
  ]
}

Elegir un modeloCopy Anchor Link

Consulte GET /v1/models?recommended_for=image o utilice la página de modelos para conocer la disponibilidad, capacidades y precios actuales.

No codifique un modelo como siempre síncrono o siempre asíncrono. Si la respuesta de creación devuelve status: "pending", siga poll_url y realice el sondeo hasta que se complete.

Manejo de respuestas basadas en tareasCopy Anchor Link

Para los 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"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        # Sondear resultado
        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:
        # 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}")

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