HTTP API リファレンス

この API は、あなたのサーバー側のコードから呼び、セッションを探す・短期のセッショントークンを発行する・文字起こしを書き出す・利用量を見るために使います。ベース URL は https://moji.kaitoranma.com です。機械可読な版は openapi.yaml（OpenAPI 3.1）にあります。文字おこしくんが文字起こしの開始と終了をあなたの URL に知らせる仕組み（Webhook）は、Webhook リファレンスにあります。

エンドポイント一覧

認証

Authorization: Bearer <資格情報>

API キーは、ボットを入れた Discord サーバーの管理者が管理画面で作ります（クイックスタート）。作るときに、管理者はスコープと期限を選びます。管理画面は作ったキーをその 1 度だけ表示します。キーの形は mjk_live_ + 32 文字の乱数 + 6 文字のチェックサム（base62）で、シークレットスキャナーは mjk_live_[0-9A-Za-z]{38} でキーを見つけられます。

• キーが無いか、無効か、失効していれば、文字おこしくんは 401 unauthorized を返します（WWW-Authenticate: Bearer realm="mojiokoshi" 付き）。
• スコープが足りなければ、文字おこしくんは 403 insufficient_scope を返します（requiredScope と WWW-Authenticate: Bearer …, error="insufficient_scope" 付き）。
• API キーで別のテナントのセッションを指定すると、文字おこしくんは 404 session_not_found を返します（存在を漏らさないため）。

API キーで発行するセッショントークンの有効期間はレート制限と上限、期限の後の取り直しは再接続とエラーの扱いにあります。

エラー（problem details）

エラーの本文は RFC 9457 の problem details（Content-Type: application/problem+json; charset=utf-8）です。code で分岐してください。 error と message は、以前の形との後方互換のためのメンバーで、code / detail と同じ値を持ちます。

{
  "type": "https://moji.kaitoranma.com/docs/errors/#rate_limited",
  "title": "要求が多すぎます",
  "status": 429,
  "detail": "要求が多すぎます。しばらくしてから、要求をやり直してください",
  "code": "rate_limited",
  "error": "rate_limited",
  "message": "要求が多すぎます。しばらくしてから、要求をやり直してください",
  "retryAfterSeconds": 1
}

• 429・5xx を受け取ったら、待ってから要求をやり直してください（Retry-After があれば、その秒数だけ待ちます）。それ以外の 4xx を受け取ったら、要求を直すまでやり直さないでください。
• コードごとの意味と対処はエラーコードにあります。

共通の決まり

• パスはすべて /v1 から始まります（/healthz を除く）。
• あなたのサーバー側のコードから呼んでください。 文字おこしくんの HTTP API は CORS のヘッダーを付けていないので、ブラウザ（別のオリジン）からはこの API を呼べません。ブラウザの画面では WebSocket（Subscribe）を使い、トークンはあなたのサーバーで発行してブラウザに渡します。
• 要求の本文は JSON（UTF-8）にし、16 KiB までにします（超えると、文字おこしくんは 413 payload_too_large を返します）。JSON の応答には Content-Type: application/json; charset=utf-8 が付きます。
• 時刻はすべてエポックミリ秒の数値（UTC）で表します。日付（from / to）は UTC の YYYY-MM-DD で表します。利用量の「1 日」は UTC の暦日で、日本時間の 9:00 に切り替わります。
• API の応答には Cache-Control: no-store が付きます。
• 互換性: 応答のフィールド・エラーコード・任意の引数は予告なく増えることがあります。知らないフィールドは無視し、知らないコードはステータスで扱ってください。文字おこしくんは、互換性の無い変更をするときに、パスの /v1 を上げます（変更履歴）。

レート制限

文字おこしくんは、API キーでの要求を、API キーごとに 1 分あたり 120 要求までに制限します。認証の無い要求・セッショントークンでの書き出しの要求・認証に失敗した要求は、送信元 IP ごとに 1 分あたり 120 要求までに制限します。制限はトークンバケットの方式で、使える要求の数は、毎秒 2 ずつ戻り、最大 120 までたまります。レート制限の対象の応答には、成功・失敗のどちらにも、IETF の草案（draft-ietf-httpapi-ratelimit-headers）の形のヘッダーが付きます。

RateLimit-Policy: "api-key";q=120;w=60
RateLimit: "api-key";r=117;t=2

