Transcrição de Áudio Avançada (Speech-to-Text)

Os serviços de STT (Speech-to-Text) do SipPulse AI convertem arquivos de áudio em texto com alta precisão, permitindo enriquecer suas aplicações com dados vocais valiosos. Nossa plataforma oferece:

Modelos proprietários de alta performance pulse-precision (foco em máxima acurácia, resultando em um excelente Word Error Rate - WER) e pulse-speed (otimizado para baixa latência), ambos com suporte avançado a diarização (identificação de múltiplos interlocutores).
Recursos avançados como anonimização de dados sensíveis e Audio Intelligence para análises estruturadas e insights automáticos a partir das transcrições.

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

Playground Interativo

O Playground Interativo de Transcrição de Áudio (acesse aqui) é a ferramenta ideal para experimentar e validar os modelos STT de forma intuitiva:

Upload de Arquivo de Áudio
- Realize o upload de arquivos de áudio (formatos MP3, WAV, PCM, OGG com limite de 25 MB) arrastando e soltando ou através do seletor de arquivos.
Seleção do Modelo de Transcrição
- Escolha entre os modelos disponíveis:
  - pulse-precision: Otimizado para a mais alta precisão na transcrição.
  - pulse-speed: Prioriza a velocidade de processamento, ideal para casos de uso que exigem menor latência.
  - pulse-precision-pro: Máxima precisão com diarização estéreo para gravações de call center. Inclui vad_preset para detecção otimizada de atividade de voz e 100% de precisão na identificação de falantes baseada em canal.
  - whisper-1: Modelo da OpenAI.
  - whisper-chat: Modelo da OpenAI com alta velocidade de resposta. Ideal para aplicações que requerem respostas rápidas, mesmo que com uma leve redução na precisão em comparação ao pulse-precision.
Configuração de Parâmetros
- Formato de Saída (format): Defina o formato desejado para a transcrição (text, json, vtt, srt, verbose_json, diarization). Obs: diarization só está disponível para os modelos pulse-precision e pulse-speed.
- Idioma (language): Especifique o idioma do áudio (e.g., pt, en, es).
- Instruções (prompt): Forneça instruções ou contexto adicional (termos específicos, nomes próprios) para orientar e refinar o processo de transcrição.
Recursos Avançados
- Anonimização (anonymize): Habilite para ofuscar automaticamente dados sensíveis identificados na transcrição (e.g., CPF, e-mail, endereços IP). Consulte a documentação de Redação de Texto para detalhes sobre o funcionamento.
- Audio Intelligence (insights): Ative para receber análises estruturadas juntamente com a transcrição. As opções incluem sumarização, identificação de tópicos, análise de sentimento, entre outras, processadas diretamente no endpoint.
Executar Transcrição
- Clique no botão Transcrever para que o áudio seja processado utilizando o modelo e os parâmetros selecionados. O resultado da transcrição será exibido na interface.
Visualizar Código de Integração
- A funcionalidade "Ver Código" gera automaticamente exemplos de código para integração em cURL (Bash), Python e JavaScript (Node.js). Estes exemplos são pré-configurados com os mesmos parâmetros utilizados no Playground, facilitando a implementação da funcionalidade de transcrição em suas aplicações.

Audio Insights

O Audio Insights fornece análises automáticas das suas transcrições diretamente na resposta da API. Este recurso é ideal para usuários que precisam de análises rápidas e integradas sem chamadas adicionais de API.

Tipos de Insights Disponíveis

Sumarização

Gera um resumo conciso da transcrição, destacando as informações mais relevantes.

json

{
  "insights": {
    "summarization": true
  }
}

Detecção de Tópicos

Identifica os principais tópicos discutidos na transcrição. Cada tópico inclui um valor de confiança (0 a 1) indicando a precisão da detecção. Você pode opcionalmente especificar tópicos a detectar (máx 20).

json

{
  "insights": {
    "topic_detection": {
      "topics": ["preço", "suporte", "cobrança"]
    }
  }
}

Se topics for omitido, o modelo detectará automaticamente os tópicos relevantes.

Formato da resposta:

json

{
  "audio_insights": {
    "content": {
      "topic_detection": [
        {
          "label": "preço",
          "confidence": 0.92,
          "fragment": "Precisamos discutir o novo modelo de preços...",
          "timestamp": "00:01:23"
        }
      ]
    }
  }
}

Análise de Sentimento

Detecta as emoções expressas na transcrição. Você pode especificar sentimentos a detectar (máx 20) ou usar os padrões.

Sentimentos padrão: alegria, confiança, medo, surpresa, tristeza, repugnância, raiva, antecipação, neutro, frustração, satisfação, empolgação, decepção, curiosidade, amor, ódio, tédio, confusão, constrangimento, culpa

