Kayıtlı Ses için Konuşmayı Yazıya Çevirme API'si

Hushscript konuşmayı yazıya çevirme API’si, /v1/ üzerinden kayıtlı sesi kabul eder; ardından betiğin işi yoklayıp deşifreyi okuyabilir. Bu, çevrimiçi bir deşifre iş akışıdır; canlı akış ya da ham tanıma modeli uç noktası değildir. İstemcin HTTP çağrıları yerine araçları tercih ediyorsa MCP sunucusu aynı hesabı, aynı bakiyeyi ve aynı bearer jetonu kullanır.

API ile ses ve videoyu yazıya çevirme

Ses deşifresi API’si, kayıtlı ses dahil hazırlanmış ses dosyalarını kabul eder. STT (speech-to-text) entegrasyonu için kayıtlı dosyalar gönder; canlı mikrofon akışı yoktur. Video deşifresi için ses parçası olan bir MP4 veya MOV dosyasını olduğu gibi yükle: sunucu ses parçasını okur, videoyu atlar. Diğer tüm video biçimlerinde önce sesi çıkar; API video URL’sini kabul etmez. Tarayıcı iş akışı videoyu metne çevirme sayfasında anlatılır.

Hızlı başlangıç

API bir kişisel erişim jetonu ister ve birini elde etmenin iki yolu vardır. Bir kişi, hesaptaki MCP sayfasında Jetonlar altında bir jeton oluşturur, izinlerini seçer ve dakika satın alıp alamayacağına karar verir. Ya da bir ajan, hesap sahibi bir insan olmadan kendi hesabını açar: POST /v1/agent/accounts ücretli bir kaydı başlatır, POST /v1/agent/accounts/{signup_id}/claim ise tek kullanımlık talep gizli anahtarını gerçek bir hesap ve ilk jetonla değiştirir. Hangi yolla olursa olsun jeton bir kez gösterilir ve hsr1:<region>:pat.<id>.<secret> biçimindedir. MCP sunucusunun OAuth ile giriş akışıyla basılan bir jeton da burada çalışır; bkz. Bağlan. Bir jeton başka jeton basamaz, listeleyemez ya da iptal edemez ve bir hesap en fazla 25 etkin jeton tutar; kimlik bilgisi döndürme dahil ajan hesabı akışının tamamı Otomatik kullanım anlatımındadır.

Bir jetonun olunca API’yi doğrudan çağır. Bu örnek, kart doğrulaması ya da satın alma öncesindeki yeni bir kişisel hesabı gösterir; ajanın oluşturduğu hesap ise ödediği dakika paketiyle başlar:

curl https://api.hushscript.com/v1/account \
  -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