• q はためられる要求の数を、w は空から満杯に戻るまでの秒数を、r は残りの要求数を、t は満杯に戻るまでの秒数を表します。ポリシー名は "api-key" か "ip" です。
• レート制限を超えると、文字おこしくんは 429 rate_limited と Retry-After（秒）を返します。Retry-After の秒数だけ待ってから、要求をやり直してください。
• 書き出し（/transcript）は文字おこしくんの API 全体で同時に 2 本までです。混んでいると、文字おこしくんは 429 rate_limited（Retry-After: 5）を返します。
• ほかの上限はレート制限と上限にあります。

Idempotency-Key（やり直しの安全）

POST /v1/sessions・POST /v1/sessions/{sessionId}/tokens・POST /v1/sessions/{sessionId}/downloads は Idempotency-Key ヘッダーを受け付けます。ネットワークの失敗でやり直すときに同じキーを使うと、文字おこしくんはセッションやトークンを二重に作りません。

ページ送り（cursor）

GET /v1/sessions は新しい順に limit 件（既定 20、最大 100）を返し、続きがあれば nextCursor を付けます。次のページは ?cursor=<nextCursor> で取ります。カーソルは不透明な文字列なので、中身に依存しないでください。ページの間にセッションが増えても、重複も抜けも出ません。nextCursor が無ければ最後のページです。

ヘルスチェック（Health）

クライアントは、この操作で文字おこしくんが動いているかを確かめる。

文字おこしくんが動いているかを確かめる（GET /healthz）

この操作は文字おこしくんが動いているかを返す。この操作には認証もレート制限も無い。

• 認証: なし
• operationId: getHealth

応答 200:

{
  "ok": true
}

curl -sS "$BASE/healthz"

セッションとトークン（Sessions）

クライアントは、API キーで、セッションの一覧・状態・作成・終了と、セッショントークンの発行を扱う。

セッションを一覧する（GET /v1/sessions）

文字おこしくんは、セッションを新しい順（createdAt の降順、同時刻は sessionId の降順）に返す。続きがあれば応答に nextCursor が付くので、次のページを取るときは、その値を cursor に渡す（キーセットのカーソルなので、ページの間にセッションが増えても、重複も抜けも出ない）。文字おこしくんは、API キーのテナント（Discord サーバー）のセッションだけを返す。

• 認証: API キー（transcripts:read）
• operationId: listSessions

応答 200:

{
  "sessions": [
    {
      "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
      "label": "#雑談 VC",
      "externalRef": "discord:111111111111111111:222222222222222222",
      "tenantId": "111111111111111111",
      "createdAt": 1790350826814,
      "live": true,
      "audioSeconds": 312.5
    },
    {
      "sessionId": "7d1e2f3a-8b9c-4d0e-a1b2-c3d4e5f60718",
      "label": "#雑談 VC",
      "externalRef": "discord:111111111111111111:222222222222222222",
      "tenantId": "111111111111111111",
      "createdAt": 1790264426814,
      "endedAt": 1790268026814,
      "live": false,
      "audioSeconds": 1234.567,
      "retainUntil": 1792860026814
    }
  ],
  "nextCursor": "eyJjIjoxNzkwMzUwODI2ODE0LCJpIjoiMGYwYzNjMWUtNWI3YS00ZDJlLTljNjEtM2YyZDhhNGI3ZTEwIn0"
}

curl -sS "$BASE/v1/sessions?status=active&limit=5" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

セッションを作る（POST /v1/sessions）

クライアントは、この操作で、自分で音声を送る（Ingest）ためのセッションを作る。文字おこしくんは、作ったセッションをすぐ稼働させ、Ingest の接続を待つ（30 分つながらなければ、セッションは自動で終わる）。クライアントは、応答の ingest.token を音声の送り手に、subscribe.token / viewerUrl / overlayUrl を見る側に渡す。reuseActive: true なら、文字おこしくんは同じ externalRef の稼働中のセッションを使い回す（200）。テナントの今日の利用量が上限に達していれば、文字おこしくんは 429 quota_exceeded を返す（公式の文字おこしくんには、1 日の上限は無い）。文字おこしくんは、API キーで作ったセッションで開いているトラックを、全部の API キー（ほかの利用者のキーを含む）で合わせて数え、同時に 20 本までにする。API キーで作ったセッションのトラックの合計が 20 本に達しているときは、文字おこしくんは、新しい track_open を、Ingest の track_limit_exceeded で断る。公式の Discord ボットが使っているセッションには、音声を送らないこと（1 セッションの Ingest は 1 本だけ）。