json

{
  "insights": {
    "sentiment_analysis": {
      "sentiments": ["satisfação", "frustração", "neutro"]
    }
  }
}

Se sentiments for omitido, todos os sentimentos padrão serão analisados.

Formato da resposta:

json

{
  "audio_insights": {
    "content": {
      "sentiment_analysis": [
        {
          "label": "satisfação",
          "score": 0.85,
          "fragment": "Estou muito feliz com o serviço...",
          "timestamp": "00:02:45"
        }
      ]
    }
  }
}

Análise Personalizada

Defina suas próprias análises para extrair informações específicas da transcrição. Cada análise personalizada requer um título, descrição e tipo de saída.

json

{
  "insights": {
    "custom": [
      {
        "title": "Palavras-chave",
        "description": "Extraia 5 palavras-chave principais da conversa",
        "type": "string"
      },
      {
        "title": "Resolução da Chamada",
        "description": "O problema do cliente foi resolvido? Responda verdadeiro ou falso",
        "type": "boolean"
      },
      {
        "title": "Nota de Satisfação",
        "description": "Avalie a satisfação do cliente de 1 a 10",
        "type": "number"
      }
    ]
  }
}

Audio Insights vs Análise Estruturada

Audio Insights é ótimo para análises rápidas e integradas durante a transcrição—ideal para casos de uso comuns como sumarização e detecção de sentimento. Para cenários mais avançados com presets personalizados, schemas JSON complexos e templates reutilizáveis, use a Análise Estruturada como uma chamada de API separada.

Formatos de Resposta

O parâmetro response_format controla a estrutura de saída da transcrição:

Formato	Descrição	Caso de Uso
`text`	Transcrição em texto plano	Extração simples de texto
`json`	Objeto JSON com campo `text`	Acesso programático ao texto
`verbose_json`	JSON com segmentos, idioma e metadados de duração	Análise detalhada com timestamps
`srt`	Formato de legenda SubRip	Legendas de vídeo
`vtt`	Formato WebVTT	Legendas para vídeos web
`diarization`	Transcrição separada por falante com timestamps	Conversas com múltiplos falantes
`stereo_diarization`	Transcrição separada por falante usando canais de áudio (L/R)	Gravações de chamadas estéreo

Disponibilidade da Diarização

O formato diarization está disponível apenas com modelos proprietários (pulse-precision, pulse-speed). Modelos OpenAI (whisper-1) não suportam diarização de falantes.

Diarização Estéreo

Para gravações de call center onde cada falante está em um canal de áudio separado (esquerdo/direito), use o recurso de diarização estéreo com o modelo pulse-precision-pro.

Aspecto	Diarização Padrão	Diarização Estéreo
Identificação de falante	Detecção por IA	Baseada em canal (L/R)
Precisão	Boa	Perfeita (100%)
Performance	Normal	Mais rápida
Labels de falante	SPEAKER 1, SPEAKER 2...	SPEAKER_L, SPEAKER_R

Perfeito para Call Centers

A diarização estéreo fornece 100% de precisão na identificação de falantes, já que cada canal de áudio representa um falante. Não é necessária inferência por IA—apenas separação de canais.

VAD Preset para Telefonia

O modelo pulse-precision-pro inclui presets otimizados de Detecção de Atividade de Voz (VAD):

Preset	Caso de Uso	Descrição
`default`	Áudio geral	Configurações VAD padrão para áudio de alta qualidade (16kHz+)
`telephony`	Chamadas telefônicas	Otimizado para áudio de telefonia de banda estreita 8kHz

Quando Usar o Preset Telephony

Use vad_preset=telephony ao transcrever gravações de chamadas de sistemas PBX. Este preset é ajustado para as características específicas do áudio telefônico, melhorando a precisão na detecção de limites de fala e reduzindo falsos positivos de ruído de linha.

Para um guia completo com exemplos de código e integração com análise estruturada, veja Transcrição de Chamadas Estéreo.

Consumo via API REST

Utilize o endpoint nativo /v1/asr/transcribe para ter controle total sobre todos os recursos e modelos, incluindo os avançados pulse-precision e pulse-speed com diarização.

cURLPythonJavaScript

bash

# Exemplo: Transcrição com diarização, anonimização e Audio Intelligence (sumarização e tópicos)
# utilizando o modelo pulse-precision.
curl -X POST 'https://api.sippulse.ai/v1/asr/transcribe' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -F 'file=@audio.wav' \
  -F 'model=pulse-precision' \
  -F 'format=verbose_json' \
  -F 'language=pt' \
  -F 'diarization=true' \
  -F 'anonymize=true' \
  -F 'insights=["summarization","topics"]'

python

