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.
Sistema seguro de autenticação via API tokens
Envio automatizado de arquivos para transcrição
Notificações automáticas sobre progresso
API REST completa e bem documentada
Gere seu token de acesso único
// Dashboard → Configurações → API → Gerar Token
// Salve o token com segurança - ele não será mostrado novamente
Use nosso SDK ou faça requisições HTTP diretas
npm install @vozparatexto/sdk
# ou
pip install vozparatexto-python
# ou use cURL/fetch diretamente
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"
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"
/v1/transcriptions
Iniciar nova transcrição
file (required)
Arquivo de áudio/vídeoquality
basic|advanced|premiumspeakers
boolean (identificar oradores)timestamps
boolean (incluir timestamps)language
pt-BR (padrão)callback_url
URL para webhookRetorna ID da transcrição e status inicial
/v1/transcriptions/{id}
Consultar status e resultado
id (required)
ID da transcriçãoformat
txt|srt|vtt|docx|json|csvinclude_metadata
booleanStatus, progresso e resultado quando completo
/v1/transcriptions
Listar transcrições
page
Número da página (padrãolimit
Itens por página (maxstatus
pending|processing|completed|faileddate_from
YYYY-MM-DDdate_to
YYYY-MM-DDLista paginada de transcrições
/v1/transcriptions/{id}
Cancelar transcrição
id (required)
ID da transcriçãoConfirmação de cancelamento
/v1/user/credits
Consultar saldo de créditos
Saldo atual e histórico de uso
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');
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
$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');
}
?>
transcription.started
Transcrição iniciada com sucesso
{
"id": "txn_1234567890",
"status": "started",
"created_at": "2024-01-15T10:30:00Z",
"estimated_duration": 300
}
transcription.progress
Progresso da transcrição atualizado
{
"id": "txn_1234567890",
"status": "processing",
"progress": 45,
"estimated_completion": "2024-01-15T10:35:00Z"
}
transcription.completed
Transcrição concluída com sucesso
{
"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
{
"id": "txn_1234567890",
"status": "failed",
"error": {
"code": "invalid_audio",
"message": "Arquivo de áudio corrompido"
},
"failed_at": "2024-01-15T10:32:15Z"
}
Recurso | Limite | Escopo | Ao Exceder |
---|---|---|---|
Autenticação | 10 requisições/minuto | Por IP | Bloqueio temporário de 5 minutos |
Upload de Arquivos | 50 uploads/hora | Por token | HTTP 429 com retry-after header |
Consultas de Status | 1000 requisições/hora | Por token | Throttling progressivo |
Listagem de Transcrições | 100 requisições/hora | Por token | HTTP 429 com retry-after header |
Parâmetros inválidos ou malformados
Ação: Verifique documentação e formato dos dados
Token ausente, inválido ou expirado
Ação: Gere um novo token ou verifique header Authorization
Token válido mas sem permissão para recurso
Ação: Verifique permissões do token
Recurso não encontrado
Ação: Verifique ID do recurso e endpoint
Rate limit excedido
Ação: Implemente backoff e respeite headers retry-after
Erro interno do servidor
Ação: Tente novamente ou contacte suporte
Acesse nossa documentação interativa completa com todos os endpoints, exemplos e ferramentas para testar a API diretamente no navegador.