Whisper-1 API: أول تفريغ صوتي لك

يتطلب أول طلب إلى Whisper-1 API ملفًا صوتيًا ومعرّف نموذج صريحًا وصيغة مخرجات. على SeedRouter، ترفع التسجيل وتحفظ معرّف المهمة المعاد، ثم تنزّل النص عند اكتمالها. ابدأ بتسجيل قصير تعرف كلماته مسبقًا: فهذا يسهّل ملاحظة الكلمات المفقودة والتهجئة غير المعتادة.

يتبع هذا الدليل عقد SeedRouter غير المتزامن. وليس مثالًا متزامنًا لـ OpenAI SDK يمكن استخدامه دون تعديل. تضم صفحة نموذج Whisper-1 أداة Playground والسعر المباشر؛ ويسرد مرجع API جميع الحقول واختبارات التوافق التي لم تُحسم بعد. ^[1]

جهّز تسجيلًا واحدًا

استخدم كلامًا تملك إذنًا بمعالجته. يعد ملف WAV أو MP3 قصير نقطة بداية مناسبة. حد الرفع الحالي 26,214,400 بايت؛ ويجب أن يحتوي الملف على صوت قابل للقراءة بمدة قابلة للقياس. لا يجعل امتداد .mp3 ملفًا نصيًا أُعيدت تسميته صوتًا صالحًا. يفصل المرجع بين صيغ الإدخال التسع الموثّقة وتلك التي اجتازت الاختبارات الفعلية. ^[1]

التسجيل التالي كلام إنجليزي اصطناعي أصلي أُعدّ لهذا الدرس. يظهر شكله الموجي على الغلاف. الجملة المقتبسة على الغلاف مأخوذة من نص التسجيل وليست ادعاءً بالدقة.

نزّل العينة التي مدتها 10.31 ثانية. يقول نص التسجيل: “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

احتفظ بمفتاح API في متغير بيئة على الخادم. لا تضعه في صفحة ويب عامة أو حزمة تطبيق جوال أو لقطة شاشة مشتركة. يستخدم مثال Python أدناه requests ويقرأ SEEDROUTER_API_KEY من البيئة.

أرسل طلب Whisper-1 API مرة واحدة

اختر json للطلب الأول. يمكنك حينها قراءة حقل text في الملف المنزّل دون التعامل مع أكواد توقيت الترجمة النصية. يجب أن يتضمن جزء multipart المسمى file بايتات فعلية؛ فوضع رابط URL كقيمة له لا يعادل رفع الملف. دع العميل يضبط نوع محتوى multipart والفاصل. ^[1]

احفظ هذا باسم transcribe.py. يكتب علامة إرسال قبل POST ويحفظ معرّف المهمة المقبولة بعده. يقرأ تشغيله مجددًا المهمة القائمة. إذا لم تُعرف نتيجة POST، تمنع العلامة البرنامج من إنشاء نسخة مكررة بالخطأ.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

شغّل python transcribe.py. إذا طبع processing، انتظر عدة ثوانٍ ثم نفّذ الأمر نفسه مجددًا. سيقرأ المعرّف المحفوظ بدلًا من الرفع مجددًا. احفظ ملف حالة منفصلًا لكل تسجيل جديد ترسله عمدًا. لا يثبت انتهاء مهلة العميل وحده فشل المهمة.

اقرأ النص المفرّغ المكتمل

تتضمن استجابة القبول id وmodel وstatus وcreated_at. ويضيف الاكتمال output.url وoutput.format. يشير الرابط إلى ملف النتيجة؛ وليس مهمة توليد وسائط تتطلب طلبًا مدفوعًا آخر. ينزّل طلب GET الملف. ^[1]

اقرأ الكلمات أثناء الاستماع إلى التسجيل. راجع الأسماء والأرقام وحدود الجمل قبل استخدام النص كترجمة نصية أو اقتباس حرفي. النص المفرّغ مسودة للكلام المنطوق، ولا تلغي الطوابع الزمنية ضرورة مراجعته.

أكملت الاختبارات المحلية من البداية إلى النهاية في 19 أكتوبر 2026 صيغ التفريغ الخمس وترجمة بمدخل إنجليزي. تثبت تلك الاختبارات سلوك التسليم والفوترة للتسجيلات المختبرة. ولا تثبت نسبة دقة أو جودة الترجمة بين اللغات.

اختر النص أو الطوابع الزمنية أو الترجمة النصية

