Hushscript Geliştirici API'si

Hushscript, bir MCP istemcisi çalıştırmak yerine doğrudan bir HTTP uç noktasını çağırmayı tercih eden ajanlar ve betikler için düz REST çağrılarını da yanıtlar. Baştan sona aynı hesap, aynı bakiye ve aynı taşıyıcı (bearer) jetonlardır: burada hiçbir şey transkripsiyonun nasıl fiyatlandırıldığını veya saklandığını değiştirmez.

Hızlı başlangıç

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

Bir jetona sahip olduğunuzda API’yi doğrudan çağırın:

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": 3,
    "max_daily_seconds": 36000,
    "active_jobs": 0,
    "daily_seconds_used": 0
  }
}

Bu, bakiyeyi saniye cinsinden, çalışan işlerin bekletilen saniyelerini, kredinin son kullanma tarihini, bir kartın kayıtlı olup olmadığını, veri bölgesini ve kabul sınırlarını (max_active_jobs, max_daily_seconds ve bunların ne kadarının kullanıldığı) yanıtlar. Yeni bir hesap sıfır bakiyeyle başlar. POST /v1/uploads, kartı değil bakiyeyi denetler: dakika yoksa 3001 insufficient_balance döner. Bakiyenin oraya ulaşmasını sağlayan şey karttır, çünkü uygulamadaki tek seferlik kart doğrulaması 30 ücretsiz dakikayı serbest bırakır ve paketler kayıtlı bir karta karşı satın alınır.

Uçtan uca otomasyon

Hesap var olduktan sonraki her şey, o hesabı uygulamada bir kişi mi yoksa /v1/agent/accounts üzerinden bir ajan mı açtığından bağımsız olarak insansız çalışır (bkz. Otomatik kullanım). Tek bir tarayıcı adımı kalır ve bir ajan o tarayıcıyı kendisi de sürebilir.

1. Hesabı okuyun. GET /v1/account. card_on_file false ise önce bir kart kaydedin.

2. Bir kart kaydedin, bir kez. 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ünüzdeki bir tarayıcıda açın ve barındırılan Stripe sayfasını tamamlayın; hiçbir şey ücretlendirilmez ve Hushscript kartı asla görmez. Ardından GET /v1/billing/cards, onu kimliğiyle birlikte listeler. Hesap birden fazla kart tutuyorsa POST /v1/billing/cards/default varsayılanı değiştirir.

3. Dakika satın alın. 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"

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

   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 }

   Bu, jetonda billing iznini ve hesap için faturalandırmanın açık olmasını gerektirir. Kart kimliği içermeyen bir gövde veya reddedilen bir kart 4021 pat_purchase_requires_app ile reddedilir; kart çıkarıcısının doğrulamak istediği bir kart 4023 pat_purchase_requires_authentication ile reddedilir. İkisi de kimsenin tamamlayamayacağı bir sayfa açmaz.

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

   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"
     }'

   Bir kredi bekletmesi koyar ve bir job_id ile ön imzalı (presigned) parça URL’lerinin ilk sayfasını yanıtlar:

   {
     "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 edin (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> üzerinden alın ve uzun bir aktarım sırasında 20 dakikalık boşta kalma (idle) zaman aşımının iyice içinde POST /v1/uploads/{job}/heartbeat çağrısı yapın. Ön imzalı URL’ler kullanılamıyorsa veya 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. Yalnızca ses: mp3, m4a, wav, flac, ogg veya opus, en fazla 5 GB, sunucuda denetlenir; bir videodan yüklemeden önce ses parçasını çıkarın.

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

   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}’i yoklayın: state, uploading, queued ve processing’den done veya failed’e geçer, ve tamamlanmış bir iş bir transcript_id taşır:

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

Transkripsiyon seçenekleri uygulamanınkiyle birebir aynıdır: language_code veya otomatik algılama, speaker_detection, medical_mode (language_code’un 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 metin bir prompt, ve GET /v1/transcription-context’in listelediği kayıtlı dictionary_ids ve prompt_preset_id.

Hesabın bir kısmı hâlâ yalnızca MCP üzerinden erişilebilir. Bir bağlantıdan içe aktarma, transkriptleri düzenleme veya silme, Insights, dışa aktarmalar, sözlük ve istem ön ayarı kaydetme, ve hesap ayarları henüz bir /v1/ rotasına sahip değildir; MCP sunucusu bunların tamamını aynı jetonla kapsar.

Kimlik doğrulama

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

Jetonun izinleri dışındaki bir çağrı, 403 durumunda pat_scope_missing ile başarısız olur. billing izni de hesap sahibi uygulamada hesap için faturalandırmayı açana kadar etkisizdir; bu anahtar kapalıyken yapılan bir faturalandırma çağrısı aynı pat_scope_missing ile başarısız olur ve jetonu yeniden basmak bunu temizlemez. Bir jeton başka jetonlar oluşturamaz, listeleyemez veya iptal edemez, ve bir hesap en fazla 25 etkin jeton tutar.

Uç noktalar

Bugün canlı, her biri gösterilen izinle korunur:

/v1/agent/accounts, henüz jeton olmadan başsız (headless) bir kaydı açar, /v1/agent/accounts/{signup_id}/claim ücretli bir kaydı gerçek bir hesaba ve onun ilk jetonuna dönüştürür, ve /v1/agent/credentials/rotate çağıran jeton için bir ardıl basar ve onu iptal eder, hesaptaki başka hiçbir kimlik bilgisine dokunmaz. Otomatik kullanım adım adım anlatımı üçünü de uçtan uca kapsar.

Her liste bir limit ve opak bir cursor alır ve son sayfada null olan bir next_cursor yanıtlar. Cursor’ı değiştirmeden geri gönderin; konumu kodlar, bu yüzden çağrılar arasında yeni satırlar geldiğinde bir sayfa asla atlanmaz veya tekrarlanmaz.

Her işlem için parametreler ve yanıt şemalarıyla birlikte eksiksiz, güncel tanım OpenAPI belgesidir: bu tabloya değil ona güvenin. İzninden bağımsız olarak her taşıyıcı jetona sunulur, bu yüzden bir istemci onu zaten sahip olduğu kimlik bilgileriyle alabilir.

MCP arayüzü

Ham HTTP yerine araçları mı tercih ediyorsunuz? MCP sunucusu, REST yerine zaten MCP konuşan bir istemci için aynı hesabı bu uç noktalar yerine 51 aracın ardına yerleştirir.

Sınırlar

Bir jetonla yapılan istekler jeton başına dakikada 1.200 ile sınırlıdır. POST /v1/billing/setup-session ve POST /v1/billing/purchase, yapacakları Stripe çağrısından önce uygulanan, hesap başına dakikada 60’lık daha sıkı bir bütçeyi paylaşır. Reddedilen bir istek, bekleme süresini saniye olarak adlandıran bir Retry-After başlığıyla 429 rate_limited yanıtı verir; yeniden denemeden önce o kadar bekleyin. Yüklemeler 5 GB ve 10 saatle sınırlıdır, 15 saniyelik bir asgari ile, ve hesabın kendi kabul sınırları (max_active_jobs, max_daily_seconds) GET /v1/account tarafından bildirilir.

Sandbox

Kuru çalıştırma (dry-run) modu yoktur: her /v1/ çağrısı gerçek bir hesaba karşı çalışır ve dakika satın almak gerçek para harcar.

Hatalar

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

OpenAPI belgesi, her işlemin döndürebileceği kesin kodu adlandırır ve MCP sunucusu eksiksiz kataloğu hushscript://error-codes kaynağı olarak yayınlar.