# Node.js ile kullanım (SDK) > @transcript1/sdk ile sunucunuzdan video ve dosya transkripsiyonu yapın. Metin veya altyazı indirin, ilerlemeyi ve hataları takip edin. Canonical: https://transcript1.com/tr/docs/sdk Language: tr Last updated: 2026-10-16 `@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 ```bash 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](https://transcript1.com/dashboard/account/tokens) 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: ```javascript 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. ```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 veya Uint8Array gönderirken dosya adını da belirtin. SDK, dosyanın türünü bu addan belirler: ```javascript 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](https://transcript1.com/tr/docs/sources-and-options) 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](https://transcript1.com/tr/docs/sources-and-options) sayfasında bulabilirsiniz. Dosya yolu dışında Blob, `ReadableStream` 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. ```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` 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. ```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` ç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 ```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` 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: | Seçenek | Kullanımı | |---|---| | `speakers` | Konuşmacı ayırmayı açın. | | `language` | Varsayılan `auto` veya bir ISO 639-1 dil kodu seçin. | | `source` | Bağlantılarda `auto` veya `stt` kullanın. YouTube, X, TikTok, Bluesky, Dailymotion ve LinkedIn'de kullanılabilir altyazı varsa `captions` da kabul edilir. | | `fresh` | Bağlantı için son 24 saatte oluşturulan transkripsiyonu kullanmak yerine yeni işlem başlatın. | | `filename` | Buffer, adsız Blob ve stream için dosya adını belirtin. Mevcut dosya adının yerine farklı bir ad da verebilirsiniz. | | `size` | Stream ve async iterable için boyutu bayt olarak belirtin. Bu kaynaklarda zorunludur. | | `idempotencyKey` | Belirtmezseniz her çağrı için yeni bir UUID oluşturulur. | | `onProgress` | İlerleme olaylarını alacak fonksiyonu verin. | | `signal` | Çağrıyı iptal edebilmek için AbortSignal verin. | `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: ```javascript await t1.transcribe('./interview.m4a', { onProgress(event) { console.log(event); }, }); ``` | Olay | Bildirdiği bilgi | |---|---| | `upload` | Gönderilen ve toplam bayt sayısı: `sent`, `total`. | | `status` | Transkripsiyonun o anki durumu: `status`. | | `waiting_slot` | Yeni transkripsiyon başlatmak için tekrar denemeye kaç saniye kaldığı: `retryAfter`. | | `reconnecting` | Ek alan içermez. Bekleme sırasında her bağlantı kesintisi için bir kez bildirilir. | ## Ç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: ```javascript 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: ```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); } } ``` | Alan | İçeriği | |---|---| | `message` | Sorunu açıklayan metin. | | `code` | API veya transkripsiyon hata kodu, `canceled` ya da SDK'nın yerel hata kodu. | | `status` | HTTP durum kodu. Transkripsiyon hatalarında ve yerel hatalarda yoktur. | | `details` | `minutes_needed` veya `action_url` gibi ek API alanları. Varsayılanı boş nesnedir. | | `retryable` | Tekrar denemenin işe yarayıp yaramayacağını belirtir. Varsayılan değer false olur. | | `transcriptionId` | Biliniyorsa transkripsiyonun kimliği. | | `transcription` | Varsa en son alınan transkripsiyon nesnesi. | 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_` 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](https://transcript1.com/tr/docs/errors), yanıt alanları [API referansı](https://transcript1.com/tr/docs/api-reference) 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.