Texto para Fala (TTS)

Os serviços de TTS (Text-to-Speech) do SipPulse AI convertem texto escrito em áudio com som natural, permitindo que suas aplicações "falem" com seus usuários. Nossa plataforma oferece uma variedade de modelos de provedores renomados como OpenAI, ElevenLabs e Microsoft, cada um com um conjunto distinto de vozes e características.

Para informações detalhadas sobre preços e especificações de cada modelo, consulte nossa página de Pricing.

1. Playground Interativo de Texto para Fala

O Playground Interativo de Texto para Fala (acesse aqui) é a ferramenta ideal para experimentar e validar os modelos TTS de forma intuitiva antes de integrá-los via API:

Seleção de Modelos e Vozes: Explore os diversos modelos de síntese de fala (OpenAI, ElevenLabs, Microsoft) e as vozes disponíveis para cada um.
Entrada de Texto: Insira o texto que deseja converter em áudio.
Ajuste de Parâmetros: Configure parâmetros como velocidade (speed) e o formato de saída do áudio (response_format).
Geração e Reprodução Imediata: Execute a síntese e ouça o áudio resultante diretamente na interface.
Visualização de Código: Obtenha exemplos de código em cURL, Python e JavaScript, pré-configurados com o modelo, voz e parâmetros que você testou, facilitando a implementação em suas aplicações.

O Playground é uma excelente maneira de descobrir a voz perfeita para seu projeto e entender como os diferentes parâmetros afetam o resultado final da síntese de fala.

Playground de Texto para Fala

2. Consumo via API REST

A integração da funcionalidade de TTS em suas aplicações é realizada através de chamadas à nossa API REST.

2.1. Sintetizar Fala

Utilize o endpoint /v1/tts/generate para converter uma string de texto em dados de áudio.

Endpoint: POST /v1/tts/generate

Corpo da Requisição (JSON):

input (string, obrigatório): O texto a ser convertido em fala.
model (string, obrigatório): O nome do modelo de TTS a ser utilizado (e.g., "tts-1" para OpenAI, "eleven_multilingual_v2" para ElevenLabs, ou um modelo específico da Microsoft). Consulte o endpoint /v1/tts/models para a lista de modelos disponíveis.
voice (string, obrigatório): A chave (key) da voz específica a ser usada para a síntese (e.g., "alloy", "shimmer" para OpenAI TTS; uma ID de voz da ElevenLabs; ou um nome de voz da Microsoft como "pt-BR-FranciscaNeural"). Consulte o endpoint /v1/tts/voices para obter as chaves das vozes disponíveis para cada modelo.
response_format (string, opcional, padrão: "mp3"): O formato do arquivo de áudio de saída. Valores suportados: "mp3", "opus", "aac", "flac", "wav", "pcm".
speed (float, opcional, padrão: 1.0): Controla a velocidade da fala. Valores típicos entre 0.25 e 4.0. O intervalo exato pode variar conforme o modelo.

Parâmetros Dinâmicos

Os parâmetros disponíveis variam conforme o modelo. Use o Playground para ver quais parâmetros são suportados por cada modelo. Parâmetros comuns incluem speed e response_format, mas nem todos os modelos suportam todas as opções.

Resposta (JSON):

Sucesso (200 OK):

json

{
  "filename": "string", // Nome do arquivo gerado
  "usage": {}, // Informações de uso (pode variar)
  "performance": {}, // Informações de performance (pode variar)
  "unit": "string", // Unidade de custo (e.g., "characters")
  "stream": "string", // URL para streaming do áudio
  "download": "string" // URL para download do áudio
}

Erro: Resposta JSON com código de status HTTP apropriado e detalhes do erro no corpo.

cURLPythonJavaScript

bash

# Exemplo: Sintetizar fala
curl -X POST 'https://api.sippulse.ai/v1/tts/generate' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "Olá, mundo! Esta é uma demonstração da síntese de fala.",
    "model": "tts-1",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1.1
  }'

python

import os
import requests
import json

