自動運用

かつてHushscriptアカウントの開設には、少なくとも一度は人の手が必要でした。しかし それがすべてではなくなりました。支払いを先に済ませるフローにより、エージェントは 自分自身のアカウントを開設し、資金を入れ、運用でき、人であるアカウント所有者は どの段階にも存在しません。/developersと/mcpは、このアカウントがその後使う 2つのインターフェースを文書化しています。このページは、そのアカウントを手に 入れるまでの手順を説明します。

サインアップ

POST /v1/agent/accountsはヘッドレスなサインアップを開始します。まだアカウントは なく、クッキーもトークンもなく、あるのは保留中の購入だけです。

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-08-01",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_emailは領収書と通知のためのものであり、ログインには使いません。 pack_idは45min、300min、900min、1800min、6000minのいずれかです。 amountやcurrencyを自分で送ることはありません。どちらもサーバー側でパックから 導出されます。サインアップ時に購入できるのは最も小さい2つのパック、45minと 300minだけです。それより大きいpack_idは拒否され、拒否のレスポンスには details.allowed_packsとして現在このアカウントが購入できるパックの一覧が 含まれるため、呼び出し側は推測せずに再試行できます。それ以外のパックは購入量では なく経過時間によって解放されます。詳しくは下記の新規アカウントが購入できるもの をご覧ください。 accept_terms_versionはサーバーが現在持つポリシーバージョンと正確に一致する必要が あり、一致しない場合はpolicy_version_staleで失敗し、そのボディに現在の値が 示されます。任意のdata_regionヒントは、あなたのネットワークの所在地がすでに 示している地域と一致する場合にのみ採用されます。任意のdry_run: trueは、Stripe セッションも課金も発生させずにすべてを検証します。この場合のsignup_idには dry_という接頭辞が付き、クレームすることは決してできません。

claim_secretはこのレスポンスで一度だけ表示されます。Hushscriptはそのハッシュのみを 保存します。クレーム呼び出しの前にこれを失うと、サインアップ自体を失うことに なります。クレームシークレットを復旧する手段はなく、エスクローされた支払いは 下記のスイープによって払い戻されるだけで、照会によって取り戻せるものでは ありません。

自分のブラウザでチェックアウトを完了する

checkout_urlはStripeのホスト型Checkoutページです。この一連の流れ全体の中で ブラウザを必要とする唯一のステップですが、それが人のブラウザである必要はありません。 エージェントは自前の自動化でそれを操作できます（カード情報を入力し、送信し、 リダイレクトに従う）。いずれの場合もHushscriptがカード情報を目にすることは なく、それはStripeが扱います。完了させてからクレームするまでの猶予は30分、 上記のexpires_atです。

支払いは済んだもののクレームされなかったサインアップは、1時間ごとのスイープに よって自動的に払い戻されます。おおむね、その30分の猶予が終わってから1時間ほど 後です。分数はクレーム時にのみ残高へ付与されるため、クレームされなかった サインアップには消費すべき分数がそもそも存在せず、払い戻しは全額になります。

アカウントをクレームする

POST /v1/agent/accounts/{signup_id}/claimは、支払い済みで未クレームの サインアップを、1回の呼び出しで実際のアカウントに変えます。

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

クレームは一度きりです。1つのアカウントだけを作成し、その背後には合成された、 解決不能なログインアイデンティティを持たせ、リクエストが再試行されても購入済みの パックを一度だけ付与し、PATを一度だけ発行します。それが上記のpatの値で、 これも一度だけ表示されます。

間違ったシークレット、存在しないsignup_id、すでにクレーム済みのサインアップ、 払い戻し済みのサインアップ、期限切れのサインアップは、すべて同一の agent_claim_invalidエラーを返します。レスポンスから呼び出し側がこれらを 区別できないのは意図的な設計です。シークレット自体が正しいことが確認できて 初めて支払い状態が問題になり、まだ確定していないCheckoutセッションの場合は 代わりにwrong_stateが返ります。

