POST/api/v1/studio/avatars

Criar avatar do Studio

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: createStudioAvatar · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`Idempotency-Key`	header	não	string

Schema do request

JSON

{
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "avatarFileId"
      ]
    },
    {
      "required": [
        "imageUrl"
      ]
    }
  ],
  "properties": {
    "avatarFileId": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "gender": {
      "type": "string"
    },
    "imageUrl": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "name": {
      "maxLength": 120,
      "minLength": 1,
      "type": "string"
    },
    "sourceInfluencerId": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "type": {
      "enum": [
        "preset",
        "custom"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}

Respostas

HTTP	Significado
`200`	Avatar criado
`default`	Erro padronizado

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.