import os
import requests
import json # Adicionado para requests.utils.json.dumps, ou usar json.dumps diretamente

def transcribe_audio_advanced(
    file_path: str,
    model: str = "pulse-precision", # Padrão para nosso modelo de alta precisão
    output_format: str = "verbose_json",
    language: str = "pt",
    enable_diarization: bool = True,
    enable_anonymization: bool = True,
    audio_insights: list = None
) -> dict:
    """
    Realiza a transcrição de um arquivo de áudio utilizando o endpoint /v1/asr/transcribe
    do SipPulse AI, com suporte a recursos avançados.

    Args:
        file_path: Caminho para o arquivo de áudio.
        model: Modelo de transcrição a ser utilizado (e.g., "pulse-precision", "pulse-speed").
        output_format: Formato da saída da transcrição.
        language: Código do idioma do áudio.
        enable_diarization: Ativa/desativa a diarização (separação de interlocutores).
        enable_anonymization: Ativa/desativa a anonimização de dados sensíveis.
        audio_insights: Lista de análises de Audio Intelligence a serem aplicadas (e.g., ["summarization", "topics"]).
    """
    api_url = "https://api.sippulse.ai/v1/asr/transcribe"
    headers = {"api-key": os.getenv("SIPPULSE_API_KEY")}

    with open(file_path, "rb") as audio_file:
        files = {"file": audio_file}
        payload = {
            "model": model,
            "format": output_format,
            "language": language,
            "diarization": str(enable_diarization).lower(),
            "anonymize": str(enable_anonymization).lower(),
        }
        if audio_insights:
            # Usando json.dumps diretamente, já que requests.utils.json é um alias para o módulo json padrão
            payload["insights"] = json.dumps(audio_insights)

        response = requests.post(api_url, headers=headers, files=files, data=payload)
    response.raise_for_status()  # Levanta uma exceção para respostas de erro HTTP
    return response.json()

if __name__ == "__main__":
    # Substitua "audio.wav" pelo caminho do seu arquivo de áudio
    # É necessário ter a variável de ambiente SIPPULSE_API_KEY configurada
    try:
        transcription_result = transcribe_audio_advanced(
            "audio.wav",
            model="pulse-precision",
            audio_insights=["summarization", "topics"]
        )
        print(json.dumps(transcription_result, indent=2, ensure_ascii=False))
    except FileNotFoundError:
        print("Erro: Arquivo de áudio não encontrado. Verifique o caminho.")
    except requests.exceptions.HTTPError as e:
        print(f"Erro na API: {e.response.status_code} - {e.response.text}")
    except Exception as e:
        print(f"Ocorreu um erro inesperado: {e}")

javascript

// Node.js com node-fetch e form-data
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch"; // Certifique-se de que node-fetch@2 está instalado ou use a API fetch nativa do Node 18+

async function transcribeAudioAdvanced(
  filePath,
  model = "pulse-precision", // Padrão para nosso modelo de alta precisão
  outputFormat = "verbose_json",
  language = "pt",
  enableDiarization = true,
  enableAnonymization = true,
  audioInsights = ["summarization", "topics"]
) {
  const apiUrl = "https://api.sippulse.ai/v1/asr/transcribe";
  const apiKey = process.env.SIPPULSE_API_KEY;

  if (!apiKey) {
    throw new Error("A variável de ambiente SIPPULSE_API_KEY não está configurada.");
  }

  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));
  form.append("model", model);
  form.append("format", outputFormat);
  form.append("language", language);
  form.append("diarization", String(enableDiarization).toLowerCase());
  form.append("anonymize", String(enableAnonymization).toLowerCase());
  if (audioInsights && audioInsights.length > 0) {
    form.append("insights", JSON.stringify(audioInsights));
  }

  const response = await fetch(apiUrl, {
    method: "POST",
    headers: {
      "api-key": apiKey,
      // FormData define Content-Type automaticamente com o boundary correto
      // ...form.getHeaders() // Descomente se estiver usando uma versão mais antiga de form-data que requer isso
    },
    body: form,
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`Erro na API: ${response.status} ${response.statusText} - ${errorBody}`);
  }
  return response.json();
}

// Exemplo de uso:
// (async () => {
//   try {
//     // Substitua "audio.wav" pelo caminho do seu arquivo de áudio
//     const result = await transcribeAudioAdvanced("audio.wav");
//     console.log(JSON.stringify(result, null, 2));
//   } catch (error) {
//     console.error("Falha ao transcrever áudio:", error);
//   }
// })();

Considerações sobre Custos Adicionais:
A utilização dos recursos de Diarization, Anonymization e Audio Intelligence pode incorrer em custos adicionais, calculados por token ou por caractere processado. Recomenda-se verificar o Dashboard da sua conta para um acompanhamento detalhado dos custos.

