SDK dan CLI Hushscript

SDK resmi membungkus REST API untuk kode server dan skrip. Satu panggilan mentranskripsikan sebuah file: rekaman diunggah, SDK menunggu pekerjaannya, lalu menyerahkan transkripnya. Di antaranya, SDK memeriksa file sebelum ada menit yang ditahan, mengulang permintaan yang aman diulang, menjaga unggahan panjang tetap hidup, dan menyertakan kunci idempotensi pada setiap unggahan dan pembelian, sehingga percobaan ulang tidak pernah menagih dua kali. CLI dibangun di atas SDK TypeScript dan melakukan hal yang sama dari terminal.

Paket

Versi runtime minimum:

• TypeScript: Node 22 atau lebih baru. Bun 1.2+ dan Deno 2+ hanya diperiksa untuk mengimpor paket, bukan untuk perilaku HTTP-nya.
• Python: 3.10 atau lebih baru.
• Go: 1.25 atau lebih baru.
• PHP: 8.2 atau lebih baru, dengan ext-json dan ext-mbstring; ext-curl untuk unggahan bagian secara bersamaan.
• CLI: Node 22 atau lebih baru.

SDK dibuat untuk server dan skrip. API tidak menerima origin browser, dan token di dalam bundle browser adalah token yang bocor, sehingga SDK TypeScript menolak berjalan di lingkungan yang memiliki window dan document.

Dapatkan token

Setiap SDK dan CLI mengautentikasi dengan token akses pribadi. Buat satu di bawah Create a new token pada halaman MCP di akun, pilih scope yang dibutuhkan kode Anda, dan tentukan apakah token boleh membeli menit. Token hanya ditampilkan sekali dan berbentuk hsr1:<region>:pat.<id>.<secret>. Scope dan cara kerja token ada di halaman API.

SDK membaca token dari HUSHSCRIPT_TOKEN bila Anda tidak mengirimkannya:

export HUSHSCRIPT_TOKEN=hsr1:...

Agen juga dapat membuka akunnya sendiri, membayarnya di halaman checkout yang dihosting, lalu mengklaim token pertamanya dari kode: Hushscript.agent.signup() dan Hushscript.agent.claim() di TypeScript, Hushscript.agent_signup() dan Hushscript.agent_claim() di Python, AgentSignup dan AgentClaim di Go, serta Client::agentSignup() dan Client::agentClaim() di PHP. Alur dan aturannya ada di Penggunaan otomatis.

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() menerima path, Blob, Uint8Array, atau ReadableStream<Uint8Array>. Stream memerlukan size dan durationSeconds yang tepat. hs.balance() mengembalikan menit yang dapat Anda pakai, hs.transcripts.list() menelusuri transkrip yang sudah selesai per halaman, dan hs.buy("300min", { acknowledgeNoRefund: true }) membeli sebuah paket. Setiap operasi /v1 juga tersedia sebagai hs.api, dengan percobaan ulang, batas waktu, dan penyamaran data yang sama.

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")

Setiap panggilan memiliki padanan asyncio pada AsyncHushscript dengan nama yang sama. transcribe() menerima path, bytes, atau objek file biner; objek file yang tidak dapat di-seek memerlukan size dan duration_seconds. hs.balance(), hs.transcripts.list(), dan hs.buy("300min", acknowledge_no_refund=True) mencakup saldo, daftar transkrip, dan pembelian.

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 menerima path, TranscribeReader menerima io.ReaderAt beserta ukuran persisnya, dan TranscribeStream menerima pembaca satu arah beserta ukuran dan DurationSeconds-nya. client.Balance, client.Transcripts.List, dan client.Buy mencakup saldo, daftar transkrip, dan pembelian. Opsi yang bisa mati, hidup, atau tidak diatur bertipe *bool, dibuat dengan hushscript.Bool.

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() menerima path atau stream yang terbuka; stream yang tidak dapat di-seek memerlukan opsi size dan duration_seconds. Opsi memakai kunci array snake_case, sedangkan hasilnya memakai properti camelCase. $hs->balance(), $hs->transcripts()->list(), dan $hs->buy('300min', true) mencakup saldo, daftar transkrip, dan pembelian. Untuk Laravel, ikat satu Client di service provider dan jalankan transkripsi dalam job antrean dengan opsi idempotency_key yang stabil.

CLI

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

CLI mengambil token dari --token, lalu HUSHSCRIPT_TOKEN, lalu token yang disimpan hushscript login. login meminta token tanpa menampilkannya dan menyimpannya di file yang hanya dapat dibaca pengguna Anda; hushscript logout menghapusnya. Di CI, pilih variabel lingkungan.

--json mencetak satu dokumen JSON di stdout dan tidak ada yang lain, serta mengubah stderr menjadi JSON Lines. Kode keluarnya 0 jika berhasil, 1 jika API atau SDK melaporkan error, 2 untuk kesalahan penggunaan (tidak ada yang dikirim), dan 130 jika proses diinterupsi.