def synthesize_speech(
    text_input: str,
    model_id: str,
    voice_key: str,
    response_format: str = "mp3",
    speed: float = 1.0
) -> dict | None:
    """
    Sintetiza fala a partir de texto utilizando a API SipPulse AI.
    """
    api_url = "https://api.sippulse.ai/v1/tts/generate"
    api_key = os.getenv("SIPPULSE_API_KEY")

    if not api_key:
        print("Erro: A variável de ambiente SIPPULSE_API_KEY não está configurada.")
        return None

    headers = {
        "api-key": api_key,
        "Content-Type": "application/json"
    }
    payload = {
        "input": text_input,
        "model": model_id,
        "voice": voice_key,
        "response_format": response_format,
        "speed": speed
    }

    try:
        response = requests.post(api_url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        error_content = e.response.text
        try:
            error_json = e.response.json()
            error_content = json.dumps(error_json, indent=2)
        except json.JSONDecodeError:
            pass
        print(f"Erro na API: {e.response.status_code}\n{error_content}")
    except Exception as e:
        print(f"Ocorreu um erro inesperado: {e}")
    return None

if __name__ == "__main__":
    tts_result = synthesize_speech(
        text_input="Testando a síntese de voz com a API.",
        model_id="tts-1", # Exemplo com modelo OpenAI
        voice_key="nova",    # Exemplo com voz OpenAI
        response_format="mp3",
        speed=1.0
    )
    if tts_result:
        print("Síntese bem-sucedida:")
        print(json.dumps(tts_result, indent=2, ensure_ascii=False))
        print(f"Link para download: {tts_result.get('download')}")
        print(f"Link para stream: {tts_result.get('stream')}")

javascript

// Node.js com fetch
async function synthesizeSpeech({
  textInput,
  modelId,
  voiceKey,
  responseFormat = "mp3",
  speed = 1.0,
}) {
  const apiUrl = "https://api.sippulse.ai/v1/tts/generate";
  const apiKey = process.env.SIPPULSE_API_KEY;

  if (!apiKey) {
    console.error("A variável de ambiente SIPPULSE_API_KEY não está configurada.");
    return null;
  }

  const payload = {
    input: textInput,
    model: modelId,
    voice: voiceKey,
    response_format: responseFormat,
    speed,
  };

  try {
    const response = await fetch(apiUrl, {
      method: "POST",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      let errorBody = await response.text();
      try {
        errorBody = JSON.stringify(JSON.parse(errorBody), null, 2);
      } catch (e) { /* não é JSON */ }
      throw new Error(`Erro na API: ${response.status} ${response.statusText}\n${errorBody}`);
    }
    return response.json();
  } catch (error) {
    console.error("Falha ao sintetizar fala:", error);
    return null;
  }
}

// Exemplo de uso:
// (async () => {
//   const result = await synthesizeSpeech({
//     textInput: "Olá, JavaScript falando aqui!",
//     modelId: "eleven_multilingual_v2", // Exemplo com ElevenLabs
//     voiceKey: "VOICE_ID_ELEVENLABS", // Substitua pela ID da voz desejada da ElevenLabs
//     responseFormat: "opus",
//     speed: 0.9
//   });
//   if (result) {
//     console.log("Resultado da Síntese:", JSON.stringify(result, null, 2));
//   }
// })();

2.2. Listar Modelos de TTS Disponíveis

Para consultar os modelos de TTS (Text-to-Speech) atualmente disponíveis para sua organização:

Endpoint: GET /v1/tts/models

Parâmetros de Query:

status (string, opcional): Filtra modelos pelo status (active ou inactive). Padrão: active.

cURLPythonJavaScript

bash

curl -X GET 'https://api.sippulse.ai/v1/tts/models?status=active' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -H 'Accept: application/json'

python

import os
import requests

def list_tts_models(status: str = "active") -> list | None:
  """
  Lista os modelos de TTS disponíveis na API SipPulse AI.
  """
  api_url = "https://api.sippulse.ai/v1/tts/models"
  api_key = os.getenv("SIPPULSE_API_KEY")

  if not api_key:
    print("Erro: A variável de ambiente SIPPULSE_API_KEY não está configurada.")
    return None

  headers = {
    "api-key": api_key,
    "Accept": "application/json"
  }
  params = {"status": status}

  try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()
  except requests.exceptions.HTTPError as e:
    print(f"Erro na API: {e.response.status_code}")
  return None

# Uso
models = list_tts_models()
if models:
  for model in models:
    print(f"{model['name']} ({model['provider']})")

javascript

async function listTTSModels(status = "active") {
  const apiUrl = `https://api.sippulse.ai/v1/tts/models?status=${status}`;
  const apiKey = process.env.SIPPULSE_API_KEY;

  if (!apiKey) {
    console.error("A variável de ambiente SIPPULSE_API_KEY não está configurada.");
    return null;
  }

  try {
    const response = await fetch(apiUrl, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Accept": "application/json",
      },
    });

    if (!response.ok) {
      throw new Error(`Erro na API: ${response.status}`);
    }
    return response.json();
  } catch (error) {
    console.error("Falha ao listar modelos TTS:", error);
    return null;
  }
}