Listagem de Modelos

Para consultar os modelos STT atualmente disponíveis para sua organização, utilize o seguinte endpoint:

cURLPythonJavaScript

bash

curl -X GET 'https://api.sippulse.ai/v1/asr/models' \
  -H 'api-key: $SIPPULSE_API_KEY'

python

import os
import requests
import json

def list_available_stt_models() -> dict:
    """
    Lista os modelos de Speech-to-Text (STT) disponíveis na API SipPulse AI.
    """
    api_url = "https://api.sippulse.ai/v1/asr/models"
    headers = {"api-key": os.getenv("SIPPULSE_API_KEY")}

    response = requests.get(api_url, headers=headers)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    # É necessário ter a variável de ambiente SIPPULSE_API_KEY configurada
    try:
        models = list_available_stt_models()
        print("Modelos STT disponíveis:")
        print(json.dumps(models, indent=2))
    except requests.exceptions.HTTPError as e:
        print(f"Erro na API: {e.response.status_code} - {e.response.text}")
    except Exception as e:
        print(f"Ocorreu um erro inesperado: {e}")

javascript

// Node.js com node-fetch
// import fetch from "node-fetch"; // Se não estiver usando Node 18+ com fetch nativo

async function listAvailableSTTModels() {
  const apiUrl = "https://api.sippulse.ai/v1/asr/models";
  const apiKey = process.env.SIPPULSE_API_KEY;

  if (!apiKey) {
    throw new Error("A variável de ambiente SIPPULSE_API_KEY não está configurada.");
  }

  const response = await fetch(apiUrl, {
    headers: { "api-key": apiKey },
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`Erro na API: ${response.status} ${response.statusText} - ${errorBody}`);
  }
  return response.json();
}

// Exemplo de uso:
// (async () => {
//   try {
//     const models = await listAvailableSTTModels();
//     console.log("Modelos STT disponíveis:");
//     console.log(JSON.stringify(models, null, 2));
//   } catch (error) {
//     console.error("Falha ao listar modelos STT:", error);
//   }
// })();

SDK da OpenAI

É possível utilizar os modelos de transcrição do SipPulse AI, incluindo os proprietários pulse-precision e pulse-speed, bem como o whisper-1, através do SDK oficial da OpenAI. Para isso, é necessário configurar o parâmetro baseURL para o endpoint do SipPulse AI, que oferece compatibilidade com a API da OpenAI para transcrições.

JavaScriptPython

javascript

import OpenAI from "openai";
import fs from "fs"; // Para ler o arquivo em Node.js

const sippulseOpenAI = new OpenAI({
  apiKey: process.env.SIPPULSE_API_KEY, // Sua chave da API SipPulse
  baseURL: "https://api.sippulse.ai/v1/openai", // Endpoint de compatibilidade do SipPulse AI
});

async function transcribeWithSippulseOpenAI(audioFilePath, modelName = "pulse-precision") {
  // Em Node.js, você precisa fornecer um File-like object, como um ReadableStream.
  // No browser, você pode usar um objeto File diretamente de um <input type="file">.
  const audioFileStream = fs.createReadStream(audioFilePath);

  try {
    console.log(`Iniciando transcrição com o modelo: ${modelName}`);
    const response = await sippulseOpenAI.audio.transcriptions.create({
      file: audioFileStream, // Pode ser um Blob, ReadableStream, ou objeto File
      model: modelName,      // Ex: "pulse-precision", "pulse-speed", ou "whisper-1"
      response_format: "verbose_json", // Formato de resposta detalhado
      temperature: 0.0, // Para maior determinismo na transcrição
      // Outros parâmetros suportados pela API de transcrição da OpenAI podem ser adicionados aqui
    });
    console.log("Transcrição concluída:");
    console.log(JSON.stringify(response, null, 2));
    return response;
  } catch (error) {
    console.error("Erro durante a transcrição com SDK OpenAI:", error);
    throw error;
  }
}

// Exemplo de uso em Node.js:
// (async () => {
//   try {
//     // Substitua "caminho/para/seu/audio.wav" pelo caminho real do arquivo
//     await transcribeWithSippulseOpenAI("audio.wav", "pulse-precision");
//     // await transcribeWithSippulseOpenAI("audio.wav", "whisper-1");
//   } catch (e) {
//     // Erro já tratado dentro da função
//   }
// })();

python

from openai import OpenAI
import os

# Configuração do cliente OpenAI para usar o endpoint SipPulse AI
client = OpenAI(
  api_key=os.getenv("SIPPULSE_API_KEY"),    # Sua chave da API SipPulse
  base_url="https://api.sippulse.ai/v1/openai" # Endpoint de compatibilidade do SipPulse AI
)

