API de Edição de Imagens GPT no TokenLab: Endpoint Correto e Formatos de Entrada de Imagem

A edição de imagens é uma das partes mais exigentes da superfície de um produto de IA: o usuário envia uma foto, descreve uma alteração e espera um resultado. Edições que usam várias imagens de origem, uma tela ampla ou um prompt mais pesado demoram mais do que uma chamada HTTP síncrona típica permite confortavelmente. Este guia aborda o endpoint correto do TokenLab, os dois formatos de entrada de imagem suportados, edições com múltiplas imagens e o caminho assíncrono para requisições lentas.

The endpoint

A edição de imagens fica em POST /v1/images/edits — observe o plural edits. (Um erro comum é escrever /images/edit, que não é o caminho documentado.)

O endpoint suporta dois formatos de requisição:

• Um fluxo de upload multipart/form-data compatível com a OpenAI.
• Uma requisição JSON que fornece referências de image_url, image_urls ou images[] oficiais para famílias imagem-para-imagem suportadas.

Os campos completos de requisição e resposta estão documentados na Referência da API de Edição de Imagem.

What gpt-image-2 accepts here

• Uploads image em multipart.
• image_url ou image_urls em JSON.
• Referências oficiais de images[], onde cada objeto contém exatamente um entre image_url ou file_id.
• Até 16 imagens de origem por requisição.

Algumas restrições que vale a pena conhecer antes de escrever código:

• As edições com gpt-image-2 não aceitam resolution; use size para as dimensões de saída (auto ou WIDTHxHEIGHT, com dimensões em múltiplos de 16, lado mais longo no máximo em 3840px e proporção lado maior/menor de no máximo 3:1).
• background aceita auto ou opaque; transparent não é suportado.
• input_fidelity não faz parte dos campos suportados para o gpt-image-2; enviá-lo retorna 400 unsupported_parameter.
• Para requisições JSON, forneça exatamente um entre image_url, image_urls ou images. Cada objeto em images[] deve conter exatamente um entre image_url ou file_id. Os valores de file_id devem ser criados primeiro via /v1/files.
• Requisições com imagem de referência do Nano Banana pertencem a /v1/images/generations com operation: "image-to-image" e image_urls — não a /v1/images/edits.

Multipart uploads vs JSON image references

Ambos funcionam para o gpt-image-2. Escolha aquele que corresponder a onde os bytes da sua imagem já estão.

Multipart — use isto quando a aplicação tiver o arquivo, seja de um upload do usuário ou de um recurso gerado. Repita o campo image para enviar várias fontes. Os arquivos devem ser PNG, JPEG ou WebP, com no máximo 50 MiB cada.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

URLs de imagem em JSON — use isto quando as imagens já estiverem em uma URL pública, ou se você as gerou em uma requisição anterior do TokenLab e já possui uma URL.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

URLs remotas devem ser públicas em http/https, sem credenciais embutidas ou fragmentos, e não devem resolver para localhost, faixas de IP privadas ou reservadas. O TokenLab busca os bytes e os entrega ao modelo como partes image em multipart. O limite por imagem é de 50 MiB; o limite agregado para imagens buscadas via URL em uma única requisição é de 200 MiB; o tempo limite (timeout) de busca é de 30 segundos; até 3 redirecionamentos são seguidos.

Multi-image edits and async polling

Edições com múltiplas imagens são o caso mais evidente para usar async: true. Enviar várias imagens com um conjunto complexo de instruções por meio de uma chamada síncrona significa manter uma conexão aberta por quanto tempo o modelo precisar. Defina async: true no gpt-image-2 (e nos modelos de edição oficiais do FLUX/BFL) para receber uma tarefa em vez disso:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Faça polling na poll_url retornada, ou use como alternativa o GET /v1/tasks/{task_id}. Os status são pending, processing, completed e failed. Uma tarefa de imagem concluída retorna data[].url. Fazer a verificação a cada 3–5 segundos é suficiente; pare em um status terminal em vez de continuar fazendo polling.

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

Tarefas assíncronas de edição retornam URLs finais de imagem, independentemente do response_format solicitado. Se você precisar do b64_json bruto, use uma requisição síncrona.

O faturamento pode reservar o valor estimado quando a tarefa for criada; uma tarefa concluída é faturada pelo uso real, e uma tarefa que falhou ou expirou por tempo limite libera ou reembolsa a reserva. Consulte Trabalhos assíncronos e polling para o ciclo de vida completo e Obter Status da Imagem para os campos de resposta.

When to use each mode

Use async: true quando:

• Você estiver enviando várias imagens de origem em uma única requisição.
• Seu prompt ou conjunto de instruções for complexo o suficiente para tornar o tempo de geração imprevisível.
• Você executar edições em um job em segundo plano, fila ou processo em lote, em vez de uma requisição em tempo real voltada para o usuário.

Mantenha síncrono quando:

• Você estiver fazendo uma edição de imagem única com um prompt curto.
• Seu cliente preferir falhar rapidamente em vez de fazer polling.

Para chamadas síncronas, defina o tempo limite (timeout) do seu cliente HTTP para pelo menos 120s; requisições de alta resolução ou alta qualidade podem levar cerca de um minuto ou mais. Se a resposta de criação ainda retornar com status: "pending", task_id ou poll_url, mude para o fluxo de polling retornado.

Input errors to expect

Falhas na busca de imagens remotas são retornadas como erros de entrada antes do início da geração. URLs inacessíveis, timeouts, respostas 403/404, hosts privados ou internos, credenciais ou fragmentos na URL, conteúdo que não seja imagem, formatos não suportados e violações de limite de tamanho retornam 400 ou 413 e identificam a image_url ou image_urls[n] causadora do problema. Para recursos privados ou protegidos por cabeçalho, envie os arquivos image em multipart diretamente, ou crie referências em /v1/files e passe-as como images[].file_id.

Os modelos de edição de imagem do xAI Grok Imagine (por exemplo, grok-imagine-image e grok-imagine-image-quality) usam os mesmos campos de entrada, mas limitam as imagens de origem a 3; mais do que isso retorna 400 too_many_images.

Integration checklist

• Direcione para POST /v1/images/edits e envie o model explicitamente.
• Escolha uploads multipart ou referências JSON com base em onde suas imagens já estão armazenadas.
• Envie exatamente um entre image_url, image_urls ou images[] em requisições JSON; cada entrada de images[] tem exatamente um entre image_url ou file_id.
• Use async: true para edições pesadas ou com múltiplas imagens; faça polling na poll_url retornada até que a tarefa alcance completed ou failed.
• Defina os timeouts do cliente para pelo menos 120 segundos para requisições síncronas e trate uma resposta pending seguindo a poll_url.
• Em caso de timeout no cliente, verifique se uma tarefa foi criada antes de tentar novamente a requisição de criação para evitar cobranças duplicadas.

Get started

Consulte GET /v1/models?recommended_for=image para ver os modelos de imagem atuais e, em seguida, abra a página de detalhes de um modelo para confirmar suas operações e campos de requisição suportados antes de enviar uma requisição. Crie uma chave de API no console para testar o endpoint de edição com suas próprias imagens.