Node.js ile kullanım (SDK)

@transcript1/sdk, TypeScript veya JavaScript sunucu kodunuzdan transkripsiyon başlatmanızı sağlar. Dosyaları yükler, işlemin bitmesini bekler ve transkripti getirir.

Sosyal medya bağlantıları için en az SDK 1.1.0 gerekir. SDK 1.0.1 yalnızca YouTube bağlantılarını tanır; diğerlerini API'ye göndermeden reddeder. Paketi npm i @transcript1/sdk@latest ile güncelleyin.

Bu minimum sürüm ilk altı platform içindir. Twitch, Dailymotion, Pinterest, LinkedIn ve Snapchat için ilgili platformun desteğini içeren bir SDK sürümü gerekir. Eski sürümler bu bağlantıları API'ye ulaşmadan reddedebilir.

Kurulum

npm i @transcript1/sdk

Aşağıdaki örnekler ES modülleriyle yazılmıştır. .mjs dosyası kullanın veya .js için package.json dosyasında "type": "module" ayarlayın. Node 20.19+ kullanıyorsanız require('@transcript1/sdk') gibi require() çağrıları da çalışır.

API anahtarınızı tanımlayın

Paneldeki “API keys” sayfasından anahtar oluşturun. Sunucuda TRANSCRIPT1_API_KEY ortam değişkenini ayarlayın. İsterseniz Transcript1 oluştururken anahtarı apiKey seçeneğiyle doğrudan verebilirsiniz:

import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });

Anahtar belirtmezseniz constructor, missing_api_key kodlu bir Transcript1Error fırlatır.

Kaydı gönderin, transkripti alın

transcribe(input, options) transkripsiyonu başlatır ve bitmesini bekler. Tamamlandığında status: 'completed' ve transcript içeren bir CompletedTranscription alırsınız. İşlem başarısız olursa veya iptal edilirse promise reddedilir.

const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);
 
const file = await t1.transcribe('./interview.m4a', { speakers: true });

Buffer veya Uint8Array gönderirken dosya adını da belirtin. SDK, dosyanın türünü bu addan belirler:

import { readFile } from 'node:fs/promises';
 
const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });

Metin olarak verdiğiniz değer http:// veya https:// ile başlıyorsa SDK bunu bağlantı, aksi halde dosya yolu olarak yorumlar. YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn ve Snapchat bağlantılarıyla ya da kendi dosyalarınızla çalışabilirsiniz. Hangi herkese açık kayıtların kabul edildiğini, altyazı desteğini ve kısıtlamaları Kaynaklar ve seçenekler sayfasından kontrol edin. Son beş platform için HTTPS zorunludur. Dosya boyutu en fazla 2.000.000.000 bayt olabilir. Kabul edilen uzantılar: mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm ve mkv.

Sosyal medya gönderisi herkese açık olmalıdır. Gönderide birkaç video varsa yalnızca ilkini yazıya çeviririz. Platformu API bağlantıdan belirler. Kabul edilen kısa bağlantıları ve diğer sınırları Kaynaklar ve seçenekler sayfasında bulabilirsiniz.

Dosya yolu dışında Blob, ReadableStream<Uint8Array> veya Uint8Array parçaları üreten bir async iterable da gönderebilirsiniz. Blob, adı olan bir File değilse filename zorunludur. Stream ve async iterable gönderirken hem filename hem de bayt cinsinden size belirtin.

Metin veya altyazı indirin

download(id, options) transkripsiyon bitene kadar bekler, ardından metin döndürür. JSON seçtiğinizde de nesne değil, API'nin JSON metnini alırsınız; kullanmak için kendiniz ayrıştırın.

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 yalnızca text formatında kullanılabilir. Diğer formatlarda invalid_input hatasıyla promise reddedilir. Transkripsiyon başarısız olursa veya iptal edilirse de download çağrısında promise reddedilir.

Transkripti beklemeden devam edin

İşlemi arka planda yürütmek için transcriptions.create çağırın. Bu metot transkript hazır olana kadar beklemez. Dosya gönderdiyseniz yine de önce yüklemeyi bitirir, sonra yanıt verir.

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 çağrısı, wait belirtmezseniz o anki durumu getirir. wait: true verirseniz transkripsiyon completed, failed veya canceled durumuna gelene kadar bekler. Transkript metnine erişmeden önce finished.status kontrolü yapın. transcribe ile farkı şudur: işlem başarısız olsa veya iptal edilse bile get çağrısında promise reddedilmez; dönen nesnenin durumunu siz değerlendirirsiniz.

