SDK และ CLI ของ Hushscript

SDK ทางการห่อหุ้ม REST API สำหรับโค้ดฝั่งเซิร์ฟเวอร์และสคริปต์ การเรียกครั้งเดียวถอดเสียงไฟล์ได้: อัปโหลดไฟล์บันทึก รองานจนเสร็จ แล้วส่ง ข้อความถอดเสียงกลับมา ระหว่างนั้น SDK จะตรวจไฟล์ก่อนกันนาทีไว้ ลองใหม่เฉพาะ สิ่งที่ลองซ้ำได้อย่างปลอดภัย รักษาการอัปโหลดที่ใช้เวลานานไม่ให้หลุด และแนบ idempotency key ไปกับทุกการอัปโหลดและการซื้อ เพื่อให้การลองใหม่ไม่เรียกเก็บเงินซ้ำ CLI สร้างบน SDK ของ TypeScript และทำสิ่งเดียวกันได้จากเทอร์มินัล

แพ็กเกจ

เวอร์ชันรันไทม์ขั้นต่ำ:

• TypeScript: Node 22 ขึ้นไป Bun 1.2+ และ Deno 2+ ตรวจสอบเฉพาะการนำเข้า แพ็กเกจเท่านั้น ไม่ได้ตรวจพฤติกรรม HTTP
• Python: 3.10 ขึ้นไป
• Go: 1.25 ขึ้นไป
• PHP: 8.2 ขึ้นไป พร้อม ext-json และ ext-mbstring และ ext-curl สำหรับ การอัปโหลดหลายส่วนพร้อมกัน
• CLI: Node 22 ขึ้นไป

SDK ออกแบบมาสำหรับเซิร์ฟเวอร์และสคริปต์ API ไม่รับต้นทางจากเบราว์เซอร์ และโทเคนที่อยู่ในบันเดิลของเบราว์เซอร์ก็คือโทเคนที่รั่วไหล SDK ของ TypeScript จึงปฏิเสธการเริ่มทำงานในที่ที่มี window และ document

รับโทเคน

SDK ทุกตัวและ CLI ยืนยันตัวตนด้วยโทเคนเข้าถึงส่วนบุคคล สร้างโทเคนได้ใต้ สร้างโทเคนใหม่ ใน หน้า MCP ในบัญชี เลือกขอบเขตสิทธิ์ที่โค้ดของคุณต้องใช้ และกำหนดว่าโทเคนจะซื้อนาทีได้หรือไม่ โทเคนจะแสดงเพียงครั้งเดียวและมีรูปแบบ hsr1:<region>:pat.<id>.<secret> ขอบเขตสิทธิ์และวิธีทำงานของโทเคนอยู่ใน หน้า API

SDK จะอ่านโทเคนจาก HUSHSCRIPT_TOKEN เมื่อคุณไม่ได้ส่งโทเคนมาเอง:

export HUSHSCRIPT_TOKEN=hsr1:...

เอเจนต์ยังเปิดบัญชีของตัวเอง ชำระเงินที่หน้าชำระเงินแบบโฮสต์ และรับโทเคนแรกจาก โค้ดได้ด้วย: Hushscript.agent.signup() และ Hushscript.agent.claim() ใน TypeScript, Hushscript.agent_signup() และ Hushscript.agent_claim() ใน Python, AgentSignup และ AgentClaim ใน Go และ Client::agentSignup() และ Client::agentClaim() ใน PHP ขั้นตอนและกฎอยู่ใน การถอดเสียงอัตโนมัติ

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() รับพาธ, Blob, Uint8Array หรือ ReadableStream<Uint8Array> สตรีมต้องระบุ size และ durationSeconds ที่แน่นอน hs.balance() คืนนาทีที่ คุณใช้จ่ายได้ hs.transcripts.list() ไล่ดูข้อความถอดเสียงที่เสร็จแล้วทีละหน้า และ hs.buy("300min", { acknowledgeNoRefund: true }) ซื้อแพ็กเกจนาที ทุกการดำเนินการ ของ /v1 ใช้ได้ผ่าน hs.api เช่นกัน ด้วยการลองใหม่ การหมดเวลา และการปกปิดข้อมูล แบบเดียวกัน

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

