Guias de mídia

Geração de imagens

Gere ou edite imagens e gerencie arquivos finalizados ou tarefas assíncronas

O TokenLab oferece suporte a text-to-image, image-to-image e edição de imagens. Os parâmetros variam de acordo com o modelo, portanto, verifique os campos de requisição do modelo selecionado antes de enviar a solicitação.

Escolha um endpoint

O que você precisaEndpointUse quandoNão use para
Text-to-imagePOST /v1/images/generationsO usuário começa apenas com textoEditar um arquivo de imagem GPT existente
Image-to-imagePOST /v1/images/generationsO modelo aceita operation: "image-to-image" e URLs de imagemModelos que exigem entrada de edição multipart
Edição de imagemPOST /v1/images/editsUm modelo de edição compatível altera uma imagem existenteGeração de referência estilo Nano Banana
VariaçãoPOST /v1/images/variationsUma integração existente já utiliza a API de variaçõesUm novo recurso de imagem de referência
StatusGET /v1/tasks/{id}Uma resposta de criação retorna task_id, status: "pending" ou poll_urlA resposta de criação já contém data[] final

Sempre envie o model; as APIs de imagem não escolhem um modelo padrão para você.

Escolha um modelo

Encontre os modelos de imagem atuais com:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Abra os detalhes do modelo selecionado para confirmar:

  • A operação suportada, como text-to-image, image-to-image ou image-edit.
  • O endpoint de requisição esperado pelo modelo.
  • Como enviar referências: image_url, image_urls, reference_image_urls, multipart image ou JSON images[].
  • Se o modelo aceita size, aspect_ratio, resolution, quality, background, output_format ou response_format.

Campos específicos do modelo

  • Requisições no estilo gpt-image-2 usam size, quality e campos de edição semelhantes aos da OpenAI. Para geração e edições com este modelo, background aceita auto ou opaque; transparent não é suportado. Omita campos opcionais para usar os padrões automáticos.
  • As famílias de imagem Gemini e Nano Banana geralmente usam aspect_ratio; envie resolution apenas quando os detalhes do modelo a exibirem. Em modelos com níveis de resolução, um size de 1K, 2K ou 4K é enviado como resolution; um nível diferente de resolution será recusado.
  • O image-to-image do Nano Banana pertence a /v1/images/generations com operation: "image-to-image" e URLs de imagem de referência.
  • /v1/images/generations não aceita images[] ou file_id de nível superior; esses são formatos de fluxo de edição.
  • Referências de imagem remotas devem ser URLs http ou https públicas. Não envie URLs de rede privada, credenciais incorporadas, fragmentos de URL ou URLs assinadas que possam expirar antes do início do processamento.

Exemplo de text-to-image

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

Exemplo de imagem de referência

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Obtenha a imagem

As respostas de imagem podem ser síncronas ou assíncronas:

  • Respostas síncronas retornam o data[] final com url ou b64_json.
  • Respostas assíncronas retornam id, task_id, status e, geralmente, poll_url. Envie "async": true em um modelo que suporte execução assíncrona pública para obter uma tarefa em vez de aguardar a imagem.
  • Para verificar uma tarefa assíncrona, chame GET /v1/tasks/{id} com o id ou task_id retornado.
  • Use uma requisição síncrona quando precisar de b64_json; resultados de imagem assíncronos usam URLs.

As URLs de resultado de imagem são URLs de mídia do TokenLab que permanecem válidas por 30 dias. media_retention.items relata o status de salvamento de cada item e expires_at; a resposta pode omitir media_retention quando o status de salvamento não é conhecido a tempo, e a URL ainda funcionará. Resultados Base64 em linha estão fora desta retenção de cópia de URL. Salvar manualmente uma imagem na Biblioteca de Mídia confere a ela um ciclo de vida separado. Veja Retenção de dados.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Persista a URL da imagem retornada, o ID da tarefa, o modelo e seu próprio ID de usuário/trabalho. Não continue consultando após um status terminal.

Antes do lançamento

  • Valide as entradas do usuário antes de chamar o TokenLab: tamanho do prompt, contagem de imagens, acessibilidade da URL e tipo de arquivo.
  • Defina os timeouts de HTTP suficientemente altos para requisições síncronas de alta resolução. Use async: true onde o modelo suportar para trabalhos longos.
  • Armazene request_id, task_id, poll_url, modelo, endpoint e os nomes dos campos enviados.
  • Quando uma requisição de imagem retorna uma tarefa, um Idempotency-Key torna a requisição de criação segura para repetir: após um timeout do cliente, envie a mesma requisição com a mesma chave para obter essa tarefa. Para uma requisição que retorna a imagem diretamente, uma repetição com a mesma chave pode retornar um status de tarefa em vez da imagem, ou 409 com idempotent_response_not_replayable. Sem uma chave, verifique se uma tarefa foi criada antes de repetir.
  • Use Usage e billing_transaction_id para a cobrança final.

Erros comuns

SintomaCausa provávelCorreção
400 com param: "model"Modelo explícito ausenteConsulte /v1/models?recommended_for=image e envie model
Campo não suportadoO campo não está documentado para esse modeloRemova o campo ou escolha um modelo/endpoint que o documente
Sem b64_json no resultado assíncronoTarefas de imagem assíncronas retornam resultados orientados a URLUse o modo síncrono para saída base64
Imagem de referência rejeitadaEndpoint incorreto ou URL privada/expiradaCombine com o formato de referência documentado do modelo e use URLs acessíveis

Referência da API

TópicoReferência
Criar imagemCriar imagem
Editar imagemEditar imagem
Criar variação de imagemCriar variação de imagem
Obter status da imagemObter status da imagem
Obter status da tarefaObter status da tarefa

Nesta página