Voltar
10 min de leitura
Integração

Integração via API

Documentação completa da API REST do VozParaTexto para desenvolvedores. Aprenda autenticação, endpoints principais, webhooks e como integrar transcrição automática em seus sistemas.

Recursos da API

Autenticação por Token

Sistema seguro de autenticação via API tokens

  • Tokens únicos por aplicação
  • Renovação automática disponível
  • Controle granular de permissões
  • Rate limiting personalizado

Upload Programático

Envio automatizado de arquivos para transcrição

  • Múltiplos formatos suportados
  • Upload direto ou via URL
  • Processamento assíncrono
  • Callback de status em tempo real

Webhooks Inteligentes

Notificações automáticas sobre progresso

  • Eventos configuráveis
  • Retry automático em falhas
  • Assinatura de segurança
  • Múltiplos endpoints por evento

Endpoints RESTful

API REST completa e bem documentada

  • Operações CRUD completas
  • Filtros e paginação avançados
  • Versionamento de API
  • Respostas estruturadas em JSON

Quick Start - Primeiros Passos

1

1. Obter Token de API

2 minutos

Gere seu token de acesso único

// Dashboard → Configurações → API → Gerar Token
// Salve o token com segurança - ele não será mostrado novamente
2

2. Instalar SDK (Opcional)

1 minuto

Use nosso SDK ou faça requisições HTTP diretas

npm install @vozparatexto/sdk
# ou
pip install vozparatexto-python
# ou use cURL/fetch diretamente
3

3. Primeiro Teste

30 segundos

Teste sua integração com endpoint básico

curl -X GET "https://api.vozparatexto.com.br/v1/user" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
4

4. Upload de Arquivo

1-2 minutos

Envie seu primeiro arquivo para transcrição

curl -X POST "https://api.vozparatexto.com.br/v1/transcriptions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/audio.mp3" \
  -F "quality=advanced"

Principais Endpoints

POST
/v1/transcriptions

Iniciar nova transcrição

Parâmetros:

  • file (required) Arquivo de áudio/vídeo
  • quality basic|advanced|premium
  • speakers boolean (identificar oradores)
  • timestamps boolean (incluir timestamps)
  • language pt-BR (padrão)
  • callback_url URL para webhook

Resposta:

Retorna ID da transcrição e status inicial

GET
/v1/transcriptions/{id}

Consultar status e resultado

Parâmetros:

  • id (required) ID da transcrição
  • format txt|srt|vtt|docx|json|csv
  • include_metadata boolean

Resposta:

Status, progresso e resultado quando completo

GET
/v1/transcriptions

Listar transcrições

