Criar Imagem

Visão GeralCopy Anchor Link

Use GET /v1/models?recommended_for=image para obter os modelos de imagem atuais e, em seguida, envie o model selecionado explicitamente.

gpt-image-2 é um modelo GPT Image precificado por token. O TokenLab segue a divisão de uso oficial da OpenAI para tokens de entrada de texto, entrada de imagem, entrada em cache reportada e saída de imagem; ele não é cobrado como um modelo de preço fixo por imagem.

Para a geração de imagem com gpt-image-2, os parâmetros públicos suportados 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. Omita size ou quality para permitir que o TokenLab use auto; valores personalizados de size devem usar o contrato flexível WIDTHxHEIGHT documentado abaixo.

input_fidelity não faz parte dos campos suportados atualmente pelo TokenLab para gpt-image-2; omita-o ou a requisição retornará 400 unsupported_parameter.

Notas sobre o comportamento do modeloCopy Anchor Link

Os modelos da família de imagem Google Gemini não compartilham o mesmo contrato de seletor:

• gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2.1 e nano-banana-pro suportam aspect_ratio além de resolution (1k, 2k, 4k) para suas operações públicas de texto para imagem, imagem para imagem e edição de imagem.
• nano-banana-2 suporta aspect_ratio e resolution (1k, 2k, 4k) tanto para geração de texto para imagem quanto de imagem para imagem.
• gemini-3.1-flash-lite-image e nano-banana-2-lite suportam texto para imagem, imagem para imagem e edição de imagem apenas na resolução 1k.
• nano-banana suporta aspect_ratio, mas não expõe a seleção pública de resolution.
• Para imagem para imagem com gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image ou gemini-3-pro-image, use este endpoint com operation: "image-to-image" e imagens de referência. Envie requisições de edição de imagem para esses modelos para /v1/images/edits.
• Para requisições de imagem de referência do Nano Banana, use nano-banana-2, nano-banana-2.1, nano-banana-2-lite ou nano-banana-pro neste endpoint (/v1/images/generations) com operation: "image-to-image" e image_urls. Requisições de edição de imagem para nano-banana-2, nano-banana-2.1, nano-banana-2-lite e nano-banana-pro também usam este endpoint, com operation: "image-edit". Não envie requisições de imagem de referência do Nano Banana para /v1/images/edits.
• Imagens de referência neste endpoint podem ser fornecidas como image_url / image_urls em JSON, ou como um arquivo image multipart. images[] e file_id não são aceitos em /v1/images/generations; crie referências /v1/files apenas para modelos de /v1/images/edits que documentam images[].file_id.

Para 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-2.0 e o legado grok-imagine-image-pro) suportam aspect_ratio além de resolution (1k, 2k). grok-imagine-image-pro é mantido como um ID de compatibilidade para grok-imagine-image-2.0.

Corpo da RequisiçãoCopy Anchor Link

Timeout de requisição síncrona: Algumas requisições de imagem retornam a imagem final em linha e aguardam a conclusão da geração. Requisições de alta resolução ou alta qualidade podem levar quase um minuto ou mais, portanto, defina 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 a poll_url retornada.

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 aguardar a imagem final na requisição de criação. A resposta inclui status: "pending", task_id e poll_url. Consulte /v1/tasks/{task_id} até que a tarefa atinja completed ou failed.

Tarefas de imagem assíncronas retornam apenas URLs de imagem final. Se você precisar de dados de imagem b64_json brutos, use uma requisição síncrona.

O faturamento pode reservar o valor estimado quando a tarefa é criada. Tarefas concluídas são cobradas pelo uso real, e tarefas com falha ou que excederam o tempo limite são liberadas ou reembolsadas.

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

Escolha um ModeloCopy Anchor Link

Consulte GET /v1/models?recommended_for=image ou use a página de Modelos para disponibilidade, capacidades e preços atuais.

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

Lidando com Respostas Baseadas em TarefasCopy Anchor Link

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

import requests
import time

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

    # Verificar 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}")

        # Consultar 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", "A geração falhou"))

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