Imagens

Editar Imagem

Edite uma imagem a partir de um prompt e de uma imagem de origem

POST
/v1/images/edits

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-data compatível com a OpenAI documentado abaixo
  • requisições JSON que fornecem image_url, image_urls ou referências oficiais de images para famílias image-to-image suportadas

gpt-image-2 é suportado aqui. Ele aceita uploads multipart de image, JSON image_url / image_urls e referências oficiais de images[] (image_url ou file_id), com até 16 imagens de origem. Crie valores de file_id por meio de /v1/files primeiro. Defina async: true para retornar uma tarefa primeiro; cada modelo que lista async entre seus parâmetros suportados, como gpt-image-2 e os modelos de edição FLUX, usa o mesmo fluxo de polling de tarefas.

Edições com gpt-image-2 não aceitam resolution; use size para as dimensões de saída. background aceita auto ou opaque; transparent não é suportado. Para edições com múltiplas imagens ou de alta latência, prefira async: true e faça 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, e 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 image-edit. Suas requisições de image-to-image usam /v1/images/generations com operation: "image-to-image".

Os modelos de edição de imagem xAI Grok Imagine aceitam um número limitado de imagens de origem: grok-imagine-image-2.0 aceita no máximo 5, e grok-imagine-image aceita no máximo 3. Requisições com mais imagens de origem do que o modelo aceita falham na validação de entrada com 400 too_many_images. Suas requisições de image-to-image também usam este endpoint.

Os detalhes de cada modelo (GET /v1/models/{model}, consulte Obter Modelo) indicam o endpoint para cada operação em tokenlab.request_format_summary.request_endpoint_by_operation, bem como os campos aceitos e limites em tokenlab.request_format_details.operation_constraints. Uma operação enviada para o endpoint incorreto retorna 400 unsupported_endpoint.

input_fidelity não faz parte dos campos atualmente suportados pelo TokenLab para gpt-image-2; omita-o ou a requisição retornará 400 unsupported_parameter.

Corpo da Requisição

Tempo limite 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 tempo limite do seu cliente HTTP para pelo menos 120s. Se a resposta de criação incluir status: "pending", task_id ou poll_url, faça polling em GET /v1/tasks/{task_id}.

URLs de imagem remotas: quando a entrada multipart for necessária, o TokenLab busca image_url, image_urls ou images[].image_url do JSON e envia os bytes como partes image multipart. As URLs devem ser http/https públicas, sem credenciais incorporadas ou fragmentos, e não devem resolver para localhost, faixas de IP privadas ou reservadas; cada redirecionamento é verificado novamente. O payload buscado deve ser uma imagem real em PNG, JPEG ou WebP. Os limites são de 50 MiB por imagem, 200 MiB no total para imagens buscadas via URL em uma única requisição, tempo limite de busca de 30s 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.

imagefile

Imagens de origem multipart. Repita image para fornecer várias fontes do GPT Image. Os arquivos devem ser PNG, JPEG ou WebP, com até 16 imagens de origem e 50 MiB cada. Os modelos de edição do xAI Grok Imagine usam os mesmos campos de entrada, mas limitam as imagens de origem: no máximo 5 para grok-imagine-image-2.0 e no máximo 3 para os outros modelos de edição da xAI.

promptstringobrigatório

Uma descrição em texto da edição desejada, com até 32.000 caracteres. Obrigatório para todos os modelos cujos detalhes listem prompt. Ferramentas sem prompt, como stability-upscale-fast, são chamadas sem ele.

maskfile | object

Uma imagem adicional cujas áreas totalmente transparentes indicam onde a imagem deve ser editada. Deve ser um arquivo PNG válido, menor que 50 MiB e com as mesmas dimensões de image.

Para requisições JSON, mask também pode ser um objeto com exatamente um entre image_url ou file_id; os valores de file_id devem vir de /v1/files e permanecer vinculados à mesma configuração de image-edit.

modelstringobrigatório

O modelo a ser usado para edições de imagem. Use gpt-image-2 para edições do GPT Image ou outro modelo atual de image-edit retornado por GET /v1/models?recommended_for=image.

