Geração de Imagem

​

Quando Usar Cada Endpoint

​

Escolha Um Modelo

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

• A operação suportada, como text-to-image, image-to-image ou image-edit.
• O endpoint de solicitação esperado pelo modelo.
• Qual forma usar para referências, como 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.

​

Regras de Forma de Solicitação

• Solicitações estilo gpt-image-2 usam campos de size, quality e edição semelhantes aos da OpenAI. Para geração e edição, background aceita auto ou opaque; transparent não é suportado. Deixe de fora os campos opcionais quando você quiser que o modelo ou o TokenLab usem padrões automáticos.
• As famílias de imagem Gemini e Nano Banana geralmente usam aspect_ratio; envie resolution apenas quando o detalhe do modelo o expuser.
• A geração de imagem-para-imagem 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 públicas http ou https. Não envie URLs de rede privada, credenciais incorporadas, fragmentos de URL ou URLs assinadas que possam expirar antes que o processamento comece.

​

Exemplo de Texto-Para-Imagens

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": "Uma foto de produto limpa de uma xícara de café de cerâmica em uma mesa de nogueira",
    "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",
    "operation": "image-to-image",
    "prompt": "Mantenha a forma do produto, mude o fundo para um estúdio brilhante",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

​

Manipulação de Resultados

• Respostas síncronas retornam data[] final com url ou b64_json.
• Respostas assíncronas retornam id, task_id, status e geralmente poll_url.
• Prefira poll_url quando estiver presente. Se você precisar de uma rota fixa, consulte GET /v1/tasks/{id}.
• Use solicitações síncronas quando você precisar especificamente de b64_json; resultados de imagem assíncronos são orientados a URL.

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

​

Lista de Verificação de Produção

• Valide as entradas do usuário antes de chamar o TokenLab: comprimento do prompt, contagem de imagens, acessibilidade da URL e tipo de arquivo.
• Defina os timeouts HTTP altos o suficiente para solicitações síncronas de alta resolução. Use o modo assíncrono onde disponível para trabalhos longos.
• Armazene request_id, task_id, poll_url, modelo, endpoint e forma de solicitação sanitizada para suporte.
• Em caso de timeout do cliente, verifique se uma tarefa foi criada antes de tentar novamente a solicitação de criação.
• Reconcilie o custo com registros de uso e billing_transaction_id quando presente, não com IDs de tarefas do provedor.

​

Erros Comuns

​

Referência da API