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ê precisa | Endpoint | Use quando | Não use para |
|---|---|---|---|
| Text-to-image | POST /v1/images/generations | O usuário começa apenas com texto | Editar um arquivo de imagem GPT existente |
| Image-to-image | POST /v1/images/generations | O modelo aceita operation: "image-to-image" e URLs de imagem | Modelos que exigem entrada de edição multipart |
| Edição de imagem | POST /v1/images/edits | Um modelo de edição compatível altera uma imagem existente | Geração de referência estilo Nano Banana |
| Variação | POST /v1/images/variations | Uma integração existente já utiliza a API de variações | Um novo recurso de imagem de referência |
| Status | GET /v1/tasks/{id} | Uma resposta de criação retorna task_id, status: "pending" ou poll_url | A 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-imageouimage-edit. - O endpoint de requisição esperado pelo modelo.
- Como enviar referências:
image_url,image_urls,reference_image_urls, multipartimageou JSONimages[]. - Se o modelo aceita
size,aspect_ratio,resolution,quality,background,output_formatouresponse_format.
Campos específicos do modelo
- Requisições no estilo
gpt-image-2usamsize,qualitye campos de edição semelhantes aos da OpenAI. Para geração e edições com este modelo,backgroundaceitaautoouopaque;transparentnã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; envieresolutionapenas quando os detalhes do modelo a exibirem. Em modelos com níveis de resolução, umsizede1K,2Kou4Ké enviado comoresolution; um nível diferente deresolutionserá recusado. - O image-to-image do Nano Banana pertence a
/v1/images/generationscomoperation: "image-to-image"e URLs de imagem de referência. /v1/images/generationsnão aceitaimages[]oufile_idde nível superior; esses são formatos de fluxo de edição.- Referências de imagem remotas devem ser URLs
httpouhttpspú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 comurloub64_json. - Respostas assíncronas retornam
id,task_id,statuse, geralmente,poll_url. Envie"async": trueem 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 oidoutask_idretornado. - 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: trueonde 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-Keytorna 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, ou409comidempotent_response_not_replayable. Sem uma chave, verifique se uma tarefa foi criada antes de repetir. - Use Usage e
billing_transaction_idpara a cobrança final.
Erros comuns
| Sintoma | Causa provável | Correção |
|---|---|---|
400 com param: "model" | Modelo explícito ausente | Consulte /v1/models?recommended_for=image e envie model |
| Campo não suportado | O campo não está documentado para esse modelo | Remova o campo ou escolha um modelo/endpoint que o documente |
Sem b64_json no resultado assíncrono | Tarefas de imagem assíncronas retornam resultados orientados a URL | Use o modo síncrono para saída base64 |
| Imagem de referência rejeitada | Endpoint incorreto ou URL privada/expirada | Combine com o formato de referência documentado do modelo e use URLs acessíveis |
Referência da API
| Tópico | Referência |
|---|---|
| Criar imagem | Criar imagem |
| Editar imagem | Editar imagem |
| Criar variação de imagem | Criar variação de imagem |
| Obter status da imagem | Obter status da imagem |
| Obter status da tarefa | Obter status da tarefa |