---
title: مرجع API المباشرة عبر HTTP
icon: BookOpen
description: مرجع على مستوى المخطط لتكاملات Batch وHTTP المتدفق.
---

استخدم هذا المرجع عندما تحتاج إلى مسارات HTTP الدقيقة، أو المعاملات، أو أجسام الطلب، أو أشكال الاستجابة، أو أمثلة الطلبات المولّدة. لاتباع تكامل موجّه باستخدام SDK بالإصدار `0.18.0`، ابدأ من [البدء السريع](/ar/quickstart) أو [أدلة API](/ar/api-guides).

## اختر حسب دورة حياة الإدخال

| سير العمل | حالة الإدخال | الاستخدام الأنسب |
| --- | --- | --- |
| النسخ الدفعي Batch | تسجيل طويل ومكتمل | الاجتماعات والبودكاست والمقابلات والأرشيفات التي تُعالج كأعمال غير متزامنة |
| النسخ السريع Fast | وحدة صوت مكتملة ومحدودة | أدوار الوكلاء الحساسة للزمن والأوامر الصوتية والعبارات الحوارية القصيرة |
| ASR الفوري | الصوت ما زال يصل | الميكروفونات والمكالمات والتدفقات التي تحتاج إلى نتائج جزئية ونهائية |
| تحويل النص إلى كلام | الإدخال نص والإخراج صوت | إنشاء تدفق صوت `PCM16` من النص |

## اضبط الوصول

احصل على مفتاح API عبر مسار الوصول المعتمد في مؤسستك. احتفظ بالمفتاح في خادم موثوق، واستخدم المضيف ومسار الخدمة المهيأين لبيئتك. راجع [المصادقة](/ar/authentication) قبل إتاحة التكامل للمستخدمين.

```bash
export API_URL="https://api.voice.humain.com"
export API_KEY="YOUR_API_KEY"
```

| API | المسار الأساسي |
| --- | --- |
| Batch API | `/v1` |
| Realtime HTTP API | `/realtime` |

## أرسل طلبًا آمنًا

يوفر استعلام للقراءة فقط عن معرّف عمل غير موجود عمدًا دليلاً تشخيصيًا غير معدّل للحالة من دون إنشاء عمل:

```bash
curl --include "$API_URL/v1/transcribe/00000000-0000-4000-8000-000000000000" \
  --header "x-api-key: $API_KEY" \
  --header "Origin: $API_URL"
```

- يتوافق `404` مع البحث عن العمل غير الموجود، لكنه لا يثبت وحده صلاحية بيانات الاعتماد وقدرة Batch.
- يشير `401` إلى أن المفتاح مفقود أو غير صالح لمسار الطلب.
- يشير `403` إلى رفض الوصول؛ تحقق من القيم المهيأة عبر مسار الوصول المعتمد في مؤسستك.

## أقسام المرجع

### [Batch API](/ar/api-reference/batch)

أرسل تسجيلات طويلة ومكتملة، ثم استعلم عن المهمة حتى يصل إلى حالة نهائية.

### [Realtime HTTP API](/ar/api-reference/realtime-http)

استخدم HTTP المتدفق للنسخ السريع أو ASR الحي أو تمييز المتحدثين أو TTS.

## الحدود التشغيلية

- قد يعيد إرسال عمل Batch الحالة `429` عند نفاد سعة معالجة الصوت. تعامل معها كضغط سعة واستخدم بيانات السعة المعادة عند توفرها.
- لا تعد محاولة رفع ملف ذي نتيجة ملتبسة بلا تحقق. سجّل نتيجة الطلب في طبقة الأعمال حتى لا ينشئ انقضاء المهلة أعمالًا مكررة من دون ملاحظة.
- استخدم استعلامًا محدودًا لأعمال Batch وتوقف عند `done` أو `failed` أو `cleared`.
- تختلف قواعد التأطير ودورة الحياة بين HTTP وSocket.IO. اتبع صفحة وسيلة النقل التي تستخدمها فعلًا.

## الوصول عبر Markdown وLLM

- استخدم [`/ar/api-reference/md`](/ar/api-reference/md) لقراءة هذه الصفحة بصيغة Markdown الخام.
- ألحق مسار عملية، مثل [`/ar/api-reference/md/batch/submit-transcription-job`](/ar/api-reference/md/batch/submit-transcription-job)، لقراءة عملية واحدة.
- استخدم [`/llms-full.txt`](/llms-full.txt) لحزمة الوثائق الثنائية اللغة كاملة.

## الخطوات التالية

### [المصادقة](/ar/authentication)

احصل على مفتاح API واضبطه واحمه.

### [أدلة API](/ar/api-guides)

اختر بروتوكولًا واتبع دورة حياته.

### [الأخطاء وحدود المعدل](/ar/api-guides/errors-and-rate-limits)

صنّف الإخفاقات ونفّذ إعادة المحاولة بأمان.