POST/api/v1/studio/avatars

Criar avatar

Bearer tokenescopo generate:video

Um avatar é o influencer que aparece no vídeo do Studio. É opcional e seu uso depende da avatarPolicy do modo (veja Catálogo do Studio): optional, required ou forbidden. O id retornado vira o avatarId da geração.

Escopo necessário: generate:video. Criar um avatar não debita créditos.

Body

Campo	Tipo	Obrigatório	Valores / restrições
`name`	string	sim	Nome do avatar (máx. 120 chars)
`imageUrl`	string	sim	URL HTTPS da foto do avatar (host não-privado)
`gender`	string	não	Gênero do avatar
`type`	string	não	`preset` ou `custom`
`sourceInfluencerId`	string	não	ID de um influencer salvo (upsert por origem)

Exemplo

cURL

curl -X POST https://avatrix.io/api/v1/studio/avatars \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camila",
    "imageUrl": "https://storage.avatrix.io/uploads/camila-face.jpg",
    "type": "custom"
  }'

Resposta — 200

JSON

{ "success": true, "data": { "id": "avt_...", "name": "Camila" } }

Idempotência

Aceita o header Idempotency-Key (opcional, máx. 128 chars). Ver Idempotência.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	`name`/`imageUrl` ausente/inválido, não-HTTPS ou host privado
`FORBIDDEN`	403	Studio indisponível no plano, ou token sem `generate:video`
`GENERATION_FAILED`	502	falha ao processar a imagem ou no engine
`FEATURE_DISABLED`	503	Marketing Studio indisponível

Ver Códigos de erro e Escopos.