• 認証: API キー（ingest:write）
• operationId: createSession

要求の本文（JSON）:

{
  "label": "会議室マイク",
  "externalRef": "my-app:room-42",
  "reuseActive": true
}

応答 200:

{
  "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
  "label": "会議室マイク",
  "externalRef": "my-app:room-42",
  "tenantId": "111111111111111111",
  "createdAt": 1790350826814,
  "reused": true,
  "ingest": {
    "url": "wss://moji.kaitoranma.com/v1/ingest",
    "token": "eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJpbmdlc3Q6d3JpdGUifQ.Zr8Tq1wE5yU3iO7pA9sD2fG4hJ6kL0zX1cV3bN5mQ7w"
  },
  "subscribe": {
    "url": "wss://moji.kaitoranma.com/v1/subscribe",
    "token": "eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OnJlYWQifQ.Hq3Jx9mK2vLw8ZtN4pR7sYc1dF5gH6jK0lM2nB3vC4x"
  },
  "viewerUrl": "https://moji.kaitoranma.com/#token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OnJlYWQifQ.Hq3Jx9mK2vLw8ZtN4pR7sYc1dF5gH6jK0lM2nB3vC4x",
  "overlayUrl": "https://moji.kaitoranma.com/#token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OnJlYWQifQ.Hq3Jx9mK2vLw8ZtN4pR7sYc1dF5gH6jK0lM2nB3vC4x&overlay=1",
  "expiresAt": 1790354426000
}

curl -sS -X POST "$BASE/v1/sessions" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label":"会議室マイク","externalRef":"my-app:room-42","reuseActive":true}'

セッションの状態を見る（GET /v1/sessions/{sessionId}）

文字おこしくんは、セッションの状態と利用量を返す。API キーで別のテナントのセッションを指定すると、文字おこしくんは 404 を返す（存在を漏らさない）。

• 認証: API キー（transcripts:read）
• operationId: getSession

応答 200:

{
  "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
  "label": "#雑談 VC",
  "externalRef": "discord:111111111111111111:222222222222222222",
  "tenantId": "111111111111111111",
  "createdAt": 1790350826814,
  "endedAt": 1790354426814,
  "live": false,
  "ingestConnected": false,
  "viewers": 0,
  "audioSeconds": 1234.567,
  "retainUntil": 1792946426814
}

curl -sS "$BASE/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

セッションを削除する（DELETE /v1/sessions/{sessionId}）

文字おこしくんは、終わったセッションの記録（文字起こし・話者・セッションの利用量の内訳）を消す。消した記録は戻らない。文字おこしくんが応答を返した時点で、セッションは一覧・状態・書き出しから消える。文字おこしくんは、記録の本文もすぐに裏で消し切る（ファイルにも残さない）。文字おこしくんは、テナントの利用量の累計を減らさない。そのセッションの Webhook の出来事（session.ended など）をまだ送り終えていなければ、文字おこしくんはその出来事を送らない。稼働中か終了の途中のセッションには、文字おこしくんは 409 session_active を返す（先に POST /v1/sessions/{sessionId}/end でセッションを終える）。

• 認証: API キー（transcripts:delete）
• operationId: deleteSession

curl -sS -X DELETE "$BASE/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

セッションを終える（POST /v1/sessions/{sessionId}/end）

文字おこしくんは、音声認識に送った音声の結果を最後まで受け取ってから（最大約 5 秒）、Subscribe でつないでいる全員に session_ended を送り、Ingest の接続も切る。文字おこしくんは、Ingest の接続を切った後に応答を返す。この操作は冪等で、文字おこしくんは、終了済みのセッションには最初の endedAt を返す。要求に本文は要らない。

• 認証: API キー（ingest:write）
• operationId: endSession

応答 200:

{
  "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
  "endedAt": 1790354426814
}

curl -sS -X POST "$BASE/v1/sessions/$SESSION_ID/end" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

セッショントークンを発行する（POST /v1/sessions/{sessionId}/tokens）

