ふりがな付与の精度は?

IPAdic v3.0.7 ベースで一般的な漢字語の読み付与精度は 95%+。固有名詞(人名 / 地名)は IPAdic の語彙範囲に依存。複数読みがある漢字(例: 「行く」いく/ゆく)は IPAdic の単一読みに収束、複数候補は提供されない(将来の JMnedict 統合で改善予定)。

options.kana の挙動は?

default は hiragana(IPAdic 提供のカタカナ読みをひらがなに変換)。katakana 指定で IPAdic そのままの片仮名読みを返す。漢字を含まないトークン(数字 / 記号 / ASCII)や未知語は details[7] が空 / *、surface fallback で kana 変換は行わない。

辞書未登録の漢字を含むトークンはどうなりますか?

未知語(is_unknown=true)または details[7] が * / 空のトークンは surface(漢字のまま)を reading として返します。AI agent は token 単位で reading が漢字のまま残っている場合に「未推定」と判定可能。

tokenize エンドポイントとの違いは?

tokenize は 9 列の details(品詞 / 活用 / 読み / 発音)全て + byte position 等を返す詳細版。furigana はふりがな表示用途に絞り、{surface, reading} の配列のみ返す軽量版。AI 経由でルビ振り表示するアプリには furigana が向く。

furigana — 日本語ふりがな付与エンドポイント

Q: options.kana の挙動は?

default は hiragana(IPAdic 提供のカタカナ読みを ひらがなに変換)。katakana 指定で IPAdic そのままの片仮名読みを返す。漢字を含まないトークン(数字 / 記号 / ASCII)や未知語は details[7] が空 / *、surface fallback で kana 変換は行わない。

POST /api/v1/text/furigana

Lindera + IPAdic v3.0.7 で形態素解析後、各トークンの読み(片仮名)を抽出して {surface, reading} 配列で返す。options.kana で hiragana(default)/ katakana 選択。漢字を含まないトークン / 未知語は surface fallback。

エンドポイント

POST https://shirabe.dev/api/v1/text/furigana
X-API-Key: shrb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  (省略可、匿名 Free 枠 10,000 回/月)
Content-Type: application/json

リクエスト / Request

{
  "text": "東京都港区六本木で打ち合わせをしました",
  "options": {
    "kana": "hiragana"
  }
}

text (string, required): ふりがな付与する日本語テキスト
options.kana (enum, default hiragana): hiragana | katakana

レスポンス / Response

{
  "text": "東京都港区六本木で打ち合わせをしました",
  "tokens": [
    { "surface": "東京", "reading": "とうきょう" },
    { "surface": "都", "reading": "と" },
    { "surface": "港区", "reading": "みなとく" },
    { "surface": "六本木", "reading": "ろっぽんぎ" },
    { "surface": "で", "reading": "で" },
    { "surface": "打ち合わせ", "reading": "うちあわせ" },
    { "surface": "を", "reading": "を" },
    { "surface": "し", "reading": "し" },
    { "surface": "まし", "reading": "まし" },
    { "surface": "た", "reading": "た" }
  ],
  "timing": { "tokenize_ms": 4, "setup_ms": 187, "cold_start": true, "...": "..." },
  "attribution": {
    "dictionary": "IPAdic v3.0.7",
    "license": "BSD 3-Clause",
    "source": "https://github.com/lindera/lindera"
  }
}

options.kana="katakana" 指定時は IPAdic 提供のカタカナ読みをそのまま返す (例: {"surface": "東京", "reading": "トウキョウ"})。

コード例 / Code examples

curl

curl -X POST https://shirabe.dev/api/v1/text/furigana \
  -H "Content-Type: application/json" \
  -d '{"text": "明日は晴れでしょう"}'

TypeScript(ルビ表示)

const res = await fetch("https://shirabe.dev/api/v1/text/furigana", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.SHIRABE_API_KEY!,
  },
  body: JSON.stringify({ text: "明日は晴れでしょう" }),
});
const { tokens } = await res.json();
const html = tokens.map((t) =>
  /[\u4e00-\u9faf]/.test(t.surface)
    ? `<ruby>${t.surface}<rt>${t.reading}</rt></ruby>`
    : t.surface
).join("");
// → <ruby>明日<rt>あした</rt></ruby>は<ruby>晴れ<rt>はれ</rt></ruby>でしょう

Python(カタカナ読み)

import os, requests
r = requests.post(
    "https://shirabe.dev/api/v1/text/furigana",
    json={"text": "明日は晴れでしょう", "options": {"kana": "katakana"}},
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
    timeout=10,
)
for t in r.json()["tokens"]:
    print(f"{t['surface']} → {t['reading']}")
