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

Autenticação

Obtendo sua API Key

Acesse o Dashboard

Faça login no VozParaTexto

Configurações de API

Vá em Configurações → API → Chaves

Gere uma nova chave

Clique em "Nova API Key" e defina permissões

Copie e armazene

Copie a chave gerada e armazene com segurança

Nunca compartilhe sua API Key publicamente. Armazene em variáveis de ambiente e nunca em código-fonte versionado.

Usando a API Key

Inclua sua API Key no header Authorization de todas as requisições:

curl -X POST https://api.vozparatexto.com.br/v1/transcribe \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3"

Endpoints Principais

Upload de Arquivo

POST /v1/upload
Content-Type: multipart/form-data

Parâmetros:

file (required) - Arquivo de áudio/vídeo
language (optional) - Código do idioma (ex: "pt-BR")
engine (optional) - Motor de transcrição ("ASSEMBLYAI", "WHISPER", "ELEVENLABS")
speaker_detection (optional) - Ativar identificação de oradores (boolean)

Resposta:

{
  "id": "upload_abc123",
  "status": "UPLOADED",
  "duration": 120.5,
  "fileSize": 2048000
}

Iniciar Transcrição

POST /v1/transcribe
Content-Type: application/json

Body:

{
  "uploadId": "upload_abc123",
  "engine": "ASSEMBLYAI",
  "speakerDetection": true,
  "language": "pt-BR"
}

Consultar Status

GET /v1/transcription/{id}/status

Resposta:

{
  "id": "trans_xyz789",
  "status": "COMPLETED",
  "progress": 100,
  "text": "Texto transcrito...",
  "duration": 120.5,
  "creditsUsed": 8
}

Baixar Resultado

GET /v1/transcription/{id}/export?format=json

Formatos disponíveis: json, txt, srt, vtt, docx, pdf

Rate Limiting

| Endpoint | Limite | Janela | |---|---|---| | Upload | 10 requisições | 60 segundos | | Transcrição | 10 requisições | 60 segundos | | Consulta | 60 requisições | 60 segundos | | Export | 30 requisições | 60 segundos |

Use webhooks ao invés de polling para acompanhar o status das transcrições. Isso reduz drasticamente o número de requisições e melhora a eficiência da integração.

Exemplos de Integração

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const API_KEY = process.env.VOZPARATEXTO_API_KEY;
const BASE_URL = 'https://api.vozparatexto.com.br/v1';

async function transcribeFile(filePath) {
  // 1. Upload
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));

  const upload = await axios.post(`${BASE_URL}/upload`, form, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...form.getHeaders()
    }
  });

  // 2. Transcrever
  const transcription = await axios.post(`${BASE_URL}/transcribe`, {
    uploadId: upload.data.id,
    engine: 'ASSEMBLYAI',
    speakerDetection: true
  }, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  return transcription.data;
}

Python

import requests
import os

API_KEY = os.environ['VOZPARATEXTO_API_KEY']
BASE_URL = 'https://api.vozparatexto.com.br/v1'

def transcribe_file(file_path):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    # 1. Upload
    with open(file_path, 'rb') as f:
        upload = requests.post(
            f'{BASE_URL}/upload',
            headers=headers,
            files={'file': f}
        )

    # 2. Transcrever
    transcription = requests.post(
        f'{BASE_URL}/transcribe',
        headers=headers,
        json={
            'uploadId': upload.json()['id'],
            'engine': 'ASSEMBLYAI',
            'speakerDetection': True
        }
    )

    return transcription.json()

Tratamento de Erros

| Código | Significado | Ação Recomendada | |---|---|---| | 400 | Requisição inválida | Verifique parâmetros | | 401 | Não autenticado | Verifique sua API Key | | 403 | Sem permissão | Verifique permissões do token | | 429 | Rate limit excedido | Aguarde e tente novamente | | 500 | Erro interno | Tente novamente após 30 segundos |

Segurança

Use HTTPS em todas as requisições
Armazene API Keys em variáveis de ambiente
Rotacione chaves regularmente
Use permissões mínimas necessárias
Implemente verificação de assinatura em webhooks

Continue aprendendo

Webhooks e Notificações - Configure callbacks automáticos
Processamento em Lote - Transcreva múltiplos arquivos via API
Automação de Fluxos - Automatize processos com a API

Integração via API | VozParaTexto - Documentação Completa para Desenvolvedores