def transcribe_with_sippulse_openai(file_path: str, model_name: str = "pulse-precision"):
    """
    Transcreve um arquivo de áudio usando um modelo do SipPulse AI
    através da interface compatível com OpenAI.
    """
    try:
        with open(file_path, "rb") as audio_file:
            print(f"Iniciando transcrição com o modelo: {model_name}")
            result = client.audio.transcriptions.create(
                file=audio_file,
                model=model_name,  # Ex: "pulse-precision", "pulse-speed", ou "whisper-1"
                response_format="verbose_json",
                temperature=0.0
                # Outros parâmetros suportados pela API de transcrição da OpenAI podem ser adicionados aqui
            )
        print("Transcrição concluída.")
        return result
    except Exception as e:
        print(f"Erro durante a transcrição com SDK OpenAI: {e}")
        raise

if __name__ == "__main__":
    # É necessário ter a variável de ambiente SIPPULSE_API_KEY configurada
    # Substitua "audio.wav" pelo caminho do seu arquivo de áudio
    try:
        # Exemplo com pulse-precision
        transcription_result = transcribe_with_sippulse_openai("audio.wav", model_name="pulse-precision")
        # Exemplo com whisper-1 (se disponível e desejado)
        # transcription_result = transcribe_with_sippulse_openai("audio.wav", model_name="whisper-1")
        
        if transcription_result:
            # Imprime o resultado da transcrição de forma legível
            import json
            print(json.dumps(transcription_result.dict(), indent=2, ensure_ascii=False))

    except FileNotFoundError:
        print(f"Erro: Arquivo de áudio 'audio.wav' não encontrado.")
    except Exception:
        # Erro já tratado e impresso pela função
        pass

Limitação Importante:
Ao utilizar o SDK da OpenAI (mesmo com o baseURL apontado para o SipPulse AI), recursos avançados e proprietários do SipPulse AI, como diarization, anonymize ou insights, não são suportados. Esses parâmetros são específicos da API REST nativa do SipPulse AI (/v1/asr/transcribe). Para usufruir da totalidade dos recursos, recomenda-se o uso direto da API REST nativa.

Transcrição em Lote (Batch)

Para cenários onde você não precisa de resultados em tempo real — como processar arquivos de áudio grandes ou executar transcrições em massa — você pode usar a API assíncrona de lote. Envie um job e consulte o resultado quando estiver pronto.

Modelos Suportados

A transcrição em lote está disponível para:

pulse-precision — Alta precisão com suporte a diarização
pulse-precision-pro — Máxima precisão com diarização estéreo

Como Funciona

Envie um job de transcrição via POST /v1/asr/transcribe/batch
Receba um x-request-id no header da resposta e um request_id no body (HTTP 202)
Consulte os resultados via GET /v1/asr/batch/{request_id}/status
Quando o status for completed, o resultado contém o texto transcrito

Rastreamento de Requisição (x-request-id)

Toda submissão batch retorna um x-request-id — um identificador único usado para:

Polling: Consultar o status do job via GET /v1/asr/batch/{request_id}/status
Rastreamento de custos: Consultar custos via GET /v1/usage-requests/{request_id} (veja Rastreamento de Requisições)

Você pode fornecer seu próprio ID enviando um header x-request-id com um UUID válido na requisição de submit. Isso é recomendado porque:

Você conhece o ID antes da resposta chegar
Se a resposta HTTP for perdida (ex: timeout de rede no 202), você ainda pode fazer poll usando seu ID pré-gerado
Simplifica a integração com seus próprios sistemas

Se você não enviar o header, o servidor gera um ID automaticamente.

Boa Prática

Sempre gere um UUID no lado do cliente e envie como x-request-id. Isso garante que você sempre pode recuperar o job, mesmo se a resposta do submit for perdida.

Valores de Status

Status	Descrição
`submitted`	Job recebido e enfileirado para processamento
`in_progress`	Transcrição sendo processada
`completed`	Transcrição finalizada — resultado disponível
`failed`	Ocorreu um erro durante o processamento

Limitações

Resultados expiram após 30 minutos. Consulte e salve o resultado antes que expire.
Jobs batch são cobrados com base na duração do áudio assim que a transcrição é concluída, independentemente de você consultar o resultado.
Anonimização e Audio Insights não estão disponíveis no modo lote.

Enviar um Job em Lote

Endpoint: POST /v1/asr/transcribe/batch

Requisição (multipart/form-data):

Parâmetro	Tipo	Obrigatório	Descrição
`file`	arquivo	Sim	Arquivo de áudio (MP3, WAV, PCM, OGG)
`model`	string	Não	Nome do modelo (padrão: inferido do preset)
`language`	string	Não	Idioma do áudio (ex: `pt`, `en`)
`response_format`	string	Não	Formato de saída: `text`, `json`, `verbose_json`, `srt`, `vtt`, `diarization`
`prompt`	string	Não	Instruções ou contexto para a transcrição