文字おこしくんは、ブラウザ・OBS・ボットに渡す短期のセッショントークンを発行する。transcript:read のトークンは Subscribe（/v1/subscribe の hello）と書き出しに、ingest:write のトークンは Ingest に使う。API キーで発行するには、transcript:read には transcripts:read のスコープが、ingest:write には ingest:write のスコープが要る。有効期間を指定しなければ 3600 秒になる。最大は 86400 秒である。文字おこしくんには、トークンを 1 つずつ失効させる仕組みが無い。クライアントは、有効期間を短くし、期限が近づいたら新しいトークンを取り直す。終わったセッションにも、クライアントは transcript:read のトークンを発行できる（書き出しと過去のログの表示に使う）。終わったセッションの ingest:write のトークンを要求すると、文字おこしくんは 409 session_ended を返す。

• 認証: API キー（transcripts:read） / API キー（ingest:write）
• operationId: createSessionToken

要求の本文（JSON）:

{
  "scope": "transcript:read",
  "ttlSeconds": 3600
}

応答 200:

{
  "token": "eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OnJlYWQifQ.Hq3Jx9mK2vLw8ZtN4pR7sYc1dF5gH6jK0lM2nB3vC4x",
  "expiresAt": 1790354426000
}

curl -sS -X POST "$BASE/v1/sessions/$SESSION_ID/tokens" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"scope":"transcript:read","ttlSeconds":3600}'

書き出し（Transcripts）

クライアントは、API キーか transcript:read のセッショントークンで、文字起こしを書き出す。クライアントは、API キーで書き出しのリンクと記録を ChatGPT に渡すリンクを作り、資格情報を持たない人にリンクを渡すこともできる。

文字起こしを書き出す（GET /v1/sessions/{sessionId}/transcript）

文字おこしくんは、発話ごとの最新の改訂（final / refined。認識途中は含まない）を startedAt の順に返す。稼働中のセッションでは、その時点までの発話を返す。文字おこしくんは応答を少しずつ流す（chunked）。文字おこしくんの API 全体で同時に流せる書き出しは 2 本までで、超えると、文字おこしくんは 429 rate_limited（Retry-After: 5）を返す。HEAD では、文字おこしくんはヘッダーだけを返す。文字おこしくんは、セッションの終了から保持期間が過ぎた記録を消し、消した記録の要求には 404 を返す。書き出しのリンク（POST /v1/sessions/{sessionId}/downloads が作る）は transcript:download のトークンをクエリの token に載せて、この操作を呼ぶ。リンクで要求すると、文字おこしくんは、Content-Disposition: attachment（ファイル名つき）・Referrer-Policy: no-referrer・X-Robots-Tag: noindex を付ける。リンクに disposition=inline を付けると、文字おこしくんは、Content-Disposition: inline にし、X-Content-Type-Options: nosniff と Content-Security-Policy: default-src 'none'; sandbox も付ける（ブラウザは、応答をページとして表示する）。クエリの token には transcript:download のトークンだけを使える（transcript:read のトークンは使えない）。クライアントは、クエリの token と Authorization ヘッダーを同時に付けない（同時に付けると、文字おこしくんは 400 を返す）。

• 認証: API キー（transcripts:read） / セッショントークン（transcript:read） / クエリの token（transcript:download）
• operationId: exportTranscript

応答 200:

{
  "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
  "label": "#雑談 VC",
  "speakers": [
    {
      "speakerId": "discord:333333333333333333",
      "displayName": "たろう",
      "avatarUrl": "https://cdn.discordapp.com/avatars/333333333333333333/a.png"
    },
    {
      "speakerId": "discord:444444444444444444",
      "displayName": "はなこ"
    }
  ],
  "utterances": [
    {
      "utteranceId": "5e0b8a54-3f21-4c7a-9d0e-7b6a5c4d3e21",
      "trackId": "discord:333333333333333333",
      "speakerId": "discord:333333333333333333",
      "speakerName": "たろう",
      "stage": "refined",
      "text": "こんにちは、今日はよろしくお願いします。",
      "rawText": "こんにちは今日はよろしくお願いします",
      "startedAt": 1790350831814
    },
    {
      "utteranceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "trackId": "discord:444444444444444444",
      "speakerId": "discord:444444444444444444",
      "speakerName": "はなこ",
      "stage": "final",
      "text": "よろしくお願いします",
      "rawText": "よろしくお願いします",
      "startedAt": 1790350835814
    }
  ]
}

format=text の応答:

[21:03:05] たろう: こんにちは、今日はよろしくお願いします。
[21:03:09] はなこ: よろしくお願いします

