أرسل الرابط واحفظ معرف التفريغ
أنشئ مفتاح API من لوحة التحكم، ثم أرسل رابط الفيديو عبر POST من خادمك أو سكربت Python. يتيح wait=60 الانتظار حتى 60 ثانية. راجع حقول الطلب وحالات الاستجابة قبل الربط.
احفظ المعرف بمجرد نجاح الطلب. إذا انتهى الانتظار ولم يجهز النص، تابع عبر GET /v1/transcriptions/:id. التفريغ مستمر؛ لا ترسل طلب إنشاء آخر لمجرد أن اتصال HTTP انتهى.
قد تظهر الحالات queued ثم fetching ثم transcribing. عند completed اقرأ النص، وعند failed تعامل مع الخطأ. لا تعرض نصا فارغا على أنه تفريغ ناجح إذا تأخر الاتصال أو تعذر جلب الفيديو.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'احتفظ بحقل transcript_source مع النص
توضح الاستجابة مصدر النص ونوع الترجمة النصية إن استخدمت. ويعرض billed_minutes مدة الفيديو بعد التقريب إلى الدقيقة الأعلى. تجد الحقول كاملة في مرجع كائن التفريغ.
احفظ transcript_source وcaption_kind إذا كان توثيق المصدر مهما لتطبيقك. تحتفظ الترجمة النصية التي رفعها صانع المحتوى بصياغتها المنشورة، دون توقيت لكل كلمة. أما المنشأة تلقائيا فتقدم بداية كل كلمة، والتفريغ من الصوت يقدم البداية والنهاية ودرجة الثقة.
لكل مقطع وقت بداية ونهاية بالثواني. استخدمهما لربط النص بالتشغيل أو بالملاحظات. اطلب include=words فقط إذا احتجت بيانات الكلمات الإضافية. مثال JSON أدناه يشرح بنية الاستجابة، ولا ينقل كلام الفيديو المستخدم في الطلب.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}هل تحتاج المسار المنشور أم تفريغا من الصوت؟
الإعداد الافتراضي هو source=auto. اختر captions (الترجمة النصية فقط) إذا كنت تحتاج المسار المنشور وحده؛ إن غاب سيظهر no_captions دون خصم رصيد. واختر stt لتفريغ الصوت دائما. راجع خيارات المصدر قبل الجمع بينها.
تمييز المتحدثين يحتاج إلى الصوت. لذلك ينتقل auto مع diarize=true إلى التفريغ بالذكاء الاصطناعي حتى مع وجود ترجمة نصية. أما جمع diarize=true مع captions فيرفض الطلب؛ لن نتجاهل أحد الخيارين بصمت.
تؤثر language أيضا في اختيار المسار. يجب أن يطابق اللغة المطلوبة، أو لغة الفيديو الأصلية عند الاختيار التلقائي. لا نستخدم ترجمة آلية إلى لغة أخرى، وتحديد لغة للتفريغ الصوتي لا يحول API إلى أداة ترجمة.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}افهم الخطأ قبل إعادة الإرسال
الفيديو الخاص أو المقيد بالعمر أو البث الجاري يحتاج إلى مصدر آخر، لا إلى تكرار المحاولة. ومع no_captions قرر إن كان التفريغ من الصوت مناسبا لك. أما التفريغ الذي لا يزال جاريا فتابعه بمعرفه. يوضح مرجع الأخطاء الحالات التي ينبغي أن يعالجها تطبيقك.
إذا اضطررت إلى إعادة طلب الإنشاء، اتبع قواعد Idempotency-Key. إعادة استخدام تفريغ حديث خيار منفصل يطابق الفيديو والإعدادات. وجود نص مخزن مؤقتا لا يعني أن إنشاء مهمة جديدة مجاني؛ قراءة تفريغ مكتمل بمعرفه لا تستهلك دقائق.
يمكن للطلب نفسه قبول روابط منصات أخرى مثل TikTok وInstagram. تدعم YouTube وX وTikTok وBluesky مسارات ترجمة نصية مع التفريغ من الصوت عند الحاجة. تحقق من قدرات كل مصدر بدلا من إتاحة تركيبات لا تدعمها المنصة.