Hushscript SDK'ları ve CLI

Resmi SDK’lar, sunucu kodu ve betikler için REST API’sini sarmalar. Tek çağrı bir dosyayı deşifre eder: kaydı yükler, işi bekler ve deşifreyi geri verir. Bu arada SDK, dakikalar ayrılmadan önce dosyayı denetler, yeniden denemesi güvenli olanı yeniden dener, uzun bir yüklemeyi canlı tutar ve her yüklemede ile her satın almada bir idempotency anahtarı taşır; böylece yeniden deneme asla iki kez ücret kesmez. CLI, TypeScript SDK’sı üzerine kuruludur ve aynı işi terminalden yapar.

Paketler

Çalışma zamanı alt sınırları:

• TypeScript: Node 22 veya üstü. Bun 1.2+ ve Deno 2+ yalnızca paketin içe aktarılması için denetlenir, HTTP davranışları için denetlenmez.
• Python: 3.10 veya üstü.
• Go: 1.25 veya üstü.
• PHP: 8.2 veya üstü, ext-json ve ext-mbstring ile; eşzamanlı parça yüklemeleri için ext-curl.
• CLI: Node 22 veya üstü.

SDK’lar sunucular ve betikler içindir. API tarayıcı kaynaklarını kabul etmez ve tarayıcı paketindeki bir jeton sızmış bir jetondur; bu yüzden TypeScript SDK’sı window ile document bulunan ortamlarda başlamayı reddeder.

Jeton al

Her SDK ve CLI, kişisel erişim jetonuyla kimlik doğrular. Hesaptaki MCP sayfasında Yeni token oluştur altında bir jeton oluştur, kodunun ihtiyaç duyduğu izinleri seç ve dakika satın alıp alamayacağına karar ver. Jeton bir kez gösterilir ve hsr1:<region>:pat.<id>.<secret> biçimindedir. İzinler ve jetonun nasıl çalıştığı API sayfasında anlatılır.

SDK’lar, sen bir jeton vermediğinde onu HUSHSCRIPT_TOKEN değişkeninden okur:

export HUSHSCRIPT_TOKEN=hsr1:...

Bir ajan kendi hesabını da açabilir, ödemesini barındırılan bir ödeme sayfasında yaptırabilir ve ilk jetonunu koddan talep edebilir: TypeScript’te Hushscript.agent.signup() ve Hushscript.agent.claim(), Python’da Hushscript.agent_signup() ve Hushscript.agent_claim(), Go’da AgentSignup ve AgentClaim, PHP’de Client::agentSignup() ve Client::agentClaim(). Akış ve kuralları Otomatik kullanım sayfasındadır.

TypeScript

npm install @hushscript/sdk

import { writeFile } from "node:fs/promises";
import { Hushscript } from "@hushscript/sdk";

const hs = new Hushscript(); // reads HUSHSCRIPT_TOKEN
const transcript = await hs.transcribe("meeting.mp3");
console.log(transcript.text);
await writeFile("meeting.srt", transcript.toSRT());

transcribe() bir yol, bir Blob, bir Uint8Array ya da bir ReadableStream<Uint8Array> alır. Akış için tam size ve durationSeconds gerekir. hs.balance() harcayabileceğin dakikaları döndürür, hs.transcripts.list() biten deşifreleri sayfa sayfa gezer ve hs.buy("300min", { acknowledgeNoRefund: true }) bir paket satın alır. Her /v1 işlemi aynı yeniden denemeler, zaman aşımları ve gizlemeyle hs.api olarak da kullanılabilir.

Python

pip install hushscript

from pathlib import Path

from hushscript import Hushscript

with Hushscript() as hs:  # reads HUSHSCRIPT_TOKEN
    transcript = hs.transcribe("meeting.mp3")
    print(transcript.text)
    Path("meeting.srt").write_text(transcript.to_srt(), encoding="utf-8")

Her çağrının AsyncHushscript üzerinde aynı adlı bir asyncio karşılığı vardır. transcribe() bir yol, bytes ya da ikili bir dosya nesnesi alır; geri sarılamayan bir dosya nesnesi için size ve duration_seconds gerekir. hs.balance(), hs.transcripts.list() ve hs.buy("300min", acknowledge_no_refund=True) sırasıyla bakiyeyi, deşifre listesini ve satın almaları kapsar.

Go

go get github.com/Hushscript/hushscript-sdk-go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	hushscript "github.com/Hushscript/hushscript-sdk-go"
)

