Guia de Integração da API de Síntese de Voz

Por Equipe editorial Delta TTS Medical · Atualizado 2026-11-19

Esta documentação técnica explica como integrar nossa API de síntese de voz em aplicações médicas. Você aprenderá a formatar requisições JSON, gerenciar autenticação por token Bearer e converter textos clínicos em áudio com precisão. O guia cobre desde a configuração inicial até o tratamento de erros comuns, focando na estabilidade para desenvolvedores indie que criam ferramentas de saúde.

Os exemplos utilizam cURL e Python para demonstrar o fluxo completo de geração de áudio. Você verá como ajustar parâmetros como velocidade e formato, além de entender os limites de taxa e o custo por caractere. Esta página é destinada a técnicos que precisam de integração direta, sem abstrações desnecessárias, para entregar guias de pacientes ou instruções médicas via áudio.

Guia de Integração da API de Síntese de Voz

Perguntas frequentes

Qual endpoint usar para gerar áudio?

Utilize o endpoint POST https://api.delta575.info/v1/audio/speech. Envie o texto no corpo JSON com os campos model, input, voice e response_format. O endpoint aceita o mesmo formato de requisição do OpenAI, garantindo compatibilidade imediata com integrações padrão.

Posso usar o SDK oficial da OpenAI?

Sim, o SDK oficial da OpenAI funciona perfeitamente. Basta alterar o parâmetro base_url para https://api.delta575.info/v1 e utilizar a sua chave de API. Isso permite reutilizar o código existente sem necessidade de adaptações complexas na lógica de integração.

Como autenticar na API?

A autenticação é feita via header Authorization: Bearer tts-... com sua chave única. Cada conta possui uma chave ativa; ao gerar uma nova, a anterior é invalidada imediatamente. Utilize a chave fornecida na página de gerenciamento da sua conta.

Qual o tamanho máximo do texto?

O limite é de 4096 caracteres por solicitação. Para textos longos, você deve dividi-los manualmente em partes menores e juntar os arquivos de áudio resultantes. Espaços e pontuação contam como caracteres, então monitore o tamanho total para evitar erros.

Quais formatos de áudio são suportados?

A API suporta mp3, wav, opus, flac e pcm. Selecione o formato desejado no campo response_format da requisição JSON. A escolha depende das necessidades de compressão e qualidade do seu aplicativo, sem custos adicionais diferenciados por formato.

Como ajustar a velocidade da voz?

Utilize o parâmetro speed na requisição, aceitando valores entre 0.25 e 4.0. O padrão é 1.0. Isso permite acelerar ou desacelerar a fala para melhor adequação ao conteúdo clínico ou educativo, mantendo a clareza da síntese.

A API retorna áudio em tempo real?

Não. A API retorna o arquivo completo após o processamento. Não há streaming WebSocket ou áudio parcial. O tempo de geração é aproximadamente real-time, mas solicitações podem aguardar na fila sob carga, retornando o arquivo final.

O que fazer se receber erro 429?

O erro 429 indica limite de taxa excedido. O limite é de 60 requisições por minuto por chave. Implemente lógica de retry com backoff exponencial. Se estiver no trial, o limite inicial é de 10 requisições por minuto.

Posso usar a API em servidores backend?

Sim, a API é projetada para uso em servidores backend. Você envia texto via JSON e recebe o áudio. Não há SDK mobile ou plugin WordPress nativo, então a integração via HTTP ou SDKs compatíveis é o método padrão.

Como testar a API sem pagar?

Registre-se com Google para receber $0.50 de crédito válido por 7 dias. Isso equivale a cerca de 50.000 caracteres. Contas criadas com email e senha não recebem esse crédito inicial, exigindo recarga via USDT-TRC20 para uso contínuo.

A API suporta SSML?

Não. A API não oferece suporte a marcação SSML, nem a dicionários de fonemas ou lexicons personalizados de pronúncia. O controle é limitado aos parâmetros de velocidade, voz e formato de áudio fornecidos na requisição JSON padrão.

Como verificar as vozes disponíveis?

Acesse o endpoint GET /v1/voices para listar todas as vozes, idiomas e formatos disponíveis. Você também pode consultar GET /v1/models. Isso permite selecionar a voz adequada (como aria ou atlas) antes de enviar a requisição de síntese.

Posso usar a API com Node.js?

Sim, você pode usar qualquer linguagem que suporte HTTP ou SDKs compatíveis. Utilize o SDK oficial da OpenAI configurando a base_url para https://api.delta575.info/v1 ou faça requisições HTTP diretas com a chave de autenticação no header.