{
  "balance_seconds": 0,
  "held_seconds": 0,
  "credits_expire_at": null,
  "card_on_file": false,
  "data_region": "eu",
  "limits": {
    "max_active_jobs": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

Yanıt; saniye cinsinden bakiyeyi, çalışan işlerin bekletilen saniyelerini, credits_expire_at (dakikaların süresi dolmadığı için her zaman null), bir kartın kayıtlı olup olmadığını, veri bölgesini ve kabul sınırlarını (max_active_jobs, max_daily_seconds ve ne kadarının kullanıldığı) içerir. Günlük sınır hesabın o anki geçerli sınırıdır, koda sabitlenecek bir değer değildir. POST /v1/uploads kartı değil, kullanılabilir dakikaları denetler: yeterli dakika yoksa 3001 insufficient_balance döndürür.

Konuşmayı yazıya çevirme API’si ücretsiz mi?

Genel bir ücretsiz API katmanı yoktur, ama tek satır kod yazmadan iş akışını deneyebilirsin: herkese açık önizleme, giriş yapmadan tek bir kayıttan beş dakikaya kadarını yazıya çevirir. Uygun bir kişisel hesap, kart doğrulamasından sonra 30 ücretsiz dakika alır (nasıl işlediği için bkz. fiyatlandırma); ajan hesabı karşılama dakikalarını atlar ve kayıtta satın aldığı paketle başlar. Tam bir API işi her durumda bir hesap ve dakika gerektirir.

Uçtan uca otomasyon

Aynı /v1/ çağrıları, uygulamada bir kişinin oluşturduğu ya da ücretli kayıttan sonra bir ajanın talep ettiği jetonla çalışır (bkz. Otomatik kullanım). Kart kaydetmek için tarayıcıda barındırılan Checkout gerekir; bunu bir ajan yürütebilir. Sonraki oturum dışı (off-session) satın almalar, kartı veren banka doğrulama isterse yine de reddedilebilir.

1. Hesabı oku. GET /v1/account. Dakika satın alman gerekiyorsa ve card_on_file false ise önce bir kart kaydet.

2. Bir kez kart kaydet. POST /v1/billing/setup-session, bir checkout_url, bir session_id ve bir expires_at döndürür:

   curl -X POST https://api.hushscript.com/v1/billing/setup-session \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
     "session_id": "seti_1PxYzQ2eZvKYlo2C",
     "expires_at": "2026-09-11T15:45:00Z"
   }

   URL’yi kontrol ettiğin bir tarayıcıda aç ve barındırılan Stripe sayfasını tamamla; hiçbir şey ücretlendirilmez ve Hushscript kartı asla görmez. Ardından GET /v1/billing/cards kartı kimliğiyle birlikte listeler. Hesapta birden fazla kart varsa POST /v1/billing/cards/default varsayılanı değiştirir.

3. Dakika satın al. GET /v1/billing/packs beş paketi id, seconds, amount ve currency ile listeler:

   curl https://api.hushscript.com/v1/billing/packs \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   POST /v1/billing/purchase, pack, quick_payment_method_id (kayıtlı kartın kimliği) ve bir idempotency_key ile kartı oturum dışında ücretlendirir ve yeni balance_seconds değerini döndürür:

   curl -X POST https://api.hushscript.com/v1/billing/purchase \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "pack": "300min",
       "quick_payment_method_id": "pm_2QeT4bY7uX9mK3nP",
       "idempotency_key": "purchase-2026-09-11-02"
     }'

   { "balance_seconds": 18000 }

   Bunun için billing izni, jetonda faturalandırmanın açık olması ve hesap için faturalandırmanın açık olması gerekir. Kart kimliği içermeyen bir gövde ya da reddedilen bir kart 4021 pat_purchase_requires_app ile reddedilir; kartı veren bankanın ek doğrulama (challenge) istediği bir kart 4023 pat_purchase_requires_authentication ile reddedilir. İkisi de kimsenin tamamlayamayacağı bir sayfa açmaz.

4. Yükle. POST /v1/uploads; size_bytes, duration_seconds (15 saniye ile 10 saat arası), isteğe bağlı bir title, transcription_options, matter_code ve bir idempotency_key ile:

   curl -X POST https://api.hushscript.com/v1/uploads \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "size_bytes": 41943040,
       "duration_seconds": 1200,
       "title": "Q3 board call",
       "transcription_options": { "speaker_detection": true },
       "idempotency_key": "upload-2026-09-11-02"
     }'

   matter_code, en fazla 64 karakterlik serbest metindir ve yalnızca bir kuruluşa ait jeton için anlam taşır: iş, o kuruluşun havuz etkinliğinde ve kullanım raporlarında bu kodla birlikte görünür. Dosya kodu politikası zorunlu olarak ayarlanmış bir kuruluş, kodsuz gelen bir yüklemeyi org_matter_code_required ile reddeder. client_code kabul edilir ama yok sayılır, çünkü müvekkil dosyanın bir özelliğidir ve kuruluşun bir yöneticisi tarafından belirlenir.

   Bir kredi bekletmesi koyar; bir job_id ile ön imzalı (presigned) parça URL’lerinin ilk sayfasını döndürür:

   {
     "job_id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "part_urls": [
       { "n": 1, "url": "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." }
     ]
   }

   Her parçayı kendi URL’sine PUT et (varsayılan olarak 32 MiB’lik parçalar, sonuncusu daha küçük):

   curl -X PUT "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." \
     --data-binary @part-01.bin

   Sonraki sayfaları GET /v1/uploads/{job}/part-urls?start=<n> ile al; uzun bir aktarım sırasında 20 dakikalık boşta kalma zaman aşımına düşmeden çok önce POST /v1/uploads/{job}/heartbeat çağır. Ön imzalı URL’ler kullanılamıyorsa ya da bir parça başarısız olursa PUT /v1/uploads/{job}/parts/{n} o parçanın baytlarını bunun yerine API üzerinden gönderir; tekrarlanan bir PUT parçanın yerini alır, bu yüzden yeniden denemeler güvenlidir. Desteklenenler: mp3, m4a, mp4 veya mov (ses parçası kullanılır, video parçaları atlanır), wav, flac, ogg veya opus; sunucuda denetlenir. Diğer tüm video biçimlerinde yüklemeden önce sesi çıkar.