ทุกการเรียกมีคู่แบบ asyncio บน AsyncHushscript ด้วยชื่อเดียวกัน transcribe() รับพาธ, bytes หรืออ็อบเจกต์ไฟล์แบบไบนารี อ็อบเจกต์ไฟล์ที่ เลื่อนตำแหน่ง (seek) ไม่ได้ต้องระบุ size และ duration_seconds hs.balance(), hs.transcripts.list() และ hs.buy("300min", acknowledge_no_refund=True) ครอบคลุมยอดคงเหลือ รายการ ข้อความถอดเสียง และการซื้อ

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 รับพาธ, TranscribeReader รับ io.ReaderAt พร้อมขนาดที่แน่นอน และ TranscribeStream รับ reader แบบอ่านไปข้างหน้าอย่างเดียว พร้อมขนาดและ DurationSeconds client.Balance, client.Transcripts.List และ client.Buy ครอบคลุมยอดคงเหลือ รายการข้อความถอดเสียง และการซื้อ ตัวเลือกที่เป็นได้ทั้งปิด เปิด หรือไม่ได้กำหนดคือ *bool สร้างด้วย 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() รับพาธหรือสตรีมที่เปิดอยู่ สตรีมที่เลื่อนตำแหน่ง (seek) ไม่ได้ ต้องระบุตัวเลือก size และ duration_seconds ตัวเลือกใช้คีย์อาร์เรย์แบบ snake_case ส่วนผลลัพธ์ใช้พร็อพเพอร์ตีแบบ camelCase $hs->balance(), $hs->transcripts()->list() และ $hs->buy('300min', true) ครอบคลุมยอดคงเหลือ รายการข้อความถอดเสียง และการซื้อ สำหรับ Laravel ให้ bind Client หนึ่งตัวใน service provider และรันการถอดเสียงในคิวจ็อบที่ใช้ตัวเลือก idempotency_key ค่าคงที่

CLI

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

CLI รับโทเคนจาก --token ก่อน แล้วจึง HUSHSCRIPT_TOKEN แล้วจึงโทเคนที่ hushscript login เก็บไว้ login ขอโทเคนโดยไม่แสดงตัวอักษรที่พิมพ์ และเก็บไว้ใน ไฟล์ที่เฉพาะผู้ใช้ของคุณอ่านได้ hushscript logout ลบไฟล์นั้น ใน CI ควรใช้ ตัวแปรสภาพแวดล้อมมากกว่า

--json พิมพ์เอกสาร JSON เดียวบน stdout และไม่พิมพ์อย่างอื่น และเปลี่ยน stderr เป็น JSON Lines รหัสออกคือ 0 เมื่อสำเร็จ 1 เมื่อ API หรือ SDK รายงาน ข้อผิดพลาด 2 สำหรับข้อผิดพลาดการใช้งาน (ไม่มีอะไรถูกส่ง) และ 130 เมื่อการรัน ถูกขัดจังหวะ

ไฟล์ที่รองรับ

MP3, M4A, MP4 และ MOV (ใช้แทร็กเสียงของวิดีโอ), WAV, FLAC และ OGG ที่เป็น Vorbis หรือ Opus ความยาวตั้งแต่ 15 วินาทีถึง 10 ชั่วโมง SDK ตรวจรูปแบบจากไบต์ ของไฟล์และตรวจความยาวก่อนกันนาทีไว้ SDK ไม่แปลงสื่อ ดังนั้นไฟล์อื่นต้องแปลง ก่อน:

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

ข้อผิดพลาด

ทุกข้อผิดพลาดที่ SDK ยกขึ้นมาอยู่ในตระกูลเดียว จึงใช้ catch เดียวครอบคลุมได้ ทั้งหมด: HushscriptError ใน TypeScript และ Python, *hushscript.Error ใน Go และ HushscriptException ใน PHP ข้อผิดพลาดมี code แบบ slug เช่น insufficient_balance รหัสตัวเลข สถานะ HTTP ข้อความ hint ที่บอกว่าควรทำอะไร ต่อ รายละเอียด และ retryAfter (ใน PHP slug คือ errorCode ส่วนใน Python retryAfter คือ 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 หมายความว่า SDK ปฏิเสธไฟล์ก่อนกันเครดิตไว้ ยอดคงเหลือพอสำหรับ ไฟล์หรือไม่เป็นการตัดสินของเซิร์ฟเวอร์: จะตอบ 402 กลับมาเมื่อสร้างการอัปโหลด ก่อนส่งส่วนใดเลย

การเรียกเก็บเงินและการลองใหม่

ทุกการอัปโหลดและทุกการซื้อแนบ idempotency key และการลองใหม่ใช้คีย์เดิม การเรียก ที่ลองซ้ำจึงเล่นซ้ำครั้งแรกแทนที่จะเริ่มครั้งที่สอง

buy() เรียกเก็บเงินจากบัตรเริ่มต้นที่บันทึกไว้ การซื้อจากโค้ดปิดอยู่จนกว่า สวิตช์สามตัวจะอนุญาต: โทเคนมีขอบเขตสิทธิ์ billing, โทเคนเปิด “อนุญาตให้โทเคนนี้ซื้อนาที” ไว้ และบัญชีเปิด “อนุญาตให้แอปที่เชื่อมต่อซื้อนาที” ไว้ ถ้าขาดข้อใดข้อหนึ่ง การเรียกจะล้มเหลวด้วย pat_scope_missing แสดงประกาศว่าไม่คืนเงินให้ผู้ซื้อของคุณดูก่อนเรียกใช้

การซื้อจะลองใหม่ได้อย่างมากหนึ่งครั้ง เมื่อเกิดข้อผิดพลาดของเครือข่าย, 502 หรือ 503 โดยใช้คีย์เดิม คำตอบบางแบบพิสูจน์ได้ว่ายังไม่มีการเรียกเก็บเงิน: 400, 402, 404 หรือ 422 และ 403 ที่มีรหัส 4021 (pat_purchase_requires_app บัตรถูกปฏิเสธ หรือเรียกเก็บเงินไม่ได้หากไม่มีคุณ) หรือ 4023 (pat_purchase_requires_authentication ธนาคารต้องการยืนยันการชำระเงิน) หลังจาก 4021 หรือ 4023 ให้ซื้อแพ็กเกจนาทีในแอป ความล้มเหลวอื่นใดหลังส่งคำขอไปแล้ว รวมถึง 401 หรือ 429 หมายความว่าบัตรอาจถูกเรียกเก็บเงินไปแล้ว ข้อผิดพลาดนั้น มี idempotency key ติดมาด้วย: ให้ขอใหม่ด้วยคีย์เดิม แล้วการซื้อจะไม่เกิดขึ้นสองครั้ง ใน 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)

