REST API
transcript API للفيديو والصوت
يوفّر transcript.im خط الاستخراج نفسه الذي يقوم عليه المنتج على شكل transcript API بإصدارات مرقّمة. أرسل رابط فيديو أو صوت واحصل على نص مزوّد بطوابع زمنية بصيغة JSON أو نص عادي، مع اكتشاف المنصة تلقائيًا. تُستخدم الترجمات الموجودة أولًا؛ وإذا لم تتوفر ترجمة للفيديو، يفرّغ الذكاء الاصطناعي الصوت المنطوق وتُسلَّم النتيجة بشكل غير متزامن.
- يقبل حقل
urlواحد رابطًا كاملًا أو مختصرًا ويكتشف YouTube وTikTok وInstagram وLinkedIn وTwitter/X تلقائيًا؛ وفي YouTube يُتعرَّف أيضًا على معرّف الفيديو وحده، بينما يغطيplatformمعexternalIdمصدرًا تعرفه مسبقًا. - تُستخدم الترجمة أولًا؛ ويفرّغ الذكاء الاصطناعي الصوت المنطوق عندما لا تتوفر ترجمة للفيديو، بينما يمرّ رفع الملف المحلي دائمًا عبر التعرّف على الكلام.
- يعيد
format=jsonمقاطع مزوّدة بطوابع زمنية، بينما يعيدformat=textنصًا عاديًا جاهزًا للصق. - يشمل الاستخراج بالدفعات قوائم الروابط وقوائم التشغيل والقنوات.
- تشمل صادرات الدفعات الصيغ txt وcsv وjson وsrt وvtt وzip؛ ويُنزَّل النص المحفوظ بصيغة txt أو srt أو vtt أو json أو md.
- تُحفظ النصوص في مكتبة الحساب، ويغطي استكشاف YouTube البحث والفيديوهات والقنوات والمقاطع المرفوعة وقوائم التشغيل والترجمات.
- نُشرت مواصفات العقد كاملةً في وثيقة OpenAPI.
ما الذي تفعله واجهة transcript.im API
تحوّل واجهة transcript.im API رابط فيديو أو صوت عام إلى نص مزوّد بطوابع زمنية يمكن لمنتجك قراءته أو تخزينه أو البحث فيه أو تغذيته إلى نموذج. أنت ترسل رابطًا؛ فتحلّل الواجهة المنصة، وتبحث عن مسار الترجمة الموجود لدى المنشئ، وتعيد النص المكتوب مع طابع زمني في كل سطر. وعندما لا تتوفر أي ترجمة للفيديو، لا تتوقف الواجهة عند خطأ — بل تنتقل إلى التفريغ بالذكاء الاصطناعي للصوت المنطوق كي يُنتج الطلب نفسه نصًا.
- طلب واحد ونص حقيقي — حلّل الرابط وأعِد مقاطع نصية مزوّدة بطوابع زمنية أو نصًا عاديًا.
- الترجمة أولًا ثم الذكاء الاصطناعي — استخدم مسار المنشئ عند توفره، وفرّغ الصوت عند غيابه.
- غير متزامن افتراضيًا في ASR — يتيح لك معرّف المهمة متابعة تفريغ طويل دون حجب.
- يدرك اللغات — اطلب أولوية لغوية واقرأ اللغة التي حلّلتها الواجهة.
- مستقل عن المنصة — لا تحتاج الجهة المستدعية إلى معرفة مكان استضافة الفيديو.
transcript API واحد لخمس منصات
YouTube
نصوص لأي فيديو عام على YouTube أو مقطع Shorts أو تسجيل مباشر، مع استخدام ترجمة المنشئ أولًا والتفريغ بالذكاء الاصطناعي عند غيابها. وYouTube أيضًا المنصة التي توفر واجهة استكشاف كاملة — البحث والفيديوهات والقنوات والمقاطع المرفوعة وقوائم التشغيل والترجمات — إلى جانب النص نفسه. ويتحوّل أرشيف قناة أو قائمة تشغيل إلى دفعة من النصوص المزوّدة بطوابع زمنية، بينما يعود الرابط الواحد نصًا مقروءًا يمكنك البحث فيه.
TikTok
نصوص لفيديوهات TikTok العامة، مع استخدام الترجمة أولًا والتعرّف على الكلام كخيار احتياطي. الصق رابط فيديو واقرأ المحتوى المنطوق نصًا نظيفًا مزوّدًا بطوابع زمنية يمكنك إعادة استخدامه أو ترجمته أو الاقتباس منه. ويغطي الطلب نفسه المقطع القصير والمقطع الأطول، فيعود المقطع الرائج والشرح ومنشور الحديث المباشر نصًا.
نصوص لمقاطع Instagram Reels ومنشورات الفيديو العامة. لا يوفّر Instagram مسار ترجمة لقراءته، لذا يعتمد الاستخراج على التعرّف على الكلام بشكل غير متزامن: أرسل الرابط، تابع المهمة دوريًا، واجمع النص عند جاهزيته. وبذلك يصبح الريل قابلًا للاقتباس والبحث حتى إن لم تنشر المنصة كلماته نصًا مكتوبًا.
نصوص لمنشورات الفيديو العامة على LinkedIn، مع استخدام الترجمة أولًا والتعرّف على الكلام كخيار احتياطي. تعود النتيجة مزوّدة بطوابع زمنية، فيتحوّل حديث أو مقطع تعريفي بالمنتج أو اجتماع مسجّل إلى نص قابل للبحث يمكنك الاستشهاد به وإعادة استخدامه. استخرج الحجّة من تسجيل ندوة، أو حوّل تحديث المؤسّس إلى مسودة قابلة للتحرير.
Twitter/X
نصوص لمنشورات الفيديو العامة على Twitter. لا يوفّر Twitter مسار ترجمة لقراءته، لذا يمرّ الاستخراج عبر التعرّف على الكلام بشكل غير متزامن: أرسل الرابط، تابع المهمة دوريًا، واجمع نصًا مزوّدًا بطوابع زمنية يمكنك البحث فيه. اقتبس الفيديو بدقة، أو أرشِف محتواه المنطوق قبل تعديل المنشور أو حذفه.
كيف يسير طلب النص
يأخذ استدعاء واحد رابطًا أو ملفًا مرفوعًا من المدخل إلى النص، وتخبرك الواجهة بالمسار الذي سلكته.
- أرسل المصدر — انشر حقل
url، أو مرّرplatformوexternalIdإن كنت تعرفهما، أو ارفع ملفًا بصيغةmultipart/form-dataإلى نقطة النهاية نفسها. - احصل على تطابق ترجمة — عندما يحمل الفيديو ترجمة بلغة ضمن قائمتك، يعود النص في الاستجابة.
- تعامل مع عدم تطابق اللغة — عندما توجد ترجمات لكن لا تطابق أيّ منها قائمتك، يواصل الطلب إلى التفريغ بالذكاء الاصطناعي ويعيد
202مع معرّف مهمة؛ ولا يُعاد404معavailableLanguagesإلا عندما لا يُسمح للتعرّف على الكلام للجهة المستدعية. - افرض ASR أو ارجع إليه — مدخل
asrصريح، أو فيديو بلا مسار ترجمة إطلاقًا، أو ملف مرفوع يبدأ مهمة ASR ويعيد معرّف مهمة. - تابِع دوريًا أو بثًّا مباشرًا — اقرأ المهمة عبر
GET /v1/transcript/job/{id}حتى تنجح أو تفشل، أو اشترك في بثّ/eventsالخاص بها للتقدّم المُرسَل من الخادم. ويعيد استعلام المهمة200حتى للمهمة الفاشلة، فاعتمد على حقلstatus. - اقرأ النتيجة — يحمل النص المكتمل لغته المحلّلة وطوله ومقاطعه المزوّدة بطوابع زمنية، وعند الطلب بيانات وصفية مثل العنوان والمؤلف وتاريخ النشر.
- أعِد الطلب بأمان — يُخدَّم النص المستخرج مسبقًا من ذاكرة التخزين المؤقت بدل بدء مهمة جديدة، فيمكن طلب المصدر نفسه مرة أخرى.
- افحص أولًا — يحلّل
GET /v1/transcript/infoمصدرًا ويسرد اللغات التي يمكن تقديمها قبل أن تلتزم بعملية استخراج.
202 مع معرّف مهمة، بينما يعيد الأصل المفقود فعلًا أو الاحتياطي غير المسموح 404. ويعيد كل مسار شكل النص نفسه بعد جاهزية النص.الاستخراج بالدفعات والتصدير
نادرًا ما تتوقف أحمال العمل الحقيقية عند فيديو واحد، لذا تقبل الواجهة دفعة على شكل قائمة روابط أو قائمة تشغيل أو قناة. وتتابع كل دفعة إجمالياتها الخاصة — عدد العناصر المعلّقة وعدد الناجحة وعدد الفاشلة — وتعيد العناصر صفحة تلو الأخرى، حتى لا تصل قناة طويلة في حمولة واحدة ضخمة.
- ثلاثة أشكال للدفعة — يقبل
POST /v1/batchقائمة روابط أو قائمة تشغيل أو قناة، بحسب الجسم الذي ترسله. - حالة مستقلة — يُوسم الرابط الفاشل وحده ولا يُسقط بقية الدفعة أبدًا؛ ويمكن إعادة محاولة العناصر الفاشلة عبر
/retry. - عناصر مقسّمة إلى صفحات — اقرأ الدفعة عبر
GET /v1/batch/{batchId}، ثم اتبع رمز الصفحة المعاد للعناصر المتبقية. - تقدّم مباشر — يعيد كل استعلام دوري أعدادًا محدّثة، فيمكن للجهة المستدعية إظهار مقدار ما اكتمل من عملية طويلة.
- صدّر بصيغتك — نزّل دفعة مكتملة من
/exportبصيغةtxtأوcsvأوjsonأوsrtأوvttأوzip.
srt وvtt مباشرةً إلى محرّر أو مشغّل. وبالنسبة إلى الأرشيف، تُبقي csv وjson وzip مكتبة كاملة من التسجيلات قابلة للبحث كمجموعة واحدة. وتتوافق الصيغ مع استجابات النص الواحد، فالجهة المستهلكة التي تتعامل مع نتيجة واحدة تعرف أصلًا كيف تقرأ دفعة.النصوص المحفوظة في مكتبة الحساب
الاستخراج والتخزين منفصلان: يصبح النص جزءًا من مكتبة الحساب بمجرد حفظه، والمكتبة هي المكان الذي تقرأ فيه النص وتبحث عنه وتنزّله وتحذفه لاحقًا دون إعادة تشغيل الاستخراج.
- اسرد المحتوى المحفوظ — يتصفّح
GET /v1/library/transcriptsنصوص الحساب وسجلات الدفعات وصفوف السجل الفاشل، مع البحث وتصفية المنصة واللغة والفرز. - اقرأ عنصرًا واحدًا — يعيد
GET /v1/library/transcripts/{platform}/{externalId}نصًا محفوظًا حسب المنصة والمعرّف الخارجي، أو للغة التي تحدّدها. - التنزيل — يصدّر مسار
/downloadنصًا محفوظًا بصيغةtxtأوsrtأوvttأوjsonأوmd. - محتوى ذو صلة — يسرد مسار
/relatedعناصر محفوظة أخرى من القناة نفسها. - الإزالة — يحذف
DELETEعنصرًا من المكتبة دون المساس بنسخة أي شخص آخر. - قراءات ضمن نطاق الحساب — لا يعيد طلب المكتبة إلا ما حفظه الحساب، ولا يبدأ استخراجًا جديدًا أبدًا، فإعادة زيارة نص محفوظ قراءةٌ لا مهمة أخرى.
استكشاف YouTube بما يتجاوز النصوص
YouTube هي المنصة التي تجيب فيها الواجهة أيضًا عن الأسئلة المحيطة بالنص، مستخدمةً أسماء الموارد نفسها التي تستخدمها YouTube Data API.
- البحث — يجد
GET /v1/youtube/searchفيديوهات أو قنوات أو قوائم تشغيل حسب الاستعلام ويعيد نتائج مقسّمة إلى صفحات بمؤشر. - الفيديوهات — يعيد
GET /v1/youtube/videosتفاصيل فيديو، بما في ذلك مدى توفّر الترجمات. - القنوات — يحلّل
GET /v1/youtube/channelsقناةً بالمعرّف أو بـ@handle. - مرفوعات القناة — يستعرض
GET /v1/youtube/channels/{channelId}/videosمرفوعات قناة. - عناصر قائمة التشغيل — يستعرض
GET /v1/youtube/playlists/{playlistId}/itemsقائمة تشغيل. - الترجمات — يعيد
GET /v1/youtube/captionsالبيانات الوصفية لمسار الترجمة ونص الترجمة لفيديو. ولا يبدأ مهمة تعرّف على الكلام أبدًا: فحين يُبلّغ عنrequiresAsync، استدعِPOST /v1/transcriptلتشغيل التفريغ.
مبنيّة للاستخدام الإنتاجي
نطاق الواجهة صغير عن قصد، والجوانب المهمة لأي خدمة موثّقة بدل أن تكون محلّ تخمين.
- بيانات اعتماد واحدة — صادِق بمفتاح API يُرسَل على شكل Bearer token، أو بـ
X-API-Keyمن سكربت أو خادم. - مفاتيح محدودة النطاقات — امنح فقط النطاقات التي تحتاجها الجهة المستدعية، مع تغطية
transcriptsوbatchesلعمليتَي الاستخراج والدفعات. - أخطاء منظّمة — تعيد إخفاقات الاستخراج والتحقق كائن خطأ يحمل
codeثابتًا وmessageمقروءًا؛ أما استجابات المصادقة (401) وحدّ المعدل (429) فتستخدم جسم خطأ مسطّحًا أبسط. - حدود قابلة للتعامل — يعيد الطلب المتجاوز لحدّ المعدل
429معRetry-After، وتحمل الاستجابات الناجحة ترويساتX-RateLimit-*كي يتمكّن العميل من التمهّل بشكل صحيح. - عقد منشور — تدعم وثيقة OpenAPI الكاملة هذه الواجهة، فيمكنك توليد عميل أو محاكاة خادم أو التحقق من الاستجابات الحقيقية مقابل المخطط.
- رفيق للوكلاء — يمكن الوصول إلى الحساب والأدوات نفسها من خادم transcript.im MCP إذا كانت الجهة المستدعية عميل ذكاء اصطناعي لا خدمة.
أدوات ذات صلة
الأسئلة الشائعة حول transcript API
ما هي واجهة transcript.im API؟
توفّر transcript API من transcript.im سطح REST يحوّل رابط فيديو أو صوت عام إلى نص مزوّد بطوابع زمنية، مستخدمًا الترجمات الموجودة أولًا والتفريغ بالذكاء الاصطناعي عند غيابها.
ما المنصات التي تدعمها واجهة transcript.im API؟
تستخرج النصوص من YouTube وTikTok وInstagram وLinkedIn وTwitter/X باكتشاف المنصة من الرابط الذي ترسله. يستخدم YouTube وTikTok وLinkedIn الترجمة أولًا مع التعرّف على الكلام كخيار احتياطي؛ أما Instagram وTwitter فلا يوفّران مسار ترجمة ويمرّان مباشرةً إلى التعرّف على الكلام.
ماذا يحدث عندما لا تتوفر ترجمة للفيديو؟
عندما لا يوجد أي مسار ترجمة للفيديو، تبدأ الواجهة مهمة ASR وتعيد معرّف مهمة؛ فتابع تلك المهمة دوريًا حتى جاهزية النص، كي لا يتعطّل الطلب أبدًا على التعرّف على الكلام.
هل يمكنني تفريغ ملف صوت أو فيديو محلي؟
نعم. يقبل POST /v1/transcript جسمًا من نوع multipart/form-data مع جزء file بدل الرابط. ويمرّ الملف المرفوع مباشرةً إلى التعرّف على الكلام، فيعيد مهمة 202 — أو نتيجة 200 إذا اكتمل ضمن ميزانية الانتظار.
هل يمكن لواجهة transcript.im API إعادة طوابع زمنية مع النص؟
نعم. تحمل استجابات JSON مقاطع مزوّدة بطوابع زمنية، ويمكن لاستجابات النص الاحتفاظ ببادئة طابع زمني في كل سطر، فتستطيع العودة إلى اللحظة التي قيل فيها السطر.
كيف أطلب نصًا بلغة محدّدة؟
أرسل قائمة أولوية لغوية مفصولة بفواصل، تشمل مدخلات asr وasr-<code>. ويُعاد تطابق الترجمة مباشرة؛ وعندما توجد ترجمات لكن لا يطابق أيّ منها القائمة، يواصل الطلب إلى التفريغ بالذكاء الاصطناعي ويعيد مهمة 202، ولا يُعاد 404 مع اللغات المتاحة إلا عندما لا يُسمح بالتعرّف على الكلام.
كيف أعرف متى يصبح النص غير المتزامن جاهزًا؟
تابع GET /v1/transcript/job/{id} دوريًا ببيانات الاعتماد نفسها حتى يُبلّغ عن النجاح أو الفشل، أو اشترك في GET /v1/transcript/job/{id}/events لتصلك التحديثات من الخادم. ويعيد استعلام المهمة 200 حتى عند فشل المهمة، فاقرأ الحقلين status وerror بدل رمز HTTP.
هل تدعم واجهة transcript.im API الاستخراج بالدفعات؟
نعم. تقبل الدفعة قائمة روابط أو قائمة تشغيل أو قناة، وتتابع حالة كل عنصر، وتعيد العناصر صفحة تلو الأخرى.
ما صيغ التصدير التي يمكنني تنزيلها؟
تُصدَّر الدفعة المكتملة بصيغة txt أو csv أو json أو srt أو vtt أو zip؛ ويُنزَّل النص المحفوظ الواحد بصيغة txt أو srt أو vtt أو json أو md.
أين تُحفظ النصوص المحفوظة؟
مكتبة الحساب هي المكان الذي تُحفظ فيه النصوص وسجلات الدفعات، ضمن /v1/library. وتتيح مسارات السرد والقراءة والتنزيل والمحتوى ذي الصلة والحذف، وتكون قراءاتها ضمن نطاق الحساب ولا تبدأ استخراجًا جديدًا أبدًا.
ماذا تعيد نقطة نهاية ترجمات YouTube؟
يعيد GET /v1/youtube/captions البيانات الوصفية لمسار ترجمة فيديو إلى جانب نص الترجمة. ولا يبدأ مهمة تعرّف على الكلام أبدًا؛ فحين يُبلّغ عن requiresAsync، استدعِ POST /v1/transcript لتشغيل التفريغ.
كيف تُبلّغ واجهة transcript.im API عن الأخطاء وحدود المعدل؟
تستخدم أخطاء الاستخراج والتحقق كائنًا يحمل code وmessage؛ وتعيد المصادقة 401 مسطّحًا، ويعيد حدّ المعدل 429 مسطّحًا مع Retry-After وترويسات X-RateLimit-* كي يتمكّن العميل من التمهّل بشكل صحيح.
أضف النصوص إلى منتجك
أنشئ مفتاح API، وأرسل رابط فيديو أو ملفًا محليًا، واقرأ النص مرة أخرى بصيغة JSON أو نص عادي.