Português

English

Português

English

Tema Escuro

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.

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.

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.
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.
bash
curl -X GET 'https://api.sippulse.ai/v1/tts/models?status=active' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -H 'Accept: application/json'
python
# (Implementação similar à seção 2.1, adaptada para GET /v1/tts/models)
# Exemplo de chamada: list_tts_models()
javascript
# (Implementação similar à seção 2.1, adaptada para GET /v1/tts/models)
# Exemplo de chamada: listTTSModels()

Exemplo de Resposta (JSON):

json
[
  {
    "name": "tts-1", // Modelo da OpenAI
    "status": "active",
    "provider": "openai"
  },
  {
    "name": "eleven_multilingual_v2", // Modelo da ElevenLabs
    "status": "active",
    "provider": "elevenlabs"
  },
  {
    "name": "MicrosoftSpeechModel", // Exemplo de modelo Microsoft
    "status": "active",
    "provider": "microsoft"
  }
  // ... outros modelos
]

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

bash
curl -X GET 'https://api.sippulse.ai/v1/tts/voices' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -H 'Accept: application/json'
python
# (Implementação similar à seção 2.1, adaptada para GET /v1/tts/voices)
# Exemplo de chamada: list_tts_voices()
javascript
# (Implementação similar à seção 2.1, adaptada para GET /v1/tts/voices)
# Exemplo de chamada: listTTSVoices()

Exemplo de Resposta (JSON):

json
{
  "tts-1": [ // Vozes para o modelo "tts-1" (OpenAI)
    { "name": "Alloy", "key": "alloy", "language": "multilingual" },
    { "name": "Echo", "key": "echo", "language": "multilingual" },
    { "name": "Fable", "key": "fable", "language": "multilingual" },
    { "name": "Onyx", "key": "onyx", "language": "multilingual" },
    { "name": "Nova", "key": "nova", "language": "multilingual" },
    { "name": "Shimmer", "key": "shimmer", "language": "multilingual" }
  ],
  "eleven_multilingual_v2": [ // Vozes para o modelo "eleven_multilingual_v2" (ElevenLabs)
    { "name": "Rachel", "key": "21m00Tcm4TlvDq8ikWAM", "language": "multilingual" },
    { "name": "Adam", "key": "pNInz6obpgDQGcFmaJgB", "language": "multilingual" }
    // ... outras vozes da ElevenLabs
  ],
  "MicrosoftSpeechModel": [ // Vozes para um modelo da Microsoft
    { "name": "Francisca (Português, Brasil)", "key": "pt-BR-FranciscaNeural", "language": "pt-BR" },
    { "name": "Antonio (Português, Brasil)", "key": "pt-BR-AntonioNeural", "language": "pt-BR" }
    // ... outras vozes da Microsoft
  ]
}

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:

  • mp3: audio/mpeg
  • opus: audio/ogg (Opus encapsulado em Ogg)
  • aac: audio/aac
  • flac: audio/flac
  • wav: audio/wav
  • pcm: audio/L16; rate=24000; channels=1 (PCM linear, 16-bit, 24kHz, mono)

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.

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", # Modelo TTS da OpenAI disponível no SipPulse AI
    voice="alloy",   # Voz desejada
    input="Olá, este áudio foi gerado usando o SDK da OpenAI através do SipPulse AI!",
    response_format="mp3" # Formato de áudio desejado
    # speed pode ser suportado dependendo da implementação do endpoint de compatibilidade
  )
  # 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: Ao usar o SDK da OpenAI, certifique-se de que o modelo e a voz especificados são compatíveis com a oferta do SipPulse AI para o endpoint https://api.sippulse.ai/v1/openai. Parâmetros como speed podem ter comportamento específico ou limitações através desta interface de compatibilidade.

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.