ابدأ مجانا

التوثيقابدأ مع transcript1

ابدأ مع transcript1

أنشئ مفتاح API وجرب تفريغ فيديو من رابط أو ملف باستخدام cURL أو Python أو Node.js.

للبدء، تحتاج إلى مفتاح API ورابط فيديو أو ملف من جهازك. عنوان API هو https://api.transcript1.com، وأرسل مفتاحك في ترويسة Authorization. توضح الخطوات التالية كيف ترسل التسجيل وتقرأ النص المفرغ.

1. أنشئ حسابا ومفتاح API

افتح صفحة إنشاء الحساب وسجل ببريدك الإلكتروني أو بحساب Google أو Microsoft. بعد تأكيد البريد تحصل على 60 دقيقة مجانية، مرة واحدة لكل حساب. إذا سجلت عبر Google أو Microsoft، تحصل عليها مباشرة. لا تحتاج إلى بطاقة دفع.

من صفحة «API keys» في لوحة التحكم، أنشئ مفتاحا وانسخه قبل مغادرة الصفحة؛ لن يظهر مرة أخرى. مسار الصفحة هو /dashboard/account/tokens، وبادئة المفاتيح t1_. ضع مفتاحك في متغير البيئة TRANSCRIPT1_API_KEY:

export TRANSCRIPT1_API_KEY="t1_..."

يمكنك إرسال رابط من YouTube أو X أو TikTok أو Instagram أو Facebook أو Bluesky أو Twitch أو Dailymotion أو Pinterest أو LinkedIn أو Snapchat. تجد أنواع التسجيلات العامة المقبولة وقيودها في المصادر والخيارات. لا يلزم تحديد platform؛ يتعرف API على المنصة من الرابط. نستخدم YouTube في الأمثلة التالية.

أرسل الرابط إلى POST /v1/transcriptions. أضف wait=60 إلى query للانتظار حتى 60 ثانية قبل وصول الرد. هذا الرد لا يحتوي على النص المفرغ. لذلك يقرأ مثال Python النص بطلب منفصل إلى GET /v1/transcriptions/:id?wait=60. أما Node.js SDK، فيقرأ المفتاح من TRANSCRIPT1_API_KEY ويتولى الانتظار وجلب النص.

cURL

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Python

import os
import requests
 
headers = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
response = requests.post(
    "https://api.transcript1.com/v1/transcriptions?wait=60",
    headers=headers,
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
)
response.raise_for_status()
transcription = response.json()
while True:
    transcription = requests.get(
        f"https://api.transcript1.com/v1/transcriptions/{transcription['id']}?wait=60",
        headers=headers,
    ).json()
    if transcription["status"] in ("completed", "failed", "canceled"):
        break
 
if transcription["status"] == "completed":
    print(transcription["transcript"]["text"])
else:
    print(transcription["status"], transcription["error"])

Node.js

احفظ المثال في index.mjs وشغله بالأمر node index.mjs. إذا استخدمت امتداد .js بدلا منه، أضف "type": "module" إلى package.json.

// npm i @transcript1/sdk
import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1();
const transcription = await t1.transcribe('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(transcription.transcript.text);

بالإعداد الافتراضي، يبحث transcript1 أولا عن ترجمة نصية قابلة للاستخدام بلغة الفيديو الأصلية على YouTube وX وTikTok وBluesky وDailymotion وLinkedIn. إن لم يجدها، يفرغ الصوت بالذكاء الاصطناعي. دعم الترجمة النصية في YouTube وX مستمر كما كان؛ وقد لا تتوفر ترجمة مناسبة لكل فيديو. خارج YouTube، تحصل على توقيت المقاطع فقط، لا توقيت كل كلمة. اختر source=stt أو فعل تمييز المتحدثين لاستخدام الصوت مباشرة. أما وضع captions (الترجمة النصية فقط)، فلا ينزل الصوت ولا يستخدم STT. راجع المصادر والخيارات لاختيار الإعداد المناسب.

3. تحقق من الحالة واقرأ النص

رمز HTTP يوضح هل انتهت المعالجة خلال الانتظار أم لا:

  • 200 تعني أن الحالة أصبحت نهائية؛ اقرأ status لمعرفة إن كانت completed أو failed أو canceled.
  • 202 تعني أن التفريغ ما زال جاريا. استدع GET /v1/transcriptions/:id?wait=60، وانتظر حتى 60 ثانية أخرى. كرر الاستعلام حتى تصل status إلى حالة نهائية.

هذا مثال مختصر لبيانات تفريغ مكتمل:

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "completed",
  "transcript_source": "youtube_captions",
  "language": "en",
  "billed_minutes": 4,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "speakers": [],
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." },
      { "start": 4.2, "end": 9.8, "speaker": null, "language": "en", "text": "Today we are looking at how transcripts are made." }
    ]
  }
}

اقرأ النص الكامل من transcript.text. وللوصول إلى المقاطع وطوابعها الزمنية، استخدم transcript.segments؛ يحدد start وend بداية كل مقطع ونهايته بالثواني.

اختر text لتنزيل نص عادي، أو srt أو vtt لتنزيل ملف ترجمة نصية. مثلا:

curl "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

يستخدم المثال GET /v1/transcriptions/:id?format=srt. لن تحصل على الملف بالتنسيق المطلوب إلا عند completed. قبل ذلك، يعيد API كائن JSON لتتابع الحالة.

4. جرب ملفا من جهازك

إذا كان لديك ملف صوت أو فيديو لا يتجاوز 95 MB، ارفعه بطلب واحد بصيغة multipart/form-data:

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected]

للملفات الأكبر، ارفع الملف على أجزاء حتى 2 GB. وإذا انقطع الاتصال، أكمل الأجزاء المتبقية. التفاصيل في رفع الملفات.

أكمل إعداد التكامل

  • المصادر والخيارات لاختيار الترجمة النصية أو التفريغ الصوتي بالذكاء الاصطناعي، وإعداد تمييز المتحدثين واللغة.
  • رفع الملفات لإرسال الملف بطلب واحد أو على أجزاء.
  • إشعارات webhook لاستقبال طلب يحمل توقيعا عند انتهاء التفريغ.
  • خادم MCP للعمل من Claude أو ChatGPT أو Cursor أو VS Code أو Claude Code.
  • مرجع API للاطلاع على كل endpoint ومعاملاته.

تاريخ التحديث 14 أكتوبر 2026