Criar influencer a partir de um arquivo

Contrato OpenAPI

operationId: createInfluencerFromFile · Implementada

Baixar o contrato OpenAPI 3.1.

Schema do request

{
  "additionalProperties": false,
  "properties": {
    "fileId": {
      "description": "ID de um arquivo em Files com purpose `avatar` e status `ready`, pertencente ao dono do token. A rota NÃO aceita URL: URL livre gravada aqui vira `<img>` no painel.",
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "name": {
      "maxLength": 100,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "fileId"
  ],
  "type": "object"
}

Respostas

POST /api/v1/influencers exige uma taskId — ou seja, uma imagem gerada pela plataforma. Esta rota é o outro caminho: você já tem a foto do personagem e quer salvá-la como influencer. É o equivalente por API do que a tela faz quando alguém chega ao Clonar Vídeo sem nenhum avatar salvo.

Escopo necessário: manage:influencers. Não debita créditos.

Só fileId, nunca URL

A rota aceita exclusivamente o fileId de um arquivo que já está em Files, com purpose: "avatar" e status ready, pertencente ao dono do token. Não existe campo de URL.

O motivo é concreto: a thumbnailUrl do influencer é renderizada como <img> no painel e baixada pelo servidor a cada turno do Chat. Aceitar uma URL arbitrária transformaria isso em SSRF armazenado, e a checagem de host privado que existe hoje na plataforma é comparação de string antes da resolução DNS — mitigação parcial, não barreira.

O arquivo é copiado para o storage durável no momento da criação. O download assinado de Files expira em 5 minutos; a foto do influencer precisa durar.

Body

Qualquer outra chave no body devolve VALIDATION_ERROR.

Por que name vai até 100 e a tela para em 60

A tela corta o nome em 60 porque o campo dela alimenta também o nome da ficha estruturada, cujo teto próprio é 60. Aqui o campo escrito é só a coluna name do influencer — a mesma que POST /api/v1/influencers e PATCH /api/v1/influencers/{id} escrevem com teto 100. Manter 60 nesta rota criaria duas verdades sobre a mesma coluna: um nome de 80 chars seria recusado na criação e aceito no PATCH seguinte. A ficha continua aplicando o próprio teto de 60 quando for gravada.

Escopo: por que manage:influencers e não manage:chat

PATCH /api/v1/chat/context amarra um influencer ao chat com escopo manage:chat. Esta rota cria o influencer, que é recurso de manage:influencers — o mesmo escopo que lista, renomeia e apaga. A assimetria é proposital: um token que só configura o chat não deveria poder criar personagens novos na conta.

Limite

O teto é de 20 influencers salvos por conta, o mesmo de POST /api/v1/influencers. Estourar devolve 409 LIMIT_REACHED.

Exemplo

curl -X POST https://avatrix.io/api/v1/influencers/from-file \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "file_01J8XY...",
    "name": "Seu João"
  }'

{
  "success": true,
  "data": {
    "influencer": {
      "id": "inf_01J8XZ...",
      "name": "Seu João",
      "thumbnailUrl": "https://storage.avatrix.io/avatars/ABC123/image-....png",
      "createdAt": "2026-08-18T12:00:00.000Z",
      "updatedAt": "2026-08-18T12:00:00.000Z"
    }
  }
}

Erros