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

エンドポイント

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 可能。

更新履歴 / 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 を参照。

関連リンク / Related

• tokenize エンドポイント(詳細版)
• name-reading エンドポイント(人名特化)
• 料金プラン
• OpenAPI 3.1 仕様