أرسل محتوى الملف في طلب multipart
ضع الملف في الحقل file. ويمكنك إضافة language وdiarize وsource وwebhook_url كحقول في النموذج. يشرح دليل الرفع بطلب واحد البنية كاملة، ويمكنك استخدام webhook لمعرفة متى ينتهي التفريغ.
هذه أبسط طريقة إذا كان التسجيل الصغير موجودا على خادمك. أرسل بايتات الملف نفسها، لا مساره المحلي داخل JSON. ودع مكتبة HTTP تضبط multipart boundary. الملف الفارغ أو الامتداد غير المدعوم يحتاج إلى تصحيح، لا إلى تكرار الطلب.
اختر طريقة الرفع بحسب حجم الملف، ثم افحص مدته على حدة. قد يقل حجم تسجيل مضغوط عن 95 MB وتتجاوز مدته 5 ساعات. وقد يكون الفيديو قصيرا لكن حجمه أكبر من حد الطلب الواحد.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F language=autoاحجز الرفع واحتفظ بخطة الأجزاء
أرسل اسم الملف وحجمه لحجز عملية الرفع. ستحصل على خطة بالأجزاء وX-Upload-Token خاص بهذه العملية. اتبع خطوات الرفع على أجزاء بالترتيب.
اعتمد الحدود التي ترجعها الخطة؛ لكل جزء فهرس وموضع بداية وحجم بالبايت. اقرأ هذا النطاق بالضبط، فقد يكون الجزء الأخير أصغر. استخدم X-Upload-Token لطلبات PUT الثنائية؛ صلاحيته ساعة واحدة ولهذا الرفع فقط، وليس بديلا عاما عن مفتاح API.
احتفظ بمفتاح Idempotency-Key ثابت للحجز الذي قد تعيده. إذا انتهت صلاحية الرمز، أعد الحجز بالمفتاح والإعدادات نفسها لتحصل على رمز جديد للعملية الموجودة. لا تفتح حجزا جديدا بعد كل انقطاع فتفقد تتبع ما أرسلته.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Idempotency-Key: interview-2026-10-13" \
-H "Content-Type: application/json" \
-d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"}}'أرسل الناقص ثم أكد اكتمال الملف
أرسل كل جزء عبر PUT إلى رابطه مع رمز الرفع، ثم اطلب إكمال العملية. نتحقق من وصول جميع الأجزاء قبل إدراج التفريغ في قائمة الانتظار. تجد مسارات التقدم والإكمال في مرجع الرفع.
عند متابعة رفع انقطع، اقرأ GET /v1/transcriptions/:id/upload وقارن received_chunks بالخطة الأصلية. أرسل الأجزاء الناقصة فقط. إعادة إرسال جزء تستبدل محتواه، ويجب أن يبقى حجمه مطابقا للخطة. قد يعني 401 أن الرمز انتهت صلاحيته، لا أن ملف الصوت تالف.
إذا ظهر 409 upload_incomplete، أصلح الأجزاء التي تحددها فهارس الخطأ. بعد نجاح الإكمال تابع حالة التفريغ أو انتظر webhook. اجعل تقدم الرفع وحالة التفريغ مرحلتين منفصلتين في واجهتك.
curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
-H "X-Upload-Token: t1u_..." \
-H "Content-Type: application/octet-stream" \
--data-binary @chunk-0.bin
curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY"اكتمال النقل لا يعني اكتمال التفريغ
تعني awaiting_upload أن الحجز ينتظر الملف، لا أن التفريغ يعمل في الخلفية. اعرض المراحل كما تحدث؛ نقل البيانات، ثم التحقق من الرفع، ثم معالجة التسجيل. إذا انقطع الاتصال بعد طلب الإكمال، اقرأ حالة المهمة قبل أن تفترض حاجتك إلى إكمالها مرة أخرى.
يمكن للفريق الاحتفاظ بما يصل إلى 20 حجز رفع مفتوحا. نلغي الحجز غير المكتمل بعد 24 ساعة ونحذف أجزاءه. وبعد وصول المعالجة إلى حالة نهائية نحذف ملف التسجيل بعد 24 ساعة أخرى. النص يبقى حتى تحذفه؛ احتفظ بالأصل لديك إذا كان تطبيقك يتيح تشغيل الصوت لاحقا.
وصول الملف ليس نهاية العمل على النص. يوضح دليل التسجيلات الصوتية كيف تجهز التسجيل وتراجع الكلام، ويشرح دليل المقابلات ربط المتحدثين بالمشاركين والحفاظ على مصدر الاقتباسات.