# حزمة Node.js SDK

> أضف التفريغ إلى كود الخادم عبر @transcript1/sdk. أرسل روابط أو ملفات، ونزل النصوص وملفات الترجمة النصية، وتابع التقدم وعالج الأخطاء.

Canonical: https://transcript1.com/ar/docs/sdk
Language: ar
Last updated: 2026-10-16

تتيح لك `@transcript1/sdk` تشغيل التفريغ من كود TypeScript أو JavaScript على الخادم. تتولى الحزمة رفع الملفات وانتظار النص المفرغ.

روابط التواصل الاجتماعي تحتاج إلى SDK 1.1.0 أو أحدث. الإصدار 1.0.1 يقبل YouTube فقط، ويرفض الروابط الجديدة قبل إرسالها إلى API. حدث الحزمة بالأمر `npm i @transcript1/sdk@latest`.

هذا الحد الأدنى يخص المنصات الست الأصلية. لروابط Twitch وDailymotion وPinterest وLinkedIn وSnapchat، استخدم إصدارا يتضمن دعمها؛ قد يرفضها إصدار أقدم محليا.

## ثبت الحزمة

```bash
npm i @transcript1/sdk
```

الأمثلة مكتوبة بصيغة ES modules. احفظها بامتداد `.mjs`، أو أضف `"type": "module"` إلى `package.json` إذا استخدمت `.js`. يمكنك استخدام `require()` على Node 20.19+ أيضا، مثل `require('@transcript1/sdk')`.

## أضف مفتاح API

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

```javascript
import { Transcript1 } from '@transcript1/sdk';

const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });
```

إذا لم تحدد مفتاحا، يرمي constructor خطأ `Transcript1Error` برمز `missing_api_key`.

## أرسل تسجيلا وانتظر النص

استخدم `transcribe(input, options)` لإنشاء التفريغ وانتظار النص في استدعاء واحد. عند نجاحه، تحصل على `CompletedTranscription` بالحالة `status: 'completed'` وحقل `transcript`. إذا فشل التفريغ أو ألغيته، يُرفض كائن Promise (reject).

```javascript
const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);

const file = await t1.transcribe('./interview.m4a', { speakers: true });
```

إذا أرسلت Buffer أو Uint8Array، أضف اسم الملف حتى يتعرف SDK على نوعه:

```javascript
import { readFile } from 'node:fs/promises';

const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });
```

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

حد حجم الملف 2,000,000,000 بايت. الامتدادات المقبولة هي mp3 وwav وm4a وflac وogg وopus وmp4 وmov وwebm وmkv.

يجب أن يكون منشور الفيديو عاما. إذا احتوى على عدة فيديوهات، نفرغ الأول فقط. يتعرف API على المنصة من الرابط. صيغ الروابط القصيرة المقبولة وحدودها موضحة في [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options).

تقبل الحزمة أيضا Blob و`ReadableStream<Uint8Array>` وasync iterable ينتج أجزاء Uint8Array. أضف `filename` مع Blob، إلا إذا كان File يحمل اسما. ومع streams أو async iterables، حدد `filename` و`size` بالبايت معا.

## نزل النص أو ملف الترجمة النصية

استخدم `download(id, options)` لانتظار اكتمال التفريغ وتنزيله كسلسلة نصية. حتى عند اختيار JSON، تحصل على نص JSON من API، لا على كائن بعد تحليله.

```javascript
const text = await t1.download(done.id); // text is the default
const withTimes = await t1.download(done.id, { timestamps: true });
const srt = await t1.download(done.id, { format: 'srt' });
const vtt = await t1.download(done.id, { format: 'vtt' });
const json = await t1.download(done.id, { format: 'json' });
```

استخدم `timestamps: true` مع `text` فقط. إذا جمعته مع تنسيق آخر، يُرفض كائن Promise (reject) برمز `invalid_input`. وفي `download`، يُرفض كائن Promise (reject) أيضا إذا فشل التفريغ أو ألغيته.

## ابدأ التفريغ وتابعه لاحقا

إذا لم ترد انتظار النص، استخدم `transcriptions.create`. عند إرسال ملف، تنتظر هذه الدالة انتهاء رفعه فقط قبل أن تعيد الرد.