A API retorna metadados do áudio?

A resposta contém o arquivo de áudio binário. Metadados de uso (tempo, caracteres, status) são mantidos para faturamento na conta, mas não são retornados diretamente no corpo da resposta de áudio. Não há metadados embutidos no arquivo gerado além da marca d'água inaudível.

Primeira solicitação

curl

curl https://api.delta575.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.delta575.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.delta575.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafeminino
novafeminino
lunafeminino
sagefeminino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Autenticação

Ilustração de onda sonora para: Autenticação

A API utiliza autenticação baseada em token para garantir acesso seguro aos endpoints. Cada requisição deve incluir o cabeçalho Authorization: Bearer <sua-chave> para validar a identidade da conta e permitir o processamento dos caracteres solicitados.

Bearer Token

Bearer Token

O token é uma string alfanumérica iniciada por tts-. Ele deve ser enviado em cada solicitação HTTP para identificar o usuário e deduzir o saldo disponível. Sem este cabeçalho, as requisições são rejeitadas imediatamente.

Regravação de chave

Regravação de chave

Você pode gerar uma nova chave a qualquer momento diretamente no painel. Isso é útil para revogar acesso caso a chave seja exposta em logs ou repositórios públicos.

  • A chave antiga é invalidada instantaneamente.
  • A nova chave entra em vigor imediatamente.
  • Não há limite para quantas vezes você pode regravar.

Chave única por conta

Cada conta de desenvolvedor mantém apenas uma chave ativa por vez, simplificando o gerenciamento de credenciais em projetos de saúde independentes. Não é necessário gerenciar múltiplos tokens para diferentes ambientes ou serviços dentro da mesma conta.

Endpoint principal

Ilustração de onda sonora para: Endpoint principal

A síntese de voz ocorre através de uma única chamada HTTP para o endpoint principal. O serviço aceita texto bruto e retorna o arquivo de áudio gerado, seguindo o formato padrão de requisições JSON. Esta abordagem minimiza a complexidade de integração para desenvolvedores indie que precisam converter guias clínicos em áudio rapidamente.

POST /v1/audio/speech

O método POST é enviado para https://api.delta575.info/v1/audio/speech. Este é o único endpoint necessário para gerar áudio. Não há necessidade de múltiplas chamadas para configurar a sessão ou recuperar tokens temporários.

JSON body

O corpo da requisição deve ser um objeto JSON contendo os parâmetros obrigatórios e opcionais. Os campos incluem model, input, voice e response_format. O texto a ser sintetizado não pode exceder 4096 caracteres por solicitação.

Requisição HTTP

A conexão deve incluir o cabeçalho Content-Type: application/json e a autenticação Bearer. O servidor processa a solicitação e retorna o arquivo de áudio no formato especificado, como mp3 ou wav, diretamente no corpo da resposta.

Parâmetros de entrada

Ilustração de onda sonora para: Parâmetros de entrada

Os parâmetros de entrada definem como o texto será convertido em áudio. Você deve especificar o modelo, a voz, o formato de saída e a velocidade para garantir que o resultado atenda aos requisitos clínicos do seu aplicativo.

Modelo tts-1 e tts-1-hd

Use "tts-1" ou "tts-1-hd" para síntese. Ambos utilizam o mesmo motor de voz e possuem o mesmo preço de $10 por milhão de caracteres. A escolha entre eles não altera o custo, mas pode alterar a qualidade percebida, pois o modelo 'tts-1-hd' utiliza um motor de voz de maior fidelidade.

Vozes disponíveis

Existem 8 vozes pré-configuradas, divididas entre masculinas e femininas, projetadas para clareza e precisão na leitura de textos médicos. Cada voz possui uma personalidade distinta, mas todas suportam as 23 línguas listadas na documentação. Não há clonagem de voz personalizada nem criação de vozes sob medida.

  • Aria: narradora quente e clara
  • Felix: energético, ideal para promoções
  • Milo: conversacional e amigável
  • Atlas: neutro, adequado para notícias

Formato de resposta

Especifique o formato do áudio de saída entre mp3, wav, opus, flac ou pcm. O arquivo é retornado diretamente na resposta da API. Não há streaming nem WebSockets; o áudio completo é gerado antes do envio. A velocidade pode ser ajustada entre 0.25 e 4.0 para adaptar o tempo de leitura.

Exemplo com cURL

Ilustração de onda sonora para: Exemplo com cURL

A execução rápida via terminal permite validar a integração antes de implementar a lógica em produção. O comando abaixo demonstra uma solicitação básica para síntese de áudio.