// Uso
// const models = await listTTSModels();
// models?.forEach(m => console.log(`${m.name} (${m.provider})`));

Exemplo de Resposta (JSON):

json

[
  {
    "name": "tts-1",
    "status": "active",
    "provider": "openai"
  },
  {
    "name": "eleven_multilingual_v2",
    "status": "active",
    "provider": "elevenlabs"
  },
  {
    "name": "azure-tts",
    "status": "active",
    "provider": "microsoft"
  }
]

2.3. Listar Vozes Disponíveis

Para consultar as vozes disponíveis para síntese. A resposta é um Record onde a chave é o nome do modelo e o valor é uma lista de suas vozes.

Endpoint: GET /v1/tts/voices

cURLPythonJavaScript

bash

curl -X GET 'https://api.sippulse.ai/v1/tts/voices' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -H 'Accept: application/json'

python

import os
import requests

def list_tts_voices(model: str = None) -> dict | None:
  """
  Lista as vozes disponíveis para modelos TTS.
  Opcionalmente filtra por nome do modelo.
  """
  api_url = "https://api.sippulse.ai/v1/tts/voices"
  api_key = os.getenv("SIPPULSE_API_KEY")

  if not api_key:
    print("Erro: A variável de ambiente SIPPULSE_API_KEY não está configurada.")
    return None

  headers = {
    "api-key": api_key,
    "Accept": "application/json"
  }
  params = {"model": model} if model else {}

  try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()
  except requests.exceptions.HTTPError as e:
    print(f"Erro na API: {e.response.status_code}")
  return None

# Uso
voices = list_tts_voices()
if voices:
  for model_name, voice_list in voices.items():
    print(f"\n{model_name}:")
    for voice in voice_list[:3]:  # Mostra as 3 primeiras vozes
      print(f"  - {voice['name']} ({voice['key']}) - {voice['languages']}")

javascript

async function listTTSVoices(model = null) {
  const params = model ? `?model=${model}` : "";
  const apiUrl = `https://api.sippulse.ai/v1/tts/voices${params}`;
  const apiKey = process.env.SIPPULSE_API_KEY;

  if (!apiKey) {
    console.error("A variável de ambiente SIPPULSE_API_KEY não está configurada.");
    return null;
  }

  try {
    const response = await fetch(apiUrl, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Accept": "application/json",
      },
    });

    if (!response.ok) {
      throw new Error(`Erro na API: ${response.status}`);
    }
    return response.json();
  } catch (error) {
    console.error("Falha ao listar vozes TTS:", error);
    return null;
  }
}

// Uso
// const voices = await listTTSVoices("tts-1");
// Object.entries(voices).forEach(([model, voiceList]) => {
//   console.log(`${model}: ${voiceList.length} vozes`);
// });

Exemplo de Resposta (JSON):

json

{
  "tts-1": [
    { "name": "Alloy", "key": "alloy", "languages": ["multi"] },
    { "name": "Echo", "key": "echo", "languages": ["multi"] },
    { "name": "Nova", "key": "nova", "languages": ["multi"] }
  ],
  "eleven_multilingual_v2": [
    { "name": "Rachel", "key": "21m00Tcm4TlvDq8ikWAM", "languages": ["multi"] },
    { "name": "Adam", "key": "pNInz6obpgDQGcFmaJgB", "languages": ["multi"] }
  ],
  "azure-tts": [
    { "name": "Francisca", "key": "pt-BR-FranciscaNeural", "languages": ["pt-BR"] },
    { "name": "Emma", "key": "en-US-EmmaNeural", "languages": ["en-US"] }
  ]
}