لطوابع الكلمات الزمنية، أرسل response_format=verbose_json وحقل multipart متكررًا باسم timestamp_granularities[] وقيمته word. أضف جزءًا آخر بقيمة segment إن احتجت كليهما. في requests ضمن Python، استخدم قائمة أزواج (name, value) للحقول المتكررة. يُقاس كل طابع زمني بالثواني. ^[2]

طوابع الكلمات الزمنية وتسميات المتحدثين مخرجات مختلفة. لا يحوّل Whisper-1 الاجتماع إلى نص ذي تسميات متحدثين لمجرد طلب المقاطع. ولا يبث نصًا جزئيًا أيضًا: يُتجاهل stream لهذا النموذج. اترك chunking_strategy محذوفًا لاستخدام المسار المتحقق منه؛ لم يجتز اختيار auto صراحةً اختبار التوافق الفعلي. ^[1]

أضف سياق اللغة والتهجئة عند الحاجة

يخبر الحقل الاختياري language=en طلب التفريغ بأن المدخلات بالإنجليزية. احذفه عندما تريد الاكتشاف التلقائي. إذا كان اسم منتج عرضة لسوء السماع، ضع تهجئته الصحيحة في prompt بلغة الصوت نفسها. توفر موجّهات Whisper السياق؛ ولا تعمل كتعليمات محادثة تضمن تنسيقًا معينًا. ^[3]

اجعل السياق مرتبطًا بالمقطع. ينظر Whisper فقط في آخر 224 توكنًا بحسب محلّل توكناته. لا يمنح إرسال مستند طويل التسجيلَ مسردًا غير محدود، وليس عدّ الأحرف بديلًا موثوقًا لقاعدة التوكنات هذه.

للترجمة إلى الإنجليزية، غيّر المسار إلى /audio/translations. حقول طلبه الخمسة هي file وmodel وprompt وresponse_format وtemperature. تنتج الترجمة الإنجليزية؛ ولا يوجد محدد للغة الهدف. استخدم موجّهًا إنجليزيًا إن أضفته. ^[4]

راجع التكلفة قبل توسيع مسار العمل

يستخدم الجدول المباشر أدناه مدة الصوت المقاسة. لا يزيد طول النص رسوم المدة للتسجيل نفسه. تُقرّب مدة كل ملف إلى ثوانٍ كاملة إلى الأعلى، ثم تُحوّل إلى وحدات قياس صوت. يتضمن مرجع API الحساب الدقيق، وتعرض Playground تقديرًا بعد أن تتمكن من قراءة مدة التسجيل. لا تُحتسب رسوم على الطلبات الفاشلة.

قبل معالجة ملفات كثيرة، اختبر تسجيلًا تمثيليًا وافحص النتيجة. احتفظ بمعرّف مهمة كل تسجيل لتتمكن من التعافي من انقطاع الاتصال بقراءة حالته القائمة. راجع المرجع الكامل للمعاملات قبل إضافة الترجمة النصية أو تركيبات الصيغ الأقل اختبارًا.

أسئلة التكامل الأول

هل يمكن استخدام مثال OpenAI Python SDK دون تعديل؟

لا. حقول multipart للمدخلات مألوفة، لكن SeedRouter يعيد معرّف مهمة غير متزامنة. يحتاج العميل المتزامن الذي يتوقع احتواء استجابة POST على text إلى تكييف. يوضّح هذا المثال إرسال الطلب وقراءة النتيجة صراحةً.

لماذا لا توجد طوابع زمنية للكلمات في نتيجة JSON؟

الصيغة الافتراضية json استجابة تركز على النص. اطلب verbose_json ودقة الطوابع الزمنية word معًا. توقيت المقاطع وحده لا ينشئ إدخالًا لكل كلمة.

هل أرسل POST آخر بعد انتهاء المهلة؟

راجع أولًا معرّف المهمة المحفوظ أو سجل المهام. ربما فُقدت الاستجابة بعد القبول. تجنّب قراءة المهمة القائمة إنشاء طلب آخر للتسجيل نفسه.

هل سيُوقَف Whisper-1؟

أعلنت OpenAI أن موعد إيقاف Whisper على واجهتها الخاصة هو 26 فبراير 2027. لا يحدد هذا الإشعار موعد إيقاف لهذه الخدمة. أدرج إشعارات دورة الحياة في قائمة الصيانة عند بناء تكامل جديد. ^[5]

المصادر

[1] مرجع SeedRouter Whisper-1 API وحالة التحقق، جرى التحقق في 19 أكتوبر 2026.

[2] مرجع OpenAI للتفريغ الصوتي.

[3] دليل OpenAI لموجّهات Whisper.

[4] مرجع OpenAI للترجمة.

[5] إشعار OpenAI بإيقاف نماذج التفريغ الصوتي.