Blogue

Guia de uso

Guia de uso do ElevenLabs Text to Dialogue: envio de áudio de diálogo entre duas pessoas com o array dialogue

Da divisão do roteiro de duas pessoas à requisição de timbre por fala, com envio e validação conforme o contrato atual do HiAPI

Nov 18, 2026
Capa com grade de trama plana sobre fundo verde-escuro, com fitas em tom de latão e verde-sombrio entrelaçadas formando uma malha aberta, em eco ao tema de diálogo entre duas pessoas.
Nesta página

Primeiro, confirme se você precisa de síntese de diálogo, e não de uma leitura única

Se o seu material é um roteiro de diálogo entre duas pessoas (ou mais personagens), a abordagem mais direta costuma ser sintetizar cada fala separadamente e depois juntá-las em ordem. O problema dessa abordagem só aparece na fase de entrega: cada fala é um áudio independente, e as pausas entre falas, a continuidade do ritmo e a consistência do timbre precisam ser refeitas na camada de montagem; com muitos personagens, a ordem de concatenação e as trocas de timbre tornam-se a principal fonte de bugs.

O elevenlabs/text-to-dialogue tem o propósito de expressar todo um diálogo em uma única requisição. Você divide o roteiro inteiro em um array dialogue e envia; o modelo realiza o diálogo com múltiplos timbres na mesma geração, e a saída é um único áudio completo. Em comparação com «múltiplas sínteses individuais + concatenação», ele coloca o mapeamento de personagens e a ordem das falas no corpo da requisição, de modo que, na validação, você só precisa verificar um único resultado.

Portanto, comece fazendo uma avaliação:

  • Se o conteúdo é a leitura contínua de um mesmo falante, basta usar conversão de texto em fala; o array dialogue não é necessário;
  • Se o conteúdo é um diálogo alternado entre dois ou mais personagens e você deseja uma percepção auditiva uniforme no conjunto, deve usar o array dialogue deste endpoint;
  • Se o conteúdo é um diálogo, mas o total de caracteres excede muito o limite, é necessário segmentar por semântica e enviar em partes, em vez de voltar à síntese fala a fala.

Depois de confirmar que se trata do segundo caso, o próximo passo é entender a estrutura do próprio array.

Esquerda: múltiplas requisições individuais depois concatenadas, com emendas visíveis; direita: uma requisição com array dialogue, gerando diretamente um único áudio contínuo.

Estrutura do array dialogue: text e voice em cada linha

No contrato do HiAPI, a entrada principal do elevenlabs/text-to-dialogue tem apenas um campo obrigatório: dialogue. É um array com no mínimo 1 item, e cada elemento é uma linha de diálogo contendo dois subcampos obrigatórios:

  • text: o texto da fala dessa linha, string, com no mínimo 1 caractere;
  • voice: o timbre usado nessa linha, string, podendo ser o nome de um timbre predefinido ou um voice_id; o padrão é EkK5I93UQWFDigLMpZcX.

Ambos os campos são obrigatórios — mesmo que você queira usar apenas o timbre padrão, recomenda-se declarar voice explicitamente para que o corpo da requisição seja autoexplicativo. Uma requisição mínima para duas pessoas tem a seguinte forma:

{
  "dialogue": [
    { "text": "Como está o progresso aí do seu lado?", "voice": "EkK5I93UQWFDigLMpZcX" },
    { "text": "Esta semana sai a primeira versão.", "voice": "Z3R5wn05IrDiVCyEkUrK" },
    { "text": "Certo, então vou te enviar a lista de verificação primeiro.", "voice": "EkK5I93UQWFDigLMpZcX" }
  ]
}

Observe que a ordem do array é a ordem do diálogo; a interface não tem um campo extra de «falante», e os personagens são distinguidos apenas por voice. Este é o ponto que mais precisa ser planejado com antecedência em toda a integração.

Estrutura em árvore do array dialogue: o array é a raiz, e cada elemento se divide nos dois campos text e voice, que devem existir simultaneamente.

Dividir o roteiro de duas pessoas em itens fala a fala

Do texto do roteiro ao array dialogue, recomenda-se seguir um fluxo fixo para evitar erros ao escrever JSON manualmente.

Primeiro passo: dividir por linha e marcar o falante

Organize o roteiro em uma estrutura de pares «falante + fala», uma fala por item; não junte as falas de dois personagens no mesmo text — assim, um elemento só pode ter um voice, e após a junção não é possível distinguir os personagens. Narrações e indicações de cena entre parênteses não são falas e devem ser removidas separadamente, sem serem colocadas em text.