Utilize a key da voz desejada no parâmetro voice da requisição de síntese (/v1/tts/generate).

3. Formatos de Áudio Suportados (`response_format`)

O SipPulse AI TTS suporta os seguintes formatos de saída de áudio:

Formato	Tipo MIME	Tamanho	Qualidade	Melhor Para
`mp3`	`audio/mpeg`	Pequeno	Boa	Aplicações web, uso geral
`opus`	`audio/ogg`	Muito pequeno	Excelente	Streaming em tempo real, VoIP
`aac`	`audio/aac`	Pequeno	Muito boa	Apps mobile, iOS
`flac`	`audio/flac`	Grande	Lossless	Arquivamento, áudio profissional
`wav`	`audio/wav`	Muito grande	Lossless	Edição de áudio, processamento
`pcm`	`audio/L16`	Muito grande	Raw	Sistemas de telefonia, processamento customizado

Recomendações de Formato

Aplicações web: Use mp3 para ampla compatibilidade
Tempo real/streaming: Use opus para melhor compressão
Apps mobile: Use aac para iOS ou opus para Android
Telefonia/URA: Use pcm (24kHz mono) para integração direta

A escolha do formato depende dos requisitos da sua aplicação em termos de qualidade, tamanho de arquivo e compatibilidade com players de áudio.

4. Integração com SDK da OpenAI

Para desenvolvedores que preferem utilizar o SDK oficial da OpenAI, o SipPulse AI oferece compatibilidade. Configure o baseURL do cliente OpenAI para o endpoint do SipPulse AI: https://api.sippulse.ai/v1/openai.

Ao usar esta integração para TTS, a API do SipPulse AI retornará diretamente o stream binário do áudio no formato solicitado, em vez do objeto JSON com links de download/stream. Isso se alinha com o comportamento padrão do SDK da OpenAI para síntese de fala.

O endpoint de compatibilidade com o SDK da OpenAI suporta os parâmetros padrão definidos pela API da OpenAI. A disponibilidade dos parâmetros pode variar dependendo do modelo específico.

Modal de Código

PythonJavaScript

python

import os
from openai import OpenAI

# Configura o cliente OpenAI para usar o endpoint do SipPulse AI
client = OpenAI(
  api_key=os.environ.get("SIPPULSE_API_KEY"),
  base_url="https://api.sippulse.ai/v1/openai" # Endpoint de compatibilidade do SipPulse AI
)

try:
  response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Olá, este áudio foi gerado usando o SDK da OpenAI através do SipPulse AI!",
    response_format="mp3",
    speed=1.0  # Opcional: 0.25 a 4.0
  )
  # A resposta 'response' contém o stream de áudio.
  # Você pode salvar em um arquivo:
  response.stream_to_file("sippulse_openai_sdk_output.mp3")
  print("Áudio gerado e salvo como sippulse_openai_sdk_output.mp3")

except Exception as e:
  print(f"Ocorreu um erro: {e}")

javascript

// Exemplo de uso com o SDK JavaScript da OpenAI em Node.js
import OpenAI from "openai";
import fs from "fs";
import path from "path";

const openai = new OpenAI({
  apiKey: process.env.SIPPULSE_API_KEY,
  baseURL: "https://api.sippulse.ai/v1/openai"
});