func main() {
	client, err := hushscript.New() // reads HUSHSCRIPT_TOKEN
	if err != nil {
		log.Fatal(err)
	}
	transcript, err := client.Transcribe(context.Background(), "meeting.mp3", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(transcript.Text(nil))
	if err := os.WriteFile("meeting.srt", []byte(transcript.SRT(nil)), 0o600); err != nil {
		log.Fatal(err)
	}
}

Transcribe bir yol, TranscribeReader bir io.ReaderAt ile tam boyutunu, TranscribeStream ise yalnızca ileri okunabilen bir okuyucuyu boyutu ve DurationSeconds ile birlikte alır. client.Balance, client.Transcripts.List ve client.Buy sırasıyla bakiyeyi, deşifre listesini ve satın almaları kapsar. Açık, kapalı ya da ayarsız olabilen seçenekler *bool türündedir ve hushscript.Bool ile oluşturulur.

PHP

composer require hushscript/sdk

<?php

require __DIR__ . '/vendor/autoload.php';

use Hushscript\Client;

$hs = new Client(); // reads HUSHSCRIPT_TOKEN

$transcript = $hs->transcribe('meeting.mp3');
echo $transcript->text();
file_put_contents('meeting.srt', $transcript->toSrt());

transcribe() bir yol ya da açık bir akış alır; geri sarılamayan bir akış için size ve duration_seconds seçenekleri gerekir. Seçenekler snake_case dizi anahtarları kullanır, sonuçlar ise camelCase özellikler taşır. $hs->balance(), $hs->transcripts()->list() ve $hs->buy('300min', true) sırasıyla bakiyeyi, deşifre listesini ve satın almaları kapsar. Laravel’de bir hizmet sağlayıcısında tek bir Client bağla ve deşifreleri sabit bir idempotency_key seçeneğiyle kuyruğa alınmış bir işte çalıştır.

CLI

npm install --global @hushscript/cli
hushscript login
hushscript transcribe meeting.mp3 --format srt --out meeting.srt

CLI jetonu sırasıyla --token, HUSHSCRIPT_TOKEN ve hushscript loginin sakladığı jetondan alır. login jetonu ekranda göstermeden ister ve yalnızca kullanıcının okuyabildiği bir dosyada saklar; hushscript logout onu siler. CI’da ortam değişkenini tercih et.

--json stdout’a yalnızca tek bir JSON belgesi yazar ve stderr’i JSON Lines biçimine çevirir. Çıkış kodu başarıda 0, API’nin ya da SDK’nın hata bildirdiği durumda 1, kullanım hatasında 2 (hiçbir şey gönderilmedi) ve çalışma kesildiğinde 130’dur.

Desteklenen dosyalar

MP3, M4A, MP4 ve MOV (videonun ses parçası kullanılır), WAV, FLAC ve Vorbis ya da Opus’lu OGG; 15 saniyeden 10 saate kadar. SDK’lar biçimi dosyanın baytlarından denetler ve dakikalar ayrılmadan önce süreyi ölçer. Medyayı dönüştürmezler, bu yüzden diğer her şeyi önce dönüştür:

ffmpeg -i input -vn -c:a libopus output.opus

Hatalar

Bir SDK’nın verdiği her hata tek bir aileye aittir, böylece tek bir catch hepsini kapsar: TypeScript ve Python’da HushscriptError, Go’da *hushscript.Error, PHP’de HushscriptException. Bir hata, insufficient_balance gibi bir slug code, sayısal kod, HTTP durumu, bir ileti, sırada ne yapılacağını söyleyen bir hint, ayrıntılar ve retryAfter (PHP’de slug errorCode, Python’da retryAfter retry_after olarak yazılır) taşır.

import { HushscriptError, InsufficientBalanceError } from "@hushscript/sdk";

try {
  await hs.transcribe("meeting.mp3");
} catch (error) {
  if (error instanceof InsufficientBalanceError) console.log(error.hint);
  else if (error instanceof HushscriptError) console.log(error.code, error.hint ?? error.message);
  else throw error;
}

PreflightError, SDK’nın dosyayı hiçbir kredi ayrılmadan reddettiği anlamına gelir. Bakiyenin bir dosyayı karşılayıp karşılamadığına sunucu karar verir: yükleme oluşturulurken, hiçbir parça gönderilmeden önce 402 döner.

Ücretlendirme ve yeniden denemeler

Her yükleme ve her satın alma bir idempotency anahtarı taşır, yeniden denemeler de onu yeniden kullanır; böylece yeniden denenen bir çağrı ikinci bir işlem başlatmak yerine ilkini yeniden oynatır.

buy() kayıtlı varsayılan kartından ücret keser. Koddan satın alma, üç anahtar izin verene kadar kapalıdır: jetonda billing izni vardır, jetonda “Bu tokenin dakika satın almasına izin ver” açıktır ve hesapta “Bağlı uygulamaların dakika satın almasına izin ver” açıktır. Biri eksikse çağrı pat_scope_missing ile başarısız olur. Çağırmadan önce alıcına iade yapılmadığı bildirimini göster.

Bir satın alma, bir ağ hatasında, 502’de ya da 503’te, aynı anahtarla en fazla bir kez yeniden denenir. Bazı yanıtlar hiçbir ücret kesilmediğini kanıtlar: 400, 402, 404 veya 422 ve 4021 (pat_purchase_requires_app, kart reddedildi ya da sen olmadan ücret kesilemiyor) ya da 4023 (pat_purchase_requires_authentication, banka ödemeyi onaylamak istiyor) kodlu bir 403. 4021 veya 4023’ten sonra paketi uygulamadan satın al. İstek gönderildikten sonraki diğer her hata, 401 ve 429 dahil, kartın borçlandırılmış olabileceği anlamına gelir. O hata idempotency anahtarını taşır: aynı anahtarla yeniden iste, satın alma asla iki kez gerçekleşemez. Python’da:

from hushscript import HushscriptError

try:
    purchase = hs.buy("300min", acknowledge_no_refund=True)
except HushscriptError as error:
    refused = error.status in {400, 402, 404, 422} or (
        error.status == 403 and error.numeric_code in {4021, 4023}
    )
    if error.idempotency_key is None or refused:
        raise  # only these refusals charged nothing; any other failure keeps the key for a retry
    purchase = hs.buy("300min", acknowledge_no_refund=True, idempotency_key=error.idempotency_key)

İsteği gönderilmeden başarısız olan bir satın alma anahtar taşımaz: hiçbir ücret kesilmemiştir. Kendi verdiğin bir anahtar A-Za-z0-9_- karakterlerinden 1 ila 128 karakter olmalıdır; onu farklı bir paket için yeniden kullanma. Bir satın alma gönderilmiş olabilecekse CLI anahtarı yazdırır:

hushscript buy 300min --yes --key <key>

Devam jetonları

İş oluştuktan sonra bir hata, idempotency anahtarının yanında bir devam jetonu taşır. Süresi dolan bir bekleme jetonla birlikte WaitTimeoutError verir ve iş çalışmaya devam eder. İkinci bir ücret kesilmeden sürdürmek için jetonu resume()a geri ver: yüklemeyi geçmiş bir iş dosya gerektirmez, hâlâ yüklenen ise aynı dosyayla sürdürülür. PHP’de:

try {
    $hs->transcribe($path, ['wait_timeout' => 60]);
} catch (\Hushscript\Exception\WaitTimeoutError $timeout) {
    $transcript = $hs->resume($timeout->resumeToken, $path);
}

CLI’da transcribe sırasında Ctrl-C, işin devam jetonunu ve onu sürdüren komutu yazdırır:

hushscript resume <token> meeting.mp3 --format srt --out meeting.srt

Günlükleme ve gizleme

SDK’lar telemetri göndermez; User-Agent başlığı tek istemci tanımlamasıdır. Günlükleme varsayılan olarak kapalıdır. HUSHSCRIPT_LOG=debug, her istek için standart hataya yöntem, yol, durum ve süreyle tek bir satır yazar; hiçbir üstbilgiyi, gövdeyi, kayıt başlığını ya da deşifre metnini yazmaz.

Jeton her hatadan, günlük satırından ve istemcinin yazdırılan her biçiminden gizlenir. Hata iletilerinde, ipuçlarında ve nedenlerde bir URL ana makinesini ve yolunu korur ama sorgu dizesi ?[redacted] olur; böylece imzalı bir yükleme URL’si asla yazdırılmaz. Talep gizli anahtarı ya da yeni bir jeton gibi bir sır veren sonuçlar onu alan olarak okunabilir tutar ama yazdırıldığında [redacted] gösterir; bir JSON dışa aktarımı sana aittir ve değeri taşır. CLI bildiği her jetonu stderr’den temizler; stdout’taki sonuçları senin çıktındır ve temizlenmez.

Yapılandırma

Kodda verilen bir seçenek ortam değişkenini geçersiz kılar ve boş bir değer ayarsız sayılır. Dakikalar uygulamayla aynı bakiyeden gelir; paketler ve fiyatlar fiyatlandırma sayfasındadır.