File yang didukung

MP3, M4A, MP4 dan MOV (trek audio video yang dipakai), WAV, FLAC, serta OGG dengan Vorbis atau Opus, dari 15 detik sampai 10 jam. SDK memeriksa format dari byte file dan memeriksa durasinya sebelum ada menit yang ditahan. SDK tidak mengonversi media, jadi konversikan dulu format lainnya:

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

Error

Setiap error yang dimunculkan SDK termasuk dalam satu keluarga, sehingga satu catch mencakup semuanya: HushscriptError di TypeScript dan Python, *hushscript.Error di Go, dan HushscriptException di PHP. Sebuah error membawa code berupa slug seperti insufficient_balance, kode numeriknya, status HTTP, pesan, hint yang menjelaskan langkah berikutnya, detail, dan retryAfter (di PHP slug-nya errorCode; di Python retryAfter ditulis retry_after).

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 berarti SDK menolak file sebelum ada kredit yang ditahan. Apakah saldo Anda cukup untuk sebuah file adalah keputusan server: 402 muncul saat unggahan dibuat, sebelum ada bagian yang dikirim.

Penagihan dan percobaan ulang

Setiap unggahan dan setiap pembelian membawa kunci idempotensi, dan percobaan ulang memakai kunci yang sama, sehingga panggilan yang diulang memutar ulang panggilan pertama dan tidak memulai yang kedua.

buy() menagih kartu default Anda yang tersimpan. Pembelian dari kode nonaktif sampai tiga sakelar mengizinkannya: token memiliki scope billing, token memiliki “Let this token buy minutes” yang diaktifkan, dan “Let connected apps buy minutes” aktif untuk akun. Jika salah satunya tidak ada, panggilan gagal dengan pat_scope_missing. Tampilkan pemberitahuan tanpa pengembalian dana kepada pembeli Anda sebelum memanggilnya.

Pembelian diulang paling banyak satu kali, saat terjadi error jaringan, 502, atau 503, dengan kunci yang sama. Beberapa jawaban membuktikan tidak ada yang ditagih: 400, 402, 404, atau 422, serta 403 dengan kode 4021 (pat_purchase_requires_app, kartu ditolak atau tidak dapat ditagih tanpa Anda) atau 4023 (pat_purchase_requires_authentication, bank ingin mengonfirmasi pembayaran). Setelah 4021 atau 4023, beli paket di aplikasi. Kegagalan lain setelah permintaan dikirim, termasuk 401 atau 429, berarti kartu mungkin sudah ditagih. Error itu membawa kunci idempotensi: ulangi dengan kunci yang sama, dan pembelian tidak pernah terjadi dua kali. Di Python:

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)

Pembelian yang gagal sebelum permintaannya dikirim tidak membawa kunci: tidak ada yang ditagih. Kunci yang Anda berikan sendiri harus terdiri dari 1 sampai 128 karakter dari A-Za-z0-9_-; jangan memakainya ulang untuk paket yang berbeda. CLI mencetak kunci itu saat pembelian mungkin sudah terkirim:

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

Token lanjutan

Begitu sebuah pekerjaan ada, error membawa token lanjutan di samping kunci idempotensi. Penantian yang kehabisan waktu memunculkan WaitTimeoutError beserta tokennya, dan pekerjaan tetap berjalan. Berikan token itu kembali ke resume() untuk melanjutkan tanpa tagihan kedua: pekerjaan yang sudah lewat tahap unggah tidak memerlukan file, dan yang masih mengunggah dilanjutkan dengan file yang sama. Di PHP:

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

Di CLI, Ctrl-C saat transcribe mencetak token lanjutan pekerjaan itu beserta perintah untuk melanjutkannya:

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

Pencatatan log dan penyamaran data

SDK tidak mengirim telemetri; header User-Agent adalah satu-satunya identifikasi klien. Pencatatan log nonaktif secara default. HUSHSCRIPT_LOG=debug menulis satu baris per permintaan ke standard error dengan metode, path, status, dan waktunya, dan tidak pernah header, body, judul, atau teks transkrip.

Token disamarkan dari setiap error, baris log, dan bentuk cetak klien. Pada pesan error, hint, dan penyebab, URL tetap menampilkan host dan path-nya tetapi query string-nya menjadi ?[redacted], sehingga URL unggahan bertanda tangan tidak pernah tercetak. Hasil yang menyerahkan rahasia kepada Anda, seperti claim secret atau token baru, tetap dapat dibaca sebagai field tetapi menampilkan [redacted] saat dicetak; ekspor JSON adalah milik Anda sendiri dan memuat nilainya. CLI membersihkan setiap token yang dikenalnya dari stderr; hasilnya di stdout adalah keluaran Anda dan tidak dibersihkan.

Konfigurasi

Opsi yang diberikan di kode mengalahkan variabel lingkungannya, dan nilai kosong dianggap tidak diatur. Menit berasal dari saldo yang sama dengan aplikasi; paket dan harga ada di halaman harga.