Imagens
Editar Imagem
Edite uma imagem a partir de um prompt e uma imagem de origem
Visão Geral
Cria uma imagem editada ou estendida a partir de uma imagem original e um prompt.
Este endpoint suporta ambos:
- o fluxo de upload
multipart/form-datacompatível com OpenAI documentado abaixo - requisições JSON que fornecem
image_url,image_urlsou referências oficiaisimagespara famílias de imagem-para-imagem suportadas
O gpt-image-2 é suportado aqui. Ele aceita uploads multipart de image, image_url / image_urls em JSON e referências oficiais images[] (image_url ou file_id), com até 16 imagens de origem. Crie valores de file_id através de /v1/files primeiro. Defina async: true para retornar uma tarefa primeiro; modelos de edição oficiais FLUX/BFL também usam o mesmo fluxo de polling de tarefas.
Edições com gpt-image-2 não aceitam resolution; use size para dimensões de saída. background aceita auto ou opaque; transparent não é suportado. Para edições com múltiplas imagens ou alta latência, prefira async: true e faça o polling da tarefa retornada.
Requisições de imagem de referência do Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite e nano-banana-pro) são expostas em /v1/images/generations com operation: "image-to-image" e image_urls, não neste endpoint /v1/images/edits. Requisições de edição de imagem para nano-banana-2, nano-banana-2.1, nano-banana-2-lite e nano-banana-pro também usam /v1/images/generations, com operation: "image-edit".
gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image e gemini-3-pro-image usam este endpoint para edição de imagem. Suas requisições de imagem-para-imagem usam /v1/images/generations com operation: "image-to-image".
Modelos de edição de imagem xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality e o legado grok-imagine-image-pro) aceitam no máximo 3 imagens de origem. Requisições com mais de 3 imagens de origem falham na validação de entrada com 400 too_many_images.
input_fidelity não faz parte dos campos suportados atualmente pelo TokenLab para gpt-image-2; omita-o ou a requisição retornará 400 unsupported_parameter.
Corpo da Requisição
Timeout de requisição síncrona: Algumas requisições de imagem retornam a imagem final em linha e aguardam a conclusão da geração. Requisições de alta resolução ou alta qualidade podem levar cerca de um minuto ou mais, portanto, defina o timeout do seu cliente HTTP para pelo menos 120s. Se a resposta de criação incluir status: "pending", task_id ou poll_url, siga a poll_url retornada.
URLs de imagem remotas: quando a entrada multipart é necessária, o TokenLab busca image_url, image_urls ou images[].image_url em JSON e envia os bytes como partes multipart de image. As URLs devem ser http/https públicas, sem credenciais ou fragmentos incorporados, e não devem resolver para localhost, IPs privados ou faixas de IP reservadas; cada redirecionamento é verificado novamente. O payload buscado deve ser uma imagem PNG, JPEG ou WebP real. Os limites são 50 MiB por imagem, 200 MiB no total para imagens buscadas via URL em uma única requisição, 30s de timeout de busca e até 3 redirecionamentos.
Para requisições JSON, forneça exatamente um entre image_url, image_urls ou images. Cada objeto images[] deve conter exatamente um entre image_url ou file_id. O limite agregado de 200 MiB inclui todas as imagens de origem e a máscara.
Imagens de origem multipart. Repita image para fornecer múltiplas fontes de GPT Image. Os arquivos devem ser PNG, JPEG ou WebP, com até 16 imagens de origem e 50 MiB cada. Modelos de edição xAI Grok Imagine usam os mesmos campos de entrada, mas limitam as imagens de origem a 3.
Uma descrição em texto da edição desejada.
Uma imagem adicional cujas áreas totalmente transparentes indicam onde a imagem deve ser editada. Deve ser um arquivo PNG válido, com menos de 50 MiB e ter as mesmas dimensões da image.
Para requisições JSON, mask também pode ser um objeto com exatamente um entre image_url ou file_id; valores de file_id devem vir de /v1/files e permanecer vinculados à mesma configuração de edição de imagem.
O modelo a ser usado para edições de imagem. Use gpt-image-2 para edições com GPT Image, ou outro modelo de edição de imagem atual retornado por GET /v1/models?recommended_for=image.
1Número de imagens a serem geradas (1-10, dependente do modelo).
O tamanho da imagem gerada. Para gpt-image-2, use auto ou WIDTHxHEIGHT; as dimensões devem ser múltiplos de 16, a borda mais longa com no máximo 3840px, a proporção longo/curto com no máximo 3:1 e o total de pixels entre 655.360 e 8.294.400.
Para gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image e gemini-3.1-flash-lite-image, size aceita um tamanho de saída da tabela de tamanhos do modelo ou um nível de resolução: 1K, 2K ou 4K. O TokenLab envia um nível como resolution. Um nível que o modelo não suporta, ou um nível diferente de resolution, retorna 400 com o código invalid_image_size_contract. A forma recomendada é aspect_ratio com resolution.
Como as imagens são retornadas: url ou b64_json.
- Omitido: quando o modelo retorna bytes de imagem, cada imagem está em
data[].b64_jsone também emdata[].urlquando o TokenLab a armazena. Quando o modelo retorna um link, cada imagem está emdata[].url. url: cada imagem está apenas emdata[].url.b64_json: cada imagem está apenas emdata[].b64_jsoncomo dados Base64.
Os links são URLs de resultados de mídia do TokenLab. Eles permanecem válidos por 30 dias. Veja Retenção de dados.
falseDefina como true com gpt-image-2 ou modelos de edição oficiais FLUX/BFL para retornar uma tarefa antes que a imagem final esteja pronta. Edições assíncronas concluídas retornam URLs independentemente do response_format solicitado; use requisições síncronas quando precisar de b64_json.
Um identificador único representando seu usuário final para monitoramento de abuso.
Resposta
Timestamp Unix de quando as imagens foram criadas.
Array de imagens geradas.
Cada objeto contém:
url(string): URL de resultado de mídia do TokenLab da imagem editada, válida por 30 dias. Não presente quandoresponse_formatéb64_json. Quandoresponse_formaté omitido, ela estará ausente se o TokenLab não puder armazenar a imagem.b64_json(string): Dados de imagem em Base64. Presente quandoresponse_formatéb64_json, ou quando é omitido e o modelo retorna bytes de imagem.
Resposta de Tarefa Assíncrona
Defina async: true com gpt-image-2 ou modelos de edição oficiais FLUX/BFL para criar uma tarefa em vez de aguardar a imagem editada na requisição. A resposta inclui status: "pending", task_id e poll_url. Faça o polling de /v1/tasks/{task_id} até que a tarefa atinja completed ou failed.
Tarefas de edição assíncronas retornam apenas URLs de imagem final. Se você precisar de dados de imagem b64_json brutos, use uma requisição síncrona.
O faturamento pode reservar o valor estimado quando a tarefa é criada. Tarefas concluídas são cobradas pelo uso real, e tarefas com falha ou que excederam o tempo limite são liberadas ou reembolsadas.
Requisição
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image=@sunlit_lounge.png" \
-F "mask=@mask.png" \
-F "prompt=A sunlit indoor lounge area with a pool" \
-F "n=1" \
-F "size=1024x1024"Resposta
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Notas
Falhas na busca de imagens remotas são retornadas como erros de entrada antes que a geração comece. URLs inacessíveis, timeouts, respostas 403/404, hosts privados/internos, credenciais ou fragmentos na URL, conteúdo que não é imagem, formatos não suportados e violações de limite de tamanho retornam 400 ou 413 e identificam a entrada image_url / image_urls[n]. Para ativos privados ou protegidos por cabeçalho, faça upload de arquivos image multipart diretamente ou crie referências em /v1/files.
O Hy Image 3.5 Preview cria imagens quadradas de 1024 pixels a partir de texto e edita imagens de referência usando instruções escritas. É útil para esboçar visuais e refinar uma composição.
{
"model": "hy-image-v3.5-preview",
"prompt": "Change the table to pale blue",
"image_url": "https://example.com/reference.png",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Autorização
BearerAuth Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Cabeçalhos
Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.
Valores permitidos
- "auto"
- "verified"
- "official"
Resposta
application/json
application/json
application/json
application/json
application/json
application/json