format=csv の応答（先頭の BOM は省いて示す）:

日時,話者,発言
2026-09-26 21:03:05,たろう,こんにちは、今日はよろしくお願いします。
2026-09-26 21:03:09,はなこ,よろしくお願いします

curl -sS "$BASE/v1/sessions/$SESSION_ID/transcript?format=text&tz=Asia/Tokyo" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

書き出しのリンクを作る（POST /v1/sessions/{sessionId}/downloads）

文字おこしくんは、クリックするだけで文字起こしをファイルとして保存できるリンク（CSV・JSON・テキスト）と、記録を ChatGPT に渡すリンク（chatgptUrl）を作る。書き出しのリンクは、transcript:download のトークンをクエリに載せた GET /v1/sessions/{sessionId}/transcript の URL である。chatgptUrl は、同じトークンを載せた GET /v1/sessions/{sessionId}/chatgpt の URL である。transcript:download のトークンでは、書き出しと ChatGPT への転送だけができる（Subscribe には使えない）。クライアントは、リンクを、チャットなどに貼って、資格情報を持たない人に渡してよい。文字おこしくんには、リンクを 1 つずつ失効させる仕組みが無い。有効期間を指定しなければ 3600 秒になる。最大は 86400 秒である。セッションに保持期限（retainUntil）があれば、文字おこしくんは、リンクの有効期限を保持期限より後にしない。保持期限を過ぎたセッションには、文字おこしくんは 404 を返す。クライアントは、稼働中のセッションにもリンクを作れる。リンクを開いた人は、開いた時点までの記録を受け取る。hasUtterances が false なら、書き出しに載る発話がまだ無い。クライアントは、要求の本文を省ける。

• 認証: API キー（transcripts:read）
• operationId: createTranscriptDownloads

要求の本文（JSON）:

{
  "ttlSeconds": 3600
}

応答 200:

{
  "expiresAt": 1790354426000,
  "hasUtterances": true,
  "urls": {
    "json": "https://moji.kaitoranma.com/v1/sessions/0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10/transcript?format=json&token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OmRvd25sb2FkIn0.Wm3Kp8Rt2Yv6Nq1Lx4Hc9Jd0Fs5Gb7Tz3Ea8Uw2Qo6r",
    "text": "https://moji.kaitoranma.com/v1/sessions/0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10/transcript?format=text&token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OmRvd25sb2FkIn0.Wm3Kp8Rt2Yv6Nq1Lx4Hc9Jd0Fs5Gb7Tz3Ea8Uw2Qo6r",
    "csv": "https://moji.kaitoranma.com/v1/sessions/0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10/transcript?format=csv&token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OmRvd25sb2FkIn0.Wm3Kp8Rt2Yv6Nq1Lx4Hc9Jd0Fs5Gb7Tz3Ea8Uw2Qo6r"
  },
  "chatgptUrl": "https://moji.kaitoranma.com/v1/sessions/0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10/chatgpt?token=eyJ2IjoxLCJzaWQiOiIwZjBjM2MxZS01YjdhIiwic2NvcGUiOiJ0cmFuc2NyaXB0OmRvd25sb2FkIn0.Wm3Kp8Rt2Yv6Nq1Lx4Hc9Jd0Fs5Gb7Tz3Ea8Uw2Qo6r"
}

curl -sS -X POST "$BASE/v1/sessions/$SESSION_ID/downloads" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ttlSeconds":3600}'

記録を ChatGPT に渡す（GET /v1/sessions/{sessionId}/chatgpt）

文字おこしくんは、クエリの token（書き出しのリンクと同じ transcript:download のトークン）を確かめてから、ブラウザを ChatGPT の新しい会話（https://chatgpt.com/?q=…）へ 302 で転送する。q には定型文「次の URL は、Discord のボイスチャンネルの会話の文字おこしです。内容を読んで、議事録として要約してください。」と、記録をページとして表示する URL（GET /v1/sessions/{sessionId}/transcript?format=text&disposition=inline&token=<同じトークン>）が入る。POST /v1/sessions/{sessionId}/downloads の応答の chatgptUrl が、この操作の URL である。ChatGPT の URL は日本語の定型文を含んで長いので、文字おこしくんは、Discord のリンクボタン（URL は 512 文字まで）に載せられる短い URL を、この操作で ChatGPT の URL に転送する。保持期間を過ぎたセッションには、文字おこしくんは 404 を返す。クライアントは、クエリの token と Authorization ヘッダーを同時に付けない（同時に付けると、文字おこしくんは 400 を返す）。HEAD では、文字おこしくんは同じ応答を本文なしで返す。

