GET/api/v1/influencers/:id/ficha

Ler a ficha estruturada do influencer

Bearer tokenImplementadoescopo manage:influencers

Contrato OpenAPI

operationId: getInfluencerFicha · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`id`	path	sim	string

Respostas

HTTP	Significado
`200`	Ficha estruturada e o texto livre legado
`default`	Erro padronizado

A ficha é o que faz o agente escrever no jeito do personagem em vez de descrever um parecido. Ela é estruturada, e não texto livre, por dois motivos medidos: o campo de texto livre é VarChar(1500) e uma ficha completa não cabe; e os campos de proibição precisam existir separados, porque negação em prompt de imagem vira menção — "não é um estúdio" desenha um estúdio.

Verbo	Caminho	Escopo
`GET`	`/api/v1/influencers/{id}/ficha`	`manage:influencers`
`PUT`	`/api/v1/influencers/{id}/ficha`	`manage:influencers`

Por que a leitura também é `manage:influencers`

A ficha carrega estrategia.palavraCta — a keyword do comment-to-DM —, além de estrategia.vilao e estrategia.propAncora. Isso é operação de funil, não metadado de catálogo. Por isso a ficha não aparece em GET /api/v1/influencers (a lista) e a leitura é rota própria, opt-in, no mesmo escopo da escrita. Um token de leitura genérica não deve carregar essa informação por acidente.

PATCH /api/v1/chat/context, que amarra um influencer ao chat, continua em manage:chat: aquilo é configuração do chat. Criar, ler ficha e escrever ficha são o influencer em si, e ficam em manage:influencers.

Tetos: o servidor corta, não recusa

Todo campo é opcional. O servidor normaliza a ficha inteira antes de gravar: campo de texto acima do teto é cortado, lista acima do limite de itens é truncada, chave desconhecida é descartada. Isso é de propósito e é o mesmo comportamento da tela — os tetos são o que segura o custo do system prompt, que é reenviado a cada mensagem da conversa.

A resposta devolve a ficha já normalizada: é o que ficou gravado, não o que você mandou.

Uma ficha inteiramente vazia apaga a ficha do influencer (grava NULL), que é o jeito de desligar a feature.

`brief` nunca é apagado por aqui

brief é o texto livre que existia antes desta ficha. Ele continua sendo o fallback de leitura para quem escreveu por lá, e o PUT desta rota não o toca — apagá-lo aqui destruiria o que a pessoa escreveu sem ela ter pedido. O GET devolve os dois para você comparar.

Body do `PUT`

JSON

{
  "ficha": {
    "identidade": {
      "nome": "Seu João",
      "umaLinha": "Vô caipira que ensina receita dos antigos",
      "nicho": "saúde natural",
      "publico": "homens 45+"
    },
    "imagem": {
      "rosto": "senhor idoso de boina preta, bigode grisalho",
      "corpo": "tronco seco de lavrador",
      "figurino": "camisa xadrez de manga comprida",
      "cenarios": ["cozinha de sítio", "quintal com galinhas"],
      "luz": "dia encoberto, difusa e plana",
      "luzProibida": ["estúdio", "gradiente"],
      "camera": "celular na mão, altura do peito"
    },
    "voz": {
      "timbreRitmo": "grave, pausado, frases curtas",
      "sotaque": "caipira do interior de Minas",
      "bordao": "ó o trem",
      "proibidosDeFala": ["gíria de internet"],
      "idioma": "pt-BR"
    },
    "estrategia": {
      "vilao": "remédio caro de farmácia",
      "propAncora": "o livro dos antigos",
      "palavraCta": "RECEITA",
      "regras": ["nunca prometer cura"]
    }
  }
}

Os campos de proibição — imagem.luzProibida, voz.proibidosDeFala e estrategia.regras — governam o comportamento do agente e não descem para o prompt de imagem.

voz.idioma é o idioma em que o personagem fala e escreve: pt-BR (padrão), es-MX, es-ES ou en-US. O agente do chat escreve nele a fala, o roteiro, a legenda e o texto de tela; a conversa com o usuário continua em português. Ausente vale pt-BR. Valor fora da lista é recusado com VALIDATION_ERROR.

voz.vozDaGaleria é a voz da galeria (o voiceId de GET /api/v1/voices) ou "original" — a voz do gerador de vídeo, que é o padrão. Ela não entra na geração do vídeo: é a troca de voz cobrada à parte no vídeo pronto. Uma voz que não está na galeria é descartada na normalização (o PUT devolve a ficha sem ela).

Exemplo

cURL

curl -X PUT https://avatrix.io/api/v1/influencers/inf_01J8XZ.../ficha \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"ficha":{"identidade":{"nome":"Seu João"}}}'