Hushscript開発者向けAPI

Hushscriptは、MCPクライアントを動かすよりHTTPエンドポイントを直接呼び出したい エージェントやスクリプトのために、素のREST呼び出しにも応答します。ここでもすべては あなた自身のアカウント、あなた自身の残高、あなた自身のベアラートークンの範囲内で完結し、 文字起こし自体の料金体系や保存方法が変わることは一切ありません。

クイックスタート

APIにはパーソナルアクセストークンが必要で、それを手に入れる方法は2つあります。人が アカウント内のMCPページのトークンで トークンを作成し、そのスコープを選び、分数の購入を許可するかどうかを決める方法。あるいは、 人を介さずエージェントが自分自身のアカウントを開設する方法です。POST /v1/agent/accounts が有料のサインアップを開始し、POST /v1/agent/accounts/{signup_id}/claimが一度きりの クレームシークレットと引き換えに実際のアカウントと最初のトークンを渡します。いずれの場合も トークンは一度だけ表示され、hsr1:<region>:pat.<id>.<secret>の形をしています。MCP サーバーのOAuthサインインを通じて発行されたトークンもここで使えます。接続 をご覧ください。トークンから他のトークンを発行、一覧表示、取り消すことは決してできず、 1つのアカウントが持てるアクティブなトークンは最大25個です。認証情報のローテーションを 含む、エージェントアカウントの一連の流れは自動運用の解説をご覧ください。

トークンを手に入れたら、直接APIを呼び出します。

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

これは秒単位の残高、実行中のジョブによって保留されている秒数、クレジットの有効期限、 カードが保存されているかどうか、データリージョン、そして受け入れ制限 （max_active_jobs、max_daily_seconds、および現在の使用量）を返します。新規 アカウントは残高ゼロから始まります。POST /v1/uploadsはカードではなく残高を確認する ため、分数がなければ3001 insufficient_balanceが返ります。残高が入るのはカード経由 です。アプリ内での一度きりのカード認証が無料30分を解放し、パックは保存済みのカードに 対して購入されるためです。

エンドツーエンドの自動化

アカウントが存在した後は、そのアカウントをアプリ内で人が開設した場合でも、エージェント が/v1/agent/accountsを通じて開設した場合でも（自動運用参照）、すべて 人を介さずに実行できます。唯一残るブラウザでの操作はエージェント自身が行うこともできます。

1. アカウントを読み取る。 GET /v1/account。card_on_fileがfalseの場合は、先に カードを保存してください。

2. カードを一度だけ保存する。 POST /v1/billing/setup-sessionはcheckout_url、 session_id、expires_atを返します。

   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を開き、Stripeのホスト型ページを完了させてください。 何も課金されず、Hushscriptがカード情報を目にすることもありません。その後 GET /v1/billing/cardsがそのカードをidとともに一覧表示します。アカウントが複数の カードを保持している場合、POST /v1/billing/cards/defaultでデフォルトを切り替え られます。

3. 分数を購入する。 GET /v1/billing/packsはid、seconds、amount、 currencyとともに5つのパックを一覧表示します。

   curl https://api.hushscript.com/v1/billing/packs \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   POST /v1/billing/purchaseにpack、quick_payment_method_id（保存済みカードの id）、idempotency_keyを添えて呼び出すと、オフセッションでカードに請求し、新しい balance_secondsを返します。

   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 }

   これにはトークンにbillingスコープがあることと、アカウントで課金が有効になって いることが必要です。カードidのないボディや拒否されたカードは 4021 pat_purchase_requires_appで拒否され、カード発行会社が本人確認を求めるカード は4023 pat_purchase_requires_authenticationで拒否されます。いずれの場合も、 誰も完了できないページが開くことはありません。

4. アップロードする。 POST /v1/uploadsにsize_bytes、duration_seconds （15秒から10時間まで）、任意のtitle、transcription_options、 idempotency_keyを添えて呼び出します。

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

   クレジットの保留を行い、job_idと署名付きパートURLの最初のページを返します。

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

   各パートをそれぞれのURLにPUTします（デフォルトでは32 MiB単位のパートで、最後の 1つだけ小さくなります）。

   curl -X PUT "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." \
     --data-binary @part-01.bin

   続きのページはGET /v1/uploads/{job}/part-urls?start=<n>から取得し、長い転送の 途中では20分のアイドルタイムアウトに十分余裕を持って POST /v1/uploads/{job}/heartbeatを呼び出してください。署名付きURLが使えない場合 や、あるパートが失敗した場合は、PUT /v1/uploads/{job}/parts/{n}がそのパートの バイト列を代わりにAPI経由で送ります。PUTを繰り返すとそのパートを置き換える だけなので、再試行しても安全です。対応するのは音声のみです。mp3、m4a、wav、 flac、ogg、opusのいずれかで、最大5 GB、サーバー側で内容を検査します。動画を アップロードする前に音声トラックを抽出してください。

