Saltar para o conteúdo principal

Visão geral

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. 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 do 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 modelos

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 mais resolution (1k, 2k, 4k) apenas para text-to-image no contrato atual da TokenLab.
  • 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.
  • Em solicitações Nano Banana image-to-image, nano-banana-pro pode incluir resolution (1k, 2k, 4k); nano-banana-edit deve omiti-lo. nano-banana e nano-banana-2 são modelos text-to-image no detalles del modelo atual.
  • 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ção

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.
model
string
obrigatório
Modelo a usar (por exemplo, gpt-image-2, flux-pro, qwen-image-plus ou nano-banana-pro). Consulte GET /v1/models?recommended_for=image para a lista recomendada atual.
prompt
string
obrigatório
Descrição em texto da imagem desejada.
image_url
string
URL HTTPS pública de imagem de referência para geração image-to-image. Em solicitações Nano Banana com imagem de referência, defina operation como image-to-image; nano-banana-pro pode incluir resolution, enquanto nano-banana-edit deve omiti-lo.
image_urls
string[]
URLs HTTPS públicas de imagens de referência. Use para uma ou mais imagens de referência em requests JSON. file_id e images[] não são suportados neste endpoint.
reference_image_urls
string[]
URLs adicionais de imagens de referência específicas do modelo para provedores que distinguem imagens principais de referências.
image
file
Arquivo multipart de imagem de referência para geração image-to-image. Use quando a imagem de origem for privada ou exigir headers. Isso não é um file_id de /v1/files; este endpoint não aceita file_id.
n
integer
padrão:"1"
Número de imagens a gerar (1-10, dependendo do modelo).
size
string
padrão:"1024x1024"
Tamanho da imagem. Use isto para famílias de imagem no estilo OpenAI e outros modelos que aceitam tamanhos exatos em pixels.Para gpt-image-2, size aceita auto ou WIDTHxHEIGHT. Dimensões personalizadas devem ter ambos os lados como múltiplos de 16, a maior aresta deve ter no máximo 3840px, a razão maior/menor lado deve ser no máximo 3:1, e o total de pixels deve ficar entre 655,360 e 8,294,400. aspect_ratio e resolution não fazem parte do detalles del modelo atual da TokenLab para gpt-image-2.Para famílias de imagem Google Gemini, size é tratado como um alias de compatibilidade que mapeia para o detalles del modelo de aspect_ratio do modelo e, quando suportado, para resolution. Para esses modelos, prefira enviar aspect_ratio diretamente.
aspect_ratio
string
Seletor de proporção dependente do modelo.Valores comuns para as famílias de imagem do Google incluem 1:1, 16:9, 9:16, 3:2 e 2:3.
resolution
string
Seletor de resolução de saída dependente do modelo.Suportado em gemini-3.1-flash-image e gemini-3-pro-image para text-to-image e image-edit, em nano-banana-pro para text-to-image e image-to-image, e em nano-banana-2 apenas para text-to-image. Os valores típicos são 1k, 2k e 4k. Não envie esse parâmetro para famílias de imagem Gemini que só aceitam proporção, a menos que o modelo documente isso explicitamente. Para modelos de imagem xAI Grok Imagine, use 1k ou 2k.
quality
string
padrão:"standard"
Qualidade da imagem. Modelos GPT Image como gpt-image-2 usam auto, low, medium ou high. Outras famílias de imagem podem usar valores específicos do provedor; verifique os metadados do modelo antes de enviar valores não padrão.
response_format
string
padrão:"url"
Formato da resposta: url ou b64_json. O padrão é url.Para solicitações gpt-image-2 Azure Official ou compatíveis com Azure, a TokenLab recebe os dados de imagem como b64_json. Para solicitações url, a TokenLab envia cada imagem ao CDN e retorna data[].url. Se o armazenamento CDN estiver indisponível ou o upload falhar, a solicitação falha em vez de ser convertida em uma resposta Base64. Para b64_json, o Base64 bruto é retornado.
async
boolean
padrão:"false"
Defina como true com gpt-image-2 ou modelos de imagem oficiais FLUX/BFL para criar uma tarefa primeiro. Tarefas assíncronas concluídas retornam URLs independentemente do response_format solicitado; use solicitações síncronas se precisar de b64_json.
style
string
Seletor de estilo opcional. Envie apenas quando o modelo selecionado documentar explicitamente esse parâmetro; omita para gpt-image-2 a menos que os metadados do modelo indiquem o contrário.
user
string
Um identificador único para o usuário final.

Resposta

Resposta em linha

created
integer
Timestamp Unix da criação.
data
array
Array de imagens geradas.Cada objeto contém:
  • url (string): URL da imagem gerada
  • b64_json (string): Imagem codificada em Base64 (se solicitada)
  • revised_prompt (string): Revisão opcional do prompt quando o modelo selecionado a retorna

Resposta de tarefa assíncrona

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.
created
integer
Timestamp Unix de criação.
task_id
string
Identificador único da tarefa para polling.
status
string
Status inicial: pending.
poll_url
string
URL relativa para fazer polling dos resultados, por exemplo /v1/tasks/{id}.
data
array
Vazio enquanto a tarefa estiver pendente. Tarefas de imagem concluídas retornam URLs de imagens geradas em data[].url.
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",
    "n": 1
  }'
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",
    aspect_ratio="16:9",
    resolution="2k",
    n=1
)

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',
  n: 1
});

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',
        'n' => 1
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];
Exemplo de família de imagem que só aceita proporção: para gemini-2.5-flash-image, nano-banana ou nano-banana-edit, envie aspect_ratio mas omita resolution:
{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}
Exemplo Nano Banana Pro com imagem de referência: envie a solicitação para /v1/images/generations, não para /v1/images/edits. resolution é opcional e pode ser 1k, 2k ou 4k:
{
  "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"
}
Para imagens de origem privadas ou locais, faça upload multipart direto. Não envie file_id para /v1/images/generations:
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..."
    }
  ]
}
{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Modelos disponíveis

Estes são exemplos atuais, não um catálogo fixo. Consulte GET /v1/models?recommended_for=image ou a página Models para disponibilidade e preços atualizados.
ModeloTipoRecursos
gpt-image-2Em linha ou baseado em tarefaModelo GPT Image com preço por token e tamanhos flexíveis
flux-proFrequentemente baseado em tarefaFotorrealista, alta qualidade
qwen-image-plusFrequentemente baseado em tarefaBom render de texto e aderência ao prompt
nano-banana-proFrequentemente baseado em tarefaWorkflows com imagem de referência e saída em alta resolução
grok-imagine-imageFrequentemente baseado em tarefaGeração de imagem xAI com seleção de aspecto e resolução
ideogram-v3Frequentemente baseado em tarefaBom render de texto
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 tarefa

Para modelos de imagem, sempre verifique se a resposta contém status: "pending":
import requests
import time

def generate_image(prompt, model="flux-pro"):
    # 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}
    )
    data = response.json()

    # Verifica se é baseada em tarefa
    if data.get("status") == "pending":
        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"}
            )
            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="flux-pro")
print(f"Imagem gerada: {url}")