```javascript
const job = await t1.transcriptions.create('./long-interview.mp4');
const now = await t1.transcriptions.get(job.id);
const finished = await t1.transcriptions.get(job.id, { wait: true });
```

تقرأ `get` الحالة الحالية دون انتظار، إلا إذا أضفت `wait: true`. عندها تنتظر وصول الحالة إلى `completed` أو `failed` أو `canceled` وتعيد الكائن. افحص `finished.status` قبل قراءة النص. بخلاف `transcribe`، لا يُرفض كائن Promise (reject) في `get` لمجرد فشل التفريغ أو إلغائه.

## اعرض التفريغات أو احذفها واقرأ حسابك

```javascript
for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) {
  console.log(item.id, item.created_at);
}

await t1.transcriptions.delete(job.id);
const account = await t1.account();
console.log(account.minutes.remaining);
```

أثناء المرور على `list`، تجلب الحزمة الصفحات عند الحاجة. يمكنك التصفية عبر `status` أو `platform` بقيمة `youtube` أو `x` أو `tiktok` أو `instagram` أو `facebook` أو `bluesky` أو `twitch` أو `dailymotion` أو `pinterest` أو `linkedin` أو `snapchat` أو `upload`. يحدد `limit` حجم الصفحة من 1 إلى 100، وافتراضي API هو 20. تبقى أسماء حقول الكائنات بصيغة `snake_case` كما في API. احتفظ بقيمة `media_id` كما هي ولا تحاول تفسير بنيتها.

إذا كان التفريغ جاريا، تلغيه `delete`. وإذا انتهى، تحذفه مع نصه المفرغ. أما `account`، فتعيد باقتك ورصيد الدقائق وحدود الاستخدام.

## اضبط خيارات العميل والتفريغ

عند إنشاء العميل، يمكنك تحديد `apiKey` و`baseUrl` و`fetch` و`maxRetries`. يقرأ `baseUrl` متغير البيئة `TRANSCRIPT1_API_URL` إن وجد، وإلا يستخدم `https://api.transcript1.com`. أرسل دالتك في `fetch` إذا أردت استبدال التنفيذ الافتراضي. يقبل `maxRetries` عددا صحيحا من 0 إلى 10، وافتراضه 2.

الخيارات التالية متاحة في كل من `transcribe` و`transcriptions.create`:

| الخيار | متى تستخدمه؟ |
|---|---|
| `speakers` | لتفعيل تمييز المتحدثين. |
| `language` | لتحديد رمز ISO 639-1، أو ترك التعرف على اللغة للإعداد الافتراضي `auto`. |
| `source` | للروابط، اختر `auto` أو `stt`. تدعم YouTube وX وTikTok وBluesky وDailymotion وLinkedIn أيضا `captions` عند توفر مسار مناسب. |
| `fresh` | لبدء تفريغ جديد للرابط، دون إعادة استخدام تفريغ من آخر 24 ساعة. |
| `filename` | لتسمية Buffer أو Blob بلا اسم أو stream؛ وهو مطلوب معها. يمكنه أيضا استبدال اسم الملف. |
| `size` | لتحديد الحجم بالبايت؛ مطلوب مع streams وasync iterables. |
| `idempotencyKey` | لتحديد مفتاح الطلب. افتراضيا، تنشئ الحزمة UUID جديدا لكل استدعاء. |
| `onProgress` | لمتابعة أحداث التقدم. |
| `signal` | لإلغاء الاستدعاء باستخدام AbortSignal. |

مع `transcriptions.get`، يمكنك استخدام `wait` و`includeWords` و`onProgress` و`signal`. فعل `includeWords: true` لطلب توقيت كل كلمة. يتابع `onProgress` تغيرات الحالة أثناء الانتظار.

لتنزيل النص، تقبل `download` الخيارات `format` و`timestamps` و`signal`. وتقبل `list` أيضا `signal`. وفي `transcriptions.delete(id, options)` أو `account(options)`، أرسل `{ signal }` ضمن معامل الخيارات.

## تابع تقدم العملية

أضف `onProgress` إلى `transcribe` أو `transcriptions.create`، أو إلى `transcriptions.get` عند الانتظار:

```javascript
await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});
```

