Criar imagem

Visão geralCopy Anchor Link

Para agentes de código, descubra primeiro a lista de imagens recomendadas atuais com GET /v1/models?recommended_for=image e, em seguida, envie o model selecionado explicitamente para este endpoint.

gpt-image-2 é um modelo GPT Image com cobrança por token. A TokenLab segue o detalhamento oficial de usage da OpenAI para liquidar tokens de entrada de texto, entrada de imagem, entrada em cache quando informada, e saída de imagem; ele não é cobrado como preço fixo por imagem.

Para geração de imagens com gpt-image-2, os parâmetros públicos aceitos são prompt, n, size, quality, response_format, async, background, output_format, output_compression ou compression, moderation e user. background aceita auto ou opaque; transparent não é suportado. Se size ou quality for omitido, a TokenLab usa auto; valores personalizados de size devem seguir o contrato flexível WIDTHxHEIGHT documentado abaixo.

input_fidelity não faz parte dos campos admitidos atual da TokenLab para gpt-image-2; omita esse campo ou a solicitação retornará 400 unsupported_parameter.

Observações sobre comportamento dos modelosCopy Anchor Link

Google Gemini não usam exatamente o mesmo contrato de seleção:

• gemini-3.1-flash-image, gemini-3-pro-image e nano-banana-pro aceitam aspect_ratio mais resolution (1k, 2k, 4k) para suas operações públicas text-to-image e image-edit/image-to-image.
• nano-banana-2 aceita aspect_ratio e resolution (1k, 2k, 4k) para text-to-image e image-to-image.
• gemini-2.5-flash-image, nano-banana e nano-banana-edit aceitam aspect_ratio, mas não expõem seleção pública de resolution.
• Para solicitações Nano Banana com imagem de referência, use nano-banana-edit ou nano-banana-pro neste endpoint (/v1/images/generations) com operation: "image-to-image" e image_urls. Não envie solicitações de referência Nano Banana para /v1/images/edits.
• Imagens de referência neste endpoint podem ser enviadas como JSON image_url / image_urls ou como arquivo multipart image. /v1/images/generations não aceita images[] nem file_id; referências de /v1/files só valem para modelos de /v1/images/edits que documentam images[].file_id.

Para as famílias de imagem do Google, prefira aspect_ratio e envie resolution apenas quando o modelo suportar explicitamente.

Os modelos de imagem xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality e o legacy grok-imagine-image-pro) aceitam aspect_ratio mais resolution (1k, 2k). grok-imagine-image-pro é mantido como ID de compatibilidade para grok-imagine-image-quality.

Corpo da requisiçãoCopy Anchor Link

Timeout de solicitações síncronas: algumas solicitações de imagem retornam a imagem final inline e aguardam a geração terminar. Solicitações de alta resolução ou alta qualidade podem levar perto de um minuto ou mais, então configure o timeout do seu cliente HTTP para pelo menos 120s. Se a resposta de criação incluir status: "pending", task_id ou poll_url, siga o poll_url retornado.

RespostaCopy Anchor Link

Resposta em linhaCopy Anchor Link

Resposta de tarefa assíncronaCopy Anchor Link

Defina async: true com gpt-image-2 ou modelos de imagem oficiais FLUX/BFL para criar uma tarefa em vez de esperar pela imagem final na solicitação de criação. A resposta inclui status: "pending", task_id e poll_url. Consulte /v1/tasks/{task_id} até a tarefa chegar a completed ou failed.

Tarefas assíncronas de imagem retornam apenas URLs das imagens finais. Se precisar dos dados brutos b64_json, use uma solicitação síncrona.

A criação da tarefa pode reservar o valor estimado. Tarefas concluídas são cobradas pelo uso real; tarefas com falha ou timeout liberam ou reembolsam a reserva.

Quando você receber status: "pending", use poll_url ou GET /v1/tasks/{task_id} para recuperar o 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 disponíveisCopy Anchor Link

Consulte GET /v1/models?recommended_for=image para ver os modelos de imagem, capacidades e preços atuais.

Não assuma que um modelo é sempre síncrono ou sempre assíncrono. Se a resposta de criação retornar status: "pending", siga poll_url e faça polling até a conclusão.

Lidando com respostas baseadas em tarefaCopy Anchor Link

Para modelos de imagem, sempre verifique se a resposta contém status: "pending" / status: "processing":

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # Criar solicitação de imagem
    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()

    # Verifica se é baseada em tarefa
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Tarefa de imagem iniciada: {task_id}")

        # Fazer polling do 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", "Falha na geração"))

            time.sleep(3)
    else:
        # Resposta em linha
        return data["data"][0]["url"]

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

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