nintegerpadrão: 1

Número de imagens a serem geradas (1-10, dependente do modelo).

sizestring

O tamanho da imagem gerada. Para gpt-image-2, use auto ou WIDTHxHEIGHT; as dimensões devem ser múltiplos de 16, lado mais longo de no máximo 3840px, proporção lado maior/menor de no máximo 3:1 e 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. O formato recomendado é aspect_ratio com resolution.

response_formatstring

Como as imagens são retornadas: url ou b64_json.

  • Omitido: quando o modelo retorna bytes da imagem, cada imagem está em data[].b64_json e também em data[].url quando o TokenLab a armazenou. Quando o modelo retorna um link, cada imagem está em data[].url.
  • url: cada imagem está apenas em data[].url.
  • b64_json: cada imagem está apenas em data[].b64_json como dados em Base64.

Os links são URLs de resultados de mídia do TokenLab. Eles permanecem válidos por 30 dias. Consulte Retenção de dados.

asyncbooleanpadrão: false

Defina como true para retornar uma tarefa antes que a imagem final esteja pronta. Apenas modelos que listam async entre seus parâmetros suportados o aceitam, por exemplo gpt-image-2; para qualquer outro modelo, a requisição retorna 400 unsupported_async_mode. Edições assíncronas concluídas retornam URLs independentemente do response_format solicitado; use requisições síncronas quando precisar de b64_json.

userstring

Um identificador exclusivo representando seu usuário final para monitoramento de abusos.

Resposta

createdinteger

Timestamp Unix de quando as imagens foram criadas.

dataarray

Array de imagens geradas.

Cada objeto contém:

  • url (string): URL do resultado de mídia do TokenLab da imagem editada, válida por 30 dias. Não está presente quando response_format for b64_json. Quando response_format for omitido, estará ausente se o TokenLab não tiver conseguido armazenar a imagem.
  • b64_json (string): Dados da imagem em Base64. Presente quando response_format for b64_json, ou quando for omitido e o modelo retornar bytes da imagem.
usageobject

Contagens de tokens (input_tokens, output_tokens, total_tokens e seus detalhes) para modelos com preço baseado em tokens, como gpt-image-2, quando disponíveis.

Resposta de Tarefa Assíncrona

Defina async: true em um modelo compatível 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 polling de /v1/tasks/{task_id} até que a tarefa atinja completed ou failed.

Tarefas de edição assíncronas retornam apenas URLs finais da imagem. Se você precisar dos dados brutos da imagem em b64_json, use uma requisição síncrona.

O faturamento pode reservar o valor estimado quando a tarefa é criada. Tarefas concluídas são faturadas pelo uso real, e tarefas com falha ou tempo limite esgotado 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

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Observações

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/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 entrada image_url / image_urls[n]. O código é invalid_image_url, unsupported_image_content_type, too_many_images ou, com 413, image_too_large ou image_input_too_large. Para ativos privados ou protegidos por cabeçalhos, faça o upload direto de arquivos multipart de image ou crie referências em /v1/files .

Envie um cabeçalho Idempotency-Key para tentar novamente uma requisição com segurança após um timeout; consulte Repetir com segurança usando uma chave de idempotência.

O Hy Image 3.5 Preview edita uma imagem de referência a partir de uma instrução por escrito. Ele aceita apenas size 1024x1024 e n 1:

{
  "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
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

Chave opcional que torna uma requisição de imagem segura para novas tentativas se a requisição criou uma tarefa. Envie um novo valor único, como um UUID, para cada requisição. Uma nova tentativa com a mesma chave e o mesmo corpo retorna essa tarefa e não cria, despacha ou cobra uma segunda tarefa. Para uma requisição que retorna a imagem diretamente, uma nova tentativa com a mesma chave pode retornar um status de tarefa em vez da imagem, ou 409 com idempotent_response_not_replayable. Um corpo diferente com uma chave que já foi aceita é rejeitado; o código de status e o código de erro para esse caso não são garantidos. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.

Comprimento1 <= length <= 255

Corpo da requisição

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json