حزمة Node.js SDK

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

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

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

ثبت الحزمة

npm i @transcript1/sdk

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

أضف مفتاح API

أنشئ مفتاحا في صفحة «API keys». يمكنك وضعه في متغير البيئة TRANSCRIPT1_API_KEY على الخادم، أو إرساله في apiKey عند إنشاء العميل:

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

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 على نوعه:

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. للاطلاع على صيغ التسجيلات العامة المقبولة ودعم الترجمة النصية والقيود، راجع المصادر والخيارات.

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

يجب أن يكون منشور الفيديو عاما. إذا احتوى على عدة فيديوهات، نفرغ الأول فقط. يتعرف API على المنصة من الرابط. صيغ الروابط القصيرة المقبولة وحدودها موضحة في المصادر والخيارات.

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

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

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

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. عند إرسال ملف، تنتظر هذه الدالة انتهاء رفعه فقط قبل أن تعيد الرد.

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 لمجرد فشل التفريغ أو إلغائه.

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

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:

مع 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 عند الانتظار:

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

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

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

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 نفسه:

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);
  }
}

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

إذا فشل التفريغ دون كائن خطأ، تعطي الحزمة transcription_failed. وإذا كانت الحالة مكتملة لكن النص مفقود حتى بعد جلبه، يُرفض كائن Promise (reject) في transcribe برمز internal_error. تجد رموز API في التعامل مع الأخطاء، وتفاصيل حقول الرد في مرجع API.

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

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