Transkripsiyonları ve hesabınızı yönetin

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 döngüsünde ilerledikçe yeni sayfalar otomatik alınır. status veya platform ile filtre koyabilirsiniz. Platform değerleri youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat ve upload olabilir. limit, sayfa başına kayıt sayısını belirler: 1–100 arasında seçebilirsiniz; API'nin varsayılanı 20'dir. Alan adları API'deki snake_case biçiminde kalır. media_id değerini olduğu gibi saklayın; içeriğinden bir anlam çıkarmayın.

delete çalışan transkripsiyonu iptal eder. İşlem sona ermişse transkripsiyonu metniyle birlikte siler. account ile planınızı, dakika bakiyenizi ve limitlerinizi sorgulayabilirsiniz.

SDK ayarları

Transcript1 oluştururken apiKey, baseUrl, fetch ve maxRetries verebilirsiniz. baseUrl belirtmezseniz önce TRANSCRIPT1_API_URL ortam değişkenine bakılır; o da yoksa https://api.transcript1.com kullanılır. Kendi HTTP çağrı fonksiyonunuz için fetch verin. maxRetries varsayılan olarak 2'dir; 0–10 arası tam sayı kabul eder.

Hem transcribe hem de transcriptions.create aşağıdaki seçenekleri kabul eder:

transcriptions.get için wait, includeWords, onProgress ve signal kullanılabilir. Kelime düzeyinde zaman damgaları istiyorsanız includeWords: true verin. onProgress, bekleme sırasında değişiklikleri bildirir.

download çağrısında format, timestamps ve signal seçenekleri vardır. list için de signal verebilirsiniz. Silme veya hesap sorgusunu iptal edilebilir yapmak için transcriptions.delete(id, options) ya da account(options) çağrısının seçenekler argümanına { signal } gönderin.

İlerlemeyi takip edin

Yükleme ve işlem durumunu takip etmek için transcribe, transcriptions.create veya bekleme açık bir transcriptions.get çağrısına onProgress ekleyin:

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

Çağrıyı iptal edin veya süre sınırı koyun

İptal edilebilir bir çağrı için AbortController üzerinden AbortSignal verin. Belirli bir süre sonunda durması için AbortSignal.timeout kullanabilirsiniz:

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

İlk istek gönderilmeden iptal ederseniz promise reddedilir; hata kodu aborted olur ve transkripsiyon kimliği bulunmaz. Yükleme sırasında iptal ederseniz SDK, hâlâ awaiting_upload durumundaki transkripsiyonu silmeye çalışır. Ardından promise reddedilir; hatada aborted kodu ve transkripsiyon kimliği bulunur.

Yalnızca beklemeyi iptal etmek, sunucudaki transkripsiyonu durdurmaz. Hatanın transcriptionId alanındaki kimlikle transcriptions.get(id, { wait: true }) çağırıp beklemeye devam edebilirsiniz. Transkripsiyonun kendisini durdurmak için transcriptions.delete(id) çağırın.

Transkripsiyonu beklerken ağ hatalarında veya HTTP 429, 500, 502, 503 ve 504 yanıtlarında SDK yeniden bağlanmayı sınırsız dener. Bekleme aralıkları sırasıyla 2, 4, 8, 16 ve ardından 30 saniyeye çıkar. Diğer isteklerde deneme sayısını maxRetries belirler. Aynı anda çalışabilecek transkripsiyon limiti doluysa oluşturma çağrısı da bekleyip yeniden dener. Toplam bekleme süresine sınır koymak için signal kullanın.

Hataları yakalayın

API'den, transkripsiyondan veya SDK'dan gelen hataları Transcript1Error ile yakalayabilirsiniz:

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

SDK'nın yerel hata kodları şunlardır: missing_api_key, invalid_input, aborted, network_error ve upload_token_refused. Hata yanıtı JSON değilse kod http_<status> biçimindedir.

Transkripsiyon başarısız olmuş ama hata nesnesi gelmemişse transcription_failed alırsınız. Durum tamamlandı görünmesine rağmen sorgudan transkript gelmezse transcribe çağrısında promise reddedilir ve kod internal_error olur. API hata kodları Hatalar, yanıt alanları API referansı sayfasında açıklanır.

Nerede çalışır?

Node 20.19+ gerekir. Bun ve Deno'nun node: uyumluluğuyla da çalışması beklenir, ancak otomatik testleri yalnızca Node üzerinde çalıştırıyoruz. SDK'yı sunucu tarafında kullanın. API anahtarınızı hiçbir zaman tarayıcıya göndermeyin.