Integração via API

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

Funcionalidades da API

Autenticação

Obter a sua API Key

Utilizar a API Key

Inclua a sua API Key no header Authorization de todos os pedidos:

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

Envio de Ficheiro

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

Parâmetros:

• file (required) - Ficheiro de áudio/vídeo
• language (optional) - Código do idioma (ex: "pt-PT")
• 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-PT"
}

Consultar Estado

GET /v1/transcription/{id}/status

Resposta:

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

Descarregar Resultado

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

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

Rate Limiting

| Endpoint | Limite | Janela | |---|---|---| | Upload | 10 pedidos | 60 segundos | | Transcrição | 10 pedidos | 60 segundos | | Consulta | 60 pedidos | 60 segundos | | Exportação | 30 pedidos | 60 segundos |

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 | Pedido inválido | Verifique os parâmetros | | 401 | Não autenticado | Verifique a sua API Key | | 403 | Sem permissão | Verifique as permissões do token | | 429 | Rate limit excedido | Aguarde e tente novamente | | 500 | Erro interno | Tente novamente após 30 segundos |

Segurança

• Utilize HTTPS em todos os pedidos
• Armazene API Keys em variáveis de ambiente
• Faça rotação de chaves regularmente
• Utilize permissões mínimas necessárias
• Implemente verificação de assinatura em webhooks

Continue a aprender

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