録音した音声の文字起こしAPI

Hushscriptの文字起こしAPIは/v1/で録音した音声を受け付け、スクリプトからジョブの状態をポーリングし、文字起こし結果を取得できます。オンラインで録音を文字起こしするためのAPIであり、ライブストリーミングや音声認識モデルを直接呼び出すエンドポイントではありません。HTTP呼び出しよりもツールを使いたいクライアントには、同じアカウント、残高、ベアラートークンで利用できるMCPサーバーもあります。

APIによる音声・動画の文字起こし

音声の文字起こしAPIは、録音した声など、事前に準備した音声ファイルを受け付けます。STT（speech-to-text）連携では録音ファイルを送信してください。マイク音声のライブストリーミングには対応していません。動画を文字起こしする場合は、音声トラックを含むMP4またはMOVファイルをそのままアップロードしてください。サーバーが音声トラックを読み取り、映像は使用しません。それ以外の動画形式は、先に音声を抽出してください。APIは動画URLを受け付けません。ブラウザでの手順は動画を文字起こしをご覧ください。

クイックスタート

APIにはパーソナルアクセストークンが必要です。取得方法は2つあります。人がアカウント内のMCPページのトークンで作成し、スコープを選び、分数の購入を許可するかどうかを決める方法です。もう1つは、人をアカウントの所有者とせず、エージェントが自分のアカウントを開設する方法です。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": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

レスポンスには、秒単位の残高、実行中のジョブが確保している秒数、credits_expire_at（分数に有効期限がないため常にnull）、カードの保存状況、データリージョン、ジョブの受付上限（max_active_jobs、max_daily_secondsと現在の使用量）が含まれます。1日あたりの上限は、そのアカウントに現在適用されている値です。固定値として実装しないでください。POST /v1/uploadsはカードの有無ではなく利用可能な分数を確認し、不足していれば3001 insufficient_balanceを返します。

文字起こしAPIの無料利用

一般向けの無料APIプランはありませんが、コードを書く前に操作を試せます。公開プレビューでは、サインイン前に1つの録音から最大5分を文字起こしできます。対象の個人アカウントはカード確認後に30分の無料分数を受け取れます。仕組みは料金ページをご覧ください。エージェントが作成したアカウントには初回の無料分数がなく、サインアップ時に購入したパックから利用を開始します。いずれも、APIで全体を処理するにはアカウントと分数が必要です。

一連の操作の自動化

人がアプリで作成したトークンでも、エージェントが有料のサインアップ後に取得したトークンでも、同じ/v1/呼び出しを利用できます（自動文字起こしを参照）。カードを保存するにはブラウザでホスト型Checkoutを完了する必要があり、エージェントが操作してもかまいません。その後のオフセッション購入でも、カード発行会社が本人認証を求めると拒否されることがあります。

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は5つのパックをid、seconds、amount、currencyとともに返します。

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

   matter_codeは最大64文字の自由入力で、ワークスペースに属するトークンでのみ意味を持ちます。そのワークスペースの台帳と利用状況レポートで、ジョブに紐づけて表示されます。案件コードを必須にしているワークスペースでは、指定のないアップロードをorg_matter_code_requiredで拒否します。client_codeは受け付けますが無視されます。クライアントはワークスペース管理者が案件に設定する属性だからです。

   処理に必要な分数を確保し、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で、最後のパートはそれより小さくなります。

   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、mp4またはmov（音声トラックを使用し、映像トラックは使用しません）、wav、flac、ogg、opusで、サーバー側で形式を確認します。それ以外の動画形式は、アップロード前に音声を抽出してください。

5. 処理を開始して待ちます。 POST /v1/uploads/{job}/completeに、署名付きURLへ送信した各パートのnとetagを指定します。すべてのパートを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を指定できます。保存済みのdictionary_idsとprompt_preset_idは、GET /v1/transcription-contextで一覧を取得できます。

一部の操作は引き続きMCPのみで利用できます。リンクからのインポート、文字起こし結果の編集・削除、Insights、エクスポート、辞書とプロンプトプリセットの保存、アカウント設定には、まだ/v1/ルートがありません。MCPサーバーは同じトークンでこれらすべてに対応します。

認証

各/v1/呼び出しはAuthorizationヘッダーにベアラートークンを指定し、MCPサーバーと同じスコープで検証されます。

トークンのスコープ外の呼び出しは、HTTP 403のpat_scope_missingで失敗します。billingスコープも、トークンとアカウントの両方で課金を有効にしないと機能しません。どちらかが無効な課金呼び出しは、同じpat_scope_missingで失敗します。トークンを再発行しても、アカウント側の課金は有効になりません。トークンからトークンを作成、一覧表示、取り消すことはできず、アクティブなトークンは1アカウントにつき最大25個です。

この11のスコープは呼び出し元が選択できます。pat:rotateは別のスコープで、エージェントアカウントの最初のトークンと、ローテーションで発行された後継トークンに付与されます。自分自身の置き換えのみを許可し、他のトークンは管理できません。アプリでトークンを作成する際には選択できません。

エンドポイント

本番のOpenAPIドキュメントには、37のパスに対する38のメソッド・パス操作が記載されています。以下の各操作には、表に示すスコープが必要です。

/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に対応するクライアント向けに、同じアカウントの操作を56のツールで提供します。公開するのは、接続したトークンのスコープで許可されたツールだけです。

利用上限

人のアカウントのトークンによるリクエストは、トークンごとに1分あたり1,200回までです。エージェントアカウントでは、ローテーションしたトークンも含め、アカウント全体でこの上限を共有します。PATでStripeを呼び出す課金ルートには、アカウントごとに1分あたり60回という別の上限があります。対象は設定セッション、購入、デフォルトカードの変更、カードの削除、カード一覧のキャッシュミスです。通常のレート制限では429 rate_limitedと、待機秒数を示すRetry-Afterを返します。指定された時間を待ってから再試行してください。エージェントアカウントの購入と、人のアカウントのPATによる購入には、アカウントごとに直近24時間で3回までという共通の試行上限があります。エージェントのサインアップ時の購入も、試行枠を確保した後のカード拒否やエラーも数に含みます。人がブラウザセッションで行う購入は対象外です。試行上限による拒否は、HTTP 429と4038 agent_purchase_capped、Retry-Afterを返します。録音は15秒〜10時間に対応します。GET /v1/accountは現在の受付上限（max_active_jobs、max_daily_seconds）を返します。

サンドボックス

一般的な文字起こし用サンドボックスはありません。通常の/v1/呼び出しは実際のアカウントを操作し、購入には実際の支払いが発生します。例外はサインアップの検証です。POST /v1/agent/accountsはdry_run: trueを受け付け、アカウントの取得に使えないdry_形式のサインアップIDを返します。Stripeセッションもアカウントも作成しません。

エラー

エラーは、以下のHTTPステータスとともに、固定の数値codeとerrorスラッグを含むJSONボディで返します。/v1/のエラーボディは、error、code、固定された詳細キーの集合で構成され、形式は固定です。/apiのエラー形式は固定ではなく、追加の情報を含むことがあります。自動化する呼び出し元が処理すべきコードは以下のとおりです。

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