Geração de Imagem

TokenLab suporta texto-para-imagem, imagem-para-imagem e edição de imagem através de endpoints de imagem públicos. Os modelos de imagem não compartilham um conjunto universal de parâmetros, portanto, os clientes de produção devem primeiro escolher o endpoint, depois escolher o modelo e, em seguida, enviar apenas os campos suportados por esse modelo.

Quando Usar Cada EndpointCopy Anchor Link

Sempre envie model. Os endpoints de imagem intencionalmente não dependem de um modelo padrão implícito histórico para tráfego de produção.

Escolha Um ModeloCopy Anchor Link

Comece com a descoberta do modelo e, em seguida, inspecione o contrato do TokenLab do modelo selecionado:

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

Para modelos não de chat, a resposta da lista pode incluir GET /v1/models. As páginas de detalhes do modelo podem expor o GET /v1/models/{model} mais completo. Use esses campos para confirmar:

• 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çãoCopy Anchor Link

• 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-ImagensCopy Anchor Link

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ênciaCopy Anchor Link

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": "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 ResultadosCopy Anchor Link

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

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

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

Lista de Verificação de ProduçãoCopy Anchor Link

• 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 ComunsCopy Anchor Link

Referência da APICopy Anchor Link