5. 開始して待つ。 署名付きURLに送信したすべてのパートのnとetagを添えて POST /v1/uploads/{job}/completeを呼び出します（すべてのパートがAPI経由だった 場合はpartsを省略してください）。

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

   そのうえでGET /v1/jobs/{id}をポーリングします。stateはuploading、 queued、processingを経てdoneまたはfailedに移り、完了したジョブには transcript_idが付きます。

   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. 結果を読み取る。 GET /v1/transcripts/{id}はメタデータと本文全体を、話者名、 検出された言語、タグ、自動削除日とともに返します。

   curl https://api.hushscript.com/v1/transcripts/trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   GET /v1/transcriptsは一覧をページ分けして返します。

文字起こしオプションはアプリのものとまったく同じです。language_codeまたは自動検出、 speaker_detection、medical_mode（language_codeがen、es、fr、deの いずれかである必要があり、+100%で課金）、translation_targets（言語ごとに+25%）、 multichannel、keyterms_prompt、自由記述のprompt、そして GET /v1/transcription-contextが一覧表示する保存済みのdictionary_idsと prompt_preset_idです。

アカウントの一部は今のところMCP専用です。リンクからのインポート、トランスクリプト の編集・削除、Insights、エクスポート、辞書とプロンプトプリセットの保存、アカウント 設定には、まだ/v1/ルートがありません。これらはすべてMCPサーバーが同じ トークンでカバーします。

認証

すべての/v1/呼び出しはAuthorizationヘッダーにベアラートークンを含み、MCPサーバー が使うのと同じスコープと照合されます。

トークンのスコープの範囲外の呼び出しは、403でpat_scope_missingとなって失敗します。 billingスコープも、アカウント所有者がアプリ内でそのアカウントの課金を有効にする までは無効なままです。そのスイッチがオフのアカウントに対する課金呼び出しは同じ pat_scope_missingで失敗し、トークンを再発行してもこれは解消されません。トークン からトークンを作成、一覧表示、取り消すことはできず、1つのアカウントが持てる アクティブなトークンは最大25個です。

エンドポイント

現在稼働しているものは、それぞれ表示されたスコープによって制限されています。

/v1/agent/accountsはまだトークンのないヘッドレスなサインアップを開始し、 /v1/agent/accounts/{signup_id}/claimは支払い済みのサインアップを実際のアカウント と最初のトークンに変え、/v1/agent/credentials/rotateは呼び出し元のトークンの後継 を発行してそれを失効させ、アカウント上の他の認証情報には一切触れません。この3つ すべてを一気通貫で扱う流れは自動運用の解説をご覧ください。

すべての一覧系エンドポイントはlimitと不透明なcursorを受け取り、最後のページ ではnullになるnext_cursorを返します。カーソルは変更せずにそのまま渡してください。 位置情報がエンコードされているため、呼び出しの間に新しい行が追加されても、ページが 飛ばされたり重複したりすることはありません。

すべての操作についてパラメータとレスポンススキーマまで含む完全かつ最新の定義は、 OpenAPIドキュメントにあります。この表 よりもそちらを正とみなしてください。スコープを問わずどのベアラートークンにも提供 されるため、クライアントはすでに持っている認証情報でこれを取得できます。

MCPインターフェース

生のHTTPよりツールの方がよいですか。MCPサーバーは、REST経由ではなくすでに MCPを話すクライアントのために、これらのエンドポイントの代わりに同じアカウントを 51個のツールの背後に置いています。

制限

トークンを使ったリクエストは1トークンあたり1分間に1,200回に制限されています。 POST /v1/billing/setup-sessionとPOST /v1/billing/purchaseは、実際に行う Stripe呼び出しよりも手前で、1アカウントあたり1分間に60回というより厳しい枠を 共有します。拒否されたリクエストには、待機時間を秒数で示すRetry-Afterヘッダー 付きで429 rate_limitedが返ります。その秒数だけ待ってから再試行してください。 アップロードは5 GBと10時間が上限で、最小は15秒、アカウント自身の受け入れ制限 （max_active_jobs、max_daily_seconds）はGET /v1/accountで確認できます。

サンドボックス

ドライランモードはありません。すべての/v1/呼び出しは実際のアカウントに対して 実行され、分数の購入は実際の金額を消費します。

エラー

エラーは、以下に示すHTTPステータスで、安定した数値のcodeとerrorスラッグを持つ JSONボディです。/v1/のエラーボディは固定された投影で、error、code、そして 決まった一連の詳細キーのみを持ちます。/apiのエラー形状は固定されておらず、より 多くの情報を持つことがあります。自動化された呼び出し元が処理すべきコードは次の とおりです。

OpenAPIドキュメントには各操作が返しうる正確なコードが記載されており、MCPサーバー はhushscript://error-codesリソースとしてカタログ全体を公開しています。