Editar imagem

Visão geralCopy Anchor Link

Cria uma imagem editada ou estendida a partir de uma imagem original e um prompt.

A rota suporta ambos:

• o fluxo de upload multipart/form-data compatível com OpenAI documentado abaixo
• requisições JSON que fornecem image_url, image_urls ou referências oficiais images para famílias de image-to-image suportadas

Corpo da requisiçãoCopy Anchor Link

Timeout de solicitações síncronas: algumas solicitações de imagem retornam a imagem final inline e aguardam a geração terminar. Solicitações de alta resolução ou alta qualidade podem levar perto de um minuto ou mais, então configure 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 o poll_url retornado.

URLs de imagem remotas: quando entrada multipart é necessária, a TokenLab busca JSON image_url, image_urls ou images[].image_url e envia os bytes como partes multipart image. As URLs devem ser públicas em http/https, sem credenciais embutidas nem fragmentos, e não podem resolver para localhost, faixas de IP privadas ou reservadas; cada redirecionamento é verificado novamente. O payload buscado deve ser uma imagem PNG, JPEG ou WebP real. Limites: 50 MiB por imagem, 200 MiB no total para imagens buscadas por URL em uma requisição, timeout de 30s e até 3 redirecionamentos.

Uma requisição JSON deve conter exatamente um de image_url, image_urls ou images. Cada objeto images[] deve conter apenas um de image_url ou file_id. O limite total de 200 MiB inclui todas as imagens de origem e a máscara.

RespostaCopy Anchor Link

Resposta de tarefa assíncronaCopy Anchor Link

Defina async: true com gpt-image-2 ou modelos oficiais de edição FLUX/BFL para criar uma tarefa em vez de esperar pela imagem editada na solicitação. A resposta inclui status: "pending", task_id e poll_url. Consulte /v1/tasks/{task_id} até a tarefa chegar a completed ou failed.

Tarefas assíncronas de edição retornam apenas URLs das imagens finais. Se precisar dos dados brutos b64_json, use uma solicitação síncrona.

Ao criar a tarefa, o valor estimado pode ser reservado. Tarefas concluídas são cobradas pelo uso real; tarefas com falha ou expiradas liberam ou reembolsam a reserva.

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"

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

ObservaçõesCopy Anchor Link

{
  "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"
}