Usar a API para desenvolvedores e webhooks

A página API no Dashboard oferece acesso programático a avatares, vozes e geração de áudio e vídeo. Abra Dashboard → API para ver a URL base atual, formato de autenticação, gestão de chaves de API, configurações de webhook e o link para a referência completa de desenvolvedores.

Quem pode criar uma chave de API

O acesso à API para desenvolvedores está disponível em planos pagos. Se o cartão da chave de API informar que é preciso ter um plano, faça upgrade por Billing antes de criar uma chave. Uma chave de API é uma credencial secreta para software, não uma senha para compartilhar com uma pessoa.

Criar e armazenar uma chave de API

1. Abra Dashboard → API e localize o cartão Developer API.

2. Digite um nome reconhecível, como “production backend” ou “staging integration”, e selecione Create.

3. Copie a chave completa imediatamente e armazene-a no gerenciador de segredos da implantação ou em configuração de ambiente protegida.

4. Depois de fechar a exibição única, o Dashboard mantém apenas o prefixo e metadados de uso; a chave completa não pode ser vista novamente.

Trate uma chave de API como uma senha capaz de gastar créditos da conta. Nunca a coloque em código de navegador, aplicativo móvel, capturas de tela, mensagens de chat, repositórios públicos ou variáveis de ambiente do cliente.

Autenticar uma solicitação

A página API mostra a URL base e o formato do cabeçalho Authorization. Envie a chave apenas de código confiável no servidor usando Authorization: Bearer <key>. Antes de criar a integração, consulte a referência para endpoints, corpos de solicitação, polling de tarefas, respostas, limites de taxa e códigos de erro atuais.

Rotacionar ou revogar uma chave

1. Primeiro crie e implante uma chave substituta quando puder fazer isso com segurança.

2. Atualize cada serviço que usa a chave antiga e confirme que as solicitações funcionam.

3. Use a ação de revogação ao lado da chave antiga em Dashboard → API.

A revogação é irreversível. Não revogue uma chave apenas porque deseja ver o valor completo de novo; crie uma substituta.

Configurar um webhook de geração

1. Em Dashboard → API, informe no cartão Webhook um endpoint HTTPS público que seu servidor controla.

2. Selecione Save. Salvar um endpoint novo ou alterado pode revelar o segredo do webhook uma vez; copie e guarde-o imediatamente.

3. No servidor, calcule HMAC-SHA256 sobre o corpo bruto da solicitação com esse segredo e compare com o cabeçalho X-Odrazio-Signature antes de aceitar o evento.

4. Use o evento para buscar o recurso correspondente no servidor ou atualizar o registro do trabalho. Uma solicitação recebida sem verificação não prova que a geração foi concluída.

Alterar ou remover um webhook

Salvar uma URL de webhook alterada pode rotacionar o segredo, portanto atualize a configuração de verificação ao mesmo tempo. Use Remove quando não quiser mais entregas. Uma URL válida deve estar publicamente acessível por HTTPS; um endereço de desenvolvimento somente local não pode receber callbacks da plataforma.