• 認証: クエリの token（transcript:download）
• operationId: openTranscriptInChatGpt

curl -sS -o /dev/null -w "%{redirect_url}\n" "$BASE/v1/sessions/$SESSION_ID/chatgpt?token=$DOWNLOAD_TOKEN"

利用量（Usage）

クライアントは、usage:read の API キーで、利用量を見る。

利用量を見る（GET /v1/usage）

文字おこしくんは、API キーのテナントの日ごとの利用量と、今日（UTC）の上限・残りを返す。利用量は音声認識にかけた音声の秒数で、文字おこしくんは利用量をトラックごとに数えて足す。from〜to には両端を含めて最大 366 日を指定できる。

• 認証: API キー（usage:read）
• operationId: getUsage

応答 200:

{
  "tenantId": "111111111111111111",
  "plan": "level-0",
  "from": "2026-09-24",
  "to": "2026-09-26",
  "days": [
    {
      "date": "2026-09-24",
      "audioSeconds": 0
    },
    {
      "date": "2026-09-25",
      "audioSeconds": 5400.25
    },
    {
      "date": "2026-09-26",
      "audioSeconds": 1234.567
    }
  ],
  "totalAudioSeconds": 6634.817,
  "today": {
    "date": "2026-09-26",
    "audioSeconds": 1234.567,
    "limitAudioSeconds": null,
    "remainingAudioSeconds": null,
    "exceeded": false,
    "resetsAt": 1790467200000
  }
}

curl -sS "$BASE/v1/usage?from=2026-09-24&to=2026-09-26" \
  -H "Authorization: Bearer $MOJIOKOSHI_API_KEY"

WebSocket のエンドポイント（WebSocket）

WebSocket のエンドポイントには Ingest と Subscribe がある。メッセージの一覧は asyncapi.yaml にある。

WebSocket の Ingest（音声を送る）に接続する（GET /v1/ingest）

クライアントは、この操作で、WebSocket の Ingest（音声を送る）に接続する。メッセージの一覧は asyncapi.yaml と WebSocket API リファレンス にある。クライアントは、URL やヘッダーではなく、接続した後の最初のメッセージ hello で ingest:write のセッショントークンを送る。普通の HTTP で要求すると、文字おこしくんは 426 を返す。同時接続数は、文字おこしくんの API 全体で 4,096、同じ送信元から 1,024 までである。超えると、文字おこしくんは upgrade に 503 / 429 の too_many_connections を返す。

• 認証: 接続後の hello でセッショントークン
• operationId: ingestWebSocket

const ws = new WebSocket("wss://moji.kaitoranma.com/v1/ingest");
ws.onopen = () => ws.send(JSON.stringify({ type: "hello", protocolVersion: 1, token: INGEST_TOKEN }));
ws.onmessage = (event) => console.log(event.data); // 詳しくは asyncapi.yaml

WebSocket の Subscribe（結果を受け取る）に接続する（GET /v1/subscribe）

クライアントは、この操作で、WebSocket の Subscribe（結果を受け取る）に接続する。メッセージの一覧は asyncapi.yaml と WebSocket API リファレンス にある。クライアントは、URL やヘッダーではなく、接続した後の最初のメッセージ hello で transcript:read のセッショントークンを送る。普通の HTTP で要求すると、文字おこしくんは 426 を返す。同時接続数は、文字おこしくんの API 全体で 4,096、同じ送信元から 1,024 までである。超えると、文字おこしくんは upgrade に 503 / 429 の too_many_connections を返す。

• 認証: 接続後の hello でセッショントークン
• operationId: subscribeWebSocket

const ws = new WebSocket("wss://moji.kaitoranma.com/v1/subscribe");
ws.onopen = () => ws.send(JSON.stringify({ type: "hello", protocolVersion: 1, token: READ_TOKEN }));
ws.onmessage = (event) => console.log(event.data); // 詳しくは asyncapi.yaml

TypeScript・Python の例