Segundo passo: limpar o texto

Verifique item por item: remova espaços no início e no fim, unifique pontuação e quebras de linha, e exclua linhas vazias. O comprimento mínimo de text é de 1 caractere, e uma string vazia provoca falha de validação imediatamente. Se uma linha tiver apenas interjeições (como «hã», «certo»), pode mantê-la; mas se após a limpeza ela se tornar uma string vazia, é preciso confirmar com a equipe de conteúdo se essa linha deve ser removida.

Terceiro passo: estabelecer o mapeamento de personagens e gerar o array

Cada rótulo de falante é mapeado para um timbre único, e os elementos são gerados na ordem das linhas. O pseudocódigo é aproximadamente:

speaker_voice = {
    "A": "EkK5I93UQWFDigLMpZcX",
    "B": "Z3R5wn05IrDiVCyEkUrK",
}

dialogue = [
    {"text": line.text, "voice": speaker_voice[line.speaker]}
    for line in script
]

Armadilhas comuns

  • O mesmo personagem usa timbres diferentes em dois pontos, causando uma clara quebra na percepção auditiva;
  • Omitir voice faz todo o trecho voltar ao timbre padrão, e o diálogo entre duas pessoas vira «uma pessoa interpretando dois papéis»;
  • A ordem do array é alterada por lógica de ordenação ou deduplicação, quebrando a semântica do diálogo.

Após gerar, imprima os primeiros itens e verifique manualmente antes de passar para a etapa do orçamento de caracteres.

Mapeamento fixo de timbres: um único voice por personagem

A razão para «fixar» o voice é que ele não só determina o timbre em si, mas também carrega o significado de «quem está falando». Se o mesmo personagem aparecer com dois valores diferentes de voice ao longo do diálogo, o ouvinte pensará que houve troca de pessoa; por outro lado, se dois personagens colidirem no mesmo voice, o diálogo perde a distinção.

Na prática, recomenda-se manter no código uma tabela de constantes que mapeia personagens para timbres, em vez de espalhar literais de string em cada linha de fala:

const VOICE = {
  host: "EkK5I93UQWFDigLMpZcX",
  guest: "Z3R5wn05IrDiVCyEkUrK",
};

Todas as linhas obtêm o valor apenas dessa tabela, e quebras de linha ou reordenações no roteiro não quebram a consistência. O voice aceita o nome de um timbre predefinido ou um voice_id; se a equipe já tem seu próprio sistema de nomenclatura de timbres, pode fazer uma conversão na camada de configuração e, no momento da requisição, unificar para um valor aceito pela interface. O contrato fornece uma enumeração de timbres; validar com a enumeração antes de enviar evita problemas simples como erros de digitação — valores fora da enumeração não são silenciosamente tratados como padrão.

Outro ponto frequentemente ignorado é a estabilidade entre segmentos. Quando o total de caracteres excede o limite e é preciso dividir em várias requisições, a tabela de mapeamento de timbres deve ser reutilizada tal como está, sem escolher novos timbres nas novas requisições; caso contrário, o mesmo personagem soará diferente em segmentos distintos.

Fixe cada falante na mesma «fita»: conectada uma vez pela extremidade esquerda, ela sustenta todo o diálogo de forma contínua.

Orçamento de caracteres e divisão de requisições

A interface tem uma restrição rígida de volume: o total de caracteres de todos os campos text no array dialogue não pode exceder 5000. Observe que é a soma de todos os textos do array, não o comprimento de uma linha nem o número de elementos. Chinês, inglês e pontuação geralmente contam como caracteres; ao estimar, prefira deixar margem adotando o critério mais amplo.

A lógica de contagem deve ser escrita após gerar o array e antes de enviar a requisição:

total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000

Quando o limite for excedido, a abordagem correta é dividir por limites semânticos em vários subdiálogos, enviar separadamente, obter os áudios separadamente e depois combiná-los conforme a necessidade do negócio — e não truncar falas ou excluir linhas. Ao dividir, observe três pontos:

  1. Escolha pontos de corte em transições de cena ou mudanças de tópico, evitando separar uma pergunta e sua resposta em duas requisições;
  2. Cada subsegmento deve ser contado separadamente e também não pode exceder 5000;
  3. Ao reconstruir o array de cada segmento após a divisão, mantenha a ordem original das linhas e o mapeamento de timbres dos personagens.

Se o conteúdo for naturalmente um diálogo longo, recomenda-se organizá-lo, já na produção de conteúdo, por «atos» ou «capítulos», de modo que cada ato caiba naturalmente no orçamento e se reduzam as descontinuidades perceptivas causadas por divisões improvisadas.