การซื้อที่ล้มเหลวก่อนส่งคำขอจะไม่มีคีย์ติดมา: ไม่มีการเรียกเก็บเงิน คีย์ที่คุณส่ง เองต้องยาว 1 ถึง 128 ตัวอักษรจาก A-Za-z0-9_- และห้ามใช้ซ้ำกับแพ็กเกจนาทีอื่น CLI จะพิมพ์คีย์เมื่อการซื้ออาจถูกส่งไปแล้ว:

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

โทเคนสำหรับทำต่อ

เมื่อมีงานแล้ว ข้อผิดพลาดจะมีโทเคนสำหรับทำต่อ (resume token) ติดมาข้าง idempotency key การรอที่หมดเวลาจะยก WaitTimeoutError พร้อมโทเคน และงานยังคงทำงานต่อไป ส่งโทเคนกลับให้ resume() เพื่อทำต่อโดยไม่ถูกเรียกเก็บเงินซ้ำ: งานที่พ้นขั้นอัปโหลด แล้วไม่ต้องใช้ไฟล์ ส่วนงานที่ยังอัปโหลดอยู่จะทำต่อด้วยไฟล์เดิม ใน PHP:

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

ใน CLI การกด Ctrl-C ระหว่าง transcribe จะพิมพ์โทเคนสำหรับทำต่อของงานและ คำสั่งที่ใช้ทำต่อ:

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

การบันทึกล็อกและการปกปิดข้อมูล

SDK ไม่ส่งเทเลเมทรี ส่วนหัว User-Agent เป็นการระบุไคลเอนต์เพียงอย่างเดียว การบันทึกล็อกปิดอยู่โดยค่าเริ่มต้น HUSHSCRIPT_LOG=debug เขียนหนึ่งบรรทัดต่อ คำขอไปยังข้อผิดพลาดมาตรฐาน (standard error) พร้อมเมธอด พาธ สถานะ และเวลาที่ใช้ และไม่เขียนส่วนหัว เนื้อหา ชื่อเรื่อง หรือข้อความถอดเสียงเลย

โทเคนถูกปกปิดจากทุกข้อผิดพลาด บรรทัดล็อก และรูปแบบที่พิมพ์ออกมาของไคลเอนต์ ในข้อความข้อผิดพลาด คำแนะนำ และสาเหตุ URL จะคงโฮสต์และพาธไว้ แต่สตริงคิวรี กลายเป็น ?[redacted] ดังนั้น URL อัปโหลดที่ลงลายเซ็นจะไม่ถูกพิมพ์ ผลลัพธ์ที่ ส่งความลับให้คุณ เช่น claim secret หรือโทเคนใหม่ จะให้อ่านค่าได้ในฟิลด์ แต่แสดง [redacted] เมื่อพิมพ์ ส่วนการส่งออก JSON เป็นของคุณเองและมีค่านั้นอยู่ CLI ล้างทุกโทเคนที่รู้จักออกจาก stderr ส่วนผลลัพธ์บน stdout เป็นเอาต์พุตของคุณและ ไม่ถูกล้าง

การกำหนดค่า

ตัวเลือกที่ส่งในโค้ดมีผลเหนือตัวแปรสภาพแวดล้อมของมัน และค่าว่างถือว่าไม่ได้ กำหนด นาทีมาจากยอดคงเหลือเดียวกับแอป แพ็กเกจและราคาอยู่ใน หน้าราคา