Laboratório: Agente de Voz com ElevenLabs e Avatar de Vídeo HeyGen Integrados via Python

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

11

Validações

4

Versões da documentação consultada

Python 3.10 ou superior · ElevenLabs Python SDK a versão estável atual · Requests a versão estável atual

Topologia

Um computador local (192.168.56.10) executa scripts Python que interagem diretamente com as APIs ElevenLabs (TTS e STT) e HeyGen (criação de vídeo). O áudio gerado é salvo localmente, enviado para transcrição, e o texto resultante é usado para criar um vídeo avatar. Todo o tráfego é iniciado do host local para as APIs públicas, sem servidores intermediários.

+---------------------+
|  Host Local (Python)|
| 192.168.56.10       |
+----------+----------+
           |
   +-------+-------+
   |               |
ElevenLabs      HeyGen
(TTS/STT API)   (Video API)

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Evite conflitos de dependências criando um ambiente virtual. Isso garante reprodutibilidade.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt do terminal mostra (venv) indicando ambiente ativado.

2. Instalar SDKs e dependências

   Instale os SDKs oficiais e requests para chamadas HTTP. Use versões estáveis.

   pip install elevenlabs requestsCopiar

   O que você deve ver: Mensagens de sucesso para cada pacote instalado.

3. Configurar variáveis de ambiente para segredos

   Nunca exponha chaves de API no código. Use variáveis de ambiente para as chaves da ElevenLabs e HeyGen.

   export ELEVEN_API_KEY='sua-chave-elevenlabs'
   export HEYGEN_API_KEY='sua-chave-heygen'Copiar

   O que você deve ver: Variáveis disponíveis na sessão (confira com 'echo $ELEVEN_API_KEY').

4. Gerar áudio a partir de texto (TTS ElevenLabs)

   Converta um texto para voz realista usando a API TTS. Escolha um voice_id disponível em sua conta ElevenLabs.

   python -c "from elevenlabs import ElevenLabs; import os; client = ElevenLabs(api_key=os.environ['ELEVEN_API_KEY']); audio = client.text_to_speech(text='Bem-vindo ao laboratório de IA.', voice_id='insira_seu_voice_id'); with open('saida.mp3','wb') as f: f.write(audio)"Copiar

   O que você deve ver: Arquivo 'saida.mp3' criado no diretório atual, contendo o áudio sintetizado.

5. Reproduzir o áudio gerado localmente

   Garanta que o áudio está correto ouvindo o arquivo.

   ffplay saida.mp3Copiar

   O que você deve ver: Áudio reproduzido com clareza e sem cortes.

6. Transcrever o áudio para texto (STT ElevenLabs)

   Use a API de Speech-to-Text para recuperar o texto a partir do áudio gerado.

   python -c "from elevenlabs import ElevenLabs; import os; client = ElevenLabs(api_key=os.environ['ELEVEN_API_KEY']); with open('saida.mp3','rb') as f: transcript = client.speech_to_text(audio=f, model_id='scribe_v2'); print(transcript)"Copiar

   O que você deve ver: Texto transcrito impresso no terminal, próximo ao original.

7. Preparar payload para criação de vídeo avatar HeyGen

   Monte o corpo da requisição com o texto transcrito, selecionando um avatar e voz disponíveis em sua conta HeyGen.

   # Exemplo de payload, consulte a documentação para campos exatos
   payload = {
     'video_inputs': {'script': 'Bem-vindo ao laboratório de IA.'},
     'character': 'insira_id_avatar',
     'voice': 'insira_id_voice'
   }
   Copiar

   O que você deve ver: Dicionário Python pronto para envio à API HeyGen.

8. Enviar requisição de criação de vídeo (HeyGen Videos API)

   Envie o payload para a API de criação de vídeo. O processo é assíncrono: guarde o ID retornado.

   import requests, os
   headers = {'x-api-key': os.environ['HEYGEN_API_KEY']}
   resp = requests.post('https://api.heygen.com/v1/videos', headers=headers, json=payload)
   print(resp.json())Copiar

   O que você deve ver: Resposta JSON com status 'processing' e um 'video_id' para consulta posterior.

9. Consultar status do vídeo até finalizar

   Acompanhe o status do vídeo usando o video_id. Repita até status 'success'.

   import time
   video_id = 'insira_video_id'
   while True:
     r = requests.get(f'https://api.heygen.com/v1/videos/{video_id}', headers=headers)
     status = r.json().get('status')
     print('Status:', status)
     if status == 'success':
       print('URL:', r.json().get('video_url'))
       break
     time.sleep(10)Copiar

   O que você deve ver: Status alterna entre 'processing' e 'success'. Ao finalizar, exibe URL do vídeo.

10. Baixar e assistir ao vídeo gerado

    Acesse a URL final e baixe o vídeo para validação local.

    wget 'URL_do_video' -O avatar_final.mp4
    ffplay avatar_final.mp4Copiar

    O que você deve ver: Vídeo com avatar falando o texto original, sincronizado e com áudio claro.

11. Registrar logs e outputs para revisão

    Salve logs de requisições, respostas e arquivos gerados para auditoria e revisão humana.

    cp saida.mp3 avatar_final.mp4 logs.txt ~/laboratorio_ia/Copiar

    O que você deve ver: Arquivos organizados para revisão e rastreabilidade.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca exponha chaves de API em código ou repositórios
• Use variáveis de ambiente para segredos
• Apague arquivos de áudio e vídeo após uso se contiverem dados sensíveis
• Limite permissões dos arquivos gerados (chmod 600)
• Reveja logs antes de compartilhar para evitar vazamento de dados pessoais

Checklist final

• Ambiente Python isolado criado e ativado
• Chaves de API configuradas em variáveis de ambiente
• Áudio TTS gerado e reproduzido localmente
• Transcrição STT obtida e comparada ao texto original
• Vídeo avatar criado e baixado com sucesso
• Logs e arquivos organizados para revisão