POST /v1/images/edits

Endpoint OpenAI-compatible para edicao de imagem. Aceita uma imagem de referencia e um prompt descrevendo a edicao desejada. Retorna a imagem editada no mesmo formato da geracao (/v1/images/generations).

Modelos suportados

Modelo	Provider	Capacidade
`flux-kontext-pro`	Black Forest Labs (Fal.ai)	Edicao geral, inpainting, outpainting
`flux-kontext-max`	Black Forest Labs (Fal.ai)	Qualidade maxima, mais lento
`flux-kontext-max-multi`	Fal.ai	Multiplas imagens de referencia
`flux-2-pro-edit`	Black Forest Labs	FLUX 2 Pro com edicao
`flux-2-dev`	Black Forest Labs	FLUX 2 Dev (pesquisa)
`gpt-image-1`	OpenAI	Edicao via DALL-E (quality: low ou medium)

Request (multipart/form-data)

Campo	Tipo	Obrigatorio	Descricao
`image`	arquivo	sim	Imagem de referencia (PNG, JPEG, WebP). Max 20MB.
`prompt`	string	sim	Descricao da edicao desejada.
`model`	string	sim	ID do modelo (ver tabela acima).
`n`	number	nao	Quantidade de imagens (default 1).
`size`	string	nao	Tamanho de saida (`1024x1024`, etc).
`quality`	string	nao	Apenas para gpt-image-1: `low` ou `medium`.

Exemplo

bash

curl https://api.usetokia.com/v1/images/edits \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -F image=@foto.png \
  -F model=flux-kontext-pro \
  -F prompt="add sunglasses to the person"

Response

json

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

Cobranca

A cobranca e por imagem gerada, nao por token. O preco depende do modelo e do cambio USD/BRL do momento. O custo aparece nos seus logs com call_type: image_edit.

Rate limit

O endpoint tem um rate limit especifico de 5 requisicoes por minuto por chave de API (configuravel). Acima disso, retorna 429 Too Many Requests.

Erros comuns

Codigo	Mensagem	Causa
400	`model_not_in_edit_whitelist`	Modelo nao suportado para edicao
400	`quality_high_blocked`	gpt-image-1 com quality=high esta bloqueado
503	`image_edit_disabled`	Feature desabilitada (beta fechado)
503	`fx_rate_unavailable`	Cambio USD/BRL indisponivel