API Integration

Complete VoxScriber REST API documentation for developers. Learn about authentication, main endpoints, webhooks, and how to integrate automatic transcription into your systems.

API Features

Token Authentication

Secure authentication system via API tokens.

Unique tokens per application
Automatic renewal available
Granular permission control
Custom rate limiting

Programmatic Upload

Automated file submission for transcription.

Multiple supported formats
Direct upload or via URL
Asynchronous processing
Real-time status callbacks

Smart Webhooks

Automatic notifications about progress.

Configurable events
Automatic retry on failure
Security signature
Multiple endpoints per event

Authentication

Getting Your API Key

Access the Dashboard

API Settings

Go to Settings -> API -> Keys

Generate a new key

Click "New API Key" and set permissions

Copy and store

Copy the generated key and store it securely

Never share your API Key publicly. Store it in environment variables and never in version-controlled source code.

Using the API Key

Include your API Key in the Authorization header of all requests:

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"

Main Endpoints

File Upload

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

Parameters:

file (required) - Audio/video file
language (optional) - Language code (e.g., "en-US")
engine (optional) - Transcription engine ("ASSEMBLYAI", "WHISPER", "ELEVENLABS")
speaker_detection (optional) - Enable speaker identification (boolean)

Response:

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

Start Transcription

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

Body:

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

Check Status

GET /v1/transcription/{id}/status

Response:

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

Download Result

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

Available formats: json, txt, srt, vtt, docx, pdf

Rate Limiting

| Endpoint | Limit | Window | |---|---|---| | Upload | 10 requests | 60 seconds | | Transcription | 10 requests | 60 seconds | | Query | 60 requests | 60 seconds | | Export | 30 requests | 60 seconds |

Use webhooks instead of polling to track transcription status. This drastically reduces the number of requests and improves integration efficiency.

Integration Examples

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()

Error Handling

| Code | Meaning | Recommended Action | |---|---|---| | 400 | Bad request | Check parameters | | 401 | Not authenticated | Check your API Key | | 403 | Forbidden | Check token permissions | | 429 | Rate limit exceeded | Wait and try again | | 500 | Internal error | Try again after 30 seconds |

Security

Use HTTPS for all requests
Store API Keys in environment variables
Rotate keys regularly
Use minimum necessary permissions
Implement signature verification for webhooks

Continue learning

Webhooks & Notifications - Set up automatic callbacks
Batch Processing - Transcribe multiple files via API
Workflow Automation - Automate processes with the API

API Integration | VoxScriber - Complete Developer Documentation