Headers:

Header	Obrigatório	Descrição
`x-request-id`	Não	UUID fornecido pelo cliente para rastreamento. Deve ser um UUID válido (ex: `550e8400-e29b-41d4-a716-446655440000`). Se omitido, o servidor gera um. Retorna 400 se o valor não for um UUID válido.

Resposta (HTTP 202):

Headers da resposta:

x-request-id: 550e8400-e29b-41d4-a716-446655440000

Body da resposta:

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "pulse-precision",
  "status": "submitted"
}

O request_id no body sempre corresponde ao header x-request-id.

Consultar Resultados

Endpoint: GET /v1/asr/batch/{request_id}/status

Você pode consultar este endpoint quantas vezes quiser. A cobrança é registrada apenas uma vez.

Resposta (em andamento):

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress"
}

Resposta (concluído):

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "text": "Olá, este é o conteúdo do áudio transcrito..."
  }
}

Exemplos de Código

cURLPythonJavaScript

bash

# 1. Gerar um UUID para rastreamento (recomendado)
REQUEST_ID="$(uuidgen)"

# 2. Enviar o job em lote com seu ID de rastreamento
curl -s -X POST "https://api.sippulse.ai/v1/asr/transcribe/batch" \
  -H "api-key: SUA_CHAVE_API" \
  -H "x-request-id: $REQUEST_ID" \
  -F "file=@audio.wav" \
  -F "model=pulse-precision" \
  -F "language=pt"

echo "Enviado: $REQUEST_ID"

# 3. Consultar até concluir (usando o mesmo ID)
while true; do
  RESPONSE=$(curl -s "https://api.sippulse.ai/v1/asr/batch/$REQUEST_ID/status" \
    -H "api-key: SUA_CHAVE_API")
  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESPONSE" | jq .
    break
  fi
  sleep 5
done

python

import requests
import time
import uuid

API_KEY = "SUA_CHAVE_API"
BASE_URL = "https://api.sippulse.ai/v1"
headers = {"api-key": API_KEY}

# 1. Gerar um UUID para rastreamento (recomendado)
request_id = str(uuid.uuid4())

# 2. Enviar o job em lote com seu ID de rastreamento
with open("audio.wav", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/asr/transcribe/batch",
        headers={**headers, "x-request-id": request_id},
        files={"file": f},
        data={"model": "pulse-precision", "language": "pt"},
    )

print(f"Enviado: {request_id}")

# 3. Consultar até concluir (usando o mesmo ID)
while True:
    status_resp = requests.get(
        f"{BASE_URL}/asr/batch/{request_id}/status",
        headers=headers,
    )
    data = status_resp.json()
    print(f"Status: {data['status']}")

    if data["status"] in ("completed", "failed"):
        print(data)
        break

    time.sleep(5)

javascript

import { randomUUID } from "crypto";
import fs from "fs";

const API_KEY = "SUA_CHAVE_API";
const BASE_URL = "https://api.sippulse.ai/v1";

async function transcreverEmLote() {
  // 1. Gerar um UUID para rastreamento (recomendado)
  const requestId = randomUUID();

  // 2. Enviar o job em lote com seu ID de rastreamento
  const form = new FormData();
  form.append("file", fs.createReadStream("audio.wav"));
  form.append("model", "pulse-precision");
  form.append("language", "pt");

  await fetch(`${BASE_URL}/asr/transcribe/batch`, {
    method: "POST",
    headers: { "api-key": API_KEY, "x-request-id": requestId },
    body: form,
  });
  console.log(`Enviado: ${requestId}`);

  // 3. Consultar até concluir (usando o mesmo ID)
  while (true) {
    const statusResp = await fetch(
      `${BASE_URL}/asr/batch/${requestId}/status`,
      { headers: { "api-key": API_KEY } }
    );
    const data = await statusResp.json();
    console.log(`Status: ${data.status}`);

    if (data.status === "completed" || data.status === "failed") {
      console.log(JSON.stringify(data, null, 2));
      break;
    }

    await new Promise((r) => setTimeout(r, 5000));
  }
}

transcreverEmLote();

Recuperacao Sincrona (x-request-id)

Para clientes que utilizam o endpoint sincrono /v1/asr/transcribe, arquivos de audio longos podem causar timeout no proxy ou no cliente. O header x-request-id oferece um mecanismo de recuperacao: se ocorrer um timeout, voce pode recuperar o resultado usando o endpoint de status do batch.

Como Funciona

