# ابدأ مع transcript1

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

Canonical: https://transcript1.com/ar/docs/getting-started
Language: ar
Last updated: 2026-10-14

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

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

افتح [صفحة إنشاء الحساب](https://transcript1.com/signup) وسجل ببريدك الإلكتروني أو بحساب Google أو Microsoft. بعد تأكيد البريد تحصل على 60 دقيقة مجانية، مرة واحدة لكل حساب. إذا سجلت عبر Google أو Microsoft، تحصل عليها مباشرة. لا تحتاج إلى بطاقة دفع.

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

```bash
export TRANSCRIPT1_API_KEY="t1_..."
```

## 2. أرسل رابط الفيديو

يمكنك إرسال رابط من YouTube أو X أو TikTok أو Instagram أو Facebook أو Bluesky أو Twitch أو Dailymotion أو Pinterest أو LinkedIn أو Snapchat. تجد أنواع التسجيلات العامة المقبولة وقيودها في [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options). لا يلزم تحديد `platform`؛ يتعرف API على المنصة من الرابط. نستخدم YouTube في الأمثلة التالية.

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

### cURL

```bash
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

```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`.

```javascript
// 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. راجع [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options) لاختيار الإعداد المناسب.

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

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

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

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

```json
{
  "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` لتنزيل ملف ترجمة نصية. مثلا:

```bash
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`:

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a
```

للملفات الأكبر، ارفع الملف على أجزاء حتى 2 GB. وإذا انقطع الاتصال، أكمل الأجزاء المتبقية. التفاصيل في [رفع الملفات](https://transcript1.com/ar/docs/uploads).

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

- [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options) لاختيار الترجمة النصية أو التفريغ الصوتي بالذكاء الاصطناعي، وإعداد تمييز المتحدثين واللغة.
- [رفع الملفات](https://transcript1.com/ar/docs/uploads) لإرسال الملف بطلب واحد أو على أجزاء.
- [إشعارات webhook](https://transcript1.com/ar/docs/webhooks) لاستقبال طلب يحمل توقيعا عند انتهاء التفريغ.
- [خادم MCP](https://transcript1.com/ar/docs/mcp) للعمل من Claude أو ChatGPT أو Cursor أو VS Code أو Claude Code.
- [مرجع API](https://transcript1.com/ar/docs/api-reference) للاطلاع على كل endpoint ومعاملاته.