---
title: "ふりがなAPI — 日本語テキストを自然な読み仮名に変換"
description: "黒猫ゲーム部のふりがなAPIの技術仕様。エンドポイント、変換モード、リクエスト例、変換パイプライン、学習機能など開発者向けの情報をまとめています。"
url: https://ryuuneko.com/blog/furigana-api
published: 2026-02-26 17:29:49.977759
updated: 2026-07-04 22:18:46.447491
---

黒猫ゲーム部が提供する**ふりがなAPI**は、日本語テキスト内の漢字・数字・日付・時刻などを自然な読み仮名に変換するAPIです。配信の読み上げBOTやコメント読み上げプラグインのバックエンドとして動作しています。

形態素解析エンジン（Lindera / IPADIC辞書）と**独自辞書**を組み合わせ、日本語的に正しい読みよりも**話し言葉として自然な読み**を優先して変換します。Rust（Axum）で実装されており、高速な処理と文脈に応じた柔軟な読み分けが特徴です。登録不要・無料で利用できます。

## ドキュメント修正のお知らせとお詫び

本ページに掲載していたAPIドキュメントの内容と、実際のAPIの動作に一部差異がございました。ご利用いただいている皆さまにはご迷惑をおかけしましたことをお詫び申し上げます。現在は本ページの内容を正しい仕様に修正済みです。今後もドキュメントの正確性を保つよう努めてまいります。

## APIエンドポイント

ベースURL: `https://ryuuneko.com/furigana`

GET / POST の両方に対応しています。POSTの場合は `Content-Type: application/json` で送信してください。

## パラメータ

:::feature-grid{}

text | 必須 | 変換対象の日本語テキスト（最大10,000文字）
mode | 任意 | 変換モード。tts / hiragana / ruby / kanji / accent / voicevox-aques（デフォルト: tts）

:::

### 詳細パラメータ

通常は指定不要です。BOTや外部ツールへの組み込み時など、細かい制御が必要な場合に使用します。

:::feature-grid{}

text_b64 | 任意 | textの代わりにBase64（URL-safe）でテキストを渡す場合に使用
short_pause | 任意 | 読点（、）の後に挿入する文字列（デフォルト: 半角スペース）
long_pause | 任意 | 句点（。）の後に挿入する文字列（デフォルト: 半角スペース3つ）
keep_period | 任意 | 句点を出力に残すか（デフォルト: true）
segmented | 任意 | 分割テキストをsegmentsとして返すか（デフォルト: false）
max_segment_len | 任意 | segmented時の最大文字数（デフォルト: 60）
debug | 任意 | 処理時間の詳細をtimings_msに含めるか（デフォルト: false）

:::

## 変換モード

用途に応じて6つの変換モードを選べます。読み上げBOT向けには `tts` モードが最適です。

:::feature-grid{}

tts | 読み上げ用 | ひらがな変換＋休止挿入＋句読点正規化。VOICEVOXなどの音声合成エンジン向け
hiragana | ひらがな変換 | 漢字をひらがなに変換。休止挿入や句読点処理は行わない
ruby | ルビ表示用 | {漢字／ひらがな} 形式で出力。Webページでのふりがな表示に
kanji | パススルー | 変換なし。入力テキストをそのまま返す
accent | アクセント解析用 | 単語（token）ごとの読みとアクセント情報をJSONで返す。読み比較や音声合成のイントネーション制御に
voicevox-aques | VOICEVOX連携用 | アクセント付きカナ記法（AquesTalk風）の文字列を返す。VOICEVOXの `POST /accent_phrases?is_kana=true` にそのまま渡せる

:::

### アクセント系モードについて（2026年7月追加）

`accent` と `voicevox-aques` は、読みに加えて**アクセント（音の高低）**の情報を返すモードです。

- `voicevox-aques` のカナ記法は、`'` がアクセント核（音が下がる位置）、`/` がアクセント句の境界、`、` がポーズ、末尾 `？` が疑問形を表します（例: `ア'メガ/フル'`）。助詞は発音どおりに変換されます（は→ワ、へ→エ、を→オ）。絵文字や英字など読みに変換できない部分は出力から除かれるため、読める部分がない場合は空文字列が返ります。`mode=voicevox` でも同じ動作です。
- `accent` は加工前の構造化データです。token ごとの表層形（surface）と読み（reading）が入り、アクセント情報を持つ語には accent_phrases（読み・アクセント核のモーラ位置・モーラ数）が付きます。読みが文脈で揺れうる語には `ambiguous: true` と読み候補の `alternatives` が付くことがあります。アクセントは辞書の登録値に加えて推定でも補完されます。