Este exemplo utiliza o modelo padrão e gera um arquivo MP3. Ajuste os parâmetros conforme a necessidade clínica ou educacional do seu aplicativo.

Código pronto

Copie e execute o comando abaixo. Substitua sua-chave-aqui pela chave da API obtida em /get-api-key/.

O comando envia texto em português e recebe o áudio binário no formato MP3.

  • curl -X POST https://api.delta575.info/v1/audio/speech
  • -H 'Authorization: Bearer sua-chave-aqui'
  • -H 'Content-Type: application/json'
  • `-d '{"model": "tts-1", "voice": "nova", "input": "Bem-vindo ao guia do paciente.", "response_format": "mp3"}'`

Substituição de chave

A autenticação exige o token Bearer válido. Cada conta possui uma chave ativa que pode ser revogada a qualquer momento.

Certifique-se de que a chave não contenha espaços extras e esteja corretamente formatada antes da execução.

Execução local

Salve a resposta binária em um arquivo .mp3 para verificação imediata. O tempo de resposta varia conforme o comprimento do texto.

Para textos longos, o limite de 4096 caracteres deve ser respeitado. O processamento ocorre sequencialmente, garantindo a ordem dos áudios gerados.

Integração com OpenAI SDK

Ilustração de onda sonora para: Integração com OpenAI SDK

A API Delta TTS segue o mesmo formato de solicitação do endpoint de fala da OpenAI, permitindo que desenvolvedores indie utilizem o SDK oficial sem reescrever a lógica de requisição. A única alteração necessária é apontar o base_url para https://api.delta575.info/v1 e utilizar a chave de API gerada no painel.

Essa compatibilidade reduz o tempo de integração, pois a estrutura JSON permanece idêntica. Você pode continuar usando as bibliotecas Python, Node.js ou Go da OpenAI, ajustando apenas a URL base e as credenciais de autenticação no objeto do cliente.

Base URL customizada

Configure o atributo base_url do cliente para https://api.delta575.info/v1. Isso redireciona todas as chamadas para a infraestrutura da Delta TTS.

A estrutura de resposta e os campos JSON são idênticos aos da API de fala original, garantindo previsibilidade no tratamento dos dados.

  • URL base: https://api.delta575.info/v1
  • Formato JSON idêntico ao padrão da OpenAI
  • Compatível com SDKs oficiais

Client initialization

Inicialize o cliente passando sua chave tts-... no parâmetro api_key. O SDK reconhecerá automaticamente o prefixo para autenticação.

Certifique-se de que a versão do SDK esteja atualizada para suportar o endpoint de síntese de voz (Audio ou Speech).

  • Use os.environ.get("DELTA_TTS_KEY") para segurança
  • Chave única por conta
  • Autenticação via header Bearer

Chamada de método

Invocar client.audio.speech.create() com os parâmetros model, input, voice e response_format. O SDK gerencia a conexão HTTP e o fluxo de bytes.

O arquivo de áudio é retornado imediatamente após a síntese, permitindo gravação direta ou processamento em memória para guias de pacientes.

Não há suporte nativo para streaming no SDK padrão; para fluxos contínuos, implemente a lógica de chunking manualmente se necessário.

  • Parâmetros: model, input, voice
  • Retorno: arquivo de áudio binário
  • Sem streaming nativo no SDK padrão
Integração com OpenAI SDK

Limites e Rate Limiting

Ilustração de onda sonora para: Limites e Rate Limiting

A API impõe limites de taxa por chave de API para garantir estabilidade. O limite padrão é de 60 requisições por minuto, suficiente para a maioria dos fluxos de integração de guias clínicos e narrativas médicas automatizadas.

Para novos registros sem recarga, o limite inicial é reduzido para 10 requisições por minuto. Isso previne consumo acidental de crédito antes que o usuário configure o pagamento via USDT-TRC20.

60 req/min

Após a primeira recarga de saldo, o limite sobe para 60 solicitações por minuto por chave. Esse volume permite processar listas de medicamentos ou instruções pós-operatórias de forma contínua sem gargalos significativos.

  • Limite padrão após top-up: 60 req/min
  • Aplicado por chave de API ativa
  • Processamento sequencial pode causar leve espera sob carga

10 req/min inicial

Contas criadas sem saldo ou recarga permanecem no tier de 10 requisições por minuto. Esse limite é suficiente para testes unitários e validação de vozes antes da produção.

O limite é elevado automaticamente minutos após a confirmação da transferência USDT-TRC20.

