Skip to main content

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. 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 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 nos detalhes atuais do modelo.
  • 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.
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.
string
obrigatório
Descrição em texto da imagem desejada.
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.
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.
string[]
URLs adicionais de imagens de referência específicas do modelo para provedores que distinguem imagens principais de referências.
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.
integer
padrão:"1"
Número de imagens a gerar (1-10, dependendo do modelo).
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 dos detalhes atuais do modelo da TokenLab para gpt-image-2.Para famílias de imagem Google Gemini, size é tratado como um alias de compatibilidade que mapeia para o aspect_ratio nos detalhes do modelo e, quando suportado, para resolution. Para esses modelos, prefira enviar aspect_ratio diretamente.
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.
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.
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.
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.
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.
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.
string
Um identificador único para o usuário final.

Resposta

Resposta em linha

integer
Timestamp Unix da criação.
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.
integer
Timestamp Unix de criação.
string
Identificador único da tarefa para polling.
string
Status inicial: pending.
string
URL relativa para fazer polling dos resultados, por exemplo /v1/tasks/{id}.
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.

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