Integración de API

Documentación completa de la API REST de VoxScriber para desarrolladores. Aprende sobre autenticación, endpoints principales, webhooks y cómo integrar la transcripción automática en tus sistemas.

Características de la API

Autenticación

Obtención de tu clave de API

Uso de la clave de API

Incluye tu clave de API en el encabezado Authorization de todas las solicitudes:

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

Endpoints principales

Carga de archivos

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

Parámetros:

• file (obligatorio) - Archivo de audio/video
• language (opcional) - Código de idioma (p. ej., "en-US")
• engine (opcional) - Motor de transcripción ("ASSEMBLYAI", "WHISPER", "ELEVENLABS")
• speaker_detection (opcional) - Habilitar identificación de hablantes (booleano)

Respuesta:

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

Iniciar transcripción

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

Cuerpo:

{
  "uploadId": "upload_abc123",
  "engine": "ASSEMBLYAI",
  "speakerDetection": true,
  "language": "en-US"
}

Consultar estado

GET /v1/transcription/{id}/status

Respuesta:

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

Descargar resultado

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

Formatos disponibles: json, txt, srt, vtt, docx, pdf

Límites de velocidad

| Endpoint | Límite | Ventana | |---|---|---| | Carga | 10 solicitudes | 60 segundos | | Transcripción | 10 solicitudes | 60 segundos | | Consulta | 60 solicitudes | 60 segundos | | Exportación | 30 solicitudes | 60 segundos |

Ejemplos de integración

Node.js

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

const API_KEY = process.env.VOXSCRIBER_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. Transcribe
  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['VOXSCRIBER_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. Transcribe
    transcription = requests.post(
        f'{BASE_URL}/transcribe',
        headers=headers,
        json={
            'uploadId': upload.json()['id'],
            'engine': 'ASSEMBLYAI',
            'speakerDetection': True
        }
    )

    return transcription.json()

Manejo de errores

| Código | Significado | Acción recomendada | |---|---|---| | 400 | Solicitud incorrecta | Verifica los parámetros | | 401 | No autenticado | Verifica tu clave de API | | 403 | Prohibido | Verifica los permisos del token | | 429 | Límite de velocidad excedido | Espera y vuelve a intentarlo | | 500 | Error interno | Intenta de nuevo después de 30 segundos |

Seguridad

• Usa HTTPS para todas las solicitudes
• Almacena las claves de API en variables de entorno
• Rota las claves regularmente
• Usa los permisos mínimos necesarios
• Implementa verificación de firma para webhooks

Continúa aprendiendo

• Webhooks y notificaciones - Configura llamadas de retorno automáticas
• Procesamiento por lotes - Transcribe múltiples archivos mediante la API
• Automatización de flujos de trabajo - Automatiza procesos con la API