Filetamento de texto

Como cada requisição aceita até 4096 caracteres, textos clínicos longos devem ser divididos pela aplicação cliente. A API não realiza split automático.

O cliente deve concatenar os arquivos de áudio resultantes para formar o guia completo, respeitando o limite de caracteres por chamada.

  • Máximo: 4096 caracteres por request
  • Texto excedente deve ser particionado pelo cliente
  • Áudios resultantes devem ser unidos localmente

Erros comuns

Ilustração de onda sonora para: Erros comuns

Erros comuns ocorrem quando a solicitação não segue as especificações ou os limites da conta. Identificar o código de status HTTP correto é essencial para depuração rápida.

Abaixo estão as causas frequentes e como resolvê-las para manter o fluxo de geração de áudio contínuo.

400 Bad Request

Retornado quando o JSON enviado está malformado ou contém valores inválidos, como velocidade fora do intervalo 0.25–4.0 ou texto excedendo 4096 caracteres.

Verifique se o campo input não ultrapassa o limite e se voice corresponde a uma das 8 presenças disponíveis.

  • Texto excedendo 4096 caracteres
  • Formato de voz inválido
  • JSON malformado

401 Unauthorized

Indica que o Authorization: Bearer está ausente ou incorreto.

Gere uma nova chave na página /get-api-key/ se a atual estiver revogada.

  • Token ausente
  • Token incorreto
  • Chave revogada

429 Too Many Requests

O limite é de 60 requisições por minuto por chave (10 antes do primeiro top-up).

Aguarde ou implemente retry com backoff.

  • Limite de 60 req/min
  • Limite inicial de 10 req/min

Exemplo de código Python

Ilustração de onda sonora para: Exemplo de código Python

A biblioteca requests simplifica a chamada HTTP POST para a API Delta TTS Medical, gerenciando automaticamente a serialização do corpo JSON e o envio do cabeçalho Authorization. Isso elimina a necessidade de configurar manualmente os conectores TCP ou a codificação de multipart, permitindo que o desenvolvedor indie foque na lógica de integração.

O módulo json do Python padrão é utilizado para estruturar os parâmetros de entrada, como o modelo tts-1-hd e a voz sage. Essa abordagem garante que a string de texto clínico seja enviada exatamente como especificado no esquema da API, sem conversões implícitas que possam corromper acentos ou pontuação.

Biblioteca requests

Utilize requests.post() com a URL https://api.delta575.info/v1/audio/speech. Defina o cabeçalho Authorization: Bearer <sua-chave> e o corpo como dicionário Python, que será convertido para JSON automaticamente.

Verifique sempre o status code 200 antes de processar a resposta binária. Em caso de erro, o corpo da resposta conterá detalhes JSON sobre a falha, facilitando o diagnóstico de parâmetros inválidos.

Parsing JSON

Após a requisição bem-sucedida, o campo json() ou content retorna os dados brutos. Para este endpoint, a resposta é o arquivo de áudio binário, não um JSON de metadados.

Se a resposta contiver JSON de erro (ex: 400 ou 401), use response.json() para extrair a mensagem de erro e o código de status, permitindo tratamento programático de falhas de autenticação ou limite excedido.

Salvamento de arquivo

Escreva o conteúdo binário diretamente em disco usando open('audio.mp3', 'wb').write(response.content). Isso preserva a integridade do arquivo gerado, seja ele MP3, WAV ou OPUS.

Garanta que o fluxo de arquivo seja fechado corretamente para evitar vazamentos de recursos, especialmente em loops de processamento de textos longos divididos em partes.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Como não há SLA garantido, observe os tempos de processamento, que podem variar sob carga, especialmente em textos longos.

Avatar da voz aria
ariafeminino
Avatar da voz nova
novafeminino
Avatar da voz luna
lunafeminino
Avatar da voz sage
sagefeminino
Avatar da voz felix
felixmasculino
Avatar da voz milo
milomasculino
Avatar da voz atlas
atlasmasculino
Avatar da voz orion
orionmasculino

23 idiomas

Qualquer voz fala qualquer um desses idiomas.

Fontes e leituras adicionais

  1. Wikipedia
  2. Node.js documentation
  3. openai-python on GitHub
  4. LibriTTS-R corpus (OpenSLR 141)
  5. curl documentation
  6. OpenAI API reference: create speech
  7. Tether (USDT)
  8. Creative Commons Attribution 4.0
  9. MDN: Web Speech API
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. LibriVox public-domain audiobooks
  12. IETF RFC 7845: Ogg Opus

Mais neste site