## リクエスト例

```
# GETリクエスト
curl "https://ryuuneko.com/furigana?text=漢字テスト&mode=tts"

# POSTリクエスト
curl -X POST https://ryuuneko.com/furigana \
  -H "Content-Type: application/json" \
  -d '{"text": "明日は9:30に集合", "mode": "tts"}'
```

## レスポンス形式

JSON形式でレスポンスが返ります。`result` の型はモードによって変わり、`accent` 以外のモードでは文字列、`accent` ではオブジェクトです。使用した解析エンジンが `engine` に入ります。

```
{
  "result": "あしたは くじはんに しゅうごう",
  "mode": "tts",
  "engine": "smart"
}
```

`segmented: true` を指定した場合は `segments` 配列が追加されます。`debug: true` を指定した場合は処理時間の詳細が `timings_ms` に含まれます。

```
// segmented: true の場合
{
  "result": "あしたは くじはんに しゅうごう",
  "segments": ["あしたは くじはんに しゅうごう"],
  "mode": "tts",
  "engine": "smart"
}

// debug: true の場合
{
  "result": "あしたは くじはんに しゅうごう",
  "mode": "tts",
  "engine": "smart",
  "timings_ms": {
    "total": 2.1,
    "tokenize": 0.8,
    "convert": 1.3
  }
}
```

アクセント系モードの例です（入力: `峠道を歩く`）。

```
// mode=voicevox-aques の場合（result はカナ記法の文字列）
{
  "result": "トウゲ'ミチオ/アルク'",
  "mode": "voicevox-aques",
  "engine": "smart"
}

// mode=accent の場合（result はオブジェクト）
{
  "result": {
    "schema_version": "1",
    "tokens": [
      {
        "surface": "峠道",
        "reading": "とうげみち",
        "accent_phrases": [
          { "reading": "とうげみち", "accent": 3, "mora": 5 }
        ]
      },
      { "surface": "を", "reading": "ヲ", "accent_phrases": [] },
      { "surface": "歩く", "reading": "アルク", "accent_phrases": [] }
    ]
  },
  "mode": "accent",
  "engine": "smart"
}
```

## 変換パイプライン

ふりがなAPIは以下の順序でテキストを変換します。

:::step-list{}

**テキスト正規化** — Unicode NFKC正規化、互換文字マッピング

**数値・日付検出** — 数字・日付・時刻・カウンタを先行検出し、読みを事前決定

**形態素解析** — Lindera（IPADIC辞書）でトークン分割・品詞判定・読み取得

**辞書照合** — ユーザー辞書（override → promoted → auto）を優先的に適用。文脈付きルールも対応

**漢字検出** — トークンに漢字が含まれる場合、辞書 → 形態素解析 → 単漢字辞書（UniHan）の順で読みを解決

**カタカナ→ひらがな変換** — 読みをひらがなに統一

**後処理ルール** — 正規表現ベースの置換ルールを適用（モード別に設定可能）

**TTS正規化**（ttsモードのみ）— 句読点の正規化、休止挿入、重複除去

:::

## 読みの改善・修正提案

漢字の読みが間違っている場合、`/furigana/suggest` エンドポイントで修正提案を送信できます。提案は運営が確認（レビュー）後、辞書に反映されます。APIを使わなくても[Webフォーム](/furigana/suggest/)から提案できます。

:::feature-grid{}

surface | 必須 | 対象の表層形（漢字表記）
reading | 必須 | 正しい読み（カタカナ）
reason | 任意 | 提案の理由やコメント

:::

```
curl -X POST https://ryuuneko.com/furigana/suggest \
  -H "Content-Type: application/json" \
  -d '{"surface": "今日", "reading": "キョウ", "reason": "配信で聞き取りにくい"}'
```

修正提案にはIPベースのレート制限があります（1時間あたり10件まで）。

:::callout{type="tip" title="読み間違いを見つけたら"}