Envie uma requisicao POST /v1/asr/transcribe com o header x-request-id (deve ser um UUID valido ou auto)
O servidor rastreia o job internamente e retorna o resultado normalmente
Se ocorrer um timeout antes da resposta chegar, consulte GET /v1/asr/batch/{request-id}/status para recuperar o resultado

Opcoes do Header

Header	Valor	Comportamento
`x-request-id`	UUID (ex: `550e8400-e29b-...`)	O servidor usa seu UUID como chave de recuperacao e rastreamento de custos
`x-request-id`	`auto`	O servidor gera um ID e o retorna no header de resposta `x-request-id`

Quando Usar

Use x-request-id ao transcrever arquivos de audio que podem levar mais tempo que o limite de timeout do seu cliente. Para processamento assincrono garantido, use o endpoint de Transcricao em Lote.

Modelos Suportados

A recuperacao sincrona funciona apenas com modelos que suportam batch (pulse-precision, pulse-precision-pro). Para outros modelos (ex: whisper-1), o header e silenciosamente ignorado e a requisicao segue normalmente.

Compatibilidade

O header legado x-job-id ainda e aceito para compatibilidade, mas esta deprecado. Use x-request-id para novas integracoes.

Exemplos de Codigo

cURLPythonJavaScript

bash

# Gerar UUID para rastreamento
REQUEST_ID="$(uuidgen)"

# Enviar requisicao sincrona com ID de recuperacao
curl -X POST "https://api.sippulse.ai/v1/asr/transcribe" \
  -H "api-key: SUA_CHAVE_API" \
  -H "x-request-id: $REQUEST_ID" \
  -F "file=@audio.wav" \
  -F "model=pulse-precision" \
  -F "language=pt"

# Se ocorrer timeout, recuperar resultado via status do batch
curl "https://api.sippulse.ai/v1/asr/batch/$REQUEST_ID/status" \
  -H "api-key: SUA_CHAVE_API"

python

import requests
import uuid

API_KEY = "SUA_CHAVE_API"
BASE_URL = "https://api.sippulse.ai/v1"
headers = {"api-key": API_KEY}

request_id = str(uuid.uuid4())

try:
    response = requests.post(
        f"{BASE_URL}/asr/transcribe",
        headers={**headers, "x-request-id": request_id},
        files={"file": open("audio.wav", "rb")},
        data={"model": "pulse-precision", "language": "pt"},
        timeout=30,  # Timeout do cliente
    )
    print(response.json())
except requests.exceptions.Timeout:
    # Recuperar via status do batch
    status = requests.get(
        f"{BASE_URL}/asr/batch/{request_id}/status",
        headers=headers,
    )
    print(f"Recuperacao: {status.json()}")

javascript

import { randomUUID } from "crypto";
import fs from "fs";

const API_KEY = "SUA_CHAVE_API";
const BASE_URL = "https://api.sippulse.ai/v1";
const requestId = randomUUID();

const controller = new AbortController();
setTimeout(() => controller.abort(), 30000); // Timeout de 30s

try {
  const form = new FormData();
  form.append("file", fs.createReadStream("audio.wav"));
  form.append("model", "pulse-precision");

  const response = await fetch(`${BASE_URL}/asr/transcribe`, {
    method: "POST",
    headers: { "api-key": API_KEY, "x-request-id": requestId },
    body: form,
    signal: controller.signal,
  });
  console.log(await response.json());
} catch (err) {
  if (err.name === "AbortError") {
    // Recuperar via status do batch
    const status = await fetch(
      `${BASE_URL}/asr/batch/${requestId}/status`,
      { headers: { "api-key": API_KEY } }
    );
    console.log("Recuperacao:", await status.json());
  }
}

Boas Praticas

Para obter os melhores resultados e otimizar o uso dos modelos STT:

Qualidade do Áudio: Forneça áudios com a maior clareza possível, minimizando ruídos de fundo e garantindo boa captação da voz.
Fragmentação de Áudios Longos: Para arquivos de áudio extensos (e.g., >60 minutos), considere dividi-los em segmentos menores antes de enviar para transcrição. Isso pode melhorar a performance e o gerenciamento do processo.
Uso Estratégico da Diarization: Em gravações de diálogos, reuniões ou qualquer cenário com múltiplos interlocutores, utilize o recurso de diarização (disponível nos modelos pulse-precision e pulse-speed). A correta identificação e separação dos falantes enriquece significativamente as análises e a usabilidade da transcrição.
Anonimização Consciente: Ative o recurso de anonimização sempre que a transcrição puder conter dados pessoais sensíveis. Esteja ciente dos custos adicionais associados a este processamento.
Audio Intelligence para Insights Imediatos: Combine a transcrição com as funcionalidades de Audio Intelligence (e.g., sumarização, identificação de tópicos, análise de sentimento) para extrair valor e insights de forma automatizada e imediata, diretamente na resposta da API.
Monitoramento de Custos: Acompanhe regularmente o consumo e os custos associados às transcrições e aos recursos avançados através do Dashboard da sua conta SipPulse AI.