Parâmetros opcionais: stability e language_code

Além de dialogue, a interface oferece dois parâmetros opcionais, cuja escolha depende do tipo de conteúdo.

stability

stability é um parâmetro numérico que aceita 0, 0.5 e 1, com padrão 0.5. Seu significado é a estabilidade do timbre:

  • Quanto menor o valor, mais rica em emoção e mais variável, adequado a diálogos com oscilações emocionais e conteúdos dramáticos;
  • Quanto maior o valor, mais estável e consistente a saída, adequado a cenários que exigem percepção auditiva uniforme, como locuções de marca e scripts de atendimento;
  • O padrão 0.5 é um meio-termo entre os dois.

Observe que este é um parâmetro no nível de toda a requisição, não configurado linha a linha. Quando as emoções dos personagens no mesmo diálogo variam muito, ou se aceita um valor de compromisso, ou se faz com que segmentos diferentes usem stability diferentes ao dividir o texto.

language_code

language_code é um código de idioma no formato ISO, com padrão de string vazia; deixá-lo vazio significa detecção automática do idioma. Quando o idioma do conteúdo é claro e se deseja evitar desvios de detecção, especificá-lo explicitamente é mais seguro, por exemplo, preencher zh para conteúdo em chinês. O contrato fornece uma enumeração completa de códigos de idioma; deve-se fazer uma validação antes de enviar, para evitar valores não suportados.

Nenhum dos dois parâmetros é obrigatório; se o conteúdo não tiver requisitos especiais, omiti-los e usar o comportamento padrão é perfeitamente válido.

Envio e validação: verificação conforme o contrato baseado em tarefas

Esta interface é enviada na forma de tarefa: você envia a entrada, recebe o resultado de uma tarefa e faz a validação em torno desse resultado. Isso implica duas coisas.

Primeiro, o contrato de entrada deve ser validado por você. Antes de enviar a requisição, verifique item por item: dialogue é um array com pelo menos 1 item; cada item tem simultaneamente text e voice não vazios; o total de caracteres de todos os text não excede 5000; stability aceita apenas 0/0.5/1; language_code pertence à enumeração ou está vazio. Colocar essas verificações no cliente reduz significativamente envios inválidos.

Segundo, não presuma comportamentos não declarados no contrato. A documentação da interface não promete repetição automática, chaves de idempotência ou compensação de falhas; portanto, não conte com «reenviar a mesma requisição» como garantia — cada envio deve ser tratado como uma tarefa independente. A prática de engenharia mais segura é:

  • Antes de enviar, registrar um resumo da entrada desta requisição (número de itens do array, total de caracteres, versão do mapeamento de timbres), para facilitar comparações posteriores;
  • Após receber o resultado, confirmar primeiro que o áudio é utilizável, que a duração é razoável e que os personagens são distinguíveis, e só então fazer a distribuição downstream;
  • Se for necessário reexecutar, refazer toda a validação de entrada, em vez de reutilizar um corpo de requisição antigo não verificado.

O foco da validação é «se o resultado atende ao esperado», e não especular sobre o fluxo interno do servidor. No HiAPI, você pode consultar o contrato atual na página do modelo elevenlabs/text-to-dialogue antes de começar.

Lista de autoverificação antes do lançamento

Transforme o conjunto de verificações abaixo em um fluxo automatizado antes do envio; isso cobre a grande maioria das causas de falha:

  1. dialogue é um array com número de elementos ≥ 1;
  2. Cada elemento contém simultaneamente text e voice, e nenhum deles é string vazia;
  3. Cada voice está dentro da enumeração do contrato, e o mesmo personagem usa globalmente apenas o mesmo valor;
  4. A ordem do array é consistente com a ordem das linhas do roteiro, sem intervenção de lógica de ordenação ou deduplicação;
  5. O total de caracteres de todos os text é ≤ 5000, e o conteúdo excedente já foi dividido por semântica;
  6. Se definidos explicitamente, stability ∈ {0, 0.5, 1} e language_code ∈ enumeração ou vazio;
  7. O resumo da entrada (número de itens, número de caracteres, versão do mapeamento) foi registrado para facilitar a comparação na validação.

Além da lista, há uma regra prática: primeiro faça o fluxo ponta a ponta funcionar em uma amostra curta e depois amplie para o roteiro completo. Problemas como mapeamento de personagens e orçamento de caracteres aparecem já em amostras de algumas dezenas de linhas; não é necessário esperar o envio de todo o conteúdo para descobri-los.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API