Trocar personagem

Substituição de personagem: insere um personagem (characterImageUrl) numa cena de destino (sceneImageUrl), preservando iluminação, ângulo e composição da cena. Usa o modelo fixo nano-banana-pro (quality 1K). Responde 202 Accepted com um taskId; acompanhe o resultado por polling em GET /api/v1/tasks/:id ou via webhook.

Escopo necessário: generate:image.

Body

As duas imagens são enviadas nesta ordem fixa: personagem (characterImageUrl) e depois cena (sceneImageUrl). Essa ordem é obrigatória — não há prompt de usuário.

Toda imagens devem ser públicas, HTTPS e ≤10 MB.

Aspect ratio: derivado automaticamente das dimensões da cena (sceneImageUrl) (encaixe no ratio suportado mais próximo). Como as dimensões não impactam no custo, a falha de detecção não bloqueia a requisição, e o provider usa a proporção padrão 1:1.

Exemplo de request

curl -X POST https://avatrix.io/api/v1/generate/character-replace \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-charrep-001" \
  -d '{
    "characterImageUrl": "https://storage.avatrix.io/uploads/AMABB58D/image-112cd253-0b81-4693-92d7-1c626f2e3cd7.png",
    "sceneImageUrl": "https://storage.avatrix.io/uploads/AMABB58D/image-f37646a6-0efb-4049-b111-391bcf07cd80.png"
  }'

Resposta — 202

{
  "success": true,
  "data": { "taskId": "...", "status": "queued" }
}

O status: "queued" é só o rótulo de criação. No polling (GET /api/v1/tasks/:id) a task evolui por pending → processing → completed (com resultUrl) ou failed. Ver Ciclo de vida da task.

Exemplo de erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'characterImageUrl' é obrigatório (URL do personagem)."
  }
}

Idempotência

Envie o header Idempotency-Key (opcional, ≤128 chars, TTL 24h). Repetir a mesma chave retorna a resposta original sem novo débito. A concorrência é limitada a 20 tasks simultâneas por usuário. Ver Idempotência.

Custo

Valor fixo por geração. Não depende dos megapixels da imagem.

Erros relevantes