# 文字おこしくん 開発者向けドキュメント（全文）

> https://moji.kaitoranma.com/docs/ の全ページの Markdown を順につなげたもの。各ページの元の URL は <!-- source: … --> に書いてある。機械可読な仕様は [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml)（OpenAPI 3.1、HTTP）、[asyncapi.yaml](https://moji.kaitoranma.com/docs/asyncapi.yaml)（AsyncAPI 3.1、WebSocket）、[JSON Schema](https://moji.kaitoranma.com/docs/schemas/common.json)（2020-12）、[errors.json](https://moji.kaitoranma.com/docs/errors.json)。規約・ポリシー（このファイルには含まない）: [利用規約](https://moji.kaitoranma.com/legal/terms.html)・[プライバシーポリシー](https://moji.kaitoranma.com/legal/privacy.html)・[特定商取引法に基づく表記](https://moji.kaitoranma.com/legal/tokushoho.html)・[データの流れと保存期間](https://moji.kaitoranma.com/legal/data-flow.html)。

<!-- source: https://moji.kaitoranma.com/docs/index.md -->

# 開発者向けドキュメント

> ボットの追加・字幕の見方・応援して機能を強化など、プログラムを書かずに使う方法は[使い方](https://moji.kaitoranma.com/help/index.md)にあります。

あなたのプログラムは、公式の表示ページと同じ、話している人ごとのリアルタイムの発話を、API で受け取れます。

## 何が作れるか

| 作りたいもの | 使う API | ガイド |
|---|---|---|
| OBS の字幕・自作のオーバーレイ・配信画面 | WebSocket（Subscribe） | [オーバーレイ](https://moji.kaitoranma.com/docs/guides/overlay.md) |
| Discord・Slack などへの中継ボット、翻訳・要約ボット | WebSocket（Subscribe） | [ボットへの中継](https://moji.kaitoranma.com/docs/guides/bot-relay.md) |
| 議事録の保存・書き出し・検索 | HTTP（書き出し）+ WebSocket | [記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md) |
| 発言量・話者ごとの統計 | HTTP（書き出し）+ WebSocket | [分析](https://moji.kaitoranma.com/docs/guides/analytics.md) |
| Discord 以外の音声（マイク・録音・別の通話アプリ）の文字起こし | WebSocket（Ingest） | [音声を送る](https://moji.kaitoranma.com/docs/ingest.md) |
| 文字起こしが終わるたびの記録の書き出し・文字起こしの最初からの発言の購読 | Webhook + HTTP（書き出し）+ WebSocket | [Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md) |

公式の表示ページ・配信用オーバーレイの見た目を変えるだけなら、プログラムは要りません。見た目の変え方は[表示ページの URL パラメータと CSS](https://moji.kaitoranma.com/docs/viewer.md)に、表示ページのリンクの OBS への貼り方は使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md)にあります。

## 始めるのに要るもの

| 資格情報 | 誰がどこで出すか | ブラウザ・OBS に置いてよいか |
|---|---|---|
| API キー（`mjk_live_…`） | ボットを入れた Discord サーバーの管理者が、[管理画面](https://moji.kaitoranma.com/app/)で作る（[手順](https://moji.kaitoranma.com/docs/quickstart.md#from-api-key)） | **置かない**。サーバー側のコードだけに置く（キーが漏れると、キーを手に入れた人が、その Discord サーバーの記録を読んだり消したりできる） |
| セッショントークン（使えるセッションも権限も 1 つだけで、期限がある） | Discord サーバーのメンバーが Discord で `/link` を実行すると、文字おこしくんが、トークンの入ったリンクを返答のボタンで渡す。API キーを持つあなたのサーバー側のコードも、トークンを発行できる | 置いてよい |
| Webhook の署名のシークレット（`whsec_…`。Webhook を使うときだけ） | ボットを入れた Discord サーバーの管理者が[管理画面](https://moji.kaitoranma.com/app/)で Webhook の送信先を作ると、管理画面がシークレットを 1 回だけ表示する（[送信先を登録する](https://moji.kaitoranma.com/docs/webhooks.md#register)） | **置かない**。Webhook を受け取るサーバー側のコードだけに置く（シークレットを手に入れた人は文字おこしくんからの知らせを装える） |

ブラウザからは、文字おこしくんの HTTP API を呼べません（文字おこしくんの HTTP API は CORS のヘッダーを返しません）。HTTP API は、あなたのサーバー側のコードから呼んでください。

**次に読む**: [クイックスタート](https://moji.kaitoranma.com/docs/quickstart.md)（字幕を受け取るまで）

## 仕様ファイルと参照実装

- 機械可読な仕様: [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml)（HTTP と Webhook の本文〔`webhooks`〕。OpenAPI 3.1）・[asyncapi.yaml](https://moji.kaitoranma.com/docs/asyncapi.yaml)（WebSocket。AsyncAPI 3.1）・JSON Schema 2020-12（[common](https://moji.kaitoranma.com/docs/schemas/common.json)・[subscribe-client-message](https://moji.kaitoranma.com/docs/schemas/subscribe-client-message.json)・[subscribe-server-message](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)・[ingest-client-message](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)・[ingest-server-message](https://moji.kaitoranma.com/docs/schemas/ingest-server-message.json)）・[errors.json](https://moji.kaitoranma.com/docs/errors.json)
- 参照実装（依存なし。そのままコピーして使える）: WebSocket で受け取るもの [mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js)・[mojiokoshi_subscribe.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_subscribe.py)、HTTP API を呼ぶもの（サーバー側だけ） [mojiokoshi-http.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-http.ts)・[mojiokoshi_http.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_http.py)、Webhook の署名を確かめるもの（サーバー側だけ） [mojiokoshi-webhook.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-webhook.ts)・[mojiokoshi_webhook.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_webhook.py)
- 文字おこしくんは、TypeScript の SDK を npm にまだ公開していません。参照実装を使ってください。

コーディングエージェントにクライアントのコードを書かせるときは、[llms.txt](https://moji.kaitoranma.com/docs/llms.txt)（全文は [llms-full.txt](https://moji.kaitoranma.com/docs/llms-full.txt)）か [Agent Skill](https://moji.kaitoranma.com/docs/skill/SKILL.md)、各ページの Markdown 版（同じパスの `.md`）をエージェントに渡してください。

---

<!-- source: https://moji.kaitoranma.com/docs/quickstart.md -->

# クイックスタート

## 1. 接続先とトークンを手に入れる

字幕を受け取るには、**Subscribe の URL**（`wss://<host>/v1/subscribe`）と、**`transcript:read` のセッショントークン**の 2 つが要ります。今すぐ試すなら A で、続けて使うサーバー側のコードを書くなら B で、URL とトークンを手に入れます。

### A. Discord のリンクから（今すぐ試す） {#from-discord}

A の方法は、文字起こしが動いている VC で使えます。文字起こしが動いている VC は、誰かが `/start` で文字起こしを始めた VC か、自動入室でボットが入っている VC です。

1. Discord で `/link` を実行し、返答の「配信用オーバーレイ（OBS 用）」のボタンを押します。
2. 開いたブラウザのアドレス欄の URL をコピーします。URL は `https://moji.kaitoranma.com/#token=…&overlay=1` の形です。URL に `#token=` が入っていれば、トークンを取れています。
3. コピーした URL から、接続先とトークンを取り出します。

```js
// オーバーレイの URL から接続先とトークンを取り出す
const overlay = new URL("https://moji.kaitoranma.com/#token=eyJ2Ijox...&overlay=1");
const token = new URLSearchParams(overlay.hash.slice(1)).get("token");
const url = `${overlay.protocol === "https:" ? "wss:" : "ws:"}//${overlay.host}/v1/subscribe`;
```

Discord のリンクのトークンには期限があります。Discord のリンクのトークンでは、リンクを取ったときに動いている文字起こしの字幕だけを受け取れます。

### B. API キーから（続けて使う・サーバー側のコード） {#from-api-key}

あなたは API キー（`mjk_live_…`、スコープ `transcripts:read`）で、動いている文字起こし（セッション）を探して、トークンを発行します。

API キーを作る手順:

1. Discord サーバーの管理者（「サーバーの管理」か「管理者」の権限を持つ人、または所有者）が、文字起こしを使う Discord サーバーに、文字おこしくんのボットを追加します（[Discord に追加](https://moji.kaitoranma.com/invite)）。
2. その Discord サーバーの管理者が、[管理画面](https://moji.kaitoranma.com/app/)に Discord でログインします。
3. その Discord サーバーの管理者が、管理画面でその Discord サーバーを選び、「開発者向け設定」（`https://moji.kaitoranma.com/app/guilds/<サーバー ID>/keys`）でキーを作ります。管理画面は作ったキーを 1 回だけ表示します。

あなたがその Discord サーバーの管理者でなければ、その Discord サーバーの管理者に API キーを作ってもらうか、A で試してください。

**API キーはソースに書かず、ブラウザに渡さないでください。** ブラウザには、発行したトークンだけを渡してください。

```sh
BASE=https://moji.kaitoranma.com
KEY=$MOJIOKOSHI_API_KEY   # mjk_live_…（ソースに書かず、環境変数などから読む）

# 動いているセッションを新しい順に一覧し、先頭の sessionId を取り出す（jq を使う例）
curl -sS "$BASE/v1/sessions?status=active&limit=5" -H "Authorization: Bearer $KEY"
SID=$(curl -sS "$BASE/v1/sessions?status=active&limit=1" -H "Authorization: Bearer $KEY" | jq -r '.sessions[0].sessionId')

# そのセッションの transcript:read のトークンを発行する（ttlSeconds は 1〜86400、既定 3600）
curl -sS -X POST "$BASE/v1/sessions/$SID/tokens" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"scope":"transcript:read","ttlSeconds":3600}'
# → {"token":"eyJ2Ijox…","expiresAt":1790355000000}
```

API キーでセッションを探してトークンを発行する TypeScript・Python の例は、[HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md#examples)の最後にあります。

## 2. 受け取る

依存なしの参照実装 [examples/mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js)（ブラウザ / Node 22 以降）をダウンロードして、次のコード（quickstart.mjs）と同じフォルダに置きます。参照実装は再接続・生存確認・改訂の置き換え・再接続せずに終えるべきエラーの扱いまで実装しています。

```js
// node quickstart.mjs <wss://…/v1/subscribe> <token>
import { subscribe, speakerName } from "./mojiokoshi-subscribe.js";

const [url, token] = process.argv.slice(2);
subscribe({
  url,
  token,
  onChange(state, message) {
    // 確定した発話だけを出す。同じ utteranceId の改訂（refined）は置き換えとして届く。
    if (message.type === "utterance" && message.utterance.stage !== "partial") {
      console.log(`${speakerName(state, message.utterance)}: ${message.utterance.text}`);
    }
  },
  onStatus(status, detail) {
    console.error(`[${status}]`, detail?.code ?? "");
    if (status === "ended" || status === "failed") process.exitCode = status === "failed" ? 1 : 0;
  },
});
```

プログラムが `[open]` と出した後に VC で誰かが話すと、プログラムは、確定した発言を `たろう: こんにちは。` のように 1 行ずつ出します。発言が出ないとき:

- `[failed] unauthorized` と出た: トークンの期限が切れています。1 の手順でトークンを取り直してください（[トークンの期限](https://moji.kaitoranma.com/docs/reconnection.md#token-expiry)）。
- `[ended]` と出た: トークンを取った文字起こしは、もう終わっています。文字起こしを始め直してから、1 に戻ってください。

参照実装はブラウザでも `<script type="module">` から読み込めます。1 ファイルで動く HTML は、[オーバーレイのガイド](https://moji.kaitoranma.com/docs/guides/overlay.md)にあります。

### Python（websockets）

[examples/mojiokoshi_subscribe.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_subscribe.py) は、確定した発話を 1 行ずつ出す参照実装です。

```sh
pip install websockets
python mojiokoshi_subscribe.py "wss://moji.kaitoranma.com/v1/subscribe" "eyJ2Ijox…"
# たろう: こんにちは、今日はよろしくお願いします。
# はなこ: よろしくお願いします。
```

### プロトコルを直接書く場合の最小の流れ

```text
→ {"type":"hello","protocolVersion":1,"token":"eyJ2Ijox…"}
← {"type":"welcome","sessionId":"…",…}
← {"type":"utterance","utterance":{"utteranceId":"utt_02","stage":"partial","revision":1,"text":"それでは始め",…}}
← {"type":"utterance","utterance":{"utteranceId":"utt_02","stage":"final","revision":3,"text":"それでは始めましょう",…}}
← {"type":"utterance","utterance":{"utteranceId":"utt_02","stage":"refined","revision":4,"text":"それでは始めましょう。",…}}
→ {"type":"ping"}
← {"type":"pong"}
← {"type":"session_ended"}
```

クライアントは、`{"type":"ping"}` を 15 秒ごとに送ります。

クライアントは、同じ `utteranceId` の発話を**置き換え**（`revision` が大きい方を採る）、接続が切れたら**バックオフして再接続**します。クライアントには置き換えと再接続の 2 つの処理が欠かせません。メッセージの一覧は [WebSocket API リファレンス](https://moji.kaitoranma.com/docs/reference.md)にあります。

## 3. 終わった後に書き出す（curl）

あなたはセッションが終わった後も、保持期間（Discord サーバーのレベルにより 30〜365 日）の間はセッションの記録を書き出せます。書き出しには、`transcript:read` のトークン（または `transcripts:read` の API キー）を使います。

```sh
# テキストで書き出す（時刻のタイムゾーンは tz で指定する。既定は Asia/Tokyo）
curl -s "$BASE/v1/sessions/$SID/transcript?format=text&tz=Asia/Tokyo" -H "Authorization: Bearer $TOKEN"
# [21:03:05] たろう: こんにちは。
# [21:03:09] はなこ: よろしくお願いします。

# JSON で書き出す
curl -s "$BASE/v1/sessions/$SID/transcript" -H "Authorization: Bearer $TOKEN"
```

JSON の形と、記録として残すときの注意は、[記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md)にあります。

## 次に読む

- [発話の改訂モデル](https://moji.kaitoranma.com/docs/revisions.md): `partial` / `final` / `refined` の扱い
- [再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md): 再接続せずに終えるべきエラーとバックオフ
- 作りたいものに合わせたガイド: [オーバーレイ](https://moji.kaitoranma.com/docs/guides/overlay.md) / [ボットへの中継](https://moji.kaitoranma.com/docs/guides/bot-relay.md) / [記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md) / [分析](https://moji.kaitoranma.com/docs/guides/analytics.md)
- [Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md): 文字起こしの開始と終了の知らせの受け取り方（あなたのサーバーが一覧を読み直さずに新しいセッションを知る方法）

## コーディングエージェント向けのプロンプト

```text
文字おこしくん（Discord VC のリアルタイム文字起こし）の Subscribe WebSocket API に接続して、確定した発話を標準出力に出すクライアントを書いてください。

仕様: https://moji.kaitoranma.com/docs/llms.txt と、そこからリンクされている asyncapi.yaml / JSON Schema を読んでから実装すること。
- 参照実装 https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js をそのまま使うか、同じ決まりで実装する。
- 接続先 URL とトークンは環境変数（MOJIOKOSHI_SUBSCRIBE_URL / MOJIOKOSHI_TOKEN）から読む。トークンはソースに書かない。
- 接続後に {"type":"hello","protocolVersion":1,"token":…} を送る。welcome を受け取ったら状態を丸ごと置き換える。
- utterance は utteranceId ごとに revision が最大のものだけを残す（追記しない）。partial は出さず、final と refined を出す（refined は同じ発話の修正版）。
- 15 秒ごとに {"type":"ping"} を送る。切断されたら 0.5 秒から倍々・上限 30 秒・ジッター付きで再接続する。
- unauthorized / protocol_version_unsupported / session_ended / superseded / quota_exceeded、fatal な invalid_message、session_ended メッセージでは再接続せずに終了する。
- 受け取ったメッセージは subscribe-server-message.json の JSON Schema で検証できるようにテストを書く。
```

---

<!-- source: https://moji.kaitoranma.com/docs/revisions.md -->

# 発話の改訂モデル

文字おこしくんが送る発話（`utterance`）は、1 回で届き切るものではありません。文字おこしくんは、同じ発話を**認識途中 → 確定 → 整形**と何度も送ります。受け手は同じ `utteranceId` の発話が届くたびに、持っている前の改訂を**置き換え**ます。受け手が追記すると、画面に同じ文が何度も並びます。

## 3 つの段階

| `stage` | 意味 | いつ届くか | 表示のしかたの例 |
|---|---|---|---|
| `partial` | 認識途中。後から文字が変わる | 話している間、数百 ms ごと | 薄く表示する・字幕なら最終行に出す |
| `final` | 音声認識の確定 | 話し終わり（発話区間の終わり）の直後 | 普通に表示する |
| `refined` | LLM による整形（句読点・表記の修正） | `final` の数百 ms〜数秒後に、非同期で届く。整形しない設定の Discord サーバーでは届かない | `final` をそのまま置き換える |

- どの段階でも、同じ発話は同じ `utteranceId` で届きます。改訂のたびに `revision` が増えます。
- クライアントの受信が、文字おこしくんからの送信に追いつかないとき、文字おこしくんは `partial` を間引くことがあります。**`revision` は連番とは限りません。**
- `refined` は来ないこともあります。整形しない設定の Discord サーバーでは `refined` は来ず、整形に失敗したときも来ません。発話が `final` のまま終わっても、エラーではありません。
- `text` は空文字のこともあります。たとえば、認識の途中で音が無かったときに、`text` が空文字になります。

## 受け手の決まり

1. 発話は **`utteranceId` をキーにした表（Map）** で持つ。
2. 届いた `utterance` の `revision` が、持っているものより**大きいときだけ**置き換える。同じか小さいものは捨てる（受け手は、到着順に頼らずに `revision` を比べるので、再接続の `welcome.recent` と重なっても、受け手の処理は冪等になる）。
3. `welcome` を受け取ったら、状態を**丸ごと置き換える**（再接続したときも）。受け手は切断中の差分を取り戻せない。代わりに、`welcome.recent`（直近の発話の最新の改訂）で状態を作り直す。
4. 文字おこしくんは、話者をまたいだ順序を揃えずに送る。時刻順に並べるときは `startedAt`（文字おこしくんが最初の音声を受け取った時刻、エポックミリ秒）で並べ、同じなら `utteranceId` で並べる。

```js
const utterances = new Map(); // utteranceId → 最新の改訂

function onUtterance(u) {
  const known = utterances.get(u.utteranceId);
  if (known !== undefined && known.revision >= u.revision) return false; // 古い・重複した改訂
  utterances.set(u.utteranceId, u); // 追記ではなく置き換え
  return true;
}

function onWelcome(welcome) {
  utterances.clear(); // スナップショットで丸ごと置き換える
  for (const u of welcome.recent) onUtterance(u);
}

const ordered = () =>
  [...utterances.values()].sort((a, b) => a.startedAt - b.startedAt || (a.utteranceId < b.utteranceId ? -1 : 1));
```

## 届き方の例

1 人の話者の 1 つの発話は、たとえば次のように届きます（表では `trackId` などを省いています）。

| 順 | `stage` | `revision` | `text` | 受け手の状態（`utt_02`） |
|---|---|---|---|---|
| 1 | `partial` | 0 | それでは | それでは |
| 2 | `partial` | 1 | それでは始め | それでは始め |
| 3 | `partial` | 2 | それでは始めましょ | それでは始めましょ |
| 4 | `final` | 3 | それでは始めましょう | それでは始めましょう |
| 5 | `refined` | 4 | それでは始めましょう。 | それでは始めましょう。 |
| 6 | `partial` | 2（遅れて届いた） | それでは始めましょ | 変えない（捨てる） |

同時に別の話者の発話（別の `utteranceId`）も並行して届きます。2 人が同時に話せば、2 つの発話が同時に `partial` のまま伸びていきます。

## 話者

`utterance.speaker` は次のどれかです。

| `kind` | 意味 | 表示 |
|---|---|---|
| `declared` | 入力元が宣言した話者（Discord のユーザーなど） | `speakerId` の話者の表示名 |
| `inferred` | 1 本の音声に複数人の声が入ったトラックで、話者分離が推定した話者 | `speakerId` の話者（「話者 1」など）。**inferred の発話は、後の改訂で別の `speakerId` の話者に付け替わることがある** |
| `unattributed` | 話者が分からない | トラック（`trackId`）単位で表示する |

- 表示名は `welcome.speakers` と `speaker_upserted` で届きます。受け手は `speaker_removed` を受け取った後も、その話者の過去の発話を消さずに残します（表示名は覚えておいたものを使います）。
- 表示名は空文字のことがあります。表示名が空文字のときは、「不明な話者」などの代替名を表示してください。

## よくある間違い

| 起きていること | 原因 | 正しくは |
|---|---|---|
| 同じ文が `partial` の数だけ並ぶ | `utterance` を受け取るたびに行を追加している | `utteranceId` で置き換える |
| 文字が前の状態に戻る | 最後に届いたものを最新とみなしている（遅れて届いた古い改訂で上書きしている） | `revision` を比べる |
| 再接続の後に、重複や消えたはずの状態が残る | 再接続の後に `welcome.recent` を前の状態に足している | 状態を `welcome` で丸ごと置き換える（`revision` の比較で重複は消える） |
| 句読点の無い文が記録に残る | `final` だけを保存して `refined` を無視している | `refined` でも置き換える（保存するときも upsert する） |
| 話者をまたいだ前後が入れ替わる | 到着順に並べている | `startedAt` で並べる |
| 発話の `text` や表示名が HTML として動く | `innerHTML` に `text` や表示名を入れている | `textContent` を使う |

## 保持する数の上限

長いセッションでは発話が増え続けるので、受け手は、ふつう画面に出す分だけの発話を持ちます（公式の表示ページは 500 件を持ちます）。次の順で発話を捨てると、長く話している途中の発話が消えません。

1. 確定した発話（`final` / `refined`）のうち `startedAt` が最も古いものから捨てる。
2. 持っている発話がすべて認識途中のときを除き、認識途中（`partial`）は捨てない。
3. 上限に達しているときに届いた、知らない `utteranceId` の `refined` は無視する（捨てた発話の整形結果なので、入れると古い発話が復活する）。

## コーディングエージェント向けのプロンプト

```text
文字おこしくんの Subscribe WebSocket API の utterance メッセージを扱う状態管理を実装してください。
仕様: https://moji.kaitoranma.com/docs/revisions.md

- 発話は utteranceId をキーにした Map で持ち、revision が大きいときだけ置き換える（同じか小さい revision は無視）。追記しない。
- welcome を受け取ったら状態を丸ごと置き換え、welcome.recent を同じ規則で入れる。
- 表示用の並びは startedAt → utteranceId の昇順。
- speaker.kind が unattributed の発話はトラック（trackId）単位、declared / inferred は speakerId 単位でまとめる。inferred は改訂で speakerId が変わりうる。
- 上限を超えたら確定済み（final / refined）の古いものから捨て、partial は残す。
- テスト: partial r0 → final r3 → 遅れた partial r2 → refined r4 の順に入れて、最後が refined のテキスト 1 件になること。welcome で置き換わること。
```

---

<!-- source: https://moji.kaitoranma.com/docs/reconnection.md -->

# 再接続とエラーの扱い

WebSocket のクライアントは、接続が切れるものとして作ってください。文字おこしくんのサーバーの再起動・ネットワークの揺れ・プロキシのアイドル切断・クライアントの受信の遅れで、つながっている接続は切れます。

## 判断の表

エラーは `{"type":"error","error":{"code":"…","message":"…","fatal":true|false}}` で届きます。`fatal: true` なら、文字おこしくんはこの後に接続を閉じます。

| 起きたこと | どうするか |
|---|---|
| `fatal: false` の `error` | 接続を使い続ける（Ingest なら送った内容を直す） |
| `unauthorized` | **再接続しない**。新しいトークンを取ってからやり直す |
| `protocol_version_unsupported` | **再接続しない**。クライアントを更新する |
| `session_ended`（エラーでもメッセージでも） | **再接続しない**。そのセッションは終わった |
| `superseded` | **再接続しない**（Ingest）。同じセッションに別の送り手がつないだ |
| `quota_exceeded` | **再接続しない**（Ingest）。利用上限に達し、セッションも終わっている。次の UTC 0 時の後に、新しいセッションを作る |
| fatal な `invalid_message` | **再接続しない**。文字おこしくんが `hello` を拒んだので、同じ `hello` を送り直しても通らない |
| fatal な `rate_limited` | 上限の待ち時間（30 秒）をおいて再接続する |
| fatal な `internal`・知らないコード | バックオフで再接続する |
| `error` を受け取らずに切れた | バックオフで再接続する |
| 非 fatal な `error` の直後に切れた（hello のタイムアウト・受信の遅いクライアントへの `rate_limited` など） | バックオフで再接続する |
| 接続するときに、文字おこしくんが HTTP 503 / 429（`too_many_connections`）で断った | バックオフで再接続する |

- 再接続するかどうかを、WebSocket の close code で判断しないでください（文字おこしくんは close code を規定していません）。あなたのクライアントは、直前に受け取った `error.code` で判断してください。
- **知らないコードも受け入れてください。** 文字おこしくんは、互換性のある変更として、エラーコードを追加します。あなたのクライアントは、`fatal` に従い、fatal な知らないコードを `internal` と同じに扱ってください。
- 一覧と機械可読な版: [エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)・[errors.json](https://moji.kaitoranma.com/docs/errors.json)

## バックオフ

```text
待ち時間 = min(30 秒, 0.5 秒 × 2^試行回数) × (1 − 0.5 × random())
```

- クライアントは、待ち時間を、1 回目は 0.25〜0.5 秒、2 回目は 0.5〜1 秒 … と倍々に延ばし、30 秒で頭打ちにします。
- ジッター（`random()`）は必ず入れてください。ジッターを入れると、文字おこしくんのサーバーの再起動のあとに、全員のクライアントが同時につなぎ直すことを避けられます。
- `welcome` を受け取ってから 10 秒以上つながっていた接続が切れたら、クライアントは、試行回数を 0 に戻します。
- `session_ended` と再接続せずに終えるべきエラーの後は、クライアントは、再接続のタイマーと生存確認（`ping`）のタイマーを止め、接続も閉じます。

## 生存確認

ブラウザは WebSocket の ping / pong フレームを扱えないので、クライアントは、接続が生きているかを、プロトコルの JSON で確かめます。

- クライアントは、`welcome` の後、15 秒ごとに `{"type":"ping"}` を送る。文字おこしくんは `{"type":"pong"}` を返す。
- `ping` を送ってから 10 秒ほど**何も**届かなければ（`pong` に限らない）、クライアントは、半開きの接続とみなして接続を自分で閉じ、再接続する。
- 15 秒ごとの `ping` で、途中のプロキシ（Cloudflare など）のアイドル切断も防げます。

## 再接続したとき

**Subscribe**

- クライアントは、もう一度 `hello` から始め、`welcome` で状態を**丸ごと置き換えます**。
- 文字おこしくんには、切断中の差分を取り戻す仕組みはありません。クライアントは、代わりに `welcome.recent`（直近の発話の最新の改訂）で状態を作り直します。記録を取りこぼしたくないなら、セッションが終わった後に記録を HTTP で書き出して、受け取った発話と比べてください（[記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md)）。
- 再接続を待っている間は、表示を薄くするなどして、表示が古いかもしれないことを示すとよいでしょう。発声中の表示（`speakingTrackIds`）も古いままです。

**Ingest** で送り直すもの（話者・トラック・切断中の音声）と順番は、[音声を送る](https://moji.kaitoranma.com/docs/ingest.md#state_synced-と再接続)にあります。

## トークンの期限 {#token-expiry}

- 文字おこしくんは、トークンを**接続するときだけ**確かめます。つながっている接続は、トークンの期限が来ても切れません。
- 期限の後に再接続すると、文字おこしくんは `unauthorized`（再接続せずに終えるべきエラー）を返します。長く動かすプログラムは、期限の前（例: 有効期間の 8 割が過ぎたら）に新しいトークンを取り、次の再接続から使ってください。
- ブラウザ・OBS で使う URL のトークンが切れたら、Discord で `/link` を実行して、リンクを取り直します。

## 疑似コード

```js
const STOP = new Set(["unauthorized", "protocol_version_unsupported", "session_ended", "superseded", "quota_exceeded"]);
let attempt = 0, stopped = false, openedAt = 0;

function connect() {
  const ws = new WebSocket(url);
  ws.onopen = () => ws.send(JSON.stringify({ type: "hello", protocolVersion: 1, token: currentToken() }));
  ws.onmessage = ({ data }) => {
    const m = JSON.parse(data);
    if (m.type === "welcome") openedAt = Date.now();
    if (m.type === "session_ended") stopped = true;
    if (m.type === "error") {
      const { code, fatal } = m.error;
      if (STOP.has(code) || (fatal && code === "invalid_message")) stopped = true;
      else if (fatal && code === "rate_limited") attempt = 6; // 次は上限の 30 秒
    }
    handle(m);
  };
  ws.onclose = () => {
    if (stopped) return;
    if (openedAt !== 0 && Date.now() - openedAt > 10_000) attempt = 0;
    openedAt = 0;
    const delay = Math.min(30_000, 500 * 2 ** attempt++) * (1 - 0.5 * Math.random());
    setTimeout(connect, delay);
  };
}
```

参照実装 [examples/mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js) に、疑似コードを完成させたものがあります。

## コーディングエージェント向けのプロンプト

```text
文字おこしくんの WebSocket クライアント（Subscribe / Ingest）に、再接続とエラーの扱いを実装してください。
仕様: https://moji.kaitoranma.com/docs/reconnection.md と errors.json
（https://moji.kaitoranma.com/docs/errors.json）。

- 予期しない切断では min(30s, 0.5s × 2^n) × (1 − 0.5 × random) の指数バックオフで再接続する。welcome から 10 秒以上続いた接続の後は n を 0 に戻す。
- unauthorized / protocol_version_unsupported / session_ended / superseded / quota_exceeded と fatal な invalid_message、session_ended メッセージでは再接続しない。fatal な rate_limited は 30 秒待つ。知らないコードは fatal に従い、fatal なら internal と同じく再接続する。
- close code では判断しない。直前の error.code で判断する。
- welcome の後 15 秒ごとに {"type":"ping"} を送り、10 秒ほど何も届かなければ自分で閉じて再接続する。
- 再接続では hello からやり直し、Subscribe は welcome で状態を丸ごと置き換える。トークンは再接続のたびに有効なものを使う。
- 偽の WebSocket と偽のタイマーで、上の分岐をすべてテストする（実サーバーには依存しない）。
```

---

<!-- source: https://moji.kaitoranma.com/docs/guides/overlay.md -->

# ガイド: OBS・自作のオーバーレイ

あなたは配信の字幕や、話者ごとの吹き出しを自分で作れます。文字おこしくんは Subscribe の WebSocket につなぐページのオリジンを制限していないので、あなたのページはどこに置いても（OBS のブラウザソースからも）Subscribe につなげます。

## 方法を選ぶ

| 方法 | 手間 | できること |
|---|---|---|
| Discord の `/link` の返答のボタンで開く、公式の配信用オーバーレイのリンク（`…#token=…&overlay=1`）を、そのまま OBS に入れる | なし | 公式のデザインで字幕を出せる。URL パラメータと OBS の「カスタム CSS」で表示・色・大きさを変えられる（[表示ページの URL パラメータと CSS](https://moji.kaitoranma.com/docs/viewer.md)）。`view=youtube` では、文字おこしくんが YouTube のライブチャットと同じ要素の形で発言を出すので、YouTube のコメント欄向けに公開されている CSS をそのまま使える |
| **自作の HTML + 参照実装**（このページ） | HTML 1 枚 | レイアウト・演出を自由に作れる |

## 自作の HTML（話者ごとに最後の一言を出す字幕）

次の 2 ファイルを同じ場所に置きます。

1. [mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js)（参照実装。中身を変えずに置く）
2. `overlay.html`（このページのコード）

OBS のブラウザソースに `https://<置いた場所>/overlay.html#token=<トークン>&server=wss://<host>/v1/subscribe` を入れます。トークンの取り方は[クイックスタート](https://moji.kaitoranma.com/docs/quickstart.md#1-接続先とトークンを手に入れる)を見てください。

```html
<!doctype html>
<html lang="ja">
<meta charset="utf-8">
<title>captions</title>
<style>
  html, body { margin: 0; background: transparent; }
  body { font: 700 36px/1.4 "Noto Sans JP", sans-serif; color: #fff; text-shadow: 0 0 6px #000, 0 0 2px #000; }
  #captions { position: fixed; left: 40px; right: 40px; bottom: 40px; display: grid; gap: 8px; }
  .line { transition: opacity .3s; }
  .line.partial .text { opacity: .7; }
  .line.speaking .name::after { content: " ●"; color: #6f6; }
  .name { color: #ffd54f; margin-right: .5em; }
  .status { position: fixed; top: 8px; right: 8px; font-size: 14px; opacity: .6; }
</style>
<div id="captions"></div>
<div class="status" id="status"></div>
<script type="module">
  import { subscribe, speakerName } from "./mojiokoshi-subscribe.js";

  // トークンは URL のフラグメント（#）に入れる。フラグメントは、ページを置いたサーバーのログや Referer に残らない。
  const params = new URLSearchParams(location.hash.slice(1));
  const token = params.get("token");
  const server = params.get("server");

  let frame = 0;
  const render = (state) => {
    // 描画は 1 フレームに 1 回にまとめる（partial は数百 ms ごとに届く）
    if (frame) return;
    frame = requestAnimationFrame(() => {
      frame = 0;
      const lastByKey = new Map(); // 話者（不明ならトラック）→ 最後の発話
      for (const u of state.utterances.values()) {
        const key = u.speaker.kind === "unattributed" ? `track:${u.trackId}` : u.speaker.speakerId;
        const last = lastByKey.get(key);
        if (!last || last.startedAt <= u.startedAt) lastByKey.set(key, u);
      }
      const lines = [...lastByKey.values()]
        .sort((a, b) => a.startedAt - b.startedAt)
        .slice(-3) // 最近話した 3 人まで
        .map((u) => {
          const line = document.createElement("div");
          line.className = `line${u.stage === "partial" ? " partial" : ""}${state.speaking.has(u.trackId) ? " speaking" : ""}`;
          const name = document.createElement("span");
          name.className = "name";
          name.textContent = speakerName(state, u); // HTML として解釈させない
          const text = document.createElement("span");
          text.className = "text";
          text.textContent = u.text;
          line.append(name, text);
          return line;
        });
      document.getElementById("captions").replaceChildren(...lines);
    });
  };

  if (!token || !server) {
    document.getElementById("status").textContent = "URL に #token=…&server=… を付けてください";
  } else {
    subscribe({
      url: server,
      token,
      onChange: render,
      onStatus: (status, detail) => {
        const labels = { connecting: "接続中…", reconnecting: "再接続中…", ended: "終了しました", failed: `接続できません（${detail?.code}）` };
        document.getElementById("status").textContent = labels[status] ?? "";
      },
    });
  }
</script>
</html>
```

- **`file://` で開くと、ブラウザが ES モジュールの読み込みを拒むことがあります。** 2 つのファイルは、GitHub Pages・Cloudflare Pages などの静的ホスティングか、ローカルの静的サーバー（`npx serve` など）に置いてください。1 ファイルにしたいときは、参照実装の中身を `<script type="module">` に貼り付けて、`import` の行と `export` を消します。
- `overlay.html` の背景は透明です。OBS のブラウザソースの幅・高さは配信の解像度に合わせ、「カスタム CSS」は空にしておきます。
- `overlay.html` は、`partial` を少し薄く表示し、発話が確定したら普通の濃さにしています。同じ発話は `utteranceId` で置き換わるので、行が増え続けることはありません（[改訂モデル](https://moji.kaitoranma.com/docs/revisions.md)）。
- `overlay.html` は、話している表示（●）を `speech_started` / `speech_ended`（参照実装では `state.speaking`）から作っています。

## セキュリティ

- **トークンはフラグメント（`#token=`）に入れる。** クエリ（`?token=`）に入れたトークンは、ページを置いたサーバーのアクセスログや `Referer` に残ります。
- **API キーをページに埋め込まない。** 配信画面は他人も見るので、ページには `transcript:read` のセッショントークンだけを渡します。
- 表示名と発言は `textContent` で入れる（`innerHTML` を使わない）。
- 文字おこしくんには、トークンを 1 つずつ取り消す仕組みが無いので、自分で発行するトークンの有効期間は、必要な長さより長くしない（[セッショントークンの有効期間](https://moji.kaitoranma.com/docs/limits.md#セッショントークンの有効期間)）。
- Discord のリンクを配信に映してしまったときは、使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md#get-link)の手順で、文字起こしを止めて始め直します。

## よくある作り方

| 作りたいもの | ヒント |
|---|---|
| 1 行の字幕（テロップ） | 全話者の中で `startedAt` が最新の発話を 1 つだけ出す |
| 話者ごとの定位置の吹き出し | 話者の登場順（`state.speakers` の挿入順）で位置を決める。`unattributed` の発話は、トラック単位で出す |
| 過去ログのスクロール | `sortedUtterances(state)` を下から積む。`partial` は最後に来る |
| アバター付き | `welcome.speakers[].speaker.avatarUrl` と `speaker_upserted` の `speaker.avatarUrl` を画像に使う（http / https の URL だけが届く） |

## コーディングエージェント向けのプロンプト

```text
OBS のブラウザソースで使う、文字おこしくんのリアルタイム字幕オーバーレイ（HTML 1 枚 + 参照実装 1 ファイル）を作ってください。
仕様: https://moji.kaitoranma.com/docs/llms.txt
参照実装: https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js（そのまま同じフォルダに置いて import する）

- 接続先とトークンは location.hash の server= と token= から読む（クエリには入れない）。API キーは使わない。
- 背景は透明。画面下に、話者ごとに最後の発話を最大 3 行、話者名つきで出す。partial は薄く、final / refined は普通に。
- 発話は utteranceId で置き換わる（参照実装の state.utterances は Map）。行を追記しない。
- 表示名・発言は textContent で入れる。描画は requestAnimationFrame で 1 フレーム 1 回にまとめる。
- 接続状態（再接続中・終了・失敗）を右上に小さく出す。
- 見た目は CSS 変数（文字色・影・大きさ）で変えられるようにする。
```

---

<!-- source: https://moji.kaitoranma.com/docs/guides/bot-relay.md -->

# ガイド: Discord・他のボットへの中継

> Discord のテキストチャンネルに発言を流すだけなら、プログラムは要りません。Discord サーバーの管理者が管理画面で「発言をテキストチャンネルにも流す」を選ぶと、文字おこしくんが、発言を話した人の名前とアイコンでテキストチャンネルに投稿します（使い方の[発言をテキストチャンネルにも流す](https://moji.kaitoranma.com/help/index.md#relay)）。

あなたのボットは、文字起こしの結果を、別の Discord チャンネル・Slack・Matrix・翻訳や要約の処理などに流せます。あなたのボットはサーバー側で動くので、API キーを安全に持てます。

## 形

1. あなたのボット（サーバー側）が、HTTP（API キー）で動いているセッションを探し、`transcript:read` のトークンを発行します。Discord サーバーの管理者が文字おこしくんの Webhook の送信先を登録し、送る出来事に「文字起こしの開始」を選んでいれば、ボットはセッションを探す代わりに、文字おこしくんが送る `session.started` を受け取ってトークンを発行できます（[Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md#store-transcripts-off)）。
2. ボットが、WebSocket `/v1/subscribe` で発話を受け取ります。
3. ボットが、受け取った発話を転送先（Discord の Webhook・Slack・翻訳 API …）に送ります。

このページの「Discord の Webhook」は Discord のチャンネルにメッセージを投稿するための Discord の仕組みです。Discord の Webhook では、あなたのボットが Discord へメッセージを送ります。文字おこしくんの Webhook（[Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md)）では、文字おこしくんがあなたのボットへ文字起こしの開始と終了を知らせます。

## 押さえどころ

1. **`partial` は流さない。** `partial` は数百 ms ごとに書き換わるので、チャットに流すと荒らしになります。`final` から流します。
2. **`refined` は「前に流した発言の修正」として扱う。** 同じ `utteranceId` の `final` を既に送っていたら、新しいメッセージではなく**編集**（Discord なら Edit Message）にします。`utteranceId` → 転送先のメッセージ ID の表を持ってください。`refined` は `final` の数秒後に来ることも、来ないこともあります。
3. **`revision` を比べる。** 再接続すると、`welcome.recent` で同じ発話がもう一度届きます。送信済みの `revision` 以下の改訂が届いたら、ボットは何もしません（二重投稿を防ぐ）。
4. **転送先のレート制限を守る。** Discord の Webhook などには送信の上限があります。発話が多いときは、数秒ぶんの発話をまとめて 1 通にするなど、キューで送る量を平らにしてください。
5. **期限の前にトークンを取り直す。** 再接続の前に、API キーで新しいトークンを発行してから使います（[トークンの期限](https://moji.kaitoranma.com/docs/reconnection.md#token-expiry)）。
6. **終わりを検知する。** `session_ended` が来たら、そのセッションの購読をやめて、次のセッションを探しに戻ります。Discord サーバーの管理者が文字おこしくんの Webhook の送信先を登録し、送る出来事に「文字起こしの開始」を選んでいれば、ボットは次のセッションが始まったことを `session.started` で知ることができます。

## 例: Discord の Webhook に中継する（Node 22）

参照実装 [mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js) を使った例です。この例のボットは、Discord の Webhook の `?wait=true` で送信したメッセージの ID を受け取り、`refined` が来たら、そのメッセージを編集します。

```js
import { subscribe, speakerName } from "./mojiokoshi-subscribe.js";

const WEBHOOK = process.env.DISCORD_WEBHOOK_URL; // https://discord.com/api/webhooks/<id>/<token>
const posted = new Map(); // utteranceId → { messageId, revision }
const queue = [];

function relay(state, message) {
  if (message.type !== "utterance") return;
  const u = message.utterance;
  if (u.stage === "partial" || u.text.trim() === "") return;
  const sent = posted.get(u.utteranceId);
  if (sent !== undefined && sent.revision >= u.revision) return; // 再接続の welcome.recent などで重複した
  queue.push({ utteranceId: u.utteranceId, revision: u.revision, content: `**${speakerName(state, u)}**: ${u.text}` });
}

// 転送先のレート制限を守るため、1 秒に 1 件ずつ送る（編集も 1 件と数える）
setInterval(async () => {
  const item = queue.shift();
  if (item === undefined) return;
  const sent = posted.get(item.utteranceId);
  const body = JSON.stringify({ content: item.content, allowed_mentions: { parse: [] } }); // メンションさせない
  const headers = { "content-type": "application/json" };
  if (sent === undefined) {
    const response = await fetch(`${WEBHOOK}?wait=true`, { method: "POST", headers, body });
    if (response.ok) posted.set(item.utteranceId, { messageId: (await response.json()).id, revision: item.revision });
  } else {
    await fetch(`${WEBHOOK}/messages/${sent.messageId}`, { method: "PATCH", headers, body });
    sent.revision = item.revision;
  }
}, 1000);

subscribe({
  url: process.env.MOJIOKOSHI_SUBSCRIBE_URL,
  token: process.env.MOJIOKOSHI_TOKEN,
  onChange: relay,
  onStatus: (status, detail) => console.error(status, detail?.code ?? ""),
});
```

- この例は `allowed_mentions: { parse: [] }` で、発言の中の `@everyone` などが実際のメンションにならないようにしています。発言は文字おこしくんが利用者の音声から作った文字列なので、転送先でも「信頼できない入力」として扱ってください。
- ボットを長く動かすなら、`onStatus` に `failed`（`unauthorized` など）が届いたときに、API キーで新しいトークンを発行し、そのトークンで `subscribe()` を呼び直します。

## 翻訳・要約に流すとき

- `final` が届いたら翻訳し、`refined` が来たら訳し直して置き換えます（`refined` の方が句読点・表記が正確です）。
- 要約は `session_ended` の後に HTTP の書き出し（[記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md)）で全文を取ってから作ると確実です。WebSocket は切断中の発話を取り戻せません。
- 発言を外部の API に送る前に、送ることを参加者に伝えてあるかと、利用規約に反しないかを確かめてください（[利用規約](https://moji.kaitoranma.com/legal/terms.html)）。

## コーディングエージェント向けのプロンプト

```text
文字おこしくんの Subscribe WebSocket API から発話を受け取り、Discord の Webhook に中継する Node 22 のボットを書いてください。
仕様: https://moji.kaitoranma.com/docs/llms.txt 、ガイド: https://moji.kaitoranma.com/docs/guides/bot-relay.md
参照実装 examples/mojiokoshi-subscribe.js を使う。

- partial は送らない。final を新しいメッセージとして送り、同じ utteranceId の refined（revision が大きい）は同じメッセージを編集する。utteranceId → { messageId, revision } を持つ。
- 送信済みの revision 以下の改訂は無視する（再接続の welcome.recent で重複して届く）。
- 送信はキューにして 1 秒に 1 件まで。allowed_mentions は空にする。
- 設定（Subscribe の URL、トークン、API キー、Discord の Webhook の URL、文字おこしくんの Webhook の署名のシークレット）は環境変数から読む。API キー・トークン・シークレットをログに出さない。
- session_ended で止まる。failed（unauthorized）になったら新しいトークンを取り直す関数を呼ぶ（取り方は差し替え可能にする）。
- 次のセッションは、文字おこしくんの Webhook の session.started（署名を生の本文で確かめる。https://moji.kaitoranma.com/docs/webhooks.md）で知るか、API キーで GET /v1/sessions?status=active を読んで探す（どちらにするかは差し替え可能にする）。
- 転送の判断（新規 / 編集 / 無視）を純粋関数にして、偽のメッセージ列でテストする。
```

---

<!-- source: https://moji.kaitoranma.com/docs/guides/archive.md -->

# ガイド: 記録と書き出し

あなたは文字起こしの記録を、議事録として残したり、検索できるようにしたり、別のシステムに取り込んだりできます。

## 2 つの取り方

| 方法 | いつ | 長所 | 短所 |
|---|---|---|---|
| **HTTP で書き出す**（`GET /v1/sessions/:id/transcript`） | セッションが終わった後（途中でも可） | 全文が確実に取れる。整形後（`refined`）のテキストと整形前（`rawText`）の両方を取れる | リアルタイムではない |
| **WebSocket で受け取りながら保存する** | セッション中 | 発話をリアルタイムに保存できる | 切断中の発話は取り戻せない。最後に HTTP で書き出して比べると確実 |

**記録はセッションの終了から保持期間（Discord サーバーのレベルにより 30〜365 日）が過ぎると消えます。** 記録が消えた後は、書き出しが `404 session_not_found` になり、記録は戻せません。残したい記録は保持期間の内に書き出してください。

## HTTP で書き出す

```sh
# JSON で書き出す（既定）
curl -s "$BASE/v1/sessions/$SID/transcript" -H "Authorization: Bearer $TOKEN" -o transcript.json

# テキストで書き出す（タイムゾーンは tz で指定する。既定は Asia/Tokyo）
curl -s "$BASE/v1/sessions/$SID/transcript?format=text&tz=UTC" -H "Authorization: Bearer $TOKEN"

# CSV で書き出す（見出しは「日時,話者,発言」。Excel で開けるように、先頭に BOM が付く）
curl -s "$BASE/v1/sessions/$SID/transcript?format=csv" -H "Authorization: Bearer $TOKEN" -o transcript.csv
```

- `$TOKEN` には、`$SID` のセッションの `transcript:read` のトークン（セッションが終わった後も発行できる）か、`transcripts:read` の API キー（[HTTP API](https://moji.kaitoranma.com/docs/http.md#exportTranscript)）を入れます。
- 文字おこしくんは、長いセッションでも受け取れるように、応答を少しずつ流します。文字おこしくんの API 全体で同時に流せる書き出しには上限があります。上限を超えると、文字おこしくんは `429 rate_limited` を返します（`Retry-After` の秒数の後にやり直してください）。
- 資格情報を持たない人（チャットの参加者など）に記録を渡すときは、あなたのサーバー側のコードが、`transcripts:read` の API キーで書き出しのリンクを作れます（`POST /v1/sessions/:id/downloads`。[HTTP API](https://moji.kaitoranma.com/docs/http.md#createTranscriptDownloads)）。リンクを開いた人のブラウザは、記録を CSV・JSON・テキストのファイルとして保存します。リンクに `&disposition=inline` を足すと、ブラウザは、記録をファイルとして保存せずに、ページとして表示します。応答の `chatgptUrl` は、記録を ChatGPT に渡して要約を頼むリンクです（[HTTP API](https://moji.kaitoranma.com/docs/http.md#openTranscriptInChatGpt)）。文字おこしくんは、リンクを 1 つずつ取り消せないので、リンクの有効期間（`ttlSeconds`。既定 1 時間）は必要な長さより長くしないでください。

JSON の形:

```json
{
  "sessionId": "0f0c3c1e-…",
  "label": "#雑談 VC",
  "speakers": [{ "speakerId": "discord:1", "displayName": "たろう", "avatarUrl": "https://cdn.discordapp.com/…" }],
  "utterances": [
    {
      "utteranceId": "utt_01",
      "trackId": "discord:1",
      "speakerId": "discord:1",
      "speakerName": "たろう",
      "stage": "refined",
      "text": "こんにちは、今日はよろしくお願いします。",
      "rawText": "こんにちは今日はよろしくお願いします",
      "startedAt": 1790350826814
    }
  ]
}
```

- `utterances` は、発話ごとの最新の改訂（`final` か `refined`。認識途中は含まない）を、`startedAt` の順に並べたものです。
- `rawText` は整形前の音声認識の結果で、`text` は整形後の結果です（整形しなかったら、`rawText` と同じです）。
- 話者が分からない発話には、`speakerId` が付かず、`speakerName` はトラック名などの代替名になります。

## WebSocket で受け取りながら保存する

保存は **`utteranceId` をキーにした upsert** にし、**`revision` が大きいときだけ**上書きします。文字おこしくんは、同じ発話を `final` → `refined` と送り、再接続の `welcome.recent` でも同じ発話をもう一度送ります。

```sql
CREATE TABLE utterances (
  session_id   TEXT    NOT NULL,
  utterance_id TEXT    NOT NULL,
  track_id     TEXT    NOT NULL,
  speaker_id   TEXT,               -- unattributed なら NULL
  stage        TEXT    NOT NULL,   -- final / refined（partial は保存しない）
  revision     INTEGER NOT NULL,
  text         TEXT    NOT NULL,
  started_at   INTEGER NOT NULL,   -- エポックミリ秒
  PRIMARY KEY (session_id, utterance_id)
);

-- 新しい改訂のときだけ上書きする（古い・重複した改訂は何もしない）
INSERT INTO utterances VALUES (:session_id, :utterance_id, :track_id, :speaker_id, :stage, :revision, :text, :started_at)
ON CONFLICT (session_id, utterance_id) DO UPDATE SET
  track_id = excluded.track_id, speaker_id = excluded.speaker_id, stage = excluded.stage,
  revision = excluded.revision, text = excluded.text, started_at = excluded.started_at
WHERE excluded.revision > utterances.revision;
```

- `partial` は保存しなくてよい（すぐに置き換わる）。
- 話者の表示名は別の表に `speakerId` → 表示名で持ち、`speaker_upserted` で更新します（名前は途中で変わることがあります）。
- `session_ended` を受け取ったら、HTTP の書き出しで記録を取り直して、保存した発話と**比べ**ます（切断中の取りこぼしを埋める）。書き出しの `utteranceId` は、WebSocket で届いた `utteranceId` と同じです。

## セッションを探す

### 終わったときに書き出す（Webhook） {#on-session-ended}

Discord サーバーの管理者が Webhook の送信先を登録し、送る出来事に「文字起こしの終了」を選ぶと、文字おこしくんはセッションが終わるたびに `session.ended` をあなたのサーバーへ送ります（[Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md)）。あなたのサーバーは `session.ended` を受け取ったら、`data.sessionId` のセッションの記録を書き出せます。文字おこしくんは確定した発言を保存し終えてから `session.ended` を送るので、あなたのサーバーが `session.ended` を受け取ってから書き出す記録には終わりまでの発言が入ります。新しく終わったセッションを探して一覧を読み直す必要はありません。

署名を確かめる依存なしの参照実装 [examples/mojiokoshi-webhook.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-webhook.ts) と依存なしのクライアント [examples/mojiokoshi-http.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-http.ts) を使う例:

```ts
// archive-webhook.mts — node archive-webhook.mts（Node 22.18 以降。2 つの例のファイルを同じフォルダに置く）
import { writeFile } from "node:fs/promises";
import { createServer } from "node:http";
import { createMojiokoshiHttp } from "./mojiokoshi-http.ts";
import { MojiokoshiWebhookError, verifyMojiokoshiWebhook } from "./mojiokoshi-webhook.ts";

const api = createMojiokoshiHttp({ apiKey: process.env.MOJIOKOSHI_API_KEY! }); // transcripts:read
const secret = process.env.MOJIOKOSHI_WEBHOOK_SECRET!; // whsec_…（ソースに書かず、環境変数などから読む）

createServer((request, response) => {
  const chunks: Buffer[] = [];
  request.on("data", (chunk: Buffer) => chunks.push(chunk));
  request.on("end", async () => {
    let event;
    try {
      event = await verifyMojiokoshiWebhook(Buffer.concat(chunks), request.headers, secret); // JSON として読む前の生の本文で確かめる
    } catch (error) {
      response.writeHead(error instanceof MojiokoshiWebhookError ? 400 : 500).end();
      return;
    }
    response.writeHead(204).end(); // 書き出す前に 2xx を返す（文字おこしくんは 15 秒で待つのをやめる）
    if (event.type !== "session.ended") return; // session.started・webhook.test・知らない出来事には何もしない
    try {
      // 同じ出来事が 2 回届いても、同じファイルを書き直すだけで済む
      const transcript = await api.exportTranscript(event.data.sessionId);
      await writeFile(`${event.data.sessionId}.json`, JSON.stringify(transcript, null, 2));
    } catch (error) {
      console.error("書き出せませんでした", event.data.sessionId, error);
    }
  });
}).listen(8787);
```

- Discord サーバーの管理者が発言を保存しない設定にしていると書き出しには何も入らないので、あなたのサーバーは `session.started` を受け取ったらすぐに WebSocket で発言を受け取りながら保存を始めてください（[「保存しない」設定で記録を残す](https://moji.kaitoranma.com/docs/webhooks.md#store-transcripts-off)）。
- 文字おこしくんが止まっている間は、文字おこしくんは `session.ended` を送りません。文字おこしくんは再起動すると、送れていない出来事から送ります（[届け方](https://moji.kaitoranma.com/docs/webhooks.md#delivery)）。
- Discord サーバーの管理者か文字おこしくんが送信先を止めている間にセッションが終わると、文字おこしくんはそのセッションの `session.ended` を後から送りません（[送らないとき](https://moji.kaitoranma.com/docs/webhooks.md#not-sent)）。あなたは送信先が止まっている間に終わったセッションを[決まった時刻に一覧を読む](#by-schedule)方法で探せます。

### 決まった時刻に一覧を読む {#by-schedule}

`transcripts:read` の API キーがあれば、Discord サーバー（テナント）のセッションを一覧できます。

```sh
# 終わったセッションを新しい順に一覧する（続きは、nextCursor を cursor に渡して取る）
curl -s "$BASE/v1/sessions?status=ended&limit=20" -H "Authorization: Bearer $KEY"
```

毎日決まった時刻に、前回の実行の後に終わったセッションを書き出す、という使い方ができます。依存なしのクライアント [examples/mojiokoshi-http.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-http.ts) を使う例:

```ts
// archive.mts — node archive.mts（Node 22.18 以降。mojiokoshi-http.ts を同じフォルダに置く）
import { writeFile } from "node:fs/promises";
import { createMojiokoshiHttp, MojiokoshiHttpError } from "./mojiokoshi-http.ts";

const api = createMojiokoshiHttp({ apiKey: process.env.MOJIOKOSHI_API_KEY! }); // transcripts:read
const since = Number(process.env.SINCE ?? 0); // 前回の実行時刻（エポックミリ秒）

// セッションは新しい順に届くので、前回の実行の 1 日前より前に作られたセッションまで来たら、ループを止める（nextCursor は allSessions がたどる）。
for await (const session of api.allSessions({ status: "ended", limit: 100 })) {
  if (session.createdAt < since - 86_400_000) break;
  if ((session.endedAt ?? 0) < since) continue;
  try {
    const transcript = await api.exportTranscript(session.sessionId); // 429 なら、api が Retry-After の秒数だけ待って、自動でやり直す
    await writeFile(`${session.sessionId}.json`, JSON.stringify(transcript, null, 2));
  } catch (error) {
    if (error instanceof MojiokoshiHttpError && error.code === "session_not_found") continue; // 保持期間を過ぎて、記録が消えた
    throw error;
  }
}
```

エンドポイントの詳細は、[HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md#listSessions)にあります。

## コーディングエージェント向けのプロンプト

```text
文字おこしくんのセッションの文字起こしを、終わった後に書き出して SQLite に保存するスクリプトを書いてください。
仕様: https://moji.kaitoranma.com/docs/guides/archive.md

- 書き出しは GET /v1/sessions/:id/transcript（Authorization: Bearer <transcript:read のトークンか API キー>）。JSON の utterances を保存する。
- 保存は (session_id, utterance_id) を主キーにした upsert で、revision が大きいときだけ上書きする（WebSocket から保存した行と突き合わせても壊れないように）。
- 429 rate_limited なら Retry-After の秒数だけ待ってやり直す。404 session_not_found は保持期間を過ぎたものとして記録して飛ばす。
- 資格情報は環境変数から読み、ログに出さない。
- HTTP は注入した fetch で呼び、偽の応答でテストする。
- 文字おこしくんの Webhook の session.ended を受けて書き出すときは、署名を JSON として読む前の生の本文で確かめ（https://moji.kaitoranma.com/docs/webhooks.md）、書き出す前に 2xx を返す。同じ webhook-id が 2 回届いても記録が壊れないようにする。
```

---

<!-- source: https://moji.kaitoranma.com/docs/guides/analytics.md -->

# ガイド: 分析（発言量・話者ごとの統計）

あなたは会議や配信の「誰がどれだけ話したか」「いつ盛り上がったか」を集計できます。

## どのデータを使うか

| 知りたいこと | データ | 注意 |
|---|---|---|
| 話者ごとの発言数・文字数 | 書き出しの JSON の `utterances`（`final` / `refined` だけが入っている） | セッションが終わった後の書き出しで集計すると確実 |
| 時間帯ごとの発言の多さ | `startedAt`（エポックミリ秒） | `startedAt` は、文字おこしくんが最初の音声を受け取った時刻を表す。`startedAt` は、話者をまたいで比べてよい |
| 話している時間 | WebSocket の `speech_started` / `speech_ended`（トラック単位） | リアルタイムに受け取って自分で数える。書き出しには入らない |
| 音声認識にかけた音声の秒数（利用量） | [`GET /v1/usage`](https://moji.kaitoranma.com/docs/http.md#getUsage)（`usage:read` の API キー） | 利用量は UTC の日ごとに出る。文字おこしくんは、利用量をトラックごとに数えて足す（2 人が同時に話せば 2 倍になる） |

- **`partial` は集計に使わない**でください。同じ発話が何度も届くので、数えると何倍にもなります。
- 話者分離が推定した話者（`inferred`）の発話は、後の改訂で別の `speakerId` の話者に付け替わることがあります。リアルタイムに集計するなら、`utteranceId` ごとに最新の改訂だけを数え直してください。
- 話者が分からない発話（書き出しでは `speakerId` が無い）は、トラック単位でまとめるか「不明」として別に数えます。

## 例: 書き出しから話者ごとの発言量を出す（Node）

```js
// node stats.mjs transcript.json
import { readFileSync } from "node:fs";

const transcript = JSON.parse(readFileSync(process.argv[2], "utf8"));
const stats = new Map(); // 話者 → { name, count, chars, first, last }
for (const u of transcript.utterances) {
  const key = u.speakerId ?? `track:${u.trackId}`;
  const s = stats.get(key) ?? { name: u.speakerName, count: 0, chars: 0, first: u.startedAt, last: u.startedAt };
  s.count += 1;
  s.chars += [...u.text].length; // コードポイント数で数える
  s.last = Math.max(s.last, u.startedAt);
  stats.set(key, s);
}
const total = [...stats.values()].reduce((sum, s) => sum + s.chars, 0) || 1;
for (const s of [...stats.values()].sort((a, b) => b.chars - a.chars)) {
  console.log(`${s.name}\t${s.count} 回\t${s.chars} 文字\t${((s.chars / total) * 100).toFixed(1)}%`);
}
```

## 例: 5 分ごとの発言数（Python）

```python
import json, sys
from collections import Counter
from datetime import datetime, timezone, timedelta

transcript = json.load(open(sys.argv[1], encoding="utf-8"))
jst = timezone(timedelta(hours=9))
buckets = Counter()
for u in transcript["utterances"]:
    t = datetime.fromtimestamp(u["startedAt"] / 1000, jst)
    buckets[t.replace(minute=t.minute - t.minute % 5, second=0, microsecond=0)] += 1
for t, n in sorted(buckets.items()):
    print(t.strftime("%H:%M"), "#" * n)
```

## 例: 話している時間をリアルタイムに数える

```js
const speakingSince = new Map(); // trackId → 話し始めた時刻（受信時刻）
const speakingMs = new Map();    // trackId → 合計

function onMessage(m) {
  if (m.type === "speech_started" && !speakingSince.has(m.trackId)) speakingSince.set(m.trackId, Date.now());
  if (m.type === "speech_ended" || m.type === "track_closed") {
    const since = speakingSince.get(m.trackId);
    if (since !== undefined) speakingMs.set(m.trackId, (speakingMs.get(m.trackId) ?? 0) + Date.now() - since);
    speakingSince.delete(m.trackId);
  }
  if (m.type === "welcome") {
    // 再接続: 切断中の分は分からないので、今話しているトラックから数え直す
    speakingSince.clear();
    for (const trackId of m.speakingTrackIds) speakingSince.set(trackId, Date.now());
  }
}
```

あなたは `welcome.tracks` と `track_opened` で届くトラックのうち、`mode: "single"` のトラックの `speakerId` から、トラックと話者の対応を取れます（`mixed` のトラックには複数人の声が入っています）。

## プライバシー

発言量の集計も、参加者の発言に関する情報です。集計は参加者に伝えた目的の範囲で使い、集計を公開する場合は本人の了承を得てください（[プライバシーポリシー](https://moji.kaitoranma.com/legal/privacy.html)）。

## コーディングエージェント向けのプロンプト

```text
文字おこしくんの書き出し JSON（GET /v1/sessions/:id/transcript）から、話者ごとの発言回数・文字数・割合と、5 分ごとの発言数を集計して CSV に出すスクリプトを書いてください。
仕様: https://moji.kaitoranma.com/docs/guides/analytics.md

- utterances には final / refined だけが入っている。speakerId が無い発話は track:<trackId> として数える。
- 文字数はコードポイント数で数える。時刻は startedAt（エポックミリ秒）を Asia/Tokyo に変換する。
- リアルタイム版を作る場合は partial を数えず、utteranceId ごとに最新の改訂だけを数え直す（inferred の話者は付け替わる）。
- 入力 JSON の小さな fixture でテストする。
```

---

<!-- source: https://moji.kaitoranma.com/docs/ingest.md -->

# 音声を送る（Ingest）

Ingest は、Discord 以外の音声（マイク・録音ファイル・別の通話アプリの参加者ごとの音声など）を文字おこしくんに送るための API です。文字おこしくんは、あなたが送った音声を、話者ごとに文字にします。あなたは文字起こしの結果を、公式の表示ページ・配信用オーバーレイで見ることも、Subscribe の API で受け取ることもできます。

> Discord のボイスチャンネルの文字起こしには、公式のボットを使ってください。

## 前提

- **1 つのセッションに Ingest の接続は 1 本だけ**です。同じセッションに新しい接続が来ると、文字おこしくんは古い方の接続を `superseded` で切ります。公式のボットが使っているセッションに音声を送ると、ボットが止まります。**自分のセッションを作って**、音声を送ってください。
- 複数の話者の音声は、1 本の接続の中で、複数の**トラック**として送ります。
- 音声を送るには、`ingest:write` のセッショントークンが要ります。スコープ `ingest:write` の API キー（作り方は[クイックスタート](https://moji.kaitoranma.com/docs/quickstart.md#from-api-key)）でセッションを作ると、応答にトークンが入っています（[HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md#createSession)）。

```sh
# セッションを作る（セッションは API キーのテナントに属する。文字おこしくんは利用上限を確かめる）
curl -s -X POST "$BASE/v1/sessions" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label":"会議室マイク","externalRef":"my-app:room-42","reuseActive":true}'
# → { "sessionId": "…", "ingest": { "url": "wss://…/v1/ingest", "token": "…" }, "subscribe": { … }, "viewerUrl": "…", "overlayUrl": "…" }

# 文字起こしが終わったら、セッションを終える
curl -s -X POST "$BASE/v1/sessions/$SID/end" -H "Authorization: Bearer $KEY"
```

## 接続の流れ

1. 接続したら、最初に `hello` を送り、`welcome` を受け取るまでほかのメッセージを送らない。
2. `welcome` を受け取ったら、**現在の状態をすべて**送る（全話者の `speaker_upsert`、全トラックの `track_open`）。
3. `state_synced` を送る。音声は `state_synced` の後に送る（文字おこしくんは、`state_synced` の前に届いた音声を捨てることがある）。
4. `state_synced` を送った後は、クライアントは、話者・トラックの変化を差分として随時送る。

| メッセージ | 送る側 | 送る時期 |
|---|---|---|
| `hello` | クライアント | 接続した直後。`protocolVersion: 1` と `token` を入れる |
| `welcome` | 文字おこしくん | `hello` を受け付けたとき。`sessionId` が入っている。受け付けなかったときは、文字おこしくんが fatal な `error` を送ってから接続を切る |
| `speaker_upsert` | クライアント | `welcome` の後に、話者の数だけ |
| `track_open` | クライアント | `speaker_upsert` の後に、開いているトラックの数だけ |
| `state_synced` | クライアント | 今の状態を送り終えたとき。文字おこしくんは、`state_synced` を受け取るまでに宣言がなかったトラックを閉じる |
| 音声フレーム（バイナリ） | クライアント | `state_synced` の後に、20ms ごと |
| `speech_start` / `speech_end` | クライアント | 発話区間の始まりと終わりで |
| `ping` | クライアント | 15 秒ごと |
| `pong` | 文字おこしくん | `ping` を受け取ったとき |
| `error` | 文字おこしくん | エラーが起きたとき。`error` が入っている。特定のトラックに関するエラーでは、`trackId` も入っている。非 fatal なら、クライアントはそのまま続けてよい |

順序の決まり:

- `single` トラックの話者は、そのトラックの `track_open` より前に、`speaker_upsert` で宣言する（宣言していなければ、文字おこしくんは `unknown_speaker` を返す）。
- `speaker_remove` の前に、その話者の `single` トラックを `track_close` する。
- `channel` は、接続の中で一意にする（使用中の番号には、文字おこしくんが `channel_in_use` を返す）。`track_close` の後は、同じ番号を再利用してよい。

## トラックと音声の形式

| 項目 | 決まり |
|---|---|
| トラックの種類 | トラックの種類は `single` か `mixed` にする。`single` では、1 トラックで 1 人の話者の音声を送る（話者は、先に `speaker_upsert` で宣言する）。`mixed` では、複数人の声をまとめた音声を送る。`diarize: true` なら、文字おこしくんが話者を分離して「話者 1」「話者 2」…として表示し、`false` ならトラック単位で表示する |
| `opus` | `opus` では、48000 Hz だけを使い、1 か 2 ch の音声を送る。**生の Opus パケット 1 個を、1 フレームで送る**（Ogg・WebM などのコンテナに入れない） |
| `pcm_s16le` | `pcm_s16le` では、8000〜48000 Hz で、1 か 2 ch の音声を送る。音声は符号付き 16 bit の**リトルエンディアン**で送り、2 ch はインターリーブする（L R L R …） |
| 送り方 | 音声は 20ms 程度ずつ、**実時間の速さで 1 フレームずつすぐ送る**（まとめて送らない。まとめると遅延が増え、認識も不安定になる） |
| 上限 | 1 つの接続で、トラックは 64 本まで開け、話者は 256 人まで宣言できる。文字おこしくんは、API キーで作ったセッションで開いているトラックを、全部の API キー（ほかの利用者のキーを含む）で合わせて数え、同時に 20 本までにする。1 メッセージは 64 KiB までにする（数は[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)にある） |
| 話者の表示名 | 表示名は 100 文字までにする |
| 発話区間 | 発話区間が分かるなら、発話区間の始まりと終わりを `speech_start` / `speech_end` で知らせる。知らせると、確定（`final`）が早く出る |

扱えない形式には、文字おこしくんが非 fatal な `unsupported_format`（`trackId` 付き）を返します。

## 音声バイナリフレーム {#binary-frame}

クライアントは、WebSocket の**バイナリフレーム 1 個で、音声フレームを 1 個**送ります。7 バイトのヘッダ（**ビッグエンディアン**）の後に、payload が続きます。

| フィールド（位置と型） | 内容 |
|---|---|
| frame type（offset 0 から 1 バイト、u8） | 常に `0x01`（audio）にする |
| channel（offset 1 から 2 バイト、u16 BE） | `track_open` で割り当てた番号（0〜65535）を入れる |
| sequence（offset 3 から 4 バイト、u32 BE） | トラックごとに 1 ずつ増やす。2^32 で 0 に折り返す |
| payload（offset 7 から最後まで、bytes） | `opus` では Opus のパケットを 1 個、`pcm_s16le` では PCM（リトルエンディアン）を入れる |

例: `channel = 1`、`sequence = 42`、payload が Opus の無音フレーム `f8 ff fe` の 3 バイトのとき、10 バイトのフレームになります。

```text
01 00 01 00 00 00 2a f8 ff fe
```

| バイト（16 進） | 内容 |
|---|---|
| `01` | frame type（`0x01` = audio） |
| `00 01` | channel（1） |
| `00 00 00 2a` | sequence（42） |
| `f8 ff fe` | payload（Opus の無音フレーム） |

- ヘッダはビッグエンディアンで、PCM の payload はリトルエンディアンです。2 つを間違えないように注意してください。
- `frame type` が `0x01` 以外、または 7 バイト未満のフレームは不正です。文字おこしくんは、開いていない `channel` のフレームを捨てます（`unknown_track` を返すことがあります）。

```js
// JavaScript（ブラウザ / Node）: フレームを作る
function audioFrame(channel, sequence, payload /* Uint8Array */) {
  const frame = new Uint8Array(7 + payload.byteLength);
  const view = new DataView(frame.buffer);
  view.setUint8(0, 0x01);
  view.setUint16(1, channel);           // ビッグエンディアン（DataView の既定）
  view.setUint32(3, sequence >>> 0);    // 2^32 で折り返す
  frame.set(payload, 7);
  return frame;
}
```

```python
# Python: フレームを作る
import struct

def audio_frame(channel: int, sequence: int, payload: bytes) -> bytes:
    return struct.pack(">BHI", 0x01, channel, sequence & 0xFFFFFFFF) + payload
```

## sequence（通し番号）

- `sequence` は、**トラックごと**に 0 から始めて、フレームごとに 1 ずつ増やします。`sequence` は 2^32 で 0 に戻ります。
- 文字おこしくんは欠番を検出して、少しの欠け（5 フレームまで）を補間（Opus は PLC、PCM は無音）で埋めます。5 フレームより長い欠けは埋めずに、文字おこしくんは欠けの後に届いた番号から数え直します。
- 文字おこしくんは、少しだけ戻った番号（64 以内）を、重複か遅延として捨てます。番号が大きく戻ったら、文字おこしくんは、送信側が数え直したとみなして受け入れます。
- 再接続の後は、0 から数え直して構いません（文字おこしくんは、接続をまたいだ番号の連続性を前提にしていません）。

## state_synced と再接続

`state_synced` は「接続直後の状態の送り直しが終わった」という合図です。文字おこしくんは、`state_synced` を受け取った時点で、クライアントが宣言しなかったトラックを閉じます（再接続の間に消えたトラックの後始末のため）。

再接続では:

1. `hello` からやり直し、`welcome` の後に**今の**全話者・全トラックを送り、`state_synced` を送る。
2. 同じトラックには同じ `trackId` を使う（`channel` は振り直してよい）。
3. 切断中の音声は上限付き（例: 1 トラック 2 秒）で溜め、`state_synced` の後に送る。溢れたら古いものから捨てる。
4. 切断中の `speech_start` / `speech_end` も、溜めた音声との前後を保って `state_synced` の後に送る。今話しているトラックは、`track_open` と `state_synced` の間に `speech_start` を送ってもよい。
5. 文字おこしくんは、送り直さなかった**話者**を消さずに残す。クライアントは、切断中に消した話者を、再接続の後に `speaker_upsert` → `speaker_remove` で消す。

再接続せずに終えるべきエラー（`unauthorized` / `session_ended` / `superseded` / `quota_exceeded` など）と、バックオフについては[再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md)を見てください。

## 例: 1 人の話者の PCM を送る（Python）

WAV（リニア PCM 16 bit）を実時間の速さで送る最小の例です（この例は再接続を省いています）。

```python
import asyncio, json, struct, sys, wave
import websockets

async def main(url: str, token: str, path: str) -> None:
    with wave.open(path, "rb") as wav:
        assert wav.getsampwidth() == 2 and wav.getnchannels() in (1, 2)
        rate, channels = wav.getframerate(), wav.getnchannels()
        pcm = wav.readframes(wav.getnframes())
    frame_bytes = rate // 50 * channels * 2  # 20ms
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({"type": "hello", "protocolVersion": 1, "token": token, "clientName": "wav-sender/1.0"}))
        welcome = json.loads(await ws.recv())
        if welcome["type"] != "welcome":
            raise SystemExit(welcome)
        await ws.send(json.dumps({"type": "speaker_upsert", "speaker": {"speakerId": "me", "displayName": "わたし"}}))
        await ws.send(json.dumps({"type": "track_open", "trackId": "mic", "channel": 0,
                                  "format": {"codec": "pcm_s16le", "sampleRate": rate, "channels": channels},
                                  "track": {"mode": "single", "speakerId": "me"}}))
        await ws.send(json.dumps({"type": "state_synced"}))
        await ws.send(json.dumps({"type": "speech_start", "trackId": "mic"}))
        loop = asyncio.get_running_loop()
        started = loop.time()
        for seq, offset in enumerate(range(0, len(pcm), frame_bytes)):
            await ws.send(struct.pack(">BHI", 1, 0, seq & 0xFFFFFFFF) + pcm[offset:offset + frame_bytes])
            await asyncio.sleep(max(0.0, started + (seq + 1) * 0.02 - loop.time()))  # 実時間の速さで
        await ws.send(json.dumps({"type": "speech_end", "trackId": "mic"}))
        await asyncio.sleep(3)  # 最後の final が出るのを待つ

asyncio.run(main(*sys.argv[1:4]))
```

音声ファイルの変換の例: `ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le input.wav`

## コーディングエージェント向けのプロンプト

```text
文字おこしくんの Ingest WebSocket API（/v1/ingest）に音声を送るクライアントを書いてください。
仕様: https://moji.kaitoranma.com/docs/ingest.md と asyncapi.yaml、
JSON Schema（https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json）。

- 接続後 hello {protocolVersion:1, token} → welcome を待つ → 全話者の speaker_upsert → 全トラックの track_open → state_synced の順に送る。再接続のたびにこれを最初からやり直す。
- 音声は 7 バイトのヘッダ（u8 0x01、u16 BE channel、u32 BE sequence）+ payload のバイナリフレームで、20ms ごとに 1 個ずつ実時間の速さで送る。PCM は s16le（リトルエンディアン）、Opus は 48kHz の生パケット 1 個。
- sequence はトラックごとに 1 ずつ増やし 2^32 で折り返す。
- speech_start / speech_end を送る。切断中の音声は 1 トラック 2 秒まで溜め、state_synced の後に区切りと前後を保って送る。
- 1 セッションに Ingest 接続は 1 本だけ（superseded で止まる）。unauthorized / session_ended / superseded / quota_exceeded / fatal な invalid_message では再接続しない。
- トークンは ingest:write のセッショントークンを環境変数から読む。送るメッセージは JSON Schema で検証するテストを書く。
```

---

<!-- source: https://moji.kaitoranma.com/docs/reference.md -->

# WebSocket API リファレンス

| エンドポイント | 用途 | トークンの権限 | protocolVersion |
|---|---|---|---|
| `wss://<host>/v1/subscribe` | 文字起こし結果を受け取る | `transcript:read` | 1 |
| `wss://<host>/v1/ingest` | 音声を送る | `ingest:write` | 1 |

機械可読な版は [asyncapi.yaml](https://moji.kaitoranma.com/docs/asyncapi.yaml)（AsyncAPI 3.1）と [schemas/](https://moji.kaitoranma.com/docs/schemas/common.json)（JSON Schema 2020-12）にあります。

## 共通の決まり

- クライアントと文字おこしくんは、制御メッセージを、WebSocket のテキストフレーム 1 個に UTF-8 の JSON オブジェクトを 1 個ずつ入れて送る。`type` がメッセージの種類を表す。
- **クライアントは、認証のトークンを最初の `hello` メッセージで送る。** トークンを URL・ヘッダー・サブプロトコルには載せない。トークンはセッション単位の短期のもので、API キーではない。
- 受け手は未知のフィールドを無視する（前方互換）。送り手は任意フィールドを省くか `null` にする。受け手は未知の `type` のメッセージを不正なメッセージとして扱う。
- 文字おこしくんは、文字列の長さを、Unicode のコードポイントの数で数える。クライアントと文字おこしくんは、1 メッセージを 64 KiB までにし、permessage-deflate を使わない。
- 文字おこしくんは、エラーを `{"type":"error","error":{"code","message","fatal"}}` の形で送る。`fatal: true` なら、文字おこしくんはこの後に接続を閉じる。文字おこしくんは WebSocket の close code を規定しない。クライアントは、切れた理由を、直前に受け取った `error.code` で判断する。
- 文字おこしくんは、非 fatal な `error` を送った後に接続を切ることがある。たとえば、hello のタイムアウトの後と、受信が文字おこしくんからの送信に追いつかないクライアントへの `rate_limited` の後に、文字おこしくんは接続を切る。クライアントは、この切断を予期しない切断として扱い、短いバックオフで再接続する。

クライアントがいつ再接続し、いつ再接続せずに終えるかは、[再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md)にあります。

## Subscribe（`/v1/subscribe`）

接続の流れ: `hello` → `welcome`（スナップショット）→ 差分のイベント → `session_ended`。受け手は `utteranceId` ごとに `revision` が最大の発話だけを採用します（[改訂モデル](https://moji.kaitoranma.com/docs/revisions.md)）。

### クライアント → サーバー

#### `hello`

クライアントは、接続の直後に hello を 1 回だけ送る。

スキーマ: [`schemas/subscribe-client-message.json#/$defs/Hello`](https://moji.kaitoranma.com/docs/schemas/subscribe-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"hello"` | ✓ |  |
| `protocolVersion` | [ProtocolVersion](#common-protocolversion) | ✓ |  |
| `token` | [Token](#common-token) | ✓ |  |

例: 接続直後の名乗り

```json
{"type":"hello","protocolVersion":1,"token":"eyJ2IjoxLCJzaWQiOiJzZXNfMDEiLCJzY29wZSI6InRyYW5zY3JpcHQ6cmVhZCJ9.c2lnbmF0dXJl"}
```

#### `ping`

ブラウザは WebSocket の ping フレームを扱えないので、クライアントは、生存確認とプロキシのアイドル切断の防止のために ping を送る。文字おこしくんは pong を返す。

スキーマ: [`schemas/subscribe-client-message.json#/$defs/Ping`](https://moji.kaitoranma.com/docs/schemas/subscribe-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"ping"` | ✓ |  |

例: 生存確認（15 秒ごとなど）

```json
{"type":"ping"}
```

### サーバー → クライアント

#### `welcome`

文字おこしくんは、接続した時点の状態のスナップショットを welcome で送る。受け手は状態を丸ごと置き換える（再接続のときも）。recent は、直近の発話の最新の改訂を startedAt の昇順に並べたものである（認識途中を含む）。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/Welcome`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"welcome"` | ✓ |  |
| `protocolVersion` | [ProtocolVersion](#common-protocolversion) | ✓ |  |
| `sessionId` | [ServerId](#common-serverid) | ✓ |  |
| `speakers` | array<object> | ✓ |  |
| `speakers[].speaker` | object | ✓ | Subscribe で文字おこしくんが送る話者を表す。 |
| `speakers[].speaker.speakerId` | [ServerId](#common-serverid) | ✓ |  |
| `speakers[].speaker.displayName` | [DisplayName](#common-displayname) | ✓ |  |
| `speakers[].speaker.avatarUrl` | [AvatarUrl](#common-avatarurl) |  |  |
| `speakers[].inferred` | boolean | ✓ |  |
| `tracks` | array<object> | ✓ |  |
| `tracks[]` | object（下のいずれか） | ✓ | トラックを表す。single は 1 人の話者だけのトラックを、mixed は複数の話者の声が入ったトラックを表す。 |
| `tracks[].trackId` | [ServerId](#common-serverid) | ✓ | mode が "single" のとき |
| `tracks[].mode` | `"single"` | ✓ | mode が "single" のとき |
| `tracks[].speakerId` | [ServerId](#common-serverid) | ✓ | mode が "single" のとき |
| `tracks[].trackId` | [ServerId](#common-serverid) | ✓ | mode が "mixed" のとき |
| `tracks[].mode` | `"mixed"` | ✓ | mode が "mixed" のとき |
| `speakingTrackIds` | array<[ServerId](#common-serverid)> | ✓ | 発声中のトラックを表す。 |
| `recent` | array<object> | ✓ |  |
| `recent[].utteranceId` | [ServerId](#common-serverid) | ✓ |  |
| `recent[].trackId` | [ServerId](#common-serverid) | ✓ |  |
| `recent[].speaker` | object（下のいずれか） | ✓ | 発話の話者を表す。declared は入力元が宣言した話者を、inferred は話者分離が推定した話者を、unattributed は話者が分からないことを表す。inferred の発話は、後の改訂で別の speakerId の話者に付け替わることがある。受け手は unattributed の発話をトラック単位で表示する。 |
| `recent[].speaker.kind` | `"declared"` \| `"inferred"` | ✓ | kind が "declared" か "inferred" のとき |
| `recent[].speaker.speakerId` | [ServerId](#common-serverid) | ✓ | kind が "declared" か "inferred" のとき |
| `recent[].speaker.kind` | `"unattributed"` | ✓ | kind が "unattributed" のとき |
| `recent[].stage` | `"partial"` \| `"final"` \| `"refined"` | ✓ |  |
| `recent[].revision` | integer（≥ 0） | ✓ | 同じ utteranceId では、大きい方が新しい。文字おこしくんが partial を間引くことがあるので、連番とは限らない。 |
| `recent[].text` | string | ✓ | 表示するテキストを表す（空文字のこともある）。受け手はテキストを HTML として埋め込まないこと。 |
| `recent[].startedAt` | [Timestamp](#common-timestamp) | ✓ | 発話の最初の音声フレームを文字おこしくんが受け取った時刻（エポックミリ秒）を表す。受け手は話者をまたいで発話を並べるときに startedAt を使う。 |

例: 接続時点のスナップショット

```json
{"type":"welcome","protocolVersion":1,"sessionId":"ses_01J8Z6Q3M4","speakers":[{"speaker":{"speakerId":"alice","displayName":"たろう","avatarUrl":"https://cdn.example.com/avatars/alice.png"},"inferred":false},{"speaker":{"speakerId":"room-mic#1","displayName":"話者 1"},"inferred":true}],"tracks":[{"trackId":"alice-mic","mode":"single","speakerId":"alice"},{"trackId":"room-mic","mode":"mixed"}],"speakingTrackIds":["alice-mic"],"recent":[{"utteranceId":"utt_01","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"refined","revision":5,"text":"こんにちは、今日はよろしくお願いします。","startedAt":1790000000000}]}
```

#### `speaker_upserted`

文字おこしくんは、話者の追加・更新を知らせる。inferred は、話者分離が推定した話者かどうかを表す。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/SpeakerUpserted`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speaker_upserted"` | ✓ |  |
| `speaker` | object | ✓ | Subscribe で文字おこしくんが送る話者を表す。 |
| `speaker.speakerId` | [ServerId](#common-serverid) | ✓ |  |
| `speaker.displayName` | [DisplayName](#common-displayname) | ✓ |  |
| `speaker.avatarUrl` | [AvatarUrl](#common-avatarurl) |  |  |
| `inferred` | boolean | ✓ |  |

例: 話者の追加・更新

```json
{"type":"speaker_upserted","speaker":{"speakerId":"bob","displayName":"はなこ"},"inferred":false}
```

#### `speaker_removed`

文字おこしくんは、話者の削除を知らせる。受け手はその話者の過去の発話を消さない。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/SpeakerRemoved`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speaker_removed"` | ✓ |  |
| `speakerId` | [ServerId](#common-serverid) | ✓ |  |

例: 話者の削除

```json
{"type":"speaker_removed","speakerId":"bob"}
```

#### `track_opened`

文字おこしくんは、トラックが開いたことを知らせる。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/TrackOpened`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"track_opened"` | ✓ |  |
| `track` | object（下のいずれか） | ✓ | トラックを表す。single は 1 人の話者だけのトラックを、mixed は複数の話者の声が入ったトラックを表す。 |
| `track.trackId` | [ServerId](#common-serverid) | ✓ | mode が "single" のとき |
| `track.mode` | `"single"` | ✓ | mode が "single" のとき |
| `track.speakerId` | [ServerId](#common-serverid) | ✓ | mode が "single" のとき |
| `track.trackId` | [ServerId](#common-serverid) | ✓ | mode が "mixed" のとき |
| `track.mode` | `"mixed"` | ✓ | mode が "mixed" のとき |

例: トラックが開いた

```json
{"type":"track_opened","track":{"trackId":"bob-mic","mode":"single","speakerId":"bob"}}
```

#### `track_closed`

文字おこしくんは、トラックが閉じたことを知らせる。受け手はそのトラックの発話を消さない。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/TrackClosed`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"track_closed"` | ✓ |  |
| `trackId` | [ServerId](#common-serverid) | ✓ |  |

例: トラックが閉じた

```json
{"type":"track_closed","trackId":"bob-mic"}
```

#### `speech_started`

文字おこしくんは、トラックが発声中になったことを知らせる（「話している」の表示に使う）。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/SpeechStarted`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speech_started"` | ✓ |  |
| `trackId` | [ServerId](#common-serverid) | ✓ |  |

例: 発声中になった

```json
{"type":"speech_started","trackId":"alice-mic"}
```

#### `speech_ended`

文字おこしくんは、トラックの発声が終わったことを知らせる。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/SpeechEnded`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speech_ended"` | ✓ |  |
| `trackId` | [ServerId](#common-serverid) | ✓ |  |

例: 発声が終わった

```json
{"type":"speech_ended","trackId":"alice-mic"}
```

#### `utterance`

文字おこしくんは、発話の改訂を 1 件ずつ送る。受け手は utteranceId ごとに revision が最大のものだけを採用し、同じか小さい revision は捨てる（追記しない。置き換える）。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/Utterance`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"utterance"` | ✓ |  |
| `utterance` | object | ✓ | 発話 1 件の、ある時点の改訂を表す。文字おこしくんが発話を partial（認識途中）→ final（確定）→ refined（LLM による整形）と改訂するたびに、revision が増える。 |
| `utterance.utteranceId` | [ServerId](#common-serverid) | ✓ |  |
| `utterance.trackId` | [ServerId](#common-serverid) | ✓ |  |
| `utterance.speaker` | object（下のいずれか） | ✓ | 発話の話者を表す。declared は入力元が宣言した話者を、inferred は話者分離が推定した話者を、unattributed は話者が分からないことを表す。inferred の発話は、後の改訂で別の speakerId の話者に付け替わることがある。受け手は unattributed の発話をトラック単位で表示する。 |
| `utterance.speaker.kind` | `"declared"` \| `"inferred"` | ✓ | kind が "declared" か "inferred" のとき |
| `utterance.speaker.speakerId` | [ServerId](#common-serverid) | ✓ | kind が "declared" か "inferred" のとき |
| `utterance.speaker.kind` | `"unattributed"` | ✓ | kind が "unattributed" のとき |
| `utterance.stage` | `"partial"` \| `"final"` \| `"refined"` | ✓ |  |
| `utterance.revision` | integer（≥ 0） | ✓ | 同じ utteranceId では、大きい方が新しい。文字おこしくんが partial を間引くことがあるので、連番とは限らない。 |
| `utterance.text` | string | ✓ | 表示するテキストを表す（空文字のこともある）。受け手はテキストを HTML として埋め込まないこと。 |
| `utterance.startedAt` | [Timestamp](#common-timestamp) | ✓ | 発話の最初の音声フレームを文字おこしくんが受け取った時刻（エポックミリ秒）を表す。受け手は話者をまたいで発話を並べるときに startedAt を使う。 |

例: 認識途中（partial）。同じ utteranceId の後の改訂で置き換わる

```json
{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"partial","revision":1,"text":"それでは始め","startedAt":1790000004000}}
```

例: 確定（final）

```json
{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"final","revision":3,"text":"それでは始めましょう","startedAt":1790000004000}}
```

例: 整形済み（refined）。final の後に非同期で届く

```json
{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"refined","revision":4,"text":"それでは始めましょう。","startedAt":1790000004000}}
```

例: 話者分離による推定の話者（mixed トラック）

```json
{"type":"utterance","utterance":{"utteranceId":"utt_03","trackId":"room-mic","speaker":{"kind":"inferred","speakerId":"room-mic#1"},"stage":"final","revision":2,"text":"よろしくお願いします","startedAt":1790000006500}}
```

例: 話者不明（トラック単位で表示する）

```json
{"type":"utterance","utterance":{"utteranceId":"utt_04","trackId":"room-mic","speaker":{"kind":"unattributed"},"stage":"partial","revision":0,"text":"えっと","startedAt":1790000009120}}
```

#### `session_ended`

文字おこしくんは、文字起こしが終了したことを知らせる。この後、文字おこしくんはイベントを送らない。クライアントは再接続しない。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/SessionEnded`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"session_ended"` | ✓ |  |

例: 文字起こしの終了

```json
{"type":"session_ended"}
```

#### `error`

文字おこしくんは、エラーを error で知らせる。error.fatal が true なら、文字おこしくんはこの後に接続を切る。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/Error`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"error"` | ✓ |  |
| `error` | object | ✓ | エラーの内容を表す。fatal が true なら、文字おこしくんはこの後に接続を閉じる。 |
| `error.code` | [ErrorCode](#common-errorcode) | ✓ |  |
| `error.message` | string | ✓ | 人が読むための説明（英語）を表す。文言は互換性の対象外である。 |
| `error.fatal` | boolean | ✓ |  |

例: 終了済み・存在しないセッション（fatal。再接続しない）

```json
{"type":"error","error":{"code":"session_ended","message":"session not found","fatal":true}}
```

例: クライアントの受信が、文字おこしくんからの送信に追いつかない（文字おこしくんは非 fatal の error を送った後に接続を切る。クライアントは短いバックオフで再接続する）

```json
{"type":"error","error":{"code":"rate_limited","message":"the client is too slow to keep up","fatal":false}}
```

#### `pong`

文字おこしくんは、ping に pong で応える。

スキーマ: [`schemas/subscribe-server-message.json#/$defs/Pong`](https://moji.kaitoranma.com/docs/schemas/subscribe-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"pong"` | ✓ |  |

例: ping への応答

```json
{"type":"pong"}
```

## Ingest（`/v1/ingest`）

接続の流れ: `hello` → `welcome` を待つ → 全話者の `speaker_upsert` → 開いている全トラックの `track_open` → `state_synced` → 音声のバイナリフレームと `speech_start` / `speech_end`。詳しい手順は[音声を送る](https://moji.kaitoranma.com/docs/ingest.md)にあります。

<h3 id="audio-frame">音声バイナリフレーム</h3>

| offset | size | type | field | 内容 |
|---|---|---|---|---|
| 0 | 1 | u8 | frame type | 常に 0x01（audio）にする。 |
| 1 | 2 | u16 BE | channel | track_open で割り当てた番号（0〜65535）を入れる。 |
| 3 | 4 | u32 BE | sequence | トラックごとに 1 ずつ増やす。2^32 で 0 に折り返す。再接続の後は 0 から数え直してよい。 |
| 7 | 残り | bytes | payload | opus では、Opus のパケットを 1 個入れる（Ogg などのコンテナに入れない）。pcm_s16le では、符号付き 16 bit リトルエンディアンの PCM を入れる（2ch はインターリーブする）。 |

例（channel = 1、sequence = 42、payload = `f8 ff fe`）:

```text
01 00 01 00 00 00 2a f8 ff fe
```

- `opus` のトラックで payload が Discord の無音フレーム（`f8 ff fe` の 3 バイト）のとき、文字おこしくんは無音フレームをデコーダーに通すだけで、音声認識にも利用量にも入れない。デコーダーは次の音声との継ぎ目に無音フレームを使うので、クライアントは無音フレームを省かずに送る。無音フレームを送らない場合も、クライアントは `sequence` を飛ばさない（文字おこしくんは、飛ばした番号を欠損として補間する）。文字おこしくんは、無音フレームの直後の欠番を補間しない（補間しても無音になるため）。

### クライアント → サーバー

#### `hello`

クライアントは、接続の直後に hello を 1 回だけ送る。welcome を受け取るまで、ほかのメッセージを送らない。

スキーマ: [`schemas/ingest-client-message.json#/$defs/Hello`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"hello"` | ✓ |  |
| `protocolVersion` | [ProtocolVersion](#common-protocolversion) | ✓ |  |
| `token` | [Token](#common-token) | ✓ |  |
| `clientName` | [ClientName](#common-clientname) |  |  |

例: 接続直後の名乗り

```json
{"type":"hello","protocolVersion":1,"token":"eyJ2IjoxLCJzaWQiOiJzZXNfMDEiLCJzY29wZSI6InRyYW5zY3JpcHQ6cmVhZCJ9.c2lnbmF0dXJl","clientName":"my-recorder/1.0"}
```

#### `speaker_upsert`

クライアントは、このメッセージで話者を追加・更新する。single トラックの話者の speaker_upsert は、そのトラックの track_open より前に送る。

スキーマ: [`schemas/ingest-client-message.json#/$defs/SpeakerUpsert`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speaker_upsert"` | ✓ |  |
| `speaker` | object | ✓ | Ingest でクライアントが宣言する話者を表す。 |
| `speaker.speakerId` | [ClientId](#common-clientid) | ✓ |  |
| `speaker.displayName` | [DisplayName](#common-displayname) | ✓ |  |
| `speaker.avatarUrl` | [AvatarUrl](#common-avatarurl) |  |  |

例: 話者の宣言

```json
{"type":"speaker_upsert","speaker":{"speakerId":"alice","displayName":"たろう","avatarUrl":"https://cdn.example.com/avatars/alice.png"}}
```

#### `speaker_remove`

クライアントは、このメッセージで話者を削除する。その話者の single トラックは、先に track_close しておく。

スキーマ: [`schemas/ingest-client-message.json#/$defs/SpeakerRemove`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speaker_remove"` | ✓ |  |
| `speakerId` | [ClientId](#common-clientid) | ✓ |  |

例: 話者の削除

```json
{"type":"speaker_remove","speakerId":"alice"}
```

#### `track_open`

クライアントは、このメッセージでトラックを開き、バイナリフレームで使う channel 番号を割り当てる。

スキーマ: [`schemas/ingest-client-message.json#/$defs/TrackOpen`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"track_open"` | ✓ |  |
| `trackId` | [ClientId](#common-clientid) | ✓ |  |
| `channel` | integer（0〜65535） | ✓ | バイナリフレームのヘッダで、このトラックを表す番号である。クライアントは、番号を接続の中で一意にする（track_close の後は再利用してよい）。 |
| `format` | object | ✓ | 音声の形式を表す。opus では、sampleRate に 48000 だけを使える（1/2ch）。pcm_s16le は、符号付き 16 bit リトルエンディアンの PCM を表す。公式の文字おこしくん（moji.kaitoranma.com）は、pcm_s16le で 8000〜48000 Hz と 1/2ch を受け付ける（2ch はインターリーブする）。扱えない組み合わせには、文字おこしくんが unsupported_format を返す。 |
| `format.codec` | `"opus"` \| `"pcm_s16le"` | ✓ |  |
| `format.sampleRate` | integer（≥ 1） | ✓ | サンプリングレート（Hz）を表す。 |
| `format.channels` | `1` \| `2` | ✓ |  |
| `track` | object（下のいずれか） | ✓ | single は、1 人の話者だけのトラックを表す（クライアントは、speakerId の話者を先に宣言しておく）。mixed は、複数の話者の声が入ったトラックを表す（diarize が true なら、文字おこしくんが話者を分離する）。 |
| `track.mode` | `"single"` | ✓ | mode が "single" のとき |
| `track.speakerId` | [ClientId](#common-clientid) | ✓ | mode が "single" のとき |
| `track.mode` | `"mixed"` | ✓ | mode が "mixed" のとき |
| `track.diarize` | boolean | ✓ | mode が "mixed" のとき |

例: 1 人の話者の Opus（48kHz・2ch）のトラック

```json
{"type":"track_open","trackId":"alice-mic","channel":1,"format":{"codec":"opus","sampleRate":48000,"channels":2},"track":{"mode":"single","speakerId":"alice"}}
```

例: 複数人の声が入った PCM 16kHz モノラルのトラック（話者分離あり）

```json
{"type":"track_open","trackId":"room-mic","channel":2,"format":{"codec":"pcm_s16le","sampleRate":16000,"channels":1},"track":{"mode":"mixed","diarize":true}}
```

#### `track_close`

クライアントは、このメッセージでトラックを閉じる。

スキーマ: [`schemas/ingest-client-message.json#/$defs/TrackClose`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"track_close"` | ✓ |  |
| `trackId` | [ClientId](#common-clientid) | ✓ |  |

例: トラックを閉じる

```json
{"type":"track_close","trackId":"room-mic"}
```

#### `state_synced`

クライアントは、接続の直後の状態の送り直し（全話者の speaker_upsert と全トラックの track_open）が終わったことを、このメッセージで知らせる。文字おこしくんは、クライアントが state_synced までに宣言しなかったトラックを閉じる。

スキーマ: [`schemas/ingest-client-message.json#/$defs/StateSynced`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"state_synced"` | ✓ |  |

例: 状態の送り直しの完了

```json
{"type":"state_synced"}
```

#### `speech_start`

クライアントは、このメッセージで発話区間の開始の目安を知らせる。capturedAt は、送信側の時計による参考値である。

スキーマ: [`schemas/ingest-client-message.json#/$defs/SpeechStart`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speech_start"` | ✓ |  |
| `trackId` | [ClientId](#common-clientid) | ✓ |  |
| `capturedAt` | [Timestamp](#common-timestamp) |  |  |

例: 発話の開始

```json
{"type":"speech_start","trackId":"alice-mic","capturedAt":1790000000000}
```

#### `speech_end`

クライアントは、このメッセージで発話区間の終わりの目安を知らせる。文字おこしくんに speech_end が届くと、確定（final）が早く出る。

スキーマ: [`schemas/ingest-client-message.json#/$defs/SpeechEnd`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"speech_end"` | ✓ |  |
| `trackId` | [ClientId](#common-clientid) | ✓ |  |
| `capturedAt` | [Timestamp](#common-timestamp) |  |  |

例: 発話の終わり

```json
{"type":"speech_end","trackId":"alice-mic"}
```

#### `ping`

クライアントは、生存確認のために ping を送る。文字おこしくんは pong を返す。

スキーマ: [`schemas/ingest-client-message.json#/$defs/Ping`](https://moji.kaitoranma.com/docs/schemas/ingest-client-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"ping"` | ✓ |  |

例: 生存確認

```json
{"type":"ping"}
```

#### `audio_frame`

クライアントは、音声をバイナリフレーム（`application/octet-stream`）で送ります。レイアウトは[音声バイナリフレーム](#audio-frame)にあります。

### サーバー → クライアント

#### `welcome`

文字おこしくんは、hello を受け付けたことを welcome で知らせる。protocolVersion は、この接続で使うバージョンである。

スキーマ: [`schemas/ingest-server-message.json#/$defs/Welcome`](https://moji.kaitoranma.com/docs/schemas/ingest-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"welcome"` | ✓ |  |
| `protocolVersion` | [ProtocolVersion](#common-protocolversion) | ✓ |  |
| `sessionId` | [ServerId](#common-serverid) | ✓ |  |

例: hello の受け付け

```json
{"type":"welcome","protocolVersion":1,"sessionId":"ses_01J8Z6Q3M4"}
```

#### `error`

文字おこしくんは、エラーを error で知らせる。trackId は、特定のトラックに関するエラーのときだけ付く。error.fatal が true なら、文字おこしくんはこの後に接続を切る。

スキーマ: [`schemas/ingest-server-message.json#/$defs/Error`](https://moji.kaitoranma.com/docs/schemas/ingest-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"error"` | ✓ |  |
| `error` | object | ✓ | エラーの内容を表す。fatal が true なら、文字おこしくんはこの後に接続を閉じる。 |
| `error.code` | [ErrorCode](#common-errorcode) | ✓ |  |
| `error.message` | string | ✓ | 人が読むための説明（英語）を表す。文言は互換性の対象外である。 |
| `error.fatal` | boolean | ✓ |  |
| `trackId` | [ServerId](#common-serverid) |  |  |

例: 宣言していない話者を参照した（非 fatal。送信内容を直す）

```json
{"type":"error","error":{"code":"unknown_speaker","message":"speaker bob is not declared","fatal":false},"trackId":"bob-mic"}
```

例: トークンが不正・期限切れ（fatal。再接続しない）

```json
{"type":"error","error":{"code":"unauthorized","message":"the token is invalid, expired, or lacks ingest:write","fatal":true}}
```

#### `pong`

文字おこしくんは、ping に pong で応える。

スキーマ: [`schemas/ingest-server-message.json#/$defs/Pong`](https://moji.kaitoranma.com/docs/schemas/ingest-server-message.json)

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `"pong"` | ✓ |  |

例: ping への応答

```json
{"type":"pong"}
```

## 共通の型

次の型は `schemas/common.json` の `$defs` にあります。

| 名前 | 型 | 説明 |
|---|---|---|
| <span id="common-clientid"></span>`ClientId` | string（1〜256 文字） | クライアントが送る ID（Ingest の trackId / speakerId）を表す。 |
| <span id="common-serverid"></span>`ServerId` | string（1〜1024 文字） | 文字おこしくんが送る ID（sessionId / trackId / speakerId / utteranceId）を表す。文字おこしくんはクライアントの ID から ID を派生させるので、ServerId は ClientId より長くなりうる。 |
| <span id="common-token"></span>`Token` | string（1〜4096 文字） | セッション単位のトークン（Ingest は ingest:write、Subscribe は transcript:read）を表す。トークンは API キーではない。 |
| <span id="common-protocolversion"></span>`ProtocolVersion` | integer（≥ 1） | プロトコルのバージョンを表す。現行のバージョンは、Ingest が 1、Subscribe が 1 である。 |
| <span id="common-timestamp"></span>`Timestamp` | number（≥ 0） | エポックミリ秒（UTC）の時刻を表す。 |
| <span id="common-displayname"></span>`DisplayName` | string（100 文字以下） | 表示名を表す。表示名は空文字のこともある（表示側が代替名にする）。表示名は利用者が入力した文字列なので、受け手は、表示名を HTML として埋め込まないこと。 |
| <span id="common-avatarurl"></span>`AvatarUrl` | string（2048 文字以下） | アバター画像の絶対 URL を表す。スキームには http: か https: だけを使える（javascript: や data: は使えない）。受け手の検証（WHATWG URL の解析）は少し広い形も受け付けるが、送る側は http(s)://host/... の形にすること。 |
| <span id="common-clientname"></span>`ClientName` | string（100 文字以下） | クライアントの識別名（ログ用）を表す。 |
| <span id="common-errorcode"></span>`ErrorCode` | string（1〜64 文字） | エラーコードを表す。既知のコードは errors.json にある。文字おこしくんはコードを互換性のある変更として追加するので、受け手は未知のコードも受け入れ、fatal に従って扱うこと。 |

## 値の上限

| 名前 | 値 |
|---|---|
| `maxIdLength` | 256 |
| `maxServerIdLength` | 1024 |
| `maxDisplayNameLength` | 100 |
| `maxAvatarUrlLength` | 2048 |
| `maxTokenLength` | 4096 |
| `maxClientNameLength` | 100 |
| `maxErrorCodeLength` | 64 |
| `maxChannel` | 65535 |

## 不正なメッセージの例

次の表に、文字おこしくんのサーバーの検証関数（`parse*`）と JSON Schema のどちらも拒否する、不正なメッセージの代表例を並べます。

| 方向 | 例 | 理由 |
|---|---|---|
| Ingest（client → server） | `{"type":"audio","trackId":"a"}` | type が未知の値 |
| Ingest（client → server） | `{"protocolVersion":1,"token":"t"}` | type が無い |
| Ingest（client → server） | `{"type":"hello","protocolVersion":1,"token":""}` | token が空 |
| Ingest（client → server） | `{"type":"hello","protocolVersion":0,"token":"t"}` | protocolVersion が 1 未満 |
| Ingest（client → server） | `{"type":"hello","protocolVersion":"1","token":"t"}` | protocolVersion が文字列 |
| Ingest（client → server） | `{"type":"track_open","trackId":"a","channel":65536,"format":{"codec":"opus","sampleRate":…` | channel が 65535 を超える |
| Ingest（client → server） | `{"type":"track_open","trackId":"a","channel":0,"format":{"codec":"pcm_s16le","sampleRate"…` | channels が 1 でも 2 でもない |
| Ingest（client → server） | `{"type":"track_open","trackId":"a","channel":0,"format":{"codec":"opus","sampleRate":4800…` | single に speakerId が無い |
| Ingest（client → server） | `{"type":"track_open","trackId":"a","channel":0,"format":{"codec":"aac","sampleRate":48000…` | codec が opus でも pcm_s16le でもない |
| Ingest（client → server） | `{"type":"speaker_upsert","speaker":{"speakerId":"a","displayName":"A","avatarUrl":"javasc…` | avatarUrl が http(s) の URL でない |
| Ingest（client → server） | `{"type":"speaker_upsert","speaker":{"speakerId":"a","displayName":"ああああああああああああああああああああああ…` | displayName が 100 文字を超える |
| Ingest（client → server） | `{"type":"speech_start","trackId":"a","capturedAt":-1}` | capturedAt が負 |
| Ingest（client → server） | `{"type":"track_close","trackId":""}` | trackId が空 |
| Ingest（client → server） | `["hello"]` | メッセージが JSON オブジェクトでない |
| Subscribe（server → client） | `{"type":"utterance","utterance":{"utteranceId":"u","trackId":"t","speaker":{"kind":"unatt…` | revision が負 |
| Subscribe（server → client） | `{"type":"utterance","utterance":{"utteranceId":"u","trackId":"t","speaker":{"kind":"unatt…` | revision が整数でない |
| Subscribe（server → client） | `{"type":"utterance","utterance":{"utteranceId":"u","trackId":"t","speaker":{"kind":"unatt…` | stage が partial・final・refined のどれでもない |
| Subscribe（server → client） | `{"type":"utterance","utterance":{"utteranceId":"u","trackId":"t","speaker":{"kind":"decla…` | declared に speakerId が無い |
| Subscribe（server → client） | `{"type":"welcome","protocolVersion":1,"sessionId":"s","speakers":[],"tracks":[],"speaking…` | welcome に recent が無い |
| Subscribe（server → client） | `{"type":"track_opened","track":"mixed"}` | track がオブジェクトでない |

---

<!-- source: https://moji.kaitoranma.com/docs/http.md -->

# HTTP API リファレンス

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

## エンドポイント一覧

| メソッド・パス | 認証 | 内容 |
|---|---|---|
| [GET `/healthz`](#getHealth) | なし | 文字おこしくんが動いているかを確かめる |
| [GET `/v1/sessions`](#listSessions) | API キー（`transcripts:read`） | セッションを一覧する |
| [POST `/v1/sessions`](#createSession) | API キー（`ingest:write`） | セッションを作る |
| [GET `/v1/sessions/{sessionId}`](#getSession) | API キー（`transcripts:read`） | セッションの状態を見る |
| [DELETE `/v1/sessions/{sessionId}`](#deleteSession) | API キー（`transcripts:delete`） | セッションを削除する |
| [POST `/v1/sessions/{sessionId}/end`](#endSession) | API キー（`ingest:write`） | セッションを終える |
| [POST `/v1/sessions/{sessionId}/tokens`](#createSessionToken) | API キー（`transcripts:read`） / API キー（`ingest:write`） | セッショントークンを発行する |
| [GET `/v1/sessions/{sessionId}/transcript`](#exportTranscript) | API キー（`transcripts:read`） / セッショントークン（`transcript:read`） / クエリの `token`（`transcript:download`） | 文字起こしを書き出す |
| [POST `/v1/sessions/{sessionId}/downloads`](#createTranscriptDownloads) | API キー（`transcripts:read`） | 書き出しのリンクを作る |
| [GET `/v1/sessions/{sessionId}/chatgpt`](#openTranscriptInChatGpt) | クエリの `token`（`transcript:download`） | 記録を ChatGPT に渡す |
| [GET `/v1/usage`](#getUsage) | API キー（`usage:read`） | 利用量を見る |
| [GET `/v1/ingest`](#ingestWebSocket) | 接続後の `hello` でセッショントークン | WebSocket の Ingest（音声を送る）に接続する |
| [GET `/v1/subscribe`](#subscribeWebSocket) | 接続後の `hello` でセッショントークン | WebSocket の Subscribe（結果を受け取る）に接続する |

## 認証

```text
Authorization: Bearer <資格情報>
```

| 資格情報 | 形 | 使える操作 | ブラウザ・OBS に置いてよいか |
|---|---|---|---|
| API キー | `mjk_live_` + 38 文字（base62） | キーのスコープが許す操作（スコープの表）。API キーは、API キーのテナント（Discord サーバー）のセッションと利用量だけを扱える | **置かない**（流出したら管理画面で取り消す） |
| セッショントークン（`transcript:read`） | `base64url.base64url` | そのセッションの[書き出し](#exportTranscript)（と WebSocket の Subscribe） | 置いてよい（使えるセッションも権限も 1 つだけで、期限がある） |
| 書き出しのリンクのトークン（`transcript:download`） | `base64url.base64url` | そのセッションの[書き出し](#exportTranscript)と[ChatGPT への転送](#openTranscriptInChatGpt)だけ。`Authorization` ではなく、クエリの `token` で送る（[書き出しのリンク](#createTranscriptDownloads)に入っている） | 置いてよい。チャットに貼ってもよい（書き出しにしか使えず、期限がある） |

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

| スコープ | 使える操作 |
|---|---|
| `transcripts:read` | [GET `/v1/sessions`](#listSessions)、[GET `/v1/sessions/{sessionId}`](#getSession)、[POST `/v1/sessions/{sessionId}/tokens`](#createSessionToken)、[GET `/v1/sessions/{sessionId}/transcript`](#exportTranscript)、[POST `/v1/sessions/{sessionId}/downloads`](#createTranscriptDownloads) |
| `transcripts:delete` | [DELETE `/v1/sessions/{sessionId}`](#deleteSession) |
| `usage:read` | [GET `/v1/usage`](#getUsage) |
| `ingest:write` | [POST `/v1/sessions`](#createSession)、[POST `/v1/sessions/{sessionId}/end`](#endSession)、[POST `/v1/sessions/{sessionId}/tokens`](#createSessionToken) |

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

API キーで発行するセッショントークンの有効期間は[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md#セッショントークンの有効期間)、期限の後の取り直しは[再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md#token-expiry)にあります。

## エラー（problem details）

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

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

| メンバー | 型 | 説明 |
|---|---|---|
| `type` | string（URI） | `https://moji.kaitoranma.com/docs/errors/#<code>`（コードごとに固定の識別子） |
| `title` | string | コードごとに固定の短い説明（日本語。文言は変わることがある） |
| `status` | integer | HTTP ステータス（応答と同じ） |
| `detail` / `message` | string | この要求で起きたエラーの説明（日本語。文言は変わることがある） |
| `code` / `error` | string | 機械向けのコード |
| `retryAfterSeconds` | integer | `rate_limited`・`quota_exceeded`: 待つ秒数（`Retry-After` と同じ） |
| `quota` | object | `quota_exceeded`: `tenantId`・`dailyAudioSeconds`・`usedAudioSeconds`・`resetsAt`（次の UTC 0 時） |
| `requiredScope` | string | `insufficient_scope`: 足りないスコープ |

- `429`・`5xx` を受け取ったら、待ってから要求をやり直してください（`Retry-After` があれば、その秒数だけ待ちます）。それ以外の `4xx` を受け取ったら、要求を直すまでやり直さないでください。
- コードごとの意味と対処は[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)にあります。

## 共通の決まり

- パスはすべて `/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` を上げます（[変更履歴](https://moji.kaitoranma.com/docs/changelog.md)）。

## レート制限

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

```text
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`）を返します。
- ほかの上限は[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)にあります。

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

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

| 項目 | 内容 |
|---|---|
| 値 | 1〜255 文字の印字可能な ASCII（UUID を勧める）。この形に合わない値には、文字おこしくんが `400 invalid_request` を返す |
| 同じ要求とみなす範囲 | API キー × メソッドとパス × キーの値 |
| 覚える期間 | 24 時間 |
| 覚える応答 | 成功（2xx）した応答だけ。失敗した要求は同じキーでやり直せる |
| 同じキー・同じ本文 | 文字おこしくんは、最初の応答をそのまま返す（`Idempotent-Replayed: true`） |
| 同じキー・違う本文 | 文字おこしくんは `422 idempotency_mismatch` を返す |
| 同じキーの要求が処理中 | 文字おこしくんは `409 idempotency_in_progress`（`Retry-After: 1`）を返す |

## ページ送り（cursor）

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

## ヘルスチェック（Health） {#tag-health}

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

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

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

- 認証: なし
- operationId: `getHealth`

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが動いている。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `ok` | true | 必須 |  |

```json
{
  "ok": true
}
```

```sh
curl -sS "$BASE/healthz"
```

## セッションとトークン（Sessions） {#tag-sessions}

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

### セッションを一覧する（GET `/v1/sessions`） {#listSessions}

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

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

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `status` | query | "active" / "ended" | 任意 | `active`（終了していない）か `ended`（終了した）を指定する。省くと、文字おこしくんは両方を返す。 |
| `limit` | query | integer（1〜100、既定 20） | 任意 | 1 ページの件数を指定する（既定 20）。 |
| `cursor` | query | string（2048 文字まで） | 任意 | 前のページの `nextCursor` を渡す。不正な値には、文字おこしくんが 400 `invalid_request` を返す。 |
| `endedSince` | query | integer（0 以上） | 任意 | 指定すると、文字おこしくんは、終了していないセッションと、この時刻（エポックミリ秒）以降に終了したセッションだけを返す。 |

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、セッションの一覧を返した。 |
| 400 | `status`・`limit`・`cursor`・`endedSince` の値が不正である（`invalid_request`） |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `transcripts:read` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `sessions` | object[] | 必須 | 文字おこしくんは、セッションを、`createdAt` の降順（同時刻は `sessionId` の降順）に並べる。 |
| `sessions[].sessionId` | string | 必須 | セッションの ID を表す。 |
| `sessions[].label` | string（1〜100 文字） | 必須 | 表示名を表す。 |
| `sessions[].externalRef` | string（1〜256 文字） | 任意 | 入力元での識別子を表す。公式の Discord ボットは、`discord:<guildId>:<channelId>` を使う。 |
| `sessions[].tenantId` | string | 任意 | テナント（Discord ではギルド ID）を表す。 |
| `sessions[].createdAt` | number（エポックミリ秒） | 必須 |  |
| `sessions[].endedAt` | number（エポックミリ秒） | 任意 | 終了した時刻を表す。セッションが終了していなければ、このフィールドは無い。 |
| `sessions[].live` | boolean | 必須 | 文字おこしくんのサーバーのプロセスで、セッションが稼働中かどうかを表す（再起動の直後は、音声の送り手（Ingest）か受け手（Subscribe）がつなぎ直すまで false）。 |
| `sessions[].audioSeconds` | number（0 以上） | 必須 | このセッションの利用量を表す。利用量は音声認識にかけた音声の秒数で、小数第 3 位までの値である。 |
| `sessions[].retainUntil` | number（エポックミリ秒） | 任意 | 終了したセッションが、保持期間を過ぎて消える時刻を表す。文字おこしくんがセッションを消さないなら、このフィールドは無い。テナント（Discord サーバー）の保持期間が延びると、文字おこしくんは、この時刻を、セッションの終了から延びた保持期間の後まで遅らせる。文字おこしくんは、この時刻を早めない。 |
| `nextCursor` | string（2048 文字まで） | 任意 | 続きがあるときだけ付く。次のページを取るときは、この値を `cursor` に渡す（不透明な文字列なので、中身に依存しない）。 |

```json
{
  "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"
}
```

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

### セッションを作る（POST `/v1/sessions`） {#createSession}

クライアントは、この操作で、自分で音声を送る（[Ingest](https://moji.kaitoranma.com/docs/ingest.html)）ためのセッションを作る。文字おこしくんは、作ったセッションをすぐ稼働させ、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`

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | 任意 | 同じ操作を安全にやり直すためのキーを表す（UUID を勧める）。文字おこしくんは、成功した応答を 24 時間覚え、同じキー・同じ本文の要求には最初の応答をそのまま返す（`Idempotent-Replayed: true`）。同じキーで本文が違えば、文字おこしくんは 422 `idempotency_mismatch` を返す。同じキーの要求が処理中なら、文字おこしくんは 409 `idempotency_in_progress` を返す。文字おこしくんは失敗した要求を覚えないので、同じキーでやり直せる。文字おこしくんは、認証に使った資格情報とメソッド・パスごとにキーを区別する。 |

要求の本文（JSON）:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `label` | string（1〜100 文字） | 必須 | 表示名を表す（前後の空白を除いて 1〜100 文字）。 |
| `externalRef` | string \| null（1〜256 文字） | 任意 | 入力元での識別子を表す。`reuseActive` で使い回すセッションを探す鍵になる。API キーで `discord:` で始まる値を使うなら、`discord:<自分の tenantId>:` で始まる値だけを使える（違えば、文字おこしくんは 403 `forbidden` を返す）。 |
| `reuseActive` | boolean \| null | 任意 | true のとき、同じ `externalRef`・同じテナントの終了していないセッションがあれば、文字おこしくんはそのセッションを使い回す（200、`reused: true`）。 |
| `tenantId` | string \| null | 任意 | テナントを表す。クライアントは、テナントを省くか、API キーのテナントと同じ値にする（違えば、文字おこしくんは 403 `forbidden` を返す）。 |

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

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、稼働中のセッションを使い回した（`reused: true`）。ラベルは既存のままで、トークンは新しく発行する。 |
| 201 | 文字おこしくんが、セッションを新しく作った。 |
| 400 | 本文か `Idempotency-Key` が不正である（`invalid_json` / `invalid_request`） |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | `tenantId` か `externalRef` が API キーのテナントと違う。または、スコープが足りないか、API キーの利用が無効になっている（`forbidden` / `insufficient_scope` / `api_access_disabled`） |
| 409 | 文字おこしくんが、同じ `Idempotency-Key` の前の要求をまだ処理している（`idempotency_in_progress`） |
| 422 | クライアントが、同じ `Idempotency-Key` で、本文の違う要求を送った（`idempotency_mismatch`） |
| 429 | 今日（UTC）の利用上限に達した。または、レート制限を超えた（`quota_exceeded` / `rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `sessionId` | string | 必須 | セッションの ID を表す。 |
| `label` | string（1〜100 文字） | 必須 | 表示名を表す。 |
| `externalRef` | string（1〜256 文字） | 任意 | 入力元での識別子を表す。公式の Discord ボットは、`discord:<guildId>:<channelId>` を使う。 |
| `tenantId` | string | 任意 | テナント（Discord ではギルド ID）を表す。 |
| `createdAt` | number（エポックミリ秒） | 必須 |  |
| `reused` | boolean | 必須 | 既存のセッションを使い回したかどうかを表す（使い回しなら 200、新規なら 201）。 |
| `ingest` | object | 必須 |  |
| `ingest.url` | string | 必須 | WebSocket の URL（`wss://<host>/v1/ingest`）を表す。 |
| `ingest.token` | string（セッショントークン） | 必須 | `ingest:write` のセッショントークンを表す。クライアントは、このトークンを hello で送る。 |
| `subscribe` | object | 必須 |  |
| `subscribe.url` | string | 必須 | WebSocket の URL（`wss://<host>/v1/subscribe`）を表す。 |
| `subscribe.token` | string（セッショントークン） | 必須 | `transcript:read` のセッショントークンを表す。クライアントは、このトークンを hello で送る。 |
| `viewerUrl` | string | 必須 | 表示ページの URL を表す（トークンはフラグメント `#token=` に入る）。 |
| `overlayUrl` | string | 必須 | OBS のブラウザソース用の URL を表す（`viewerUrl` + `&overlay=1`）。 |
| `expiresAt` | number（エポックミリ秒） | 必須 | 2 つのトークンの有効期限を表す。 |

```json
{
  "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
}
```

```sh
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}`） {#getSession}

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

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

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、セッションの状態を返した。 |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `transcripts:read` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い。保持期間を過ぎて消えたセッションと、別のテナントのセッションにも、文字おこしくんはこの応答を返す（`session_not_found`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `sessionId` | string | 必須 | セッションの ID を表す。 |
| `label` | string（1〜100 文字） | 必須 | 表示名を表す。 |
| `externalRef` | string（1〜256 文字） | 任意 | 入力元での識別子を表す。公式の Discord ボットは、`discord:<guildId>:<channelId>` を使う。 |
| `tenantId` | string | 任意 | テナント（Discord ではギルド ID）を表す。 |
| `createdAt` | number（エポックミリ秒） | 必須 |  |
| `endedAt` | number（エポックミリ秒） | 任意 | 終了した時刻を表す。セッションが終了していなければ、このフィールドは無い。 |
| `live` | boolean | 必須 | 文字おこしくんのサーバーのプロセスで、セッションが稼働中かどうかを表す。 |
| `ingestConnected` | boolean | 必須 | Ingest（音声の送り手）がつながっているかどうかを表す。 |
| `viewers` | integer（0 以上） | 必須 | 購読中の Subscribe の接続数を表す。 |
| `audioSeconds` | number（0 以上） | 必須 | このセッションの利用量を表す。利用量は音声認識にかけた音声の秒数で、小数第 3 位までの値である。文字おこしくんは、利用量をトラックごとに数えて足す。 |
| `retainUntil` | number（エポックミリ秒） | 任意 | 終了したセッションが、保持期間を過ぎて消える時刻を表す。文字おこしくんがセッションを消さないなら、このフィールドは無い。テナント（Discord サーバー）の保持期間が延びると、文字おこしくんは、この時刻を、セッションの終了から延びた保持期間の後まで遅らせる。文字おこしくんは、この時刻を早めない。 |

```json
{
  "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
}
```

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

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

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

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

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |

| ステータス | 意味 |
|---|---|
| 204 | 文字おこしくんが記録を消した（本文なし）。 |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `transcripts:delete` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い。消えたセッションと、別のテナントのセッションにも、文字おこしくんはこの応答を返す（`session_not_found`） |
| 409 | セッションが稼働中か、終了の途中である（`session_active`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

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

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

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

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

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんがセッションを終えた。 |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `ingest:write` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い（`session_not_found`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `sessionId` | string | 必須 |  |
| `endedAt` | number（エポックミリ秒） | 必須 | 終了した時刻を表す（終了済みなら最初の時刻）。 |

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

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

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

文字おこしくんは、ブラウザ・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`

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |
| `Idempotency-Key` | header | string | 任意 | 同じ操作を安全にやり直すためのキーを表す（UUID を勧める）。文字おこしくんは、成功した応答を 24 時間覚え、同じキー・同じ本文の要求には最初の応答をそのまま返す（`Idempotent-Replayed: true`）。同じキーで本文が違えば、文字おこしくんは 422 `idempotency_mismatch` を返す。同じキーの要求が処理中なら、文字おこしくんは 409 `idempotency_in_progress` を返す。文字おこしくんは失敗した要求を覚えないので、同じキーでやり直せる。文字おこしくんは、認証に使った資格情報とメソッド・パスごとにキーを区別する。 |

要求の本文（JSON）:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `scope` | "transcript:read" / "ingest:write" | 必須 | `transcript:read`（Subscribe と書き出し。API キーでは `transcripts:read` が要る）か `ingest:write`（Ingest。API キーでは `ingest:write` が要る）を指定する。 |
| `ttlSeconds` | integer \| null（1〜86400） | 任意 | 有効期間を秒で表す（既定 3600）。 |

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

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんがトークンを発行した。 |
| 400 | `scope`・`ttlSeconds`・`Idempotency-Key` が不正である（`invalid_json` / `invalid_request`） |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに、そのトークンを発行するスコープが無い。または、API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い（`session_not_found`） |
| 409 | 終わったセッションの `ingest:write` のトークンを要求した。または、文字おこしくんが同じ `Idempotency-Key` の前の要求をまだ処理している（`session_ended` / `idempotency_in_progress`） |
| 422 | クライアントが、同じ `Idempotency-Key` で、本文の違う要求を送った（`idempotency_mismatch`） |
| 429 | レート制限を超えた（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `token` | string（セッショントークン） | 必須 | セッショントークンを表す。ブラウザ・OBS に渡してよい（使えるセッションも権限も 1 つだけで、期限がある）。 |
| `expiresAt` | number（エポックミリ秒） | 必須 | 有効期限を表す。文字おこしくんは、接続するときにだけ有効期限を確かめる（つながっている WebSocket は切れない）。 |

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

```sh
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） {#tag-transcripts}

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

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

文字おこしくんは、発話ごとの最新の改訂（`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`

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |
| `format` | query | "json" / "text" / "csv"（既定 "json"） | 任意 | `json`（既定）・`text`（1 発話 1 行）・`csv`（見出し `日時,話者,発言` と 1 発話 1 行。Excel で開ける）のどれかを指定する。 |
| `tz` | query | string（1 文字以上、既定 "Asia/Tokyo"） | 任意 | `text` の時刻のタイムゾーンを IANA 名で表す（既定は `Asia/Tokyo`）。`csv` の日時と、書き出しのリンクで保存するファイルの名前の日時にも、文字おこしくんはこのタイムゾーンを使う。 |
| `disposition` | query | "attachment" / "inline"（既定 "attachment"） | 任意 | 書き出しのリンク（クエリの `token`）で、ブラウザに応答をどう扱わせるかを指定する。`attachment`（既定）ならファイルとして保存させ、`inline` ならページとして表示させる。ほかの資格情報では、文字おこしくんは値を確かめるだけで、`Content-Disposition` を付けない。 |

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、文字起こしを書き出した。文字おこしくんは、`format=json` なら JSON を、`format=text` なら `[HH:mm:ss] 名前: 本文` の行を、`format=csv` なら CSV（RFC 4180。先頭に UTF-8 の BOM、改行は CRLF、1 行目は見出し `日時,話者,発言`、日時は `YYYY-MM-DD HH:mm:ss`）を返す。CSV では、文字おこしくんは、`=`・`+`・`-`・`@`・タブ・CR で始まるセルの先頭に `'` を付ける（表計算ソフトに数式として読ませない）。 |
| 400 | `format`・`tz`・`disposition` のどれかが不正である。または、クエリの `token` と `Authorization` ヘッダーを同時に付けた（`invalid_request`） |
| 401 | 資格情報が、無いか、無効か、期限切れである（`unauthorized`） |
| 403 | トークンが別のセッションのものである。または、API キーのスコープが足りないか、API キーの利用が無効になっている（`forbidden` / `insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い。保持期間を過ぎて消えたセッションにも、文字おこしくんはこの応答を返す（`session_not_found`） |
| 429 | レート制限を超えた。または、書き出しが混み合っている（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `sessionId` | string | 必須 |  |
| `label` | string | 必須 |  |
| `speakers` | object[] | 必須 | そのセッションに一度でも現れた話者（途中で抜けた人も含む）の最後の情報を表す。 |
| `speakers[].speakerId` | string | 必須 |  |
| `speakers[].displayName` | string（100 文字まで） | 必須 |  |
| `speakers[].avatarUrl` | string（http(s) の URL） | 任意 |  |
| `utterances` | object[] | 必須 | 文字おこしくんは、発話ごとの最新の改訂を、`startedAt` の昇順に並べる。 |
| `utterances[].utteranceId` | string | 必須 | WebSocket の utterance と同じ ID を表す（WebSocket の発話と対応づけるのに使える）。 |
| `utterances[].trackId` | string | 必須 |  |
| `utterances[].speakerId` | string | 任意 | 話者を表す。話者の分からない発話には、このフィールドは無い。 |
| `utterances[].speakerName` | string | 必須 | 表示名を表す（空・不明なら代替名）。 |
| `utterances[].stage` | "final" / "refined" | 必須 | `final`（音声認識の確定）か `refined`（整形後）を表す。認識途中（`partial`）は含まない。 |
| `utterances[].text` | string | 必須 | 本文を表す（整形しなかったら `rawText` と同じ）。 |
| `utterances[].rawText` | string | 必須 | 整形前の音声認識の結果を表す。 |
| `utterances[].startedAt` | number（エポックミリ秒） | 必須 | 発話の最初の音声を文字おこしくんが受け取った時刻を表す。 |

```json
{
  "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` の応答:

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

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

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

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

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

文字おこしくんは、クリックするだけで文字起こしをファイルとして保存できるリンク（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`

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |
| `Idempotency-Key` | header | string | 任意 | 同じ操作を安全にやり直すためのキーを表す（UUID を勧める）。文字おこしくんは、成功した応答を 24 時間覚え、同じキー・同じ本文の要求には最初の応答をそのまま返す（`Idempotent-Replayed: true`）。同じキーで本文が違えば、文字おこしくんは 422 `idempotency_mismatch` を返す。同じキーの要求が処理中なら、文字おこしくんは 409 `idempotency_in_progress` を返す。文字おこしくんは失敗した要求を覚えないので、同じキーでやり直せる。文字おこしくんは、認証に使った資格情報とメソッド・パスごとにキーを区別する。 |

要求の本文（JSON）:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `ttlSeconds` | integer \| null（1〜86400） | 任意 | リンクの有効期間を秒で表す（既定 3600）。セッションに保持期限（`retainUntil`）があれば、文字おこしくんは、有効期限を保持期限より後にしない。 |

```json
{
  "ttlSeconds": 3600
}
```

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、書き出しのリンクを作った。 |
| 400 | `ttlSeconds` か `Idempotency-Key` が不正である（`invalid_json` / `invalid_request`） |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `transcripts:read` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 404 | セッションが無い。保持期間を過ぎたセッションと、別のテナントのセッションにも、文字おこしくんはこの応答を返す（`session_not_found`） |
| 409 | 文字おこしくんが、同じ `Idempotency-Key` の前の要求をまだ処理している（`idempotency_in_progress`） |
| 422 | クライアントが、同じ `Idempotency-Key` で、本文の違う要求を送った（`idempotency_mismatch`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `expiresAt` | number（エポックミリ秒） | 必須 | リンクの有効期限を表す。どのリンクも同じトークンを使うので、有効期限も同じである。 |
| `hasUtterances` | boolean | 必須 | リンクを作った時点で、書き出しに載る発話（本文のある発話）が 1 件でもあったかを表す。false なら、クライアントはリンクを人に見せなくてよい。 |
| `urls` | object | 必須 | 形式ごとの書き出しのリンクを表す。リンクは `GET /v1/sessions/{sessionId}/transcript?format=<形式>&token=<transcript:download のトークン>` の形である。リンクを開いたブラウザは、応答をファイルとして保存する（リンクに `&disposition=inline` を足すと、ブラウザは応答をページとして表示する）。文字おこしくんは、リンクを開いた時点までの記録を書き出す。 |
| `urls.json` | string | 必須 | `format=json` の書き出しのリンクを表す。 |
| `urls.text` | string | 必須 | `format=text` の書き出しのリンクを表す。 |
| `urls.csv` | string | 必須 | `format=csv` の書き出しのリンクを表す。 |
| `chatgptUrl` | string | 必須 | 記録を ChatGPT に渡すリンク（`GET /v1/sessions/{sessionId}/chatgpt?token=<同じトークン>`）を表す。リンクを開いたブラウザは、定型文と記録の URL を入れた ChatGPT の新しい会話を開く。公式のサーバーでは、リンクの長さは Discord のリンクボタンの上限（512 文字）に収まる。 |

```json
{
  "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"
}
```

```sh
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`） {#openTranscriptInChatGpt}

文字おこしくんは、クエリの `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`

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `sessionId` | path | string | 必須 | セッションの ID を指定する。 |

| ステータス | 意味 |
|---|---|
| 302 | 文字おこしくんが、ブラウザを ChatGPT の新しい会話へ転送した（転送先は `Location`）。 |
| 400 | クエリの `token` と `Authorization` ヘッダーを同時に付けた（`invalid_request`） |
| 401 | クエリの `token` が、無いか、無効か、期限切れである（`unauthorized`） |
| 403 | トークンが別のセッションのものである（`forbidden`） |
| 404 | セッションが無い。保持期間を過ぎたセッションにも、文字おこしくんはこの応答を返す（`session_not_found`） |
| 429 | レート制限（送信元 IP ごと）を超えた（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

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

## 利用量（Usage） {#tag-usage}

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

### 利用量を見る（GET `/v1/usage`） {#getUsage}

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

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

| パラメーター | 場所 | 型 | | 説明 |
|---|---|---|---|---|
| `from` | query | string | 任意 | 最初の日（UTC、YYYY-MM-DD）を指定する。既定は今日。 |
| `to` | query | string | 任意 | 最後の日（UTC、YYYY-MM-DD）を指定する。既定は今日。`from` 以後の日にする。 |

| ステータス | 意味 |
|---|---|
| 200 | 文字おこしくんが、利用量を返した。 |
| 400 | `from` / `to` が、不正か、逆順か、長すぎる（`invalid_request`） |
| 401 | `Authorization: Bearer` が無いか、不正である。または、API キーが失効している（`unauthorized`） |
| 403 | API キーに `usage:read` のスコープが無い。または、テナントで API キーの利用が無効になっている（`insufficient_scope` / `api_access_disabled`） |
| 429 | レート制限を超えた。`Retry-After` の秒数の後にやり直す（`rate_limited`） |
| default | ほかのステータスのエラー（problem details）。たとえば `413 payload_too_large`・`405 method_not_allowed`・`500 internal`・`503 shutting_down` がある。`code` で分岐し、知らないコードはステータスで扱う（5xx と 429 は待ってやり直す）。 |

応答 200:

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `tenantId` | string | 必須 | テナント（Discord ではギルド ID）を表す。 |
| `plan` | string | 必須 | プラン名を表す。 |
| `from` | string | 必須 | UTC の日付（YYYY-MM-DD）を表す。 |
| `to` | string | 必須 | UTC の日付（YYYY-MM-DD）を表す。 |
| `days` | object[] | 必須 | 文字おこしくんは、`from`〜`to` のすべての日（使っていない日は 0）を、日付の昇順に並べる。 |
| `days[].date` | string | 必須 | UTC の日付（YYYY-MM-DD）を表す。 |
| `days[].audioSeconds` | number（0 以上） | 必須 | その日の利用量を秒で表す。 |
| `totalAudioSeconds` | number（0 以上） | 必須 | 期間の合計を秒で表す。 |
| `today` | object | 必須 | 文字おこしくんは、範囲によらず、常に今日（UTC）の値と上限を返す。 |
| `today.date` | string | 必須 | UTC の日付（YYYY-MM-DD）を表す。 |
| `today.audioSeconds` | number（0 以上） | 必須 | 今日の利用量を秒で表す（文字おこしくんがまだ保存していない直近の分も含む）。 |
| `today.limitAudioSeconds` | integer \| null（0 以上） | 必須 | 1 日の上限を秒で表す。null なら、日ごとの上限は無い。 |
| `today.remainingAudioSeconds` | number \| null（0 以上） | 必須 | 残りを秒で表す（0 未満にならない）。上限が無いなら null になる。 |
| `today.exceeded` | boolean | 必須 | `audioSeconds >= limitAudioSeconds` かどうかを表す（上限が無いなら false）。 |
| `today.resetsAt` | number（エポックミリ秒） | 必須 | 次の UTC 0 時（日本時間 9:00）を表す。 |

```json
{
  "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
  }
}
```

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

## WebSocket のエンドポイント（WebSocket） {#tag-websocket}

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

### WebSocket の Ingest（音声を送る）に接続する（GET `/v1/ingest`） {#ingestWebSocket}

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

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

| ステータス | 意味 |
|---|---|
| 101 | 接続が WebSocket に切り替わった。この後のメッセージは asyncapi.yaml にある。 |
| 426 | クライアントが、WebSocket ではない普通の HTTP で要求した（`upgrade_required`） |
| 429 | 同じ送信元からの同時接続が多すぎるので、文字おこしくんが upgrade を断った。または、普通の HTTP での要求がレート制限を超えた（`too_many_connections` / `rate_limited`） |
| 503 | 文字おこしくんの API 全体の同時接続が多すぎる。または、文字おこしくんが停止の途中である（`too_many_connections` / `shutting_down`） |

```js
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`） {#subscribeWebSocket}

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

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

| ステータス | 意味 |
|---|---|
| 101 | 接続が WebSocket に切り替わった。この後のメッセージは asyncapi.yaml にある。 |
| 426 | クライアントが、WebSocket ではない普通の HTTP で要求した（`upgrade_required`） |
| 429 | 同じ送信元からの同時接続が多すぎるので、文字おこしくんが upgrade を断った。または、普通の HTTP での要求がレート制限を超えた（`too_many_connections` / `rate_limited`） |
| 503 | 文字おこしくんの API 全体の同時接続が多すぎる。または、文字おこしくんが停止の途中である（`too_many_connections` / `shutting_down`） |

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

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

### TypeScript

```ts
// 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

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

---

<!-- source: https://moji.kaitoranma.com/docs/webhooks.md -->

# Webhook リファレンス

文字おこしくんは文字起こしの開始と終了を、Discord サーバーの管理者が登録した URL に HTTPS の `POST` で知らせます（Webhook）。あなたのサーバーは知らせを受け取ったら、[HTTP API](https://moji.kaitoranma.com/docs/http.md) で記録を書き出したり、[WebSocket の Subscribe](https://moji.kaitoranma.com/docs/reference.md) で発言を受け取ったりできます。本文は JSON で、発言の文字は入りません。機械可読な版は [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml) の `webhooks` にあります。

## 送信先を登録する {#register}

Discord サーバーの管理者は[管理画面](https://moji.kaitoranma.com/app/)でその Discord サーバーを選び、「開発者向け設定」の「Webhook」の節の「送信先を追加」で、受け取る URL と送る出来事を登録します。管理画面は署名のシークレット（`whsec_…`）を、送信先を作ったときに 1 回だけ表示します。

- あなたがその Discord サーバーの管理者でなければ、管理者に送信先を登録してもらい、シークレットを受け取ってください。
- シークレットはあなたのサーバー側だけに置いてください（ブラウザ・リポジトリ・ログに置かない）。シークレットをほかの人に知られたときは、Discord サーバーの管理者だけが管理画面の「シークレットを作り直す」で新しいシークレットに替えられます。
- URL は `https://` で始まり、ホストがインターネットに公開しているドメイン名の URL にします（2048 文字まで）。文字おこしくんは IP アドレスを直に書いた URL と、`localhost`・`*.localhost`・`*.local`・`*.internal` の URL を受け付けません。文字おこしくん自身のドメイン（`moji.kaitoranma.com` とその下の名前）の URL と、ユーザー名・パスワード・`#` を含む URL も受け付けません。
- Discord サーバーごとの送信先の数の上限は[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)にあります。
- Discord サーバーの管理者が管理画面の「テストを送る」を押すと、文字おこしくんは [`webhook.test`](#webhook-test) を 1 回送ります。受け取る側を作ったら、まず Discord サーバーの管理者に「テストを送る」を押してもらい、あなたのサーバーに `webhook.test` が届くかを確かめてください。

## 出来事 {#events}

| 出来事 | 内容 |
|---|---|
| [`session.started`](#session-started) | 文字起こしが始まったことを知らせる |
| [`session.ended`](#session-ended) | 文字起こしが終わったことを知らせる |
| [`webhook.test`](#webhook-test) | Discord サーバーの管理者が「テストを送る」を押したことを知らせる |

Discord サーバーの管理者は送信先ごとに、管理画面の「送る出来事」で「文字起こしの開始」（`session.started`）と「文字起こしの終了」（`session.ended`）のどちらを送るかを選びます。両方を選ぶこともできます。Discord サーバーの管理者が「テストを送る」を押したときだけ、文字おこしくんは `webhook.test` を送ります。文字おこしくんは出来事の種類と本文のフィールドを足すことがあります。知らない `type` の出来事にも 2xx を返し、知らないフィールドは無視してください。

### `session.started` {#session-started}

文字おこしくんは文字起こしのセッションを新しく作ると、この出来事を送る。公式の Discord ボットが `/start` や自動入室でセッションを作ったときも、あなたが API キーで `POST /v1/sessions` を呼んでセッションを作ったときも、文字おこしくんはこの出来事を送る。文字おこしくんは動いているセッションを使い回したとき（`reuseActive`）と、再起動の後にセッションを動かし直したときには、この出来事を送らない。本文（JSON）には発言が入らない。発言を受け取るときは、あなたのサーバーが `data.sessionId` の `transcript:read` のトークンを発行し、Subscribe で購読する。

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `id` | string | 必須 | 出来事の ID を表す。`webhook-id` ヘッダーと同じ値である。文字おこしくんは送り直しても、同じ出来事を複数の送信先へ送っても、同じ ID を使う。受け取る側はこの ID で重複を捨てる。 |
| `type` | "session.started" | 必須 | 出来事の種類を表す。 |
| `createdAt` | number（エポックミリ秒） | 必須 | 出来事の時刻（セッションを作った時刻。`data.createdAt` と同じ）を表す。 |
| `data` | object | 必須 | 始まったセッションを表す（フィールドの名前と意味は `GET /v1/sessions/{sessionId}` の応答と同じ）。 |
| `data.sessionId` | string | 必須 | セッションの ID を表す。 |
| `data.tenantId` | string | 必須 | セッションのテナント（Discord サーバー）を表す。 |
| `data.label` | string（1〜100 文字） | 必須 | セッションの表示名を表す。 |
| `data.externalRef` | string（1〜256 文字） | 任意 | 入力元での識別子を表す。公式の Discord ボットのセッションでは `discord:<guildId>:<channelId>` になる。入力元での識別子の無いセッションには、このフィールドは無い。 |
| `data.createdAt` | number（エポックミリ秒） | 必須 | セッションを作った時刻を表す。 |

```json
{
  "id": "evt_2Gd7Np4Qx9Ls1Vk6Rc3Wm8Hb",
  "type": "session.started",
  "createdAt": 1790350826814,
  "data": {
    "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
    "tenantId": "111111111111111111",
    "label": "#雑談 VC",
    "externalRef": "discord:111111111111111111:222222222222222222",
    "createdAt": 1790350826814
  }
}
```

### `session.ended` {#session-ended}

文字おこしくんはセッションが終わると、音声認識の結果を最後まで受け取ってから、この出来事を送る。発言を保存する Discord サーバーでは、文字おこしくんは確定した発言を保存し終えてからこの出来事を送るので、あなたがこの出来事を受け取ってから書き出す（`GET /v1/sessions/{sessionId}/transcript`）と、終わりまでの確定した発言を受け取れる。`data.audioSeconds`（利用量）と `data.retainUntil`（削除される時刻）も、この時点で確定している。文字おこしくんの停止と再起動ではセッションは終わらないので、文字おこしくんはこの出来事を送らない。

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `id` | string | 必須 | 出来事の ID を表す。`webhook-id` ヘッダーと同じ値である。文字おこしくんは送り直しても、同じ出来事を複数の送信先へ送っても、同じ ID を使う。受け取る側はこの ID で重複を捨てる。 |
| `type` | "session.ended" | 必須 | 出来事の種類を表す。 |
| `createdAt` | number（エポックミリ秒） | 必須 | 出来事の時刻（セッションが終わった時刻。`data.endedAt` と同じ）を表す。 |
| `data` | object | 必須 | 終わったセッションを表す（フィールドの名前と意味は `GET /v1/sessions/{sessionId}` の応答と同じ）。 |
| `data.sessionId` | string | 必須 | セッションの ID を表す。 |
| `data.tenantId` | string | 必須 | セッションのテナント（Discord サーバー）を表す。 |
| `data.label` | string（1〜100 文字） | 必須 | セッションの表示名を表す。 |
| `data.externalRef` | string（1〜256 文字） | 任意 | 入力元での識別子を表す。公式の Discord ボットのセッションでは `discord:<guildId>:<channelId>` になる。入力元での識別子の無いセッションには、このフィールドは無い。 |
| `data.createdAt` | number（エポックミリ秒） | 必須 | セッションを作った時刻を表す。 |
| `data.endedAt` | number（エポックミリ秒） | 必須 | セッションが終わった時刻を表す。 |
| `data.endReason` | "requested" / "idle" / "quota_exceeded" \| string | 必須 | セッションが終わった理由を表す。今は `requested`（`POST /v1/sessions/{sessionId}/end` で終わった。公式の Discord ボットが Discord の `/stop` で終えたときも含む）・`idle`（Ingest（音声の送り手）がつながらないまま 30 分が過ぎた。または、文字おこしくんの再起動の後に、誰もつなぎ直さなかった）・`quota_exceeded`（テナントの今日（UTC）の利用量が上限に達した。公式の文字おこしくんには 1 日の上限が無い）のどれかである。文字おこしくんは理由を足すことがあるので、受け取る側は知らない値も受け入れる。 |
| `data.audioSeconds` | number（0 以上） | 必須 | このセッションの利用量（音声認識にかけた音声の秒数。小数第 3 位まで）を表す。`GET /v1/sessions/{sessionId}` の `audioSeconds` と同じ値である。 |
| `data.retainUntil` | number（エポックミリ秒） | 任意 | セッションの記録が保持期間を過ぎて削除される時刻を表す。文字おこしくんが記録を削除しないなら、このフィールドは無い。 |

```json
{
  "id": "evt_5Jt1Ry8Fk3Zm6Qa9Lw2Pc4Xn",
  "type": "session.ended",
  "createdAt": 1790354426814,
  "data": {
    "sessionId": "0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10",
    "tenantId": "111111111111111111",
    "label": "#雑談 VC",
    "externalRef": "discord:111111111111111111:222222222222222222",
    "createdAt": 1790350826814,
    "endedAt": 1790354426814,
    "endReason": "requested",
    "audioSeconds": 1234.567,
    "retainUntil": 1792946426814
  }
}
```

### `webhook.test` {#webhook-test}

Discord サーバーの管理者が管理画面の「テストを送る」を押すと、文字おこしくんはこの出来事を 1 回だけ送り、失敗しても自動では送り直さない。管理者が送信の記録の「もう一度送る」を押すと、文字おこしくんは同じ `webhook-id` でもう一度送る（受け取る側はほかの出来事と同じく ID で重複を捨てる）。管理者が送信先を止めているときも、文字おこしくんは `webhook.test` を送る（管理者は再開する前に受け取る側を確かめられる）。受け取る側はほかの出来事と同じく署名を確かめてから 2xx を返す。

| フィールド | 型 | | 説明 |
|---|---|---|---|
| `id` | string | 必須 | 出来事の ID を表す。`webhook-id` ヘッダーと同じ値である。文字おこしくんは送り直しても、同じ出来事を複数の送信先へ送っても、同じ ID を使う。受け取る側はこの ID で重複を捨てる。 |
| `type` | "webhook.test" | 必須 | 出来事の種類を表す。 |
| `createdAt` | number（エポックミリ秒） | 必須 | 出来事の時刻（文字おこしくんがテストを送った時刻）を表す。 |
| `data` | object | 必須 | テストを送った送信先を表す。 |
| `data.webhookId` | string | 必須 | テストを送った送信先の ID を表す。 |
| `data.tenantId` | string | 必須 | 送信先のテナント（Discord サーバー）を表す。 |

```json
{
  "id": "evt_7Bv3Mh6Ks1Dx9Tq4Wj2Ne8Uc",
  "type": "webhook.test",
  "createdAt": 1790350226814,
  "data": {
    "webhookId": "wh_4fT9kQ2mX7pL1vR8cZ3nB6yD",
    "tenantId": "111111111111111111"
  }
}
```

## ヘッダー {#headers}

文字おこしくんは次のヘッダーを付けて、本文を `Content-Type: application/json` で送ります。

| ヘッダー | 内容 |
|---|---|
| `webhook-id` | 出来事の ID を表す（本文の `id` と同じ）。文字おこしくんは送り直しても同じ ID を使う。受け取る側はこの ID で重複を捨てる。 |
| `webhook-timestamp` | この試行の時刻（Unix 秒）を表す。文字おこしくんは送り直すたびに新しい時刻にする。受け取る側は自分の時刻と 5 分より離れた時刻の要求を捨てる。 |
| `webhook-signature` | 署名を表す。署名は `v1,` + base64(HMAC-SHA256(鍵, `<webhook-id>.<webhook-timestamp>.<本文>`)) で、鍵はシークレットの `whsec_` の後ろを base64 で戻した 32 バイトである。シークレットを作り直してから 24 時間、文字おこしくんは前のシークレットの署名と新しいシークレットの署名を空白で区切って並べる。受け取る側はどれか 1 つが一致すれば要求を受け入れる。 |

## 署名を確かめる {#verify}

文字おこしくんは [Standard Webhooks](https://www.standardwebhooks.com/) の形で本文に署名します。署名を確かめると、要求が文字おこしくんから届いたことと、本文が途中で書き換えられていないことが分かります。文字おこしくんは Cloudflare のネットワークから送るので、送信元の IP アドレスではなく署名で確かめてください。

1. JSON として読む前のバイト列のまま、受け取った本文を取っておきます。JSON として読んでから書き直した文字列では、署名が合いません。
2. `webhook-timestamp` があなたのサーバーの今の時刻から 5 分より離れていれば、要求を捨てます。古い要求をもう一度送られても受け付けないためです。
3. シークレットの `whsec_` の後ろを base64 として読み、32 バイトの鍵にします。
4. `webhook-id`・`.`・`webhook-timestamp`・`.`・本文をこの順につないだバイト列の HMAC-SHA256 を、手順 3 の鍵で計算し、base64 にします。
5. `webhook-signature` を空白で区切ります。`v1,` で始まる署名のどれかが `v1,` と手順 4 の値をつないだ文字列と一致すれば、要求は文字おこしくんから届いたものです。署名が一致するかは定数時間で比べる関数（Node の `crypto.timingSafeEqual`、Python の `hmac.compare_digest`）で確かめます。
6. 確かめられなければ、`400` などを返して要求を捨てます。

Discord サーバーの管理者がシークレットを作り直すと、文字おこしくんは 24 時間、前のシークレットの署名と新しいシークレットの署名を `webhook-signature` に並べます。その 24 時間の内に、あなたのサーバーのシークレットを新しいものに替えてください。

Standard Webhooks の各言語のライブラリでも署名を確かめられます。依存の無い例は TypeScript の [examples/mojiokoshi-webhook.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-webhook.ts)（Node 22.18 以降 / Deno / Bun / Cloudflare Workers）と Python の [examples/mojiokoshi_webhook.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_webhook.py)（Python 3.10 以降、標準ライブラリだけ）にあります。

### TypeScript {#verify-typescript}

```ts
// webhook.mts を node webhook.mts で実行する（Node 22.18 以降。examples/mojiokoshi-webhook.ts を同じフォルダに置く）
import { createServer } from "node:http";
import { MojiokoshiWebhookError, verifyMojiokoshiWebhook } from "./mojiokoshi-webhook.ts";

const secret = process.env.MOJIOKOSHI_WEBHOOK_SECRET!; // whsec_…（ソースに書かず、環境変数などから読む）
const seen = new Set<string>(); // 受け取った webhook-id（本番では DB に置く）

createServer((request, response) => {
  const chunks: Buffer[] = [];
  request.on("data", (chunk: Buffer) => chunks.push(chunk));
  request.on("end", async () => {
    let event;
    try {
      // JSON として読む前の生の本文で確かめる
      event = await verifyMojiokoshiWebhook(Buffer.concat(chunks), request.headers, secret);
    } catch (error) {
      response.writeHead(error instanceof MojiokoshiWebhookError ? 400 : 500).end();
      return;
    }
    response.writeHead(204).end(); // すぐに 2xx を返し、時間のかかる仕事はこの後に始める
    if (seen.has(event.id)) return; // 同じ出来事が 2 回以上届くことがある
    seen.add(event.id);
    switch (event.type) {
      case "session.started":
        console.log("始まった", event.data.sessionId, event.data.label);
        break;
      case "session.ended":
        console.log("終わった", event.data.sessionId, event.data.endReason);
        break;
      default:
        break; // webhook.test と知らない出来事には何もしない
    }
  });
}).listen(8787);
```

### Python {#verify-python}

```python
# examples/mojiokoshi_webhook.py を同じフォルダに置く（Python 3.10 以降、標準ライブラリだけ）
import os

from mojiokoshi_webhook import HeadersLike, WebhookVerificationError, verify_webhook

seen: set[str] = set()  # 受け取った webhook-id（本番では DB に置く）


def handle(body: bytes, headers: HeadersLike) -> int:
    """生の本文（bytes）とヘッダーから、返すステータスを決める（Flask なら request.get_data() と request.headers を渡す）"""
    try:
        event = verify_webhook(body, headers, os.environ["MOJIOKOSHI_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return 400
    if event["id"] not in seen:  # 同じ出来事が 2 回以上届くことがある
        seen.add(event["id"])
        if event["type"] == "session.ended":
            print("終わった", event["data"]["sessionId"], event["data"]["endReason"])
    return 204  # 時間のかかる仕事は応答を返してから始める
```

`python mojiokoshi_webhook.py 8787` を実行すると、例のファイルが試しの受け取り口になり、届いた出来事を表示します。文字おこしくんから出来事が届くようにするには、外から `https://` の URL で受け取り口につながるようにしてください。

### 例の値で試す {#test-vector}

あなたが書いた署名の確かめ方はこの節の値で試せます。次のシークレット・ヘッダー・本文の組では、署名が一致します。手順 2 の時刻のずれの確かめは外して試してください。シークレットは例のためだけに作った値で、どの送信先のものでもありません。

| 項目 | 値 |
|---|---|
| シークレット | `whsec_RcH9I+W4YiNiF5/mN29sT9OdBZqc5KWM7rKcdRhK84Q=` |
| `webhook-id` | `evt_2Gd7Np4Qx9Ls1Vk6Rc3Wm8Hb` |
| `webhook-timestamp` | `1790350826` |
| `webhook-signature` | `v1,jV/+k3t+ftGc5l+2rz1BaaVl0jG9zw06s4btUWryOEE=` |

本文（1 行の JSON。改行も空白もこの文字列のとおりです）:

```json
{"id":"evt_2Gd7Np4Qx9Ls1Vk6Rc3Wm8Hb","type":"session.started","createdAt":1790350826814,"data":{"sessionId":"0f0c3c1e-5b7a-4d2e-9c61-3f2d8a4b7e10","tenantId":"111111111111111111","label":"#雑談 VC","externalRef":"discord:111111111111111111:222222222222222222","createdAt":1790350826814}}
```

## 応答のしかた {#respond}

- 出来事を受け取ったら、すぐに 2xx を返してください。文字おこしくんは 2xx の応答だけを成功にし、応答の本文を読みません。書き出しのような時間のかかる仕事は 2xx を返してから始めてください。
- 文字おこしくんは 15 秒の内に応答が無い試行を打ち切り、失敗にします。Discord サーバーの管理者が管理画面の「テストを送る」か「もう一度送る」を押したときは、文字おこしくんは 5 秒の内に応答が無い試行を打ち切ります。
- 3xx を含め、2xx のほかのステータスはすべて失敗です。文字おこしくんはリダイレクトをたどりません。
- 受け取る側が `410 Gone` を返すと、文字おこしくんはすぐにその送信先を止めます（管理画面の状態は「送信先が受け取りをやめたため停止」）。Discord サーバーの管理者が管理画面で再開するまで、文字おこしくんはその送信先に出来事を送りません（[送らないとき](#not-sent)）。`410 Gone` はその送信先で出来事を受け取るのをやめるときだけ返してください。Discord サーバーの管理者が「テストを送る」か「もう一度送る」で送った出来事に受け取る側が `410` を返しても、文字おこしくんは送信先を止めません。

## 送り直し {#retries}

文字おこしくんは失敗した出来事を、次の間隔で送り直します。送り直しても `webhook-id` は変わりません。文字おこしくんは送り直すたびに `webhook-timestamp` と署名を作り直します。

| 試行 | 文字おこしくんが送るとき |
|---|---|
| 1 回目 | 出来事が起きたとき |
| 2 回目 | 1 回目が失敗してから 5 秒後 |
| 3 回目 | 2 回目が失敗してから 5 分後 |
| 4 回目 | 3 回目が失敗してから 30 分後 |
| 5 回目 | 4 回目が失敗してから 2 時間後 |
| 6 回目 | 5 回目が失敗してから 5 時間後 |
| 7 回目 | 6 回目が失敗してから 10 時間後 |
| 8 回目 | 7 回目が失敗してから 10 時間後 |

文字おこしくんは最初の試行を含めて 8 回まで送ります。間隔を足すと、最初の試行から最後の試行まで約 27.6 時間です。8 回目も失敗すると、その出来事は失敗になり、文字おこしくんはその送信先を止めます（管理画面の状態は「失敗が続いたため停止」）。止めた送信先のほかの送信待ちの出来事も失敗になります。Discord サーバーの管理者が再開するまで、文字おこしくんはその送信先に出来事を送らず、その間に起きた出来事を後から送ることもありません（[送らないとき](#not-sent)）。

受け取る側へ送れなかった原因が文字おこしくんの側にあるときは、その試行は 8 回までの試行の回数に入りません。文字おこしくんはその出来事を 5 分後に送り直します。原因が文字おこしくんの側にある失敗が続いても、文字おこしくんは送信先を止めません。

Discord サーバーの管理者は管理画面の「送信の記録」の「もう一度送る」で、失敗した出来事を 1 つずつ送り直せます。終わった送信の記録は 7 日で削除されるので、Discord サーバーの管理者は失敗した出来事を 7 日の内に送り直してください。

## 届け方 {#delivery}

- 文字おこしくんは同じ出来事を 2 回以上送ることがあります。たとえば、受け取る側の応答が打ち切りの時間（15 秒）に間に合わなかったときと、受け取る側が 2xx を返した後、文字おこしくんが結果を記録する前に再起動したときに、文字おこしくんは同じ出来事をもう一度送ります。`webhook-id`（本文の `id`）を覚えておき、覚えている `webhook-id` の要求には何もせずに 2xx を返してください。
- 文字おこしくんは送信先ごとに、次の試行の時刻が早い出来事から送るので、出来事を起きた順に届けるとは限りません。たとえば、`session.started` を送り直している間に、同じセッションの `session.ended` が先に届くことがあります。順番が必要なときは、本文の `createdAt` で並べてください。
- 文字おこしくんが止まっている間は、文字おこしくんは出来事を送りません。文字おこしくんは再起動すると、送れていない出来事から送ります。

## 送らないとき {#not-sent}

文字おこしくんは次のときに出来事を送りません。

- 動いているセッションを使い回したとき（`POST /v1/sessions` の `reuseActive`）。公式の Discord ボットも同じ VC で動いているセッションを使い回します。文字おこしくんはセッションを作ったときに 1 回だけ `session.started` を送ります。
- 文字おこしくんの再起動の後に、動いていたセッションを動かし直したとき。文字おこしくんの停止と再起動ではセッションは終わらないので、文字おこしくんは `session.ended` も送りません。
- 文字おこしくんの運営者がその Discord サーバーの API キーの利用を止めているとき（API キーでの要求には、文字おこしくんが [`api_access_disabled`](https://moji.kaitoranma.com/docs/errors/index.md#api_access_disabled) を返します）。文字おこしくんの運営者が API キーの利用を止める前から送信待ちだった出来事も、文字おこしくんは送らずに失敗にします。
- Discord サーバーの管理者か文字おこしくんが送信先を止めているとき（[応答のしかた](#respond)・[送り直し](#retries)）。止めたときに送信待ちだった出来事は失敗になります。Discord サーバーの管理者が送信先を再開した後も、文字おこしくんは送信先が止まっている間に起きた出来事を送りません。
- Discord サーバーの管理者が送信先の「送る出来事」でその出来事を選んでいないとき。
- 1 つの送信先に送信待ちの出来事が 1000 件あるとき。文字おこしくんはその送信先の送信待ちが 1000 件より少なくなるまで、新しく起きた出来事をその送信先に送らず、送信の記録にも残しません。
- 文字おこしくんが出来事を送り終える前に、その出来事のセッションが削除されたとき（保持期間が過ぎたときと、あなたが [`DELETE /v1/sessions/{sessionId}`](https://moji.kaitoranma.com/docs/http.md#deleteSession) を呼んだとき）。

Discord サーバーの管理者は管理画面の「送信の記録」の「もう一度送る」で、失敗になった出来事を 7 日の内に送り直せます（[送り直し](#retries)）。送信先が止まっている間に起きた出来事は送信の記録に無いので、Discord サーバーの管理者も送り直せません。あなたは文字おこしくんが出来事を送らなかったセッションを [`GET /v1/sessions`](https://moji.kaitoranma.com/docs/http.md#listSessions) の一覧から探せます。

## 「保存しない」設定で記録を残す {#store-transcripts-off}

Discord サーバーの管理者が管理画面の「管理者向け設定」の「文字おこしの保存」で発言を保存しないように決めると、文字おこしくんはその Discord サーバーの発言を保存しません。書き出しには何も入りません。あなたが途中から購読すると、文字おこしくんは直近の発言だけを `welcome` で送ります（件数は[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md#websocket)にあります）。記録をあなたの所に残すときは、`session.started` を受け取ったらすぐに購読を始めます。

Discord サーバーの管理者は参加者に「記録を残さない」と伝えたうえで「保存しない」を選んでいることがあります。あなたの所に記録を残すときは、記録を残すことを参加者に伝え、了承を得てください（[プライバシーポリシー](https://moji.kaitoranma.com/legal/privacy.html#who-can-see)）。

1. Discord サーバーの管理者に、管理画面の「送る出来事」で「文字起こしの開始」（`session.started`）と「文字起こしの終了」（`session.ended`）の両方を選んでもらいます。
2. `session.started` を受け取ったら、あなたのサーバーが API キー（`transcripts:read`）で [`POST /v1/sessions/{sessionId}/tokens`](https://moji.kaitoranma.com/docs/http.md#createSessionToken) を呼び、`data.sessionId` の `transcript:read` のトークンを発行します。API キーの作り方は[クイックスタート](https://moji.kaitoranma.com/docs/quickstart.md#from-api-key)にあります。
3. 発行したトークンで Subscribe（`/v1/subscribe`）に接続し、確定した発言（`final`・`refined`）を `utteranceId` ごとに置き換えながら保存します（[発話の改訂モデル](https://moji.kaitoranma.com/docs/revisions.md)。参照実装は [examples/mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js)）。トークンの期限の後につなぎ直すときは、トークンを発行し直します（[再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md#token-expiry)）。
4. `session.ended` を受け取ったら、そのセッションの発言の保存を終えます。文字おこしくんは Subscribe の接続にも `session_ended` を送ります。

文字おこしくんが発言を保存する Discord サーバーでは、`session.ended` を受け取ってから [`GET /v1/sessions/{sessionId}/transcript`](https://moji.kaitoranma.com/docs/http.md#exportTranscript) で書き出すと、終わりまでの記録を受け取れます（[記録と書き出し](https://moji.kaitoranma.com/docs/guides/archive.md)）。新しく終わったセッションを探して一覧を読み直す必要はありません。

---

<!-- source: https://moji.kaitoranma.com/docs/errors/index.md -->

# エラーコード

機械可読な版は [errors.json](https://moji.kaitoranma.com/docs/errors.json) にあります。

## WebSocket のコード

### `unauthorized` {#unauthorized}

- 対処: 新しいセッショントークン（Ingest は ingest:write、Subscribe は transcript:read）や有効な API キーを使う。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: クライアントが資格情報を送らなかった。または、送った資格情報が、不正か、期限切れか、失効している。または、トークンの権限（scope）が足りない。
- HTTP: 401「認証が必要です」（WWW-Authenticate: Bearer realm="mojiokoshi"）

### `protocol_version_unsupported` {#protocol_version_unsupported}

- 対処: hello の protocolVersion を 1 にする（クライアントを更新する）。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: hello の protocolVersion を文字おこしくんが扱えない。

### `invalid_message` {#invalid_message}

- 対処: 送るメッセージを JSON Schema で検証して直す。fatal なら、文字おこしくんが hello を拒んだので、同じ hello で再接続しない。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、再接続しない。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: クライアントが、JSON として読めないメッセージか、形式に違反するメッセージを送った。hello の前にほかのメッセージを送ったときと、hello が時間内（10 秒）に届かないときも、文字おこしくんはこのコードを送る。

### `unknown_track` {#unknown_track}

- 対処: track_open でトラックを開いてから、その channel で音声を送り、その trackId で speech_start / speech_end を送る。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: クライアントが、開いていない trackId か channel を参照した。

### `unknown_speaker` {#unknown_speaker}

- 対処: speaker_upsert で話者を宣言してから、その話者の single トラックを track_open する。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: クライアントが、speaker_upsert で宣言していない speakerId を参照した。たとえば、single トラックの speakerId が、宣言していない話者を指していた。

### `channel_in_use` {#channel_in_use}

- 対処: 使っていない channel 番号で track_open し直す（track_close した番号は再利用してよい）。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: track_open で指定した channel を、同じ接続の別のトラックが使っている。

### `track_limit_exceeded` {#track_limit_exceeded}

- 対処: 使っていないトラックを track_close してから、新しいトラックを開く。文字おこしくんが開かなかったトラックの音声は送らない。全部の API キーを合わせた上限に当たったときは、時間をおいてから、文字おこしくんが開かなかったトラックを開き直す。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: トラックの数が、1 接続あたりの上限（64 本）を超えた。または、API キーで作ったセッションで開いているトラックの数が、全部の API キー（ほかの利用者のキーを含む）を合わせた上限を超えた。または、テナント（Discord サーバー）の同時トラック数が、文字おこしくんの運営者が付けた上限を超えた。公式の文字おこしくん（moji.kaitoranma.com）には、テナントの同時トラック数の上限は無い。

### `unsupported_format` {#unsupported_format}

- 対処: opus は 48000 Hz・1/2ch、pcm_s16le は 8000〜48000 Hz・1/2ch で track_open し直す。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: track_open の format（コーデック・サンプルレート・チャンネル数）を文字おこしくんが扱えない。

### `rate_limited` {#rate_limited}

- 対処: 送る量を減らす。HTTP では、Retry-After の秒数だけ待ってから要求をやり直す。WebSocket では、文字おこしくんが接続を切ったら、待ち時間をおいて再接続する。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、30 秒待って再接続する。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: 送信量・要求数・接続数・話者数などが上限を超えた。または、Subscribe のクライアントの受信が、文字おこしくんからの送信に追いつかない。
- HTTP: 429「要求が多すぎます」（Retry-After、retryAfterSeconds、RateLimit / RateLimit-Policy）

### `session_ended` {#session_ended}

- 対処: 再接続しない。文字起こしを続けるなら、新しいセッションを作る。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: セッションが終了しているか、存在しない。保持期間を過ぎて消えたセッションにも、文字おこしくんはこのコードを送る。
- HTTP: 409「セッションは終了しています」

### `superseded` {#superseded}

- 対処: 再接続しない。新しい接続のほうが有効になっている。1 セッションに、Ingest の送り手は 1 つだけにする。
- WebSocket（Ingest）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: 同じセッションに新しい Ingest の接続が来たので、文字おこしくんがこの接続を新しい接続に置き換えた。

### `quota_exceeded` {#quota_exceeded}

- 対処: 次の UTC 0 時（日本時間 9:00）の後に新しいセッションを作る。公式の文字おこしくん（moji.kaitoranma.com）には、1 日の利用量の上限は無い。上限を変えたいときは、文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- WebSocket（Ingest）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: テナント（Discord サーバー）の利用量が、今日（UTC）の利用上限に達した。Ingest では、セッションも終わっている。
- HTTP: 429「利用上限に達しました」（Retry-After（次の UTC 0 時までの秒数）、retryAfterSeconds、quota）

### `internal` {#internal}

- 対処: 指数バックオフ（ジッター付き）でやり直す。問題が続くなら、文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、バックオフで再接続する。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: 文字おこしくんの内部で問題が起きた。
- HTTP: 500「文字おこしくんの内部のエラーです」

## HTTP だけのコード

### `forbidden` {#forbidden}

- 対処: 対象のセッションとテナントに合った資格情報を使う。
- 起きたこと: 要求に使ったトークンが、別のセッションのものだった。または、要求の tenantId か externalRef が、API キーのテナントと違っていた。
- HTTP: 403「この操作は許可されていません」

### `insufficient_scope` {#insufficient_scope}

- 対処: 応答の requiredScope が示すスコープを持つ API キーを、Discord サーバーの管理者に管理画面で発行してもらう。
- 起きたこと: 要求に使った API キーに、その操作のスコープが無い。
- HTTP: 403「API キーの権限が足りません」（WWW-Authenticate（error="insufficient_scope", scope="…"）、requiredScope）

### `api_access_disabled` {#api_access_disabled}

- 対処: 文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- 起きたこと: このテナント（Discord サーバー）では、API キーの利用が止まっている。公式の文字おこしくん（moji.kaitoranma.com）では、文字おこしくんの運営者が止めたときだけ、この状態になる。
- HTTP: 403「API キーの利用が無効です」

### `invalid_json` {#invalid_json}

- 対処: Content-Type: application/json で正しい JSON のオブジェクトを送る。
- 起きたこと: 文字おこしくんが、要求の本文を JSON として読めなかった。
- HTTP: 400「本文が JSON ではありません」

### `invalid_request` {#invalid_request}

- 対処: detail が示すフィールドを直す。
- 起きたこと: 要求の値が不正だった。本文の形・クエリの形・パスの tenantId の形・Idempotency-Key の形のどれかが不正なときも、文字おこしくんはこのコードを返す。
- HTTP: 400「要求の値が不正です」

### `session_not_found` {#session_not_found}

- 対処: sessionId を確かめる。消えた記録は戻らないので、残したい記録は保持期間の内に書き出す。
- 起きたこと: 指定したセッションが無い。保持期間を過ぎて消えたセッションを指定したときと、API キーのテナントとは別のテナントのセッションを指定したときにも、文字おこしくんはこのコードを返す。
- HTTP: 404「セッションが見つかりません」

### `session_active` {#session_active}

- 対処: POST /v1/sessions/:id/end でセッションを終えてから削除する。終了の途中なら、少し待ってから削除をやり直す。
- 起きたこと: クライアントが、稼働中か終了の途中のセッションを削除しようとした。
- HTTP: 409「セッションは終了していません」

### `idempotency_in_progress` {#idempotency_in_progress}

- 対処: Retry-After の秒数だけ待ってから、同じキーと同じ本文で要求をやり直す。
- 起きたこと: 同じ Idempotency-Key の前の要求を、文字おこしくんがまだ処理している。
- HTTP: 409「同じ Idempotency-Key の要求を処理中です」（Retry-After: 1）

### `idempotency_mismatch` {#idempotency_mismatch}

- 対処: 別の操作には新しい Idempotency-Key を使う。
- 起きたこと: クライアントが、前の要求と同じ Idempotency-Key で、本文の違う要求を送った。
- HTTP: 422「この Idempotency-Key は、本文の違う要求で使用済みです」

### `not_found` {#not_found}

- 対処: パスを確かめる。API のパスは /v1 から始まる。
- 起きたこと: 要求したパスの API が無い。
- HTTP: 404「見つかりません」

### `method_not_allowed` {#method_not_allowed}

- 対処: リファレンス（openapi.yaml）が示すメソッドを使う。
- 起きたこと: そのパスでは、要求したメソッドを使えない。
- HTTP: 405「このメソッドは使えません」

### `payload_too_large` {#payload_too_large}

- 対処: 要求の本文を小さくする。
- 起きたこと: 要求の本文が 16 KiB を超えた。
- HTTP: 413「本文が大きすぎます」

### `upgrade_required` {#upgrade_required}

- 対処: WebSocket（wss://）でつなぐ。
- 起きたこと: クライアントが、WebSocket のパス（/v1/ingest・/v1/subscribe）に普通の HTTP でアクセスした。
- HTTP: 426「WebSocket で接続してください」（Upgrade: websocket）

### `too_many_connections` {#too_many_connections}

- 対処: 普通の切断と同じく指数バックオフで再接続する。使っていない接続を閉じる。
- 起きたこと: WebSocket の同時接続数が、上限（文字おこしくんの API 全体で 4,096、同じ送信元から 1,024）を超えた。文字おこしくんは、upgrade の要求への HTTP の応答でこのコードを返す。
- HTTP: 503 / 429「接続が多すぎます」（API 全体の上限は 503、同じ送信元の上限は 429）

### `shutting_down` {#shutting_down}

- 対処: バックオフしてから、要求をやり直す。文字おこしくんが再起動した後は、要求が通る。
- 起きたこと: 再起動かデプロイのために、文字おこしくんは停止の途中だった。
- HTTP: 503「文字おこしくんは停止の途中です」

## 使わなくなったコード

文字おこしくんは、この節のコードを、今は返しません。クライアントは、このコードを扱う処理を残しておいても、消しても構いません。

### `credits_exhausted` {#credits_exhausted}

- 使わなくなったコード: 文字おこしくんは、2026-10-14 から、このコードを返さない。
- 対処: 対処は要らない。古いクライアントは、このコードを扱う処理を残しておいてよい。
- 起きたこと: 以前、Discord サーバーのクレジットが残っていないときに返していたコード。文字おこしくんは、2026-10-14 から、このコードを返さない。
- HTTP: 402「クレジットが残っていません」

## 一覧

| code | WebSocket の接続 | HTTP |
|---|---|---|
| [`unauthorized`](#unauthorized) | 文字おこしくんが切り、クライアントは再接続しない | 401 |
| [`protocol_version_unsupported`](#protocol_version_unsupported) | 文字おこしくんが切り、クライアントは再接続しない | — |
| [`invalid_message`](#invalid_message) | fatal なら文字おこしくんが切り、クライアントは再接続しない | — |
| [`unknown_track`](#unknown_track) | 文字おこしくんは切らない | — |
| [`unknown_speaker`](#unknown_speaker) | 文字おこしくんは切らない | — |
| [`channel_in_use`](#channel_in_use) | 文字おこしくんは切らない | — |
| [`track_limit_exceeded`](#track_limit_exceeded) | 文字おこしくんは切らない | — |
| [`unsupported_format`](#unsupported_format) | 文字おこしくんは切らない | — |
| [`rate_limited`](#rate_limited) | fatal なら文字おこしくんが切り、クライアントは 30 秒待って再接続する | 429 |
| [`session_ended`](#session_ended) | 文字おこしくんが切り、クライアントは再接続しない | 409 |
| [`superseded`](#superseded) | 文字おこしくんが切り、クライアントは再接続しない | — |
| [`quota_exceeded`](#quota_exceeded) | 文字おこしくんが切り、クライアントは再接続しない | 429 |
| [`internal`](#internal) | fatal なら文字おこしくんが切り、クライアントはバックオフで再接続する | 500 |
| [`forbidden`](#forbidden) | — | 403 |
| [`insufficient_scope`](#insufficient_scope) | — | 403 |
| [`api_access_disabled`](#api_access_disabled) | — | 403 |
| [`invalid_json`](#invalid_json) | — | 400 |
| [`invalid_request`](#invalid_request) | — | 400 |
| [`session_not_found`](#session_not_found) | — | 404 |
| [`session_active`](#session_active) | — | 409 |
| [`idempotency_in_progress`](#idempotency_in_progress) | — | 409 |
| [`idempotency_mismatch`](#idempotency_mismatch) | — | 422 |
| [`not_found`](#not_found) | — | 404 |
| [`method_not_allowed`](#method_not_allowed) | — | 405 |
| [`payload_too_large`](#payload_too_large) | — | 413 |
| [`upgrade_required`](#upgrade_required) | — | 426 |
| [`credits_exhausted`](#credits_exhausted)（使わなくなった） | — | 402 |
| [`too_many_connections`](#too_many_connections) | — | 503 / 429 |
| [`shutting_down`](#shutting_down) | — | 503 |

クライアントは、未知のコードも受け入れ、error.fatal に従う。fatal な未知のコードでは、クライアントは internal と同じくバックオフで再接続する。HTTP では、クライアントは未知のコードをステータスで扱う（5xx と 429 は待ってやり直し、それ以外の 4xx はやり直さない）。

クライアントがいつ再接続し、いつ再接続せずに終えるかは[再接続とエラーの扱い](https://moji.kaitoranma.com/docs/reconnection.md)に、HTTP のエラーの形は [HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md#エラーproblem-details)にあります。

## 公式のアプリだけが受け取るコード

文字おこしくんは、公式のアプリ（管理画面と Discord アクティビティ）と文字おこしくんの運営者だけが使う操作に、この節のコードを返します。

### `key_not_found` {#key_not_found}

- 対処: keyId を確かめる。
- 起きたこと: 指定した API キーが無いか、別のテナントのものだった。
- HTTP: 404「API キーが見つかりません」

### `webhook_not_found` {#webhook_not_found}

- 対処: webhookId を確かめる。
- 起きたこと: 指定した Webhook の送信先が無いか、別のテナントのものだった。
- HTTP: 404「Webhook の送信先が見つかりません」

### `webhook_delivery_not_found` {#webhook_delivery_not_found}

- 対処: deliveryId と webhookId の組を確かめる。
- 起きたこと: 指定した送信の記録がその送信先に無い。終わった送信の記録は 7 日で削除される。削除された記録を指定したときにも、文字おこしくんはこのコードを返す。
- HTTP: 404「Webhook の送信の記録が見つかりません」

### `key_limit_exceeded` {#key_limit_exceeded}

- 対処: 使っていないキーを管理画面で取り消してから、新しいキーを作る。
- 起きたこと: テナントの有効な API キーの数が、上限（既定 25 個）に達した。
- HTTP: 409「API キーの数が上限に達しています」（limit）

### `webhook_limit_exceeded` {#webhook_limit_exceeded}

- 対処: 使っていない送信先を管理画面で削除してから、新しい送信先を追加する。
- 起きたこと: テナントの Webhook の送信先の数が上限（既定 5 個）に達した。
- HTTP: 409「Webhook の送信先の数が上限に達しています」（limit）

### `activity_not_configured` {#activity_not_configured}

- 対処: あなたの側では直せない（原因は、文字おこしくんの運営者の側の設定にある）。問題が続くときは、文字おこしくんの運営者に連絡する。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。文字おこしくんのサーバーに、アクティビティの設定が無い。
- HTTP: 503「アクティビティの設定がありません」

### `invalid_grant` {#invalid_grant}

- 対処: アクティビティを開き直して認可をやり直す。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。クライアントが送った OAuth2 の認可コードが、不正か、期限切れか、使用済みだった。
- HTTP: 400「認可コードが無効です」

### `not_in_channel` {#not_in_channel}

- 対処: ボイスチャンネルに入ってから、アクティビティを開く。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。要求した人が、アクティビティを開いた Discord サーバーのどのボイスチャンネルにもいない。要求した人がボイスチャンネルにいるかを確かめられないときも、文字おこしくんはこのコードを返す。
- HTTP: 403「ボイスチャンネルにいません」

### `no_active_session` {#no_active_session}

- 対処: 誰かが /start を実行して、文字起こしが始まるのを待つ。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。要求した人が今いるボイスチャンネルで、文字起こしが動いていない。
- HTTP: 404「稼働中のセッションがありません」

### `discord_unavailable` {#discord_unavailable}

- 対処: 少し待ってから、要求をやり直す。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。Discord の障害か上限のために、文字おこしくんが Discord の API に問い合わせられない。
- HTTP: 502「Discord に接続できません」

---

<!-- source: https://moji.kaitoranma.com/docs/limits.md -->

# レート制限と上限

> このページの値は、公式の文字おこしくん（`moji.kaitoranma.com`）の今の値で、予告なく変わることがあります。上限に当たったときの扱いは[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)にあります。

## WebSocket

| 対象 | 上限 | 超えたとき |
|---|---|---|
| 1 メッセージ（テキスト・バイナリ） | 64 KiB | 文字おこしくんが fatal な `invalid_message` を送って、接続を切る |
| 同時接続数（Ingest + Subscribe、文字おこしくんの API 全体） | 4,096 | 文字おこしくんが upgrade を HTTP 503（`too_many_connections`）で断る |
| 同時接続数（同じ送信元アドレスから） | 1,024 | 文字おこしくんが upgrade を HTTP 429（`too_many_connections`）で断る |
| `hello` が届くまで | 10 秒 | 文字おこしくんが `invalid_message` を送って、接続を切る |
| 1 セッションを同時に購読できる接続（Subscribe） | 100 | 文字おこしくんが fatal な `rate_limited` を送る |
| 送信待ちの詰まり（Subscribe。受け手の受信が遅い） | 文字おこしくんは、送信待ちが 64 KiB になると `partial` を間引き、1 MiB になると接続を切る | 文字おこしくんが非 fatal な `rate_limited` を送ってから、接続を切る（再接続すると、新しい `welcome` から始まる） |
| `welcome.recent` の発話 | 直近 50 件 | — |
| 1 セッションの Ingest 接続 | 1 本 | 文字おこしくんが古い接続を `superseded` で切る |
| 1 接続のトラック（Ingest） | 64 本 | 文字おこしくんが非 fatal な `track_limit_exceeded` を返す |
| 同時に開いているトラック（Ingest。API キーで作ったセッション全部の合計。ほかの利用者の API キーを含む） | 20 本 | 文字おこしくんが非 fatal な `track_limit_exceeded` を返し、新しいトラックを開かない。クライアントは、時間をおいてから、文字おこしくんが開かなかったトラックを開き直す。文字おこしくんは、公式の Discord ボットのセッションのトラックを数えない |
| 1 接続の話者（Ingest） | 256 人 | 文字おこしくんが非 fatal な `rate_limited` を返す |

## サーバーごとの上限（テナント = Discord サーバーごと）

| 項目 | 公式の文字おこしくんの値 | 超えたとき |
|---|---|---|
| 記録の保持期間 | セッションの終了から、Discord サーバーのレベルの日数（30・90・180・365 日。[利用規約 第6条](https://moji.kaitoranma.com/legal/terms.html#levels)）。日数は終了した時点のレベルで決まる。その後にレベルが上がると、文字おこしくんは、まだ消していない記録の保持期限（`retainUntil`）も、終了から上がったレベルの日数まで延ばす。レベルが下がっても、文字おこしくんは保持期限を早めない | 文字おこしくんは、期間を過ぎた記録を消す（そのセッションへの要求には `404 session_not_found` を返す） |
| API キーの利用 | 可（どの Discord サーバーでも） | 文字おこしくんの運営者がその Discord サーバーの API キーの利用を止めたときだけ、文字おこしくんが `403 api_access_disabled` を返す |
| 有効な API キーの数 | 25 個（Discord サーバーごと） | Discord サーバーの管理者は、管理画面で新しいキーを作れない（使っていないキーを取り消してから作る） |
| Webhook の送信先の数 | 5 個（Discord サーバーごと。止めている送信先も数える） | Discord サーバーの管理者は管理画面で新しい送信先を追加できない（使っていない送信先を削除してから追加する） |

- 利用量は**音声認識にかけた音声の秒数**で、文字おこしくんは利用量をトラックごとに数えて足します（3 人が同時に話せば 3 倍になります）。今の利用量は [`GET /v1/usage`](https://moji.kaitoranma.com/docs/http.md#getUsage)（`usage:read` の API キー）で分かります。公式の文字おこしくん（`moji.kaitoranma.com`）には、1 日の利用量の上限と、Discord サーバーごとの同時トラック数の上限はありません。
- Discord サーバーのメンバーは、[管理画面](https://moji.kaitoranma.com/app/)の「利用状況」で、その Discord サーバーの日ごとの発話の時間を確かめられます。
- Webhook の送り直しの間隔と回数は [Webhook リファレンスの送り直し](https://moji.kaitoranma.com/docs/webhooks.md#retries)に、応答を待つ時間は[応答のしかた](https://moji.kaitoranma.com/docs/webhooks.md#respond)にあります。
- 上限を変えたいときは、[contact@kaitoranma.com](mailto:contact@kaitoranma.com) へご連絡ください。

## HTTP API

| 対象 | 既定 | 超えたとき |
|---|---|---|
| API キーごと | 1 分あたり 120 要求（使える要求の数は、毎秒 2 ずつ戻り、最大 120 までたまる） | `429 rate_limited`（`Retry-After`） |
| 送信元 IP ごと（API キーを使わない要求: セッショントークンでの書き出しと ChatGPT への転送（`/chatgpt`）・認証に失敗した要求など） | 1 分あたり 120 要求 | `429 rate_limited`（`Retry-After`） |
| 書き出し（`/transcript`）の同時実行 | 文字おこしくんの API 全体で 2 本 | `429 rate_limited`（`Retry-After: 5`） |
| 本文の大きさ | 16 KiB | `413 payload_too_large` |
| セッションの一覧の 1 ページ（`limit`） | 既定 20、最大 100 | `400 invalid_request` |
| 利用量の期間（`from`〜`to`） | 両端を含めて 366 日まで | `400 invalid_request` |
| `Idempotency-Key` を覚える期間 | 24 時間 | — |

`RateLimit` ヘッダー・`Retry-After` の読み方と `Idempotency-Key` の使い方は、[HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md#レート制限)にあります。

### セッショントークンの有効期間

| 発行のしかた | 既定 | 最大 |
|---|---|---|
| API キーで `POST /v1/sessions/{sessionId}/tokens`（`ttlSeconds`） | 1 時間（3,600 秒） | 24 時間（86,400 秒） |
| API キーで `POST /v1/sessions`（応答の `ingest.token` / `subscribe.token`）・Discord の `/link`（返答のボタンで開くオーバーレイの URL） | 24 時間 | — |
| API キーで `POST /v1/sessions/{sessionId}/downloads`（書き出しのリンクの `transcript:download` のトークン。`ttlSeconds`） | 1 時間（3,600 秒） | 24 時間（86,400 秒）。文字おこしくんは、期限を記録の保存期限より後にしません |

**文字おこしくんには、トークンを 1 つずつ取り消す仕組みがありません**（流出したトークンは、期限まで使えてしまいます）。トークンの有効期間は、必要な長さより長くしないでください。

---

<!-- source: https://moji.kaitoranma.com/docs/viewer.md -->

# 表示ページの URL パラメータと CSS

> リンクの受け取り方と OBS への貼り方は、使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md)にあります。表示を一から自分で作るときは、あなたのプログラムが、同じトークンで公開 API から字幕のデータを受け取れます（[クイックスタート](https://moji.kaitoranma.com/docs/quickstart.md)・[ガイド: オーバーレイ](https://moji.kaitoranma.com/docs/guides/overlay.md)）。

## URL パラメータ

リンクの `#` の後ろに `&名前=値` を足すと、表示を変えられます（例: `https://moji.kaitoranma.com/#token=<トークン>&overlay=1&view=meeting&scale=1.5`）。

| したいこと | パラメータ | 既定 | 内容 |
|---|---|---|---|
| 表示の種類を変える | `view`: `seats` / `captions` / `lanes` / `meeting` / `flow`。`overlay=1` では、ほかに `telop` / `youtube` | `seats`（`overlay=1` では `telop`） | `seats` は対面（左右に話者、真ん中に会話）を、`captions` は字幕（新しい発言を下に足していく字幕）を、`lanes` はレーン（話者ごとの横長の帯に、いまの発言を出す表示）を、`meeting` は会議（話者ごとのカード）を、`flow` は流れる（確定した発言が右から左へ流れる表示）を表す。`telop` はテロップ（配信画面の下の字幕）を、`youtube` は [YouTube のコメント欄風](#youtube)を表す |
| 文字を大きく・小さくする | `scale`: 0.5〜4 | 1 | 文字の大きさの倍率を表す。どの表示でも、文字の大きさは、表示ページの大きさ（OBS ではブラウザソースの大きさ）にも比例する |
| テロップの行の数を変える | `lines`: 1〜10 | 3 | `telop` で重ねて出す行の数を表す |
| 消えるまでの秒数を変える | `fadeSeconds`: 0〜3600 | 20（`overlay=1` では 8） | 確定した発言が消えるまでの秒数を表す。0 なら、表示ページは発言を消さない。`youtube` では、表示ページは発言を消さない |
| 消えるまでの秒数を変える | `shortFadeSeconds`: 0〜3600 | 5（`overlay=1` では 3） | 相槌などの短い発言が消えるまでの秒数を表す |
| 消えるまでの秒数を変える | `shortChars`: 0〜50 | 5 | 表示ページは、`shortChars` の文字数以下の発言を、`shortFadeSeconds` で消す短い発言とみなす |
| アイコン・名前を出さない | `hideAvatars`: `1` | オフ | 表示ページは、アイコンを出さない |
| アイコン・名前を出さない | `hideNames`: `1` | オフ | 表示ページは、名前を出さない |
| 配色を変える | `theme`: `auto` / `dark` / `light` | `auto` | `auto` では、表示ページが配色を端末の設定に合わせる |
| 読み上げる | `live`: `1` | オフ | 表示ページは、確定した発言をスクリーンリーダーに読み上げさせる |
| （リンクに最初から入っている） | `token` | — | 表示用のトークンが入る |
| （リンクに最初から入っている） | `overlay`: `1` | オフ | 表示ページは、背景を透過し、ボタンなどを出さない（配信用オーバーレイ）。表示ページは、終了と失敗の知らせだけを右下に小さく出す |

- あなたは `telop` と `youtube` を、配信用オーバーレイ（`overlay=1` のリンク）でだけ選べます。表示ページは、`overlay=1` の無いリンクの `view=telop` と `view=youtube` を、`seats` で開きます。
- 表示ページは、なくした表示のリンクも開きます。表示ページは、`view=stage` を `seats` で、`view=timeline` を `lanes` で開きます。表示ページは、なくしたパラメータの `cols` と `window` を無視します。

あなたが表示ページの画面で表示の種類を切り替えると、表示ページが `view` を、アドレス欄の URL に書き戻します。書き戻した後の URL をコピーすれば、そのまま OBS に貼れます。

## 見た目を変える（カスタム CSS）

あなたは OBS のブラウザソースの「カスタム CSS」に CSS を書き足して、表示ページの色やフォントを変えられます。表示ページの CSS が、同じプロパティを、もっと詳しいセレクタで決めていることがあります。書き足した値が反映されないときは、値に `!important` を付けてください。

```css
/* 例: 文字のフォントを変え、対面の吹き出しを少し透かす */
.mv-root {
  --mv-font: "Noto Sans JP", sans-serif;
}
.mv-seats {
  --mv-msg-bg: rgba(14, 21, 40, 0.6) !important;
}
```

| プロパティ | 既定 | 内容 |
|---|---|---|
| `--mv-font` | BIZ UDPGothic → Hiragino Sans → Noto Sans JP → … | 文字のフォントを表す |
| `--mv-bg` / `--mv-surface` / `--mv-line` / `--mv-ink` | 暗い配色: `#14161d` / `#1e212b` / `#2e3242` / `#f1f2f5`、明るい配色: `#f7f6f2` / `#ffffff` / `#e5e3dc` / `#1c1f2a` | `--mv-bg` は表示ページの背景の色を表す（`overlay=1` では背景は透明）。`--mv-surface` は名札・レーンの面の色を、`--mv-line` は線の色を、`--mv-ink` は文字の色を表す |
| `--mv-leave-ms` | `600ms` | 発言が消えるときのフェードの長さを表す |
| `--mv-msg-bg` / `--mv-seat-avatar` / `--mv-seat-col` | 対面の表示が決める | `--mv-msg-bg` は対面の吹き出しの地の色を、`--mv-seat-avatar` は席のアイコンの大きさを、`--mv-seat-col` は左右の列の幅を表す。`--mv-msg-bg`・`--mv-seat-avatar`・`--mv-seat-col` は `.mv-seats` に書く |
| `--mv-display-font` / `--mv-rounded-font` | Dela Gothic One → … / M PLUS Rounded 1c → … | `--mv-display-font` は、テロップと会議の見出しの太い文字のフォントを表す。`--mv-rounded-font` は、会議のカードと名札の丸い文字のフォントを表す |
| `--mv-speaker` | 話者ごとに決まる | 話している人ごとの色を表す（話者を見分けるための色で、ブランドの色とは別）。表示ページが `--mv-speaker` を話者ごとに付けるので、`.mv-root` に書いても色は変わらない |

## YouTube のコメント欄風 {#youtube}

配信用オーバーレイ（`overlay=1` のリンク）に `&view=youtube` を足すと、表示ページは、確定した発言を、YouTube のライブチャットと同じ要素名・ID・入れ子・class で描きます。あなたが、YouTube のコメント欄向けに公開されている CSS（ジェネレーターで作った CSS など）を、OBS のブラウザソースの「カスタム CSS」にそのまま貼ると、表示ページは、貼った CSS の見た目で発言を出します。

| 階層 | 要素 |
|---|---|
| 外側 | `yt-live-chat-app` > `div#contents` > `yt-live-chat-renderer[hide-timestamps]` |
| `yt-live-chat-renderer` の中 | `tp-yt-iron-pages#content-pages` > `div#chat-messages` > `div#contents` > `div#chat` > `div#item-list` |
| 一覧 | `yt-live-chat-item-list-renderer[allow-scroll]` > `div#contents` > `div#item-scroller` > `div#item-offset` > `div#items` |
| コメント 1 件 | `yt-live-chat-text-message-renderer[author-type=""]` |
| コメントの中 | `yt-img-shadow#author-photo` > `img#img`、`div#content` > `span#timestamp`・`yt-live-chat-author-chip`（> `span#author-name`・`span#chat-badges`）・`span#message-container` > `span#message` |

表示ページは、YouTube と同じく、各要素に `class="style-scope <親の要素名>"` を付けます。

- 表示ページは、確定した発言（`final`・`refined`）だけを、確定した順に `#items` の末尾へ足します。表示ページは、新しい発言を下に足し、古い発言を上へ押し出します。表示ページは、話している途中の発言を出しません。
- 表示ページは、`fadeSeconds` では発言を消しません。発言を消したいときは、貼る CSS のアニメーションで消してください。
- 名前とアイコンは、話した人の Discord の名前とアイコンです。`hideNames=1` では、表示ページは `yt-live-chat-author-chip` を描きません。`hideAvatars=1` では、表示ページは `yt-img-shadow` を描きません。アイコンが無いときは、表示ページが、話者の色の地に頭文字を描いた絵を `img#img` に出します。
- 表示ページは、`#timestamp` に話し始めの時刻（見ている端末の時計の「時:分」）を書きます。表示ページは、YouTube の既定と同じく時刻を隠します。時刻を出すかは、貼る CSS が決めます。
- 表示ページは、`yt-live-chat-text-message-renderer` に、`data-utterance-id`・`data-seat-key`（例: `discord:<ユーザー ID>`）・`data-stage`（`final` か `refined`）と、話者の色の `--mv-speaker` も付けます。貼る CSS は、`data-seat-key` と `--mv-speaker` で、話者ごとに見た目を変えられます。
- 表示ページの標準の見た目は透明の地に白い文字です。表示ページは標準の見た目の規則の詳細度を 0 にしているので、貼った CSS は `!important` が無くても標準の見た目に勝ちます。

## デモ

表示ページの URL に `demo=1` を付けると、Discord で文字起こしをしていなくても、表示ページが架空のデータで字幕を表示します（トークンは要りません）。OBS のブラウザソースの URL を本物のリンクに貼り替える前に、表示の種類・位置・大きさを確かめられます。

| 見られるもの | URL |
|---|---|
| 対面（4 人） | [https://moji.kaitoranma.com/?demo=1](https://moji.kaitoranma.com/?demo=1) |
| 会議（10 人。`n` は話者の数で、1〜24） | [https://moji.kaitoranma.com/?demo=1&view=meeting&n=10](https://moji.kaitoranma.com/?demo=1&view=meeting&n=10) |
| 配信用のテロップ（背景は透過。OBS に貼って位置を合わせる） | [https://moji.kaitoranma.com/?demo=1&overlay=1](https://moji.kaitoranma.com/?demo=1&overlay=1) |
| 配信用のテロップを、ゲーム画面の代わりの背景の上で見る（ブラウザでの確認用） | [https://moji.kaitoranma.com/?demo=1&overlay=1&backdrop=1](https://moji.kaitoranma.com/?demo=1&overlay=1&backdrop=1) |

- 表示の設定（`view`・`theme`・`scale`・`lines`・`fadeSeconds` など）は、本物と同じように反映されます。
- `overlay=1` の無いデモでは、あなたは、Discord のアクティビティと同じ 5 つの表示（対面・字幕・レーン・会議・流れる）を選べます。テロップと YouTube のコメント欄風は、`overlay=1` のデモでだけ見られます。
- 架空のデータだと分かるように、表示ページはヘッダーに「デモ（架空のデータ）」と出します。配信用オーバーレイでは、表示ページは左上に小さく「DEMO」と出します。

---

<!-- source: https://moji.kaitoranma.com/docs/changelog.md -->

# 変更履歴

文字おこしくんは、公開 API（WebSocket・HTTP・Webhook）と、このドキュメント・仕様ファイルの変更を、新しい順にこのページに載せます。互換性の無い変更をするときは、WebSocket では `protocolVersion` を、HTTP ではパスの `/v1` を上げます。フィールド・エラーコード・任意の引数は、互換性のある変更として、予告なく足すことがあります。

## 2026-10-25

### Webhook

- 文字おこしくんは Webhook を始めました。文字おこしくんは文字起こしの開始（`session.started`）と終了（`session.ended`）を、Discord サーバーの管理者が登録した URL へ知らせます。Discord サーバーの管理者は管理画面の「開発者向け設定」で送信先を追加し、送る出来事を選べます（[Webhook リファレンス](https://moji.kaitoranma.com/docs/webhooks.md)）。
- 文字おこしくんは Webhook の本文に Standard Webhooks の形で署名します。署名を確かめる依存なしの例 [mojiokoshi-webhook.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-webhook.ts)（TypeScript）と [mojiokoshi_webhook.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_webhook.py)（Python）を公開しました（[署名を確かめる](https://moji.kaitoranma.com/docs/webhooks.md#verify)）。Webhook の本文の形は [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml) の `webhooks` にあります。
- Discord サーバーの管理者が発言を保存しない設定にしていても、あなたが `session.started` を受け取ってすぐに Subscribe で購読すれば、あなたの所に記録を残せます（[「保存しない」設定で記録を残す](https://moji.kaitoranma.com/docs/webhooks.md#store-transcripts-off)）。
- [レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)に、Webhook の送信先の数の上限（Discord サーバーごとに 5 個）を足しました。
- [エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)に、管理画面の Webhook の操作に文字おこしくんが返すコード（[`webhook_not_found`](https://moji.kaitoranma.com/docs/errors/index.md#webhook_not_found)・[`webhook_delivery_not_found`](https://moji.kaitoranma.com/docs/errors/index.md#webhook_delivery_not_found)・[`webhook_limit_exceeded`](https://moji.kaitoranma.com/docs/errors/index.md#webhook_limit_exceeded)）を足しました。

## 2026-10-14

### 料金と上限

- 文字おこしくんは、クレジットをなくしました。文字おこしくんは、どの Discord サーバーでも、文字起こし・HTTP API・書き出しを無料で提供します。文字おこしくんは、Discord サーバーの記録の保存期間を延ばす月額の応援（使い方の[応援して機能を強化](https://moji.kaitoranma.com/help/charge.md)）だけを有料にしました。
- 文字おこしくんは、Discord サーバーのレベルが上がったときに、まだ消していない記録の保持期限（`retainUntil`）も、セッションの終了から上がったレベルの日数まで延ばすようにしました。レベルが下がっても、文字おこしくんは保持期限を早めません（[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)）。
- 文字おこしくんは、セッションの作成に `402 credits_exhausted` を返さなくなりました。[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md#credits_exhausted)には、使わなくなったコードとして `credits_exhausted` を残します。
- 文字おこしくんは、Discord サーバーごとの同時トラック数の上限（10）をなくしました。1 接続のトラックの上限（64 本）は変わりません（[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)）。
- 文字おこしくんは、API キーで作ったセッションで開いているトラックを、全部の API キー（ほかの利用者のキーを含む）で合わせて数え、同時に 20 本までにしました。文字おこしくんは、20 本を超える `track_open` を、非 fatal な [`track_limit_exceeded`](https://moji.kaitoranma.com/docs/errors/index.md#track_limit_exceeded) で断ります。文字おこしくんは、公式の Discord ボットのセッションのトラックを数えません（[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)）。

### 書き出しと ChatGPT

- [文字起こしの書き出し](https://moji.kaitoranma.com/docs/http.md#exportTranscript)に、`disposition`（`attachment` か `inline`。既定は `attachment`）を足しました。`transcript:download` のトークンのリンクに `disposition=inline` を付けると、ブラウザは記録をファイルとして保存せず、ページとして表示します。
- [書き出しのリンクを作る](https://moji.kaitoranma.com/docs/http.md#createTranscriptDownloads)の応答に、`chatgptUrl` を足しました。`chatgptUrl`（[`GET /v1/sessions/{sessionId}/chatgpt`](https://moji.kaitoranma.com/docs/http.md#openTranscriptInChatGpt)）を開くと、文字おこしくんは、記録を議事録として要約するよう頼む文と、記録のページのアドレス（`format=text&disposition=inline`）を入れた ChatGPT（`https://chatgpt.com/`）へ転送します。`chatgptUrl` には、`urls` と同じ `transcript:download` のトークンが入っています。

### 表示ページ

- 表示ページの `view` から `stage` と `timeline` をなくしました。表示ページは、`view=stage` を対面（`seats`）で、`view=timeline` をレーン（`lanes`）で開きます。`stage` だけが使う `cols` と、`timeline` だけが使う `window` もなくしました（[表示ページの URL パラメータと CSS](https://moji.kaitoranma.com/docs/viewer.md)）。
- 表示ページ（`overlay=1` の無いリンク）で選べる表示を、Discord のアクティビティと同じ 5 つ（`seats`・`captions`・`lanes`・`meeting`・`flow`）にしました。表示ページは、`overlay=1` の無いリンクの `view=telop` と `view=youtube` を、対面（`seats`）で開きます。
- 配信用オーバーレイ（`overlay=1`）に、YouTube のコメント欄風の表示（`view=youtube`）を足しました。配信用オーバーレイは、確定した発言を、YouTube のライブチャットと同じ要素名・ID の形で出します。あなたは YouTube のコメント欄向けに公開されている CSS を、OBS の「カスタム CSS」にそのまま貼れます（使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md#customize)）。
- 表示ページの Content-Security-Policy を広げ、OBS の「カスタム CSS」（インラインの `<style>`）と、カスタム CSS が `@import` で読み込む https の CSS と Web フォントを通すようにしました。

### Discord のコマンドと管理画面

- 文字おこしくんは、Discord の `/charge` をなくしました。今のコマンドは `/start`・`/stop`・`/link`・`/usage`・`/help`・`/settings` の 6 つです（使い方の[コマンドの一覧](https://moji.kaitoranma.com/help/index.md#commands)）。登録をやめた `/transcribe-key` に古いクライアントから届いた要求にも、文字おこしくんは返答しなくなりました。
- 文字おこしくんは、文字起こしが終わったときのお知らせを、VC のチャットにだけ出すようにしました。お知らせには、「CSV でダウンロード」「JSON でダウンロード」に加えて、「ChatGPT で要約」のボタンが付きます。
- 管理画面の「API キー」の画面の名前を「開発者向け設定」に変えました。画面の URL（`https://moji.kaitoranma.com/app/guilds/<サーバー ID>/keys`）は変わりません。

## 2026-10-02

### Discord のコマンドの返答

- 文字おこしくんは、`/start` の返答に、表示ページと配信用オーバーレイを開くボタンを付けるのをやめました。表示ページと配信用オーバーレイのリンク（トークンの入った URL）は、`/link` の返答のボタンで受け取ってください（使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md#get-link)）。

### エラーコード

- 文字おこしくんは、Discord アクティビティ専用のエラー `not_in_channel` と `no_active_session` の `detail` の文と、[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)の説明を書き直しました。文字おこしくんは、アクティビティを開いたチャンネルではなく、アクティビティを開いた人が今いるボイスチャンネルで、2 つのエラーを返すかを決めるようになりました。

## 2026-09-30

### 書き出しのリンクと CSV

- 書き出しのリンクを作る [POST `/v1/sessions/{sessionId}/downloads`](https://moji.kaitoranma.com/docs/http.md#createTranscriptDownloads)（API キーの `transcripts:read`）を足しました。リンクには書き出しにだけ使える `transcript:download` のトークンが、クエリの `token` で入っています。資格情報を持たない人も、リンクを開くだけで記録をファイルとして保存できます。
- [文字起こしの書き出し](https://moji.kaitoranma.com/docs/http.md#exportTranscript)の `format` に `csv`（見出し `日時,話者,発言`。先頭に UTF-8 の BOM）を足しました。

### Discord のコマンドの名前（英語の名前に変更）

- 文字おこしくんは、Discord のコマンドを、トップレベルの英語の名前に変えました: `/start`・`/stop`・`/link`・`/usage`・`/help`・`/charge`。どの言語の Discord でも同じ名前です。設定を見る `/settings` も足しました。今の名前の一覧は、使い方の[コマンドの一覧](https://moji.kaitoranma.com/help/index.md#commands)にあります。
- このドキュメントでは、コマンドを今の名前で書きます（2026-09-29 の「日本語の名前だけで書く」はやめました）。
- 文字おこしくんは、HTTP API のエラー `no_active_session` と `credits_exhausted` の `detail` の文を、今のコマンドの名前（`/start`・`/charge`）で書くようにしました。

### 表示ページ

- 表示ページの右上の「⋯」から、「名前を出す」「アイコンを出す」「スクリーンリーダーで読み上げ」を外しました。あなたは名前・アイコンを出さない表示と読み上げを、URL パラメータの `hideNames`・`hideAvatars`・`live` で選びます（[表示ページの URL パラメータと CSS](https://moji.kaitoranma.com/docs/viewer.md)）。表示ページは、`live` を URL に書き戻さなくなりました。

### Discord のコマンドの名前と、エラーの文

- 文字おこしくんは、Discord のコマンドの日本語の名前を、`/文字起こし` から `/字幕` に変えました（`/字幕 開始`・`/字幕 停止`・`/字幕 リンク`・`/字幕 利用状況`・`/字幕 ヘルプ`）。`/チャージ` と、英語の Discord での名前（使い方の[コマンドの一覧](https://moji.kaitoranma.com/help/index.md#commands)）は変わりません。
- Discord は、コマンドの名前が変わると、そのコマンドの権限の設定を消します。Discord サーバーの管理者が、サーバーの設定の「連携サービス」で `/文字起こし` の権限を変えていたときは、`/字幕` の権限を設定し直してください。
- 文字おこしくんは、HTTP API のエラー `no_active_session` の `detail` の文を、今のコマンドの名前（`/字幕 開始`）で書くようにしました。ほかのエラーの `title` と `detail` の文と、[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)の説明の文も、主語と目的語のある文に書き直しました。

## 2026-09-29

### ドキュメント

- コマンドは日本語の名前だけで書くようにしました（2026-09-28 の「英語の Discord での名前を添えます」はやめました）。英語の Discord での名前は、使い方の[コマンドの一覧](https://moji.kaitoranma.com/help/index.md#commands)にあります。
- 管理 API と Discord アクティビティ専用の操作を、[HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md)と公開の [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml) から外しました。どちらも第三者の開発者は使えない操作です。
- 表示ページのページを[表示ページの URL パラメータと CSS](https://moji.kaitoranma.com/docs/viewer.md)にして、URL パラメータとカスタム CSS の一覧にしました。リンクの受け取り方と OBS への貼り方は、使い方の[表示ページと OBS](https://moji.kaitoranma.com/help/obs.md)にあります。

## 2026-09-28

### Discord のコマンド

- `/文字起こしキー`（英語の Discord では `/transcribe-key`）の登録をやめました。API キーの発行・一覧・取り消しは、管理画面の「API キー」（`https://moji.kaitoranma.com/app/guilds/<サーバー ID>/keys`）で行います。発行済みのキーはそのまま使えます。
- `/文字起こし ヘルプ`（英語の Discord では `/transcribe help`）を追加しました。始め方・字幕の見方・無料枠とチャージを、実行した人にだけ返します。
- `/文字起こし 開始`（英語の Discord では `/transcribe start`）を実行した人への返答に、表示ページと配信用オーバーレイを開くボタンを付けました（本文には URL を書きません）。`/文字起こし リンク`（英語の Discord では `/transcribe link`）の返答も、URL を本文に書かず、同じ 2 つのボタンで渡すようにしました（配信中に取り直しても、配信画面に URL が映りません）。リンクの返答は、Discord がボタンを受け付けないときだけ URL を本文に書きます（開始の返答は、ボタンなしで `/文字起こし リンク` を案内します）。
- このドキュメントでは、コマンドを日本語の Discord での名前で書き、英語の Discord での名前を添えます（例: `/文字起こし 開始`（英語の Discord では `/transcribe start`））。どちらも同じコマンドです。

### ドキュメントの場所

- 開発者向けドキュメントは `https://moji.kaitoranma.com/docs/`、規約・ポリシーは `https://moji.kaitoranma.com/legal/` に移りました。
- 公式の表示ページ・配信用オーバーレイの使い方（URL パラメータ・OBS の設定・デモ）を[表示ページと OBS](https://moji.kaitoranma.com/docs/viewer.md)にまとめました。
- エラーの `type`（`https://moji.kaitoranma.com/docs/errors/#<code>`）と JSON Schema の `$id` も新しい URL になります。`type` で分岐せず、`code` で分岐してください。
- プログラムを書かない利用者向けの[使い方](https://moji.kaitoranma.com/help/index.md)（`https://moji.kaitoranma.com/help/`）を作りました。ボットの追加・コマンド・字幕の見方・チャージ・困ったときは、そちらにあります。

### 表示ページの配色

- 公式の表示ページとアクティビティの地・面・線・文字の標準の色を、LP・管理画面と同じブランドの色にしました（[表示ページと OBS](https://moji.kaitoranma.com/docs/viewer.md#見た目を変えるカスタム-css)）。カスタム CSS で `--mv-*` を上書きしている場合は、上書きした色がそのまま反映されます。

### クレジット

- 文字起こしはサーバーごとのクレジット（1 クレジット ＝ 話している人 1 人ぶんの発話 60 秒）を使います。残りが無いサーバーでは、新しいセッションの作成が `402 credits_exhausted` になります（[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)）。

### API キーの発行は管理画面へ

- API キーの発行・一覧・取り消しは、Discord の `/文字起こしキー` から管理画面の「API キー」（`https://moji.kaitoranma.com/app/guilds/<サーバー ID>/keys`。Discord でログイン）に移りました。`/文字起こしキー` は、この画面へのボタンを返すだけにしたあと、登録をやめました（上の「Discord のコマンド」）。発行済みのキーはそのまま使えます。
- 発行のときにスコープ `transcripts:delete`（`DELETE /v1/sessions/{sessionId}`）と期限（`expiresAt`）を選べます。一覧に `lastUsedAt`・`expiresAt` が出ます。
- Discord の無音フレーム（Opus の `F8 FF FE`）は利用量に数えません。送らない場合も `sequence` は飛ばさないでください（[リファレンス](https://moji.kaitoranma.com/docs/reference.md)）。

## 2026-09-26

### HTTP API の公開

- API キー（`mjk_live_…`）で使う HTTP API を公開しました。ベース URL は `https://moji.kaitoranma.com` です。Discord サーバーの管理者が `/transcribe-key create`（日本語では `/文字起こしキー 発行`）でキーを発行し、`/transcribe-key list` / `/transcribe-key revoke` で管理します。
  - セッションの一覧（`GET /v1/sessions`、カーソルでページ送り）・状態（`GET /v1/sessions/{sessionId}`）
  - `transcript:read` / `ingest:write` のセッショントークンの発行（`POST /v1/sessions/{sessionId}/tokens`。API キーでは既定 1 時間・最大 24 時間）
  - 書き出し（`GET /v1/sessions/{sessionId}/transcript`、JSON / テキスト）
  - 利用量（`GET /v1/usage`）
  - 自分で音声を送るためのセッションの作成・終了（`POST /v1/sessions`・`POST /v1/sessions/{sessionId}/end`、`ingest:write`）
- リファレンス: [HTTP API リファレンス](https://moji.kaitoranma.com/docs/http.md) と [openapi.yaml](https://moji.kaitoranma.com/docs/openapi.yaml)（OpenAPI 3.1）。openapi.yaml はサーバーのコードの定数とエラーコードから生成し、本物のサーバーの全操作の応答（ステータス・ヘッダー・本文）を契約テストで検証しています。
- エラーは RFC 9457 の problem details（`application/problem+json`）になりました。以前からの `error` / `message` も同じ値で残しています（互換性あり）。コードの一覧は[エラーコード](https://moji.kaitoranma.com/docs/errors/index.md)と [errors.json](https://moji.kaitoranma.com/docs/errors.json)（HTTP のコードもサーバーのコードから生成）。
- レート制限（API キーごと・送信元 IP ごとに 1 分あたり 120 要求）と `RateLimit-Policy` / `RateLimit` / `Retry-After` ヘッダー、`Idempotency-Key`（24 時間）を入れました（[レート制限と上限](https://moji.kaitoranma.com/docs/limits.md)）。
- 依存なしの HTTP クライアントの例を公開しました: [mojiokoshi-http.ts](https://moji.kaitoranma.com/docs/examples/mojiokoshi-http.ts)（本物のサーバーを相手にテスト済み）、[mojiokoshi_http.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_http.py)。

### 開発者向けドキュメントの公開

- 開発者向けドキュメントを公開しました（このサイトの `/developers/`、[llms.txt](https://moji.kaitoranma.com/docs/llms.txt)、[llms-full.txt](https://moji.kaitoranma.com/docs/llms-full.txt)、[Agent Skill](https://moji.kaitoranma.com/docs/skill/SKILL.md)）。
- WebSocket API（Ingest `protocolVersion` 1・Subscribe `protocolVersion` 1）の機械可読な仕様を公開しました: [asyncapi.yaml](https://moji.kaitoranma.com/docs/asyncapi.yaml)（AsyncAPI 3.1）、[JSON Schema](https://moji.kaitoranma.com/docs/schemas/common.json)（2020-12）、[errors.json](https://moji.kaitoranma.com/docs/errors.json)。どれもサーバーのコードと同じ定義から生成し、本物のサーバーとの契約テストで確かめています。
- 依存なしの参照実装を公開しました: [mojiokoshi-subscribe.js](https://moji.kaitoranma.com/docs/examples/mojiokoshi-subscribe.js)、[mojiokoshi_subscribe.py](https://moji.kaitoranma.com/docs/examples/mojiokoshi_subscribe.py)。
- エラーコード `quota_exceeded` を追加しました（Ingest。テナントの 1 日の利用上限に達したとき、fatal）。エラーコードの追加は互換性のある変更なので `protocolVersion` は変わりません。知らないコードを受け入れるクライアントはそのまま動きます。

---