5. Başlat ve bekle. POST /v1/uploads/{job}/complete; ön imzalı bir URL’ye gönderdiğin her parçanın n ve etag değerleriyle (her parça API üzerinden gittiyse parts’ı çıkar):

   curl -X POST https://api.hushscript.com/v1/uploads/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8/complete \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "parts": [
         { "n": 1, "etag": "\"9f86d081884c7d65\"" }
       ]
     }'

   Ardından GET /v1/jobs/{id} ile yokla: state sırasıyla uploading, queued ve processing aşamalarından geçip done ya da failed olur; biten bir işte transcript_id bulunur:

   curl https://api.hushscript.com/v1/jobs/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "state": "done",
     "transcript_id": "trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9"
   }

6. Sonucu oku. GET /v1/transcripts/{id}, konuşmacı adları, algılanan dil, etiketler ve otomatik silme tarihiyle birlikte meta verileri ve tam metni döndürür:

   curl https://api.hushscript.com/v1/transcripts/trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   GET /v1/transcripts listeyi sayfalar.

Deşifre seçenekleri uygulamadakilerle birebir aynıdır: language_code ya da otomatik algılama, speaker_detection, medical_mode (language_code değerinin en, es, fr veya de olmasını gerektirir, %100 ek ücretle faturalandırılır), translation_targets (dil başına %25), multichannel, keyterms_prompt, serbest metinli bir prompt ve GET /v1/transcription-context çağrısının listelediği kayıtlı dictionary_ids ile prompt_preset_id.

Hesabın bir kısmına hâlâ yalnızca MCP üzerinden ulaşılıyor. Bir bağlantıdan içe aktarma, deşifreleri düzenleme ya da silme, Insights, dışa aktarmalar, sözlük ve istem ön ayarı kaydetme ile hesap ayarları için henüz /v1/ rotası yok; MCP sunucusu bunların hepsini aynı jetonla kapsar.

Kimlik doğrulama

Her /v1/ çağrısı Authorization başlığında bir bearer jeton taşır ve MCP sunucusunun kullandığı izinlere göre denetlenir:

İzinlerin dışında kalan bir çağrı 403 ile pat_scope_missing hatası verir. billing izni de, faturalandırma hem jetonda hem hesapta açık olmadıkça etkisizdir. Ayarlardan biri kapalıyken yapılan bir faturalandırma çağrısı aynı pat_scope_missing hatasıyla sonuçlanır; jetonu yeniden basmak hesap ayarını açmaz. Bir jeton başka jeton oluşturamaz, listeleyemez ya da iptal edemez ve bir hesap en fazla 25 etkin jeton tutar.

Bu 11 izni çağıran seçebilir. pat:rotate ayrı bir izindir; bir ajan hesabının ilk jetonuna ve döndürülmüş ardıllarına verilir. Bu izin, jetonun kendini değiştirmesine izin verir, başka jetonları yönetmesine değil. Uygulamada jeton oluştururken bu izni seçemezsin.

Uç noktalar

