Otomatik Kullanım

Bir Hushscript hesabı açmak eskiden en az bir kez bir kişiyi gerektirirdi. Artık hikâyenin tamamı bu değil. Ödeme öncelikli bir akış, bir ajanın kendi hesabını açmasına, ona bakiye yüklemesine ve onu çalıştırmasına imkân tanır; sürecin hiçbir yerinde insan bir hesap sahibi bulunmaz. /developers ve /mcp, bu hesabın ardından kullandığı iki arayüzü belgeler; bu sayfa bir tane edinmenin adım adım anlatımıdır.

Kaydolun

POST /v1/agent/accounts başsız (headless) bir kaydı başlatır. Henüz hesap, çerez veya jeton yoktur: yalnızca bekleyen bir satın alma vardır.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-08-01",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email yalnızca makbuzlar ve bildirimler içindir, asla oturum açma için değildir. pack_id, 45min, 300min, 900min, 1800min, 6000min değerlerinden biridir; amount veya currency’yi asla kendiniz göndermeyin, ikisi de sunucuda paketten türetilir. Kayıt sırasında yalnızca en küçük iki paket, 45min ve 300min, satın alınabilir. Daha büyük bir pack_id reddedilir ve ret, bu hesabın şu anda ne satın alabileceğini listeleyen details.allowed_packs alanını taşır; böylece çağıran taraf tahmin yürütmeden yeniden deneyebilir. Merdivenin geri kalanı hacimle değil, yaşla açılır: aşağıdaki Yeni bir hesap ne satın alabilir bölümüne bakın. accept_terms_version, sunucunun geçerli politika sürümüyle tam olarak eşleşmelidir; aksi halde çağrı, gövdesinde geçerli değeri adlandıran policy_version_stale hatasıyla başarısız olur. İsteğe bağlı bir data_region ipucu, yalnızca ağ konumunuzun zaten ima ettiği bölgeyle uyuştuğunda dikkate alınır. İsteğe bağlı bir dry_run: true, hiçbir Stripe oturumu ve hiçbir ücretlendirme olmadan her şeyi doğrular; signup_id’si dry_ önekini taşır ve asla talep edilemez.

claim_secret, yalnızca bu yanıtta, tam olarak bir kez gösterilir. Hushscript yalnızca onun hash’ini saklar. Talep çağrısından önce onu kaybetmek, kaydı kaybetmek anlamına gelir: bir talep gizli bilgisi için kurtarma yolu yoktur ve emanetteki ödeme, bir sorguyla geri verilmek yerine aşağıda anlatılan süpürme (sweep) tarafından iade edilir.

Ödemeyi kendi tarayıcınızda tamamlayın

checkout_url, barındırılan bir Stripe Checkout sayfasıdır. Bu, tüm akış boyunca tarayıcı gerektiren tek adımdır ve bunun bir kişinin tarayıcısı olması gerekmez: bir ajan onu kendi otomasyonuyla yürütebilir (kart alanlarını doldurur, gönderir, yönlendirmeyi izler). Hushscript her iki durumda da kart bilgilerini asla görmez; onları Stripe görür. Bunu tamamlamak ve ardından talep etmek için pencere 30 dakikadır, yukarıdaki expires_at.

Ödemesi yapılan ama hiç talep edilmeyen bir kayıt, saatlik bir süpürme tarafından otomatik olarak iade edilir; bu, 30 dakikalık pencere kapandıktan yaklaşık bir saat sonra gerçekleşir. İade tamdır, çünkü dakikalar yalnızca talep anında bir bakiyeye eklenir, bu yüzden talep edilmemiş bir kaydın hiç harcayacak dakikası olmamıştır.

Hesabı talep edin

POST /v1/agent/accounts/{signup_id}/claim, ödemesi yapılmış ama talep edilmemiş bir kaydı tek bir çağrıda gerçek bir hesaba dönüştürür.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Talep etmek tek kullanımlıktır. Tam olarak bir hesap oluşturur, arkasında sentetik ve çözümlenemez bir oturum açma kimliği bulunur; istek yeniden denense bile ödenmiş paketi tam olarak bir kez verir ve tam olarak bir PAT basar: yukarıdaki pat değeri, o da tam olarak bir kez gösterilir.

Yanlış bir gizli bilgi, bilinmeyen bir signup_id, zaten talep edilmiş bir kayıt, iade edilmiş bir kayıt ve süresi dolmuş bir kayıt, hepsi aynı agent_claim_invalid hatasını verir. Çağıran tarafın yanıttan bunları birbirinden ayırmasının bilerek bir yolu yoktur. Ödeme durumu yalnızca gizli bilginin kendisi doğrulandıktan sonra devreye girer: henüz sonuçlanmamış bir Checkout Session, bunun yerine wrong_state yanıtı verir.

