Solução de API de edição
Endpoints de edição recebem pelo menos duas entradas: a imagem e a instrução. É na imagem — URL pública, upload confirmado ou data URI embutida — que a maioria das integrações trava.
O desafio
O prompt é a metade fácil. A outra é um arquivo no celular dos seus usuários, que precisa chegar ao modelo sem expor um bucket privado e caber em limites verificados antes de a tarefa existir.
01
Um campo de imagem declarado aceita URL HTTPS pública, URI de arquivo spicy:// confirmada ou data URI embutida. Embutida: 1 MiB decodificado e 8.388.608 pixels por imagem, dentro de um corpo de 2 MiB. Acima disso, é preciso um tíquete de upload.
02
A presigned link can reference a private bucket if the URL lets our servers download the file without cookies or a separate login. Keep it valid during processing. Private network addresses, loopback hosts and user:password URL credentials are rejected.
03
O nome público da chamada termina em /edit, o esquema normalmente exige image_url ou image_urls e alguns endpoints acrescentam mask_url ou strength. Um valor model de text-to-image num fluxo de edição falha na validação em vez de degradar.
A abordagem
Para arquivos do usuário peça um tíquete, envie por PUT exatamente os bytes declarados com todos os cabeçalhos devolvidos, confirme e passe a URI spicy:// no campo de imagem do modelo. A referência passa a ser da sua conta, é verificada uma vez e pode ser reutilizada sem novo upload.
Tíquete, PUT, confirmação, criação. Mídia já pública pula os três primeiros passos.
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}Contrato
| Campo ou cabeçalho | Valor ou limite |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
Deslize horizontalmente para ver todas as colunas.
Integração
Adequação
Evidências
A confirmação compara bytes e tipo de mídia com o tíquete, verifica a assinatura da imagem e calcula um SHA-256. Só então o arquivo pode ser referenciado.
Data URIs são guardadas como arquivos ligados à conta. A entrada normalizada que recordInfo devolve traz URIs de arquivo, nunca os bytes Base64 originais.
O material enviado fica um dia; os resultados gerados, 14 dias. Os dois prazos são publicados e não se negociam por conta.
Antes de lançar
Perguntas frequentes
Modelos
Cada link abre a página daquela família de modelos: entradas, limites, política de conteúdo e o preço atual por unidade.
A seguir
Envie uma imagem que você já tem mais uma instrução. Como a referência entra, quais são os limites de pixels e pelo que se cobra.