Üretimdeki OpenAPI belgesi, 37 yol üzerinde 38 yöntem/yol işlemi listeler. Aşağıdaki her işlem, gösterilen izinle korunur:

/v1/agent/accounts henüz jeton yokken başsız (headless) bir kayıt açar, /v1/agent/accounts/{signup_id}/claim ücretli bir kaydı gerçek bir hesaba ve onun ilk jetonuna çevirir, /v1/agent/credentials/rotate ise çağıran jeton için bir ardıl basar ve ardıl ilk kez kullanıldığında onu devre dışı bırakır; hesaptaki başka hiçbir kimlik bilgisine dokunmaz. Otomatik kullanım anlatımı üçünü de uçtan uca ele alır.

Her liste bir limit ve opak bir cursor alır, son sayfada null olan bir next_cursor döndürür. Cursor’ı değiştirmeden geri gönder; konumu kodlar, bu yüzden çağrılar arasında yeni satırlar gelse bile bir sayfa asla atlanmaz ya da tekrarlanmaz.

Her işlemin parametreleri ve yanıt şemalarıyla birlikte eksiksiz, güncel tanımı OpenAPI belgesidir: bu tabloya değil ona güven. İzninden bağımsız olarak her bearer jetona sunulur, dolayısıyla bir istemci onu elindeki kimlik bilgileriyle alabilir.

MCP arayüzü

Ham HTTP yerine araçları mı tercih ediyorsun? MCP sunucusu, zaten REST yerine MCP konuşan bir istemci için aynı hesabı bu uç noktaların yerine 56 aracın arkasına koyar. Yalnızca bağlı jetonun izinlerinin izin verdiği araçları duyurur.

Sınırlar

Bir insan hesabının jetonuyla yapılan istekler, jeton başına dakikada 1.200 istekle sınırlıdır. Bir ajan hesabının döndürülmüş jetonları bu bütçeyi hesap genelinde paylaşır. Stripe’ı çağıran faturalandırma rotaları, PAT ile çağıranlar için hesap başına dakikada 60’lık daha sıkı bir bütçeyi paylaşır: kurulum oturumu, satın alma, varsayılan kartı değiştirme, kart kaldırma ve kart listesi önbelleğinde ıskalama. Olağan kısıtlama, saniye cinsinden Retry-After ile 429 rate_limited döndürür; yeniden denemeden önce o kadar bekle. Bir ajan hesabının ya da bir insan hesabının PAT’iyle yapılan satın almalar, hesap başına kayan 24 saatte 3 denemelik bir üst sınırı paylaşır. Ajanın kayıt satın alması sayılır; rezervasyondan sonraki ret ya da hatalar da sayılır. İnsan tarayıcı oturumundaki satın alma muaftır. Üst sınıra takılan bir ret, 4038 agent_purchase_capped ve Retry-After ile HTTP 429 döndürür. Kayıtlar 15 saniyeden 10 saate kadar olabilir. GET /v1/account hesabın geçerli kabul sınırlarını (max_active_jobs, max_daily_seconds) bildirir.

Sandbox

Genel bir deşifre sandbox’ı yoktur: olağan /v1/ çağrıları gerçek hesaplara karşı çalışır ve satın almalar gerçek para harcar. İstisna kayıt doğrulamasıdır: POST /v1/agent/accounts dry_run: true kabul eder, talep edilemeyen bir dry_ kayıt kimliği döndürür ve ne Stripe oturumu ne de hesap açar.

Hatalar

Bir hata, aşağıda gösterilen HTTP durumunda, sabit bir sayısal code ve bir error slug’ı taşıyan JSON gövdesidir. /v1/ hata gövdeleri sabitlenmiş bir alt kümedir: error, code ve sabit bir ayrıntı anahtarları kümesi. /api’nin hata şekli sabit değildir ve daha fazlasını taşıyabilir. Otomatik bir çağıranın ele alması gereken kodlar:

OpenAPI belgesi her işlemin döndürebileceği kesin kodu adlandırır; MCP sunucusu ise kodların tüm kataloğunu hushscript://error-codes kaynağı olarak yayınlar.