Yukarıdaki balance_seconds, başlangıç bakiyesinin tamamıdır. Ajan hesapları, bir kişinin ilk hesabının aldığı gibi bir hoş geldin bonusu veya kart doğrulamasından gelen ücretsiz dakikalar almaz; yalnızca ödedikleri paketle başlarlar. Bu bir eksiklik değil, bilinçli bir tercihtir: hesap, var olmadan önce zaten ödenmişti.

Daha fazla dakika satın alın

Buradan itibaren hesap, /developers’ın eksiksiz belgelediği aynı /v1/ yüzeyi üzerinden diğer her hesap gibi davranır.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Bu, yukarıdaki talep yanıtının zaten verdiği billing iznini gerektirir ve kart kaydetme yoluyla, ikisinin de yaptığı Stripe çağrısından önce uygulanan, hesap başına dakikada 60 istekten oluşan daha sıkı bir sınırı paylaşır.

Yeni bir hesap ne satın alabilir

Paket boyutu, hesabın ne kadar harcadığına değil, ödemesi tamamlanmış işlemlerin yaşına göre açılır. Bir satın alma, kendi ödeme tarihinin 7 gün üzerine çıkmadıkça bir sonraki katman için sayılmaz; bu yüzden yepyeni bir hesap hızlıca satın alarak büyük paketlere ulaşamaz.

Reddedilen bir satın alma, körlemesine başarısız olmak yerine geçerli kümeyi details.allowed_packs içinde adlandırır. Kayıt çağrısı bu tablonun ilk satırını uygular; yukarıdaki adım adım anlatımın 300min satın almasının ve daha büyük bir şey almamasının nedeni budur. Merdivenden ayrı olarak, henüz itiraz penceresini aşacak kadar yaşlanmamış bakiyenin ne kadar hızlı harcanabileceğini kayan bir 24 saatlik yakma sınırı sınırlar.

Deşifre edin

Yükleme ve deşifre etme, diğer her hesapla aynı çok parçalı (multipart) akıştır.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

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

Her parçayı kendi ön imzalı (presigned) URL’sine PUT edin, ardından aynı işin /complete uç noktasına bu şekilde gönderilen her parçanın n ve etag değerleriyle POST gönderin. Ardından işi yoklayın:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Kimlik bilgisini döndürün

Bir makine hesabının parolası ve kullanılabilir bir posta kutusu yoktur; bu yüzden bir PAT sızarsa veya sadece değiştirilmesi gerekirse “parolamı unuttum” gibi bir yol yoktur. Döndürme (rotation) o yoldur.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

Çağrı hiçbir gövde almaz. Atomik olarak bir ardıl basar ve isteği doğrulayan jetonu iptal eder; bu yüzden eski PAT, onunla yapılan bir sonraki çağrıda başarısız olur. Ardıl, öncekinin izinlerini, faturalandırma iznini, adını, istemci etiketini ve son kullanma politikasını korur. Bu uç nokta, çağıranın kendi jetonundan başka hiçbir şeye dokunmaz: hesaptaki başka hiçbir kimlik bilgisini listeleyemez, basamaz veya iptal edemez. Bu, bir makine hesabının sahip olduğu tek kimlik bilgisi kurtarma yoludur; bu yüzden eski jeton atılmadan önce döndürün, sonra değil.

Hatalar

Bu dört hata ajan hesaplarına özgüdür ve bir insan hesabı tarafından asla tetiklenmez:

Talep gizli bilgisinin kendisi doğrulandıktan sonra, ödemesi yapılmamış bir Checkout Session, agent_claim_invalid yerine wrong_state (4001) yanıtı verir. Eksiksiz katalog OpenAPI belgesidir.

Sınırlar

Çağrılar dakikada 1.200 ile sınırlıdır. Bir ajan hesabı için bu bütçe tek bir jetona değil, hesabın kendisine aittir: döndürme soyağacındaki her kimlik bilgisi aynı bütçeden çeker, bu yüzden bir PAT’ı döndürmek ardıla yeni bir kota vermez. İki faturalandırma yazma işlemi, bir kart kaydetmek ve bir paket satın almak, ikisinin de yaptığı Stripe çağrısından önce uygulanan, hesap başına dakikada 60’lık daha sıkı bir sınırı paylaşır. Yukarıdaki 24 saatlik satın alma sınırı da aynı şekilde, kimlik bilgisi başına değil hesap başına sayılır.

Daha fazla bilgi

Bu sayfa hesap yaşam döngüsünü kapsar: birini açmak, ona bakiye yüklemek ve kimlik bilgisini geçerli tutmak. Hesabın ardından yapabileceği her şey için, eksiksiz OpenAPI belgesi dahil REST API’ye ya da aynı hesap için ham HTTP yerine araçlar üzerinden çalışan MCP sunucusu’na bakın.