| نوع الحدث | البيانات التي تصلك |
|---|---|
| `upload` | البايتات المرسلة في `sent` والحجم الكلي في `total`. |
| `status` | حالة التفريغ الحالية في `status`. |
| `waiting_slot` | عدد الثواني في `retryAfter` قبل محاولة بدء المهمة مجددا عند توفر مكان. |
| `reconnecting` | لا بيانات إضافية. يصدر مرة واحدة لكل انقطاع في الاتصال أثناء الانتظار. |

## ألغ الاستدعاء أو حدد مهلة

لإلغاء استدعاء، أرسل `AbortSignal` من AbortController. ولإيقاف الانتظار بعد مدة محددة، استخدم `AbortSignal.timeout`:

```javascript
await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});
```

إذا ألغيت الاستدعاء قبل أول طلب، يُرفض كائن Promise (reject) برمز `aborted` دون معرف مهمة. أثناء الرفع، يحاول SDK حذف المهمة إذا ظلت بحالة `awaiting_upload`، ثم يُرفض كائن Promise (reject) برمز `aborted` ومعه المعرف.

إلغاء الانتظار لا يوقف التفريغ على الخادم. خذ `transcriptionId` من الخطأ لتتابعه عبر `transcriptions.get(id, { wait: true })`. وإذا أردت إلغاء التفريغ نفسه، استدع `transcriptions.delete(id)`.

خلال انتظار التفريغ، يعيد SDK الاتصال عند أخطاء الشبكة أو ردود HTTP 429 و500 و502 و503 و504 دون حد لعدد المحاولات. ينتظر 2 ثم 4 ثم 8 ثم 16 ثم 30 ثانية بين محاولات إعادة الاتصال. أما الطلبات الأخرى، فيحكم عدد محاولاتها `maxRetries`. وإذا بلغت حد المهام النشطة عند الإنشاء، تنتظر الحزمة وتحاول مجددا. استخدم `signal` لوضع حد للوقت الكلي.

## عالج أخطاء SDK وAPI

التقط `Transcript1Error` للوصول إلى رمز الخطأ، سواء جاء من API أو من التفريغ أو من SDK نفسه:

```javascript
import { Transcript1Error } from '@transcript1/sdk';

try {
  await t1.transcribe('./call.mp3');
} catch (error) {
  if (error instanceof Transcript1Error) {
    console.error(error.code, error.message, error.transcriptionId);
  }
}
```

| الحقل | ما الذي يوضحه؟ |
|---|---|
| `message` | رسالة تصف الخطأ. |
| `code` | رمز خطأ API أو فشل التفريغ، أو `canceled`، أو رمز من SDK محليا. |
| `status` | رمز HTTP؛ لا يوجد لأخطاء التفريغ أو الأخطاء المحلية. |
| `details` | بيانات API الإضافية، مثل `minutes_needed` أو `action_url`. الافتراضي كائن فارغ. |
| `retryable` | هل يمكن أن تنجح محاولة أخرى؟ القيمة الافتراضية false. |
| `transcriptionId` | معرف التفريغ إذا كان متاحا. |
| `transcription` | أحدث كائن تفريغ حصلت عليه الحزمة، إن توفر. |

الأخطاء المحلية لها الرموز `missing_api_key` و`invalid_input` و`aborted` و`network_error` و`upload_token_refused`. إذا لم يكن رد الخطأ بصيغة JSON، تستخدم الحزمة `http_<status>`.

إذا فشل التفريغ دون كائن خطأ، تعطي الحزمة `transcription_failed`. وإذا كانت الحالة مكتملة لكن النص مفقود حتى بعد جلبه، يُرفض كائن Promise (reject) في `transcribe` برمز `internal_error`. تجد رموز API في [التعامل مع الأخطاء](https://transcript1.com/ar/docs/errors)، وتفاصيل حقول الرد في [مرجع API](https://transcript1.com/ar/docs/api-reference).

## شغل الحزمة على الخادم فقط

تحتاج إلى Node 20.19+. يفترض أن تعمل الحزمة على Bun وDeno عبر توافقهما مع `node:`، لكن الاختبارات الآلية تعمل على Node فقط. أبق SDK على الخادم، ولا ترسل مفتاح API إلى المتصفح أبدا.