Perguntas Frequentes (FAQ)

Qual é a principal diferença entre os modelos pulse-precision e pulse-speed?

pulse-precision: É otimizado para máxima acurácia na transcrição, sendo a escolha ideal quando a precisão do texto é o fator mais crítico. Este modelo tende a apresentar um Word Error Rate (WER) inferior, mas pode ter uma latência ligeiramente maior. pulse-speed: Prioriza a velocidade de processamento e menor latência, sendo adequado para aplicações que requerem respostas mais rápidas, mesmo que isso implique uma acurácia marginalmente inferior em comparação ao pulse-precision.

É possível utilizar o recurso de diarização com o modelo whisper-1 através do SipPulse AI?

Não. A funcionalidade de diarização é um recurso avançado e exclusivo dos modelos proprietários do SipPulse AI: pulse-precision e pulse-speed. Estes modelos foram especificamente desenvolvidos para oferecer uma análise detalhada de áudios com múltiplos interlocutores.

Como posso obter análises estruturadas, como sumarização ou tópicos, a partir da minha transcrição?

Para receber análises estruturadas, você deve utilizar o parâmetro insights ao fazer a requisição para o endpoint nativo da API REST do SipPulse AI (/v1/asr/transcribe). Especifique uma lista com as análises desejadas (e.g., ["summarization", "topics"]). Os resultados dessas análises serão incluídos no objeto audio_insights dentro da resposta JSON. A funcionalidade "Ver Código" no Playground do SipPulse AI pode gerar exemplos de como formatar corretamente este parâmetro na sua requisição.

Qual o tempo médio para processamento de uma transcrição?

O tempo de processamento pode variar, mas geralmente corresponde a alguns segundos por minuto de áudio. Fatores como o modelo selecionado (pulse-speed tende a ser mais rápido), a duração e complexidade do áudio, e a carga atual do sistema podem influenciar o tempo total.

Agentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Configurações

Transcrição de Áudio Avançada (Speech-to-Text)

Playground Interativo

Audio Insights

Tipos de Insights Disponíveis

Sumarização

Detecção de Tópicos

Análise de Sentimento

Análise Personalizada

Formatos de Resposta

Diarização Estéreo

VAD Preset para Telefonia

Consumo via API REST

Listagem de Modelos

SDK da OpenAI

Transcrição em Lote (Batch)

Modelos Suportados

Como Funciona

Rastreamento de Requisição (x-request-id)

Valores de Status

Enviar um Job em Lote

Consultar Resultados

Exemplos de Código

Recuperacao Sincrona (x-request-id)

Como Funciona

Opcoes do Header

Exemplos de Codigo

Boas Praticas

Perguntas Frequentes (FAQ)

Configuração

Ferramentas

Avançado

Implantando Agentes

Transcrição de Áudio Avançada (Speech-to-Text) ​

Playground Interativo ​

Audio Insights ​

Tipos de Insights Disponíveis ​

Sumarização ​

Detecção de Tópicos ​

Análise de Sentimento ​

Análise Personalizada ​

Formatos de Resposta ​

Diarização Estéreo ​

VAD Preset para Telefonia ​

Consumo via API REST ​

Listagem de Modelos ​

SDK da OpenAI ​

Transcrição em Lote (Batch) ​

Modelos Suportados ​

Como Funciona ​

Rastreamento de Requisição (x-request-id) ​

Valores de Status ​

Enviar um Job em Lote ​

Consultar Resultados ​

Exemplos de Código ​

Recuperacao Sincrona (x-request-id) ​

Como Funciona ​

Opcoes do Header ​

Exemplos de Codigo ​

Boas Praticas ​

Perguntas Frequentes (FAQ) ​

Transcrição de Áudio Avançada (Speech-to-Text)

Playground Interativo

Audio Insights

Tipos de Insights Disponíveis

Sumarização

Detecção de Tópicos

Análise de Sentimento

Análise Personalizada

Formatos de Resposta

Diarização Estéreo

VAD Preset para Telefonia

Consumo via API REST

Listagem de Modelos

SDK da OpenAI

Transcrição em Lote (Batch)

Modelos Suportados

Como Funciona

Rastreamento de Requisição (x-request-id)

Valores de Status

Enviar um Job em Lote

Consultar Resultados

Exemplos de Código

Recuperacao Sincrona (x-request-id)

Como Funciona

Opcoes do Header

Exemplos de Codigo

Boas Praticas

Perguntas Frequentes (FAQ)