依存なしのクライアント examples/mojiokoshi-http.ts（Node 22.18 以降 / Deno / Bun / tsx）か examples/mojiokoshi_http.py（Python 3.10 以降、標準ライブラリだけ）と、ライブの購読の参照実装 examples/mojiokoshi-subscribe.js か examples/mojiokoshi_subscribe.py（websockets）を同じフォルダに置いて、例を動かします。例のコードは、API キーを環境変数 MOJIOKOSHI_API_KEY から読みます。

TypeScript

// recipes.mts を node recipes.mts で実行する（Node 22.18 以降。または npx tsx recipes.mts。examples/ の 2 つのファイルを同じフォルダに置く）
import { createMojiokoshiHttp } from "./mojiokoshi-http.ts";
import { subscribe, speakerName } from "./mojiokoshi-subscribe.js";

// MOJIOKOSHI_BASE_URL を省くと、公式の文字おこしくん（https://moji.kaitoranma.com）につなぐ
const api = createMojiokoshiHttp({ apiKey: process.env.MOJIOKOSHI_API_KEY!, baseUrl: process.env.MOJIOKOSHI_BASE_URL });

// 1. 自分のセッションを新しい順に一覧する（続きは nextCursor で取る。全部を取るなら allSessions() を使う）
const { sessions } = await api.listSessions({ limit: 5 });
for (const s of sessions) console.log(s.sessionId, s.live ? "live" : "ended", s.label);

// 2. 文字起こしを書き出す（JSON と、1 発話 1 行のテキストで）
const latest = sessions[0];
if (latest !== undefined) {
  const transcript = await api.exportTranscript(latest.sessionId);
  console.log(transcript.utterances.length, "発話");
  console.log(await api.exportTranscriptText(latest.sessionId, "Asia/Tokyo"));
}

// 3. transcript:read のトークンを発行して、ライブで購読する
const [live] = (await api.listSessions({ status: "active", limit: 1 })).sessions;
if (live !== undefined) {
  const { token } = await api.mintReadToken(live.sessionId, 3600); // ブラウザ・OBS には、このトークンだけを渡す
  subscribe({
    url: api.subscribeUrl(),
    token,
    onChange(state, message) {
      if (message.type === "utterance" && message.utterance.stage !== "partial") {
        console.log(`${speakerName(state, message.utterance)}: ${message.utterance.text}`);
      }
    },
    onStatus(status, detail) {
      // 期限（1 時間）の後に再接続すると、文字おこしくんが unauthorized を返し、購読が止まる。長く動かすなら、mintReadToken でトークンを取り直して、subscribe し直す。
      if (status === "failed" || status === "ended") console.error(status, detail?.code ?? "");
    },
  });
}

// 4. 今日（UTC）の利用量を見る
const usage = await api.getUsage();
console.log(`今日 ${(usage.today.audioSeconds / 60).toFixed(1)} 分`);

Python

# recipes.py を python recipes.py で実行する（examples/ の mojiokoshi_http.py と mojiokoshi_subscribe.py を同じフォルダに置く）
import asyncio
import os

from mojiokoshi_http import DEFAULT_BASE_URL, MojiokoshiHttp
from mojiokoshi_subscribe import run  # ライブの購読（pip install websockets）

api = MojiokoshiHttp(os.environ["MOJIOKOSHI_API_KEY"], os.environ.get("MOJIOKOSHI_BASE_URL", DEFAULT_BASE_URL))

# 1. 自分のセッションを新しい順に一覧する（続きは nextCursor を cursor に渡して取る）
page = api.list_sessions(limit=5)
for s in page["sessions"]:
    print(s["sessionId"], "live" if s["live"] else "ended", s["label"])

# 2. 文字起こしを書き出す（JSON と、1 発話 1 行のテキストで）
if page["sessions"]:
    session_id = page["sessions"][0]["sessionId"]
    print(len(api.export_transcript(session_id)["utterances"]), "発話")
    print(api.export_transcript_text(session_id, tz="Asia/Tokyo"))

# 3. 今日（UTC）の利用量を見る
today = api.get_usage()["today"]
print(f"今日 {today['audioSeconds'] / 60:.1f} 分")

# 4. transcript:read のトークンを発行して、ライブで購読する（Ctrl+C で止める）
live = api.list_sessions(status="active", limit=1)["sessions"]
if live:
    token = api.mint_read_token(live[0]["sessionId"], ttl_seconds=3600)["token"]
    asyncio.run(run(api.subscribe_url(), token))