配信やAPIで漢字の読みが間違っている場合は、[ふりがな修正提案フォーム](/furigana/suggest/)から簡単に報告できます。API利用者でなくても、どなたでも提案可能です。

:::

## レート制限

APIキーなしの一般利用では **毎分60リクエスト**（バースト10）の制限があります。通常の配信利用では十分な量です。制限を超えた場合はHTTP `429 Too Many Requests` が返ります。

自作アプリやサービスへの組み込みなど、より多くのリクエストが必要な場合は**APIキー**を発行できます。APIキーを `X-API-Key` ヘッダーで送信すると、キーごとに設定されたレート上限が適用されます。

```
# APIキーを使ったリクエスト
curl "https://ryuuneko.com/furigana?text=テスト" \
  -H "X-API-Key: your-api-key-here"
```

APIキーの発行は[お問い合わせフォーム](/contact/)よりご連絡ください。その際、**利用用途**（どのようなサービス・アプリで使用するか）もあわせてお知らせいただけますようお願いいたします。

## 利用規約

ふりがなAPIは**登録不要・無料**で利用できます。以下の利用規約に同意のうえご利用ください。

### 無料利用の範囲

個人利用・非営利目的での利用は自由です。配信の読み上げBOT、個人開発のアプリ・プラグイン、学習目的など、営利を主目的としない用途であれば制限なくご利用いただけます。

### クレジット表記（任意）

ツールやサービスにふりがなAPIを組み込む場合、**任意**で以下のクレジット表記をお願いしています。必須ではありませんが、表記いただけると開発の励みになります。

```
ふりがな変換: 黒猫ゲーム部 ふりがなAPI (https://ryuuneko.com/?slug=furigana-api)
```

### 組み込み利用のご報告（任意）

プラグインやアプリなどにAPIを組み込んで公開する場合、[お問い合わせフォーム](/contact/)から利用用途をご報告いただけると幸いです。必須ではありませんが、どのようなサービスで利用されているかを把握することで、API改善の参考にさせていただきます。

### 商用利用について

**営利目的でのサービスへの組み込み（商用利用）は原則として禁止**です。収益化しているサービスやアプリへの組み込みをご検討の場合は、事前に[お問い合わせフォーム](/contact/)よりご相談ください。

### 禁止事項

以下の行為は禁止です。違反が確認された場合、アクセスを制限することがあります。

- 過剰なリクエストによるサーバーへの負荷（レート制限を意図的に回避する行為を含む）
- APIの応答結果を大量に収集・蓄積してデータセットとして再配布する行為
- APIを利用した違法行為、または他者の権利を侵害する行為
- 許可なく商用サービスへ組み込む行為

### 免責事項

本APIは現状のまま（as-is）で提供しており、変換精度・可用性・応答速度について保証するものではありません。予告なくAPI仕様の変更やサービスの停止を行う場合があります。本APIの利用により発生した損害について、運営者は一切の責任を負いません。

## 技術仕様

:::feature-grid{}

言語 | Rust | Axumフレームワーク + Tokio非同期ランタイム
形態素解析 | ja-furigana lib | Lindera + IPADIC ベース + 文脈ルール
辞書 | 数万語規模 | `ja-furigana-dict` OSS（単漢字・熟語・異体字・外来語・作品造語などを含む。CalVer 日次リリースで増え続けるため、最新の件数は[`STATS.md`](https://github.com/RyuuNeko1107/ja-furigana-dict) 参照）
後処理ルール | TOML ルール | `ja-furigana-dict/rules/` で管理 (助数詞・日付・大数・単位・文脈)
永続化 | TOML / JSONL | APIキー・改善 signal は file ベース (PostgreSQL 撤去済)
レスポンス | ~2-5ms | 平均応答時間（p50）。2026年6月時点の目安値
テキスト上限 | 10,000文字 | 1リクエストあたり

:::

## APIデモ

実際の変換結果を試せます。テキストを入力して変換ボタンを押してみてください。

:::api-demo{type="furigana"}

## 関連

わんコメ用の読み上げプラグインについては、以下の記事をご覧ください。

→ [【わんコメ】読み上げ補助プラグイン — 漢字・数字を自然に読み上げる](/?slug=furigana-plugin)

---

*※本記事は2026年7月時点の情報をもとにしています。サービス・コマンド・仕様は予告なく変わることがあります。*