تكامل API

وثائق VoxScriber REST API الشاملة للمطورين. تعرف على المصادقة، نقاط النهاية الرئيسية، webhooks، وكيفية دمج النسخ التلقائي في أنظمتك.

ميزات API

المصادقة

الحصول على مفتاح API الخاص بك

استخدام مفتاح API

قم بتضمين مفتاح API الخاص بك في رأس Authorization لجميع الطلبات:

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"

نقاط النهاية الرئيسية

رفع الملف

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

المعاملات:

• file (مطلوب) - ملف صوت/فيديو
• language (اختياري) - رمز اللغة (مثل 'en-US')
• engine (اختياري) - محرك النسخ ("ASSEMBLYAI", "WHISPER", "ELEVENLABS")
• speaker_detection (اختياري) - تمكين التعرف على المتحدث (قيمة منطقية)

الاستجابة:

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

بدء النسخ

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

المحتوى:

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

التحقق من الحالة

GET /v1/transcription/{id}/status

الاستجابة:

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

تنزيل النتيجة

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

الصيغ المتاحة: json, txt, srt, vtt, docx, pdf

تحديد المعدل

| نقطة النهاية | الحد | النافذة | |---|---|---| | الرفع | 10 طلبات | 60 ثانية | | النسخ | 10 طلبات | 60 ثانية | | الاستعلام | 60 طلبًا | 60 ثانية | | التصدير | 30 طلبًا | 60 ثانية |

أمثلة التكامل

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

معالجة الأخطاء

| الرمز | المعنى | الإجراء الموصى به | |---|---|---| | 400 | طلب غير صحيح | تحقق من المعاملات | | 401 | لم يتم المصادقة | تحقق من مفتاح API الخاص بك | | 403 | محظور | تحقق من أذونات الرمز | | 429 | تجاوز الحد المسموح | انتظر وحاول مرة أخرى | | 500 | خطأ داخلي | حاول مرة أخرى بعد 30 ثانية |

الأمان

• استخدم HTTPS لجميع الطلبات
• قم بتخزين مفاتيح API في متغيرات البيئة
• قم بتدوير المفاتيح بانتظام
• استخدم الحد الأدنى من الأذونات الضرورية
• قم بتنفيذ التحقق من التوقيع لـ webhooks

مواصلة التعلم

• Webhooks & Notifications - إعداد الاستدعاءات التلقائية
• Batch Processing - نسخ ملفات متعددة عبر API
• Workflow Automation - أتمتة العمليات باستخدام API