Parâmetros:

  • page Número da página (padrão
  • limit Itens por página (max
  • status pending|processing|completed|failed
  • date_from YYYY-MM-DD
  • date_to YYYY-MM-DD

Resposta:

Lista paginada de transcrições

DELETE
/v1/transcriptions/{id}

Cancelar transcrição

Parâmetros:

  • id (required) ID da transcrição

Resposta:

Confirmação de cancelamento

GET
/v1/user/credits

Consultar saldo de créditos

Parâmetros:

    Resposta:

    Saldo atual e histórico de uso

    Exemplos de Código

    JavaScript/Node.js

    const axios = require('axios');
    const FormData = require('form-data');
    const fs = require('fs');
    
    const API_TOKEN = 'your_api_token_here';
    const BASE_URL = 'https://api.vozparatexto.com.br/v1';
    
    async function transcribeFile(filePath) {
      const form = new FormData();
      form.append('file', fs.createReadStream(filePath));
      form.append('quality', 'advanced');
      form.append('speakers', 'true');
      
      try {
        const response = await axios.post(
          `${BASE_URL}/transcriptions`,
          form,
          {
            headers: {
              ...form.getHeaders(),
              'Authorization': `Bearer ${API_TOKEN}`
            }
          }
        );
        
        console.log('Transcrição iniciada:', response.data);
        return response.data.id;
      } catch (error) {
        console.error('Erro:', error.response.data);
      }
    }
    
    // Uso
    transcribeFile('./meu_audio.mp3');

    Python

    import requests
    import time
    
    API_TOKEN = 'your_api_token_here'
    BASE_URL = 'https://api.vozparatexto.com.br/v1'
    
    def transcribe_file(file_path):
        headers = {'Authorization': f'Bearer {API_TOKEN}'}
        
        with open(file_path, 'rb') as f:
            files = {'file': f}
            data = {
                'quality': 'advanced',
                'speakers': True,
                'timestamps': True
            }
            
            response = requests.post(
                f'{BASE_URL}/transcriptions',
                headers=headers,
                files=files,
                data=data
            )
        
        if response.status_code == 201:
            transcription_id = response.json()['id']
            print(f'Transcrição iniciada: {transcription_id}')
            return transcription_id
        else:
            print(f'Erro: {response.json()}')
    
    def check_status(transcription_id):
        headers = {'Authorization': f'Bearer {API_TOKEN}'}
        response = requests.get(
            f'{BASE_URL}/transcriptions/{transcription_id}',
            headers=headers
        )
        
        return response.json()
    
    # Uso
    transcription_id = transcribe_file('meu_audio.mp3')
    while True:
        status = check_status(transcription_id)
        if status['status'] == 'completed':
            print('Transcrição completa!')
            print(status['result']['text'])
            break
        elif status['status'] == 'failed':
            print('Transcrição falhou:', status['error'])
            break
        else:
            print(f"Status: {status['status']} - {status['progress']}%")
            time.sleep(10)

    PHP

    <?php
    
    $API_TOKEN = 'your_api_token_here';
    $BASE_URL = 'https://api.vozparatexto.com.br/v1';
    
    function transcribeFile($filePath) {
        global $API_TOKEN, $BASE_URL;
        
        $ch = curl_init();
        
        curl_setopt_array($ch, [
            CURLOPT_URL => "$BASE_URL/transcriptions",
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => [
                'file' => new CURLFile($filePath),
                'quality' => 'advanced',
                'speakers' => 'true'
            ],
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer $API_TOKEN"
            ],
            CURLOPT_RETURNTRANSFER => true
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 201) {
            $data = json_decode($response, true);
            echo "Transcrição iniciada: " . $data['id'] . "\n";
            return $data['id'];
        } else {
            echo "Erro: $response\n";
            return null;
        }
    }
    
    function checkStatus($transcriptionId) {
        global $API_TOKEN, $BASE_URL;
        
        $ch = curl_init();
        
        curl_setopt_array($ch, [
            CURLOPT_URL => "$BASE_URL/transcriptions/$transcriptionId",
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer $API_TOKEN"
            ],
            CURLOPT_RETURNTRANSFER => true
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // Uso
    $transcriptionId = transcribeFile('meu_audio.mp3');
    if ($transcriptionId) {
        do {
            $status = checkStatus($transcriptionId);
            echo "Status: " . $status['status'] . "\n";
            if ($status['status'] === 'completed') {
                echo "Resultado: " . $status['result']['text'] . "\n";
                break;
            }
            sleep(10);
        } while ($status['status'] !== 'failed');
    }
    
    ?>

    Webhooks - Notificações em Tempo Real

    transcription.started

    Transcrição iniciada com sucesso

    Payload exemplo:

    {
      "id": "txn_1234567890",
      "status": "started",
      "created_at": "2024-01-15T10:30:00Z",
      "estimated_duration": 300
    }

    transcription.progress

    Progresso da transcrição atualizado

    Payload exemplo:

    {
      "id": "txn_1234567890",
      "status": "processing",
      "progress": 45,
      "estimated_completion": "2024-01-15T10:35:00Z"
    }

    transcription.completed

    Transcrição concluída com sucesso

    Payload exemplo:

    {
      "id": "txn_1234567890",
      "status": "completed",
      "result": {
        "text": "Texto transcrito...",
        "duration": 280,
        "confidence": 0.95
      },
      "completed_at": "2024-01-15T10:34:30Z"
    }

    transcription.failed

    Transcrição falhou

    Payload exemplo:

    {
      "id": "txn_1234567890",
      "status": "failed",
      "error": {
        "code": "invalid_audio",
        "message": "Arquivo de áudio corrompido"
      },
      "failed_at": "2024-01-15T10:32:15Z"
    }

    Limites de Taxa (Rate Limits)

    RecursoLimiteEscopoAo Exceder
    Autenticação10 requisições/minutoPor IPBloqueio temporário de 5 minutos
    Upload de Arquivos50 uploads/horaPor tokenHTTP 429 com retry-after header
    Consultas de Status1000 requisições/horaPor tokenThrottling progressivo
    Listagem de Transcrições100 requisições/horaPor tokenHTTP 429 com retry-after header

    Códigos de Erro Comuns

    400

    Bad Request

    Parâmetros inválidos ou malformados

    Ação: Verifique documentação e formato dos dados

    401

    Unauthorized

    Token ausente, inválido ou expirado

    Ação: Gere um novo token ou verifique header Authorization

    403

    Forbidden

    Token válido mas sem permissão para recurso

    Ação: Verifique permissões do token

    404

    Not Found

    Recurso não encontrado

    Ação: Verifique ID do recurso e endpoint

    429

    Too Many Requests

    Rate limit excedido

    Ação: Implemente backoff e respeite headers retry-after

    500

    Internal Server Error

    Erro interno do servidor

    Ação: Tente novamente ou contacte suporte

    Melhores Práticas

    Segurança

    • Nunca exponha tokens de API em código front-end
    • Use HTTPS para todas as requisições
    • Implemente retry com backoff exponencial
    • Valide assinaturas de webhook
    • Rotacione tokens periodicamente

    Performance

    • Use upload assíncrono para arquivos grandes
    • Implemente cache para consultas frequentes
    • Utilize paginação em listagens
    • Configure timeouts apropriados
    • Monitore rate limits

    Confiabilidade

    • Implemente tratamento de erro robusto
    • Use webhooks para notificações
    • Mantenha logs detalhados
    • Teste em ambiente de desenvolvimento
    • Monitore saúde da integração

    Documentação Completa da API

    Acesse nossa documentação interativa completa com todos os endpoints, exemplos e ferramentas para testar a API diretamente no navegador.

    Pronto para integrar?

    Comece agora mesmo integrando o VozParaTexto em seus sistemas. Nossa API é robusta, confiável e fácil de usar.

    Continue aprendendo