async function main() {
  try {
    const speechStream = await openai.audio.speech.create({
      model: "tts-1",
      voice: "nova",
      input: "Testando a síntese de fala com o SDK JavaScript e SipPulse AI.",
      response_format: "opus"
    });

    // speechStream é um ReadableStream. Você pode salvá-lo em um arquivo.
    const filePath = path.resolve("./sippulse_openai_sdk_output.opus");
    const writer = fs.createWriteStream(filePath);

    // Node.js < 18 (sem ReadableStream.toWeb()):
    // speechStream.body.pipe(writer);
    // await new Promise((resolve, reject) => {
    //   writer.on("finish", resolve);
    //   writer.on("error", reject);
    // });

    // Node.js >= 18 (com ReadableStream.toWeb() e Readable.fromWeb())
    // Ou se o SDK retornar um ReadableStream do Node diretamente:
    for await (const chunk of speechStream) {
        writer.write(chunk);
    }
    writer.end();
    // Alternativamente, se speechStream.body for um stream web:
    // const nodeStream = Readable.fromWeb(speechStream.body);
    // nodeStream.pipe(writer);
    // ... (código de promise para aguardar 'finish')


    console.log(`Áudio gerado e salvo como ${filePath}`);

  } catch (error) {
    console.error("Ocorreu um erro:", error);
  }
}

main();

Nota: O endpoint de compatibilidade do SDK OpenAI suporta modelos TTS da OpenAI (tts-1, tts-1-hd) com suas vozes padrão. Para acessar outros provedores como ElevenLabs ou Azure, use a API REST nativa (/v1/tts/generate).

5. Boas Práticas para Síntese de Fala

Texto Claro e Bem Estruturado: Forneça texto gramaticalmente correto e bem pontuado para a melhor prosódia e inteligibilidade.
Escolha Adequada de Voz e Idioma: Utilize os endpoints /v1/tts/models e /v1/tts/voices para selecionar a combinação de modelo e voz que melhor se alinham com seu público-alvo e o contexto da aplicação.
Experimente Formatos de Saída: Teste diferentes response_format para encontrar o equilíbrio ideal entre qualidade sonora e tamanho de arquivo.
Gerenciamento de Erros Robusto: Implemente tratamento de erros detalhado em sua aplicação para lidar com possíveis falhas na API.
Caching: Para textos frequentemente sintetizados, armazene os links de download ou stream (ou o próprio áudio, se baixado) para evitar requisições repetidas e otimizar custos e latência.

6. Perguntas Frequentes (FAQ)

P: Como os custos são calculados para o serviço de TTS?R: Os custos são tipicamente baseados no número de caracteres no campo input processados para síntese. Diferentes modelos e vozes (especialmente premium ou customizadas) podem ter custos distintos. Consulte a página de Pricing e o seu dashboard de conta para um detalhamento preciso.

P: Posso usar os links de download e stream múltiplas vezes?R: Sim, os links fornecidos na resposta da API /v1/tts/generate podem ser usados para acessar o áudio gerado. No entanto, a disponibilidade desses links a longo prazo pode depender das políticas de armazenamento do SipPulse AI. Para uso persistente, recomenda-se baixar o áudio.

Agentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Configurações

Texto para Fala (TTS)

1. Playground Interativo de Texto para Fala

2. Consumo via API REST

2.1. Sintetizar Fala

2.2. Listar Modelos de TTS Disponíveis

2.3. Listar Vozes Disponíveis

3. Formatos de Áudio Suportados (`response_format`)

4. Integração com SDK da OpenAI

5. Boas Práticas para Síntese de Fala

6. Perguntas Frequentes (FAQ)

Configuração

Ferramentas

Avançado

Implantando Agentes

Texto para Fala (TTS) ​

1. Playground Interativo de Texto para Fala ​

2. Consumo via API REST ​

2.1. Sintetizar Fala ​

2.2. Listar Modelos de TTS Disponíveis ​

2.3. Listar Vozes Disponíveis ​

3. Formatos de Áudio Suportados (response_format) ​

4. Integração com SDK da OpenAI ​

5. Boas Práticas para Síntese de Fala ​

6. Perguntas Frequentes (FAQ) ​

Texto para Fala (TTS)

1. Playground Interativo de Texto para Fala

2. Consumo via API REST

2.1. Sintetizar Fala

2.2. Listar Modelos de TTS Disponíveis

2.3. Listar Vozes Disponíveis

3. Formatos de Áudio Suportados (`response_format`)

4. Integração com SDK da OpenAI

5. Boas Práticas para Síntese de Fala

6. Perguntas Frequentes (FAQ)