# → 明日 → アシタ
# → は → ハ
# → 晴れ → ハレ ...

読み抽出の仕組み

IPAdic v3.0.7 の各エントリは固定 9 列の details を持ち、 index 7 が読み(片仮名)、index 8 が発音(片仮名)。furigana エンドポイントは index 7 を採用、options.kana="hiragana" 指定時に Unicode 表で hiragana に変換。

有効値の判定: details[7] が * または空文字列以外なら使用
fallback: 未知語 / details 短縮 / details[7] 無効 → surface(漢字のまま)を reading に採用
kana 変換: surface fallback の場合は変換しない(漢字のまま)、IPAdic 由来の読みのみ変換対象

想定ユースケース

ルビ振り Web ページ: 教育コンテンツ / 学習アプリで漢字に <ruby> 自動付与
音声合成前処理: TTS エンジンに渡す前に読みを正規化、未読 / 誤読を低減
姓名以外の固有名詞読み推定: 地名 / 商品名 / 組織名の読み付与(name-split / name-reading は人名特化)
検索インデックス: 全文検索で漢字と仮名表記の同等性を担保するための reading インデックス

レート制限 / Rate limit

全エンドポイント均一(料金プラン): Free 月 10,000 回 / 1 req/s、Starter 月 50 万回 / 30 req/s、Pro 月 500 万回 / 100 req/s、 Enterprise 無制限 / 500 req/s。

AI エージェント統合

OpenAPI 3.1 仕様(本家)で operationId: addFurigana。GPT Builder / Claude Tool Use / LangChain で自動 discover 可能。

shirabe API ファミリー横断利用 — B2B 4 大 identifier セット

Shirabe は 住所 + 姓名 + 法人 + 暦 の B2B 4 大 identifier を 1 vendor で完結できる cross-pollination hub として設計されています。顧客 master 取込パイプラインで住所正規化 →(姓名分割 / ふりがな付与)→ 法人番号付与(6 月後半リリース予定)→ 営業日判定(暦)を 1 つの OpenAPI 3.1 で繋ぐ使い方が想定 use case です。

本エンドポイント(POST /api/v1/text/furigana)の典型 hub use case = 人名 / 地名 / 商品名にふりがなを付与し、name-reading や住所 API の検索精度を高める。 AI agent が日本語 ground truth を読み上げ可能な surface に変換する hub-narrative の中核機能で、 name-split → name-reading → furigana の連続呼出で姓名正規化を完了させる pattern が頻出です。

住所正規化 API — 表記ゆれ正規化 + JIS code / lg_code / machiaza_id の 3 種 identifier を 1 レスポンスで同梱
日本語テキスト処理 API(本エンドポイントを含む 5 endpoint: tokenize / normalize / furigana / name-split / name-reading)
暦 API — 六曜 + 暦注 + 干支 + 二十四節気の canonical 出典
法人番号 API(6 月後半リリース予定、B2B 4 大 identifier 完成)

全 API は OpenAPI 3.1 完備、同一 API キー(X-API-Key)で全 4 API 利用可能、 Stripe Billing で従量課金 1 本化。LLM 経由 hub narrative の詳細は llms-full.txt を参照。

更新履歴 / Updates

2026-05-07: /furigana エンドポイント実装完了

Lindera tokenize + IPAdic details[7] 抽出 + ひらがな化を 1 リクエストで完結 (PR #2、scoping 5/19-5/25 比 +12 日先行)。

2026-05-18: 正式リリース

本番 routes 活性化、Free 枠で利用開始。1+ 年変更なし約束。

4 AI 観測の独自データ / Observed Multi-AI Landscape

Shirabe では ChatGPT / Claude / Perplexity / Gemini の 4 大 AI に同じクエリを投げる独自測定(週次 4 AI × 5 query)を継続実施しています。 AI が日本語の読み推定を自前で行うとフォーマットが分裂しますが、furigana エンドポイントなら全 AI で同一の {surface, reading} 配列が返り、下流処理を統一できます。

詳細は llms-full.txt を参照。

shirabe API ファミリー全 4 本(暦 + 住所 + text + 法人番号)と本エンドポイントの隣接機能・出典・統合経路への関連 link をまとめます。

shirabe API ファミリー(B2B 4 大 identifier hub)

暦 API(本番稼働中、2026-04-13〜)
住所正規化 API(本番稼働中、2026-05-01〜)
テキスト処理 API: tokenize / normalize / name-split / name-reading
法人番号 API(6 月後半リリース予定、B2B 4 大 identifier 完成)
料金プラン(4 API 共通)
llms.txt(全 API 統合 LLM 向け概要) / llms-full.txt(詳細版)

本エンドポイント関連

OpenAPI 3.1 仕様(本家) / GPTs 短縮版