上記のbalance_secondsが開始時点の残高のすべてです。エージェントアカウントには ウェルカムボーナスもなく、人の最初のアカウントのようなカード認証による無料分数も ありません。購入したパック以外は何もない状態から始まります。これは欠落では なく意図的な仕様です。すでにアカウントが存在する前に支払いは済んでいるからです。

さらに分数を購入する

ここから先、このアカウントは他のアカウントと同じ/v1/インターフェース上で /developersがすべて文書化しているとおりに振る舞います。

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

これにはbillingスコープが必要で、上記のクレームのレスポンスですでに付与 されています。また、カード保存ルートと同じ、1アカウントあたり1分間に60回という より厳しい制限を共有します。これはいずれの呼び出しが行うStripe呼び出しよりも 手前で適用されます。

新規アカウントが購入できるもの

パックのサイズは、決済済みの支払いの経過時間によって解放されるのであって、 アカウントがどれだけ使ったかによるものではありません。ある購入が次の段階に カウントされるのは、その支払い日から7日間が経過してからだけです。そのため 作ったばかりのアカウントが素早い購入で大きなパックに到達することはできません。

拒否された購入は、闇雲に失敗するのではなく、details.allowed_packsに現在の 一覧を示します。サインアップの呼び出しはこの表の最初の行を適用するため、上記の 説明で300minを購入し、それより大きいものを購入していないのはそのためです。 この段階制とは別に、まだ係争対応期間を経過していない残高が使われる速さには、 24時間の移動累計による消費上限がかかります。

文字起こし

アップロードと文字起こしは、他のどのアカウントとも同じマルチパートのフロー です。

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

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

PUTで各パートをそれぞれの署名付きURLに送り、そのやり方で送ったすべての パートのnとetagを添えて同じジョブの/completeにPOSTします。そのうえで ジョブをポーリングします。

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

認証情報をローテーションする

マシンアカウントにはパスワードも使えるメールボックスもないため、PATが漏洩 したり単に差し替えが必要になったりしても「パスワードを忘れた」という復旧経路が ありません。ローテーションがその経路です。

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

この呼び出しにボディは不要です。後継トークンをアトミックに発行し、そのリクエストを 認証していたトークンを失効させるため、古いPATは次の呼び出しの時点でただちに 失敗するようになります。後継トークンは前任のスコープ、課金権限、名前、クライアント ラベル、有効期限のポリシーをそのまま引き継ぎます。このルートが触れるのは呼び出し 元自身のトークンだけで、アカウント上の他の認証情報を一覧表示したり、発行したり、 取り消したりすることはできません。これはマシンアカウントが持つ唯一の認証情報 復旧経路であり、古いトークンが破棄された後ではなく、その前にローテーションして ください。

エラー

以下の4つはエージェントアカウント固有のもので、人のアカウントでは決して発生 しません。

クレームシークレット自体が確認できた後で、支払いが済んでいないCheckout セッションは、agent_claim_invalidではなくwrong_state（4001）を返します。 完全なカタログはOpenAPIドキュメント にあります。

制限

呼び出しは1分間に1,200回に制限されています。エージェントアカウントの場合、この 上限は個々のトークンではなくアカウントに属します。ローテーションの系譜にある すべての認証情報が同じ枠を使うため、PATをローテーションしても後継トークンに 新しい枠が与えられるわけではありません。2つの課金に関わる書き込み、つまり カードの保存とパックの購入は、1アカウントあたり1分間に60回というより厳しい 制限を共有し、いずれの呼び出しが行うStripe呼び出しよりも手前で適用されます。 上記の24時間の購入上限も同じ方式で、認証情報単位ではなくアカウント単位で カウントされます。

詳しく知る

このページはアカウントのライフサイクル、つまり開設、資金の投入、認証情報を 生かし続けることをカバーしています。アカウントがその後行えることすべてに ついては、完全なOpenAPIドキュメント を含むREST API、または同じアカウントを生のHTTPの代わりに ツール経由で扱うMCPサーバーをご覧ください。