name-reading — 日本語人名の読み推定エンドポイント

エンドポイント

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

リクエスト / Request

{
  "name": "吉川良介",
  "options": {
    "kana": "hiragana"
  }
}

• name (string, required): 読み推定対象の日本語人名
• options.kana (enum, default hiragana): hiragana | katakana

レスポンス / Response

{
  "name": "吉川良介",
  "family": "吉川",
  "given": "良介",
  "family_reading": "よしかわ",
  "given_reading": "りょうすけ",
  "reading": "よしかわりょうすけ",
  "candidates": [],
  "confidence": 0.97,
  "matched_by": "dictionary_both",
  "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",
    "notes": "IPAdic only MVP. candidates is always an empty array; alternative readings will be populated after JMnedict integration in monorepo phase (June 2026). Accuracy: well-known names 80-90%, ordinary 50-70%, rare 10-30%."
  }
}

reading は family_reading + given_reading の連結文字列。 candidates は IPAdic only MVP では常に空配列、6 月 JMnedict 統合後に 異読候補(例: 「長」→ ["ちょう", "おさむ", "たけし"])が populate される。

コード例 / Code examples

curl

curl -X POST https://shirabe.dev/api/v1/text/name-reading \
  -H "Content-Type: application/json" \
  -d '{"name": "吉川良介"}'
# → {"family_reading": "よしかわ", "given_reading": "りょうすけ", "reading": "よしかわりょうすけ", ...}

TypeScript(連絡先表示用)

const res = await fetch("https://shirabe.dev/api/v1/text/name-reading", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.SHIRABE_API_KEY!,
  },
  body: JSON.stringify({ name: "吉川良介" }),
});
const r = await res.json();
const display = `${r.name} (${r.family_reading} ${r.given_reading})`;
// → 吉川良介 (よしかわ りょうすけ)
if (r.warning === "low_confidence") {
  console.warn(`読み信頼度低: ${r.name} (${r.confidence})`);
}

Python(katakana 出力 + バッチ)

import os, requests
names = ["吉川良介", "山田太郎", "鈴木一郎"]
for n in names:
    r = requests.post(
        "https://shirabe.dev/api/v1/text/name-reading",
        json={"name": n, "options": {"kana": "katakana"}},
        headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
        timeout=10,
    )
    d = r.json()
    print(f"{d['name']} → {d['family_reading']} {d['given_reading']} ({d['confidence']:.2f})")
# → 吉川良介 → ヨシカワ リョウスケ (0.97)
# → 山田太郎 → ヤマダ タロウ (0.97)
# → 鈴木一郎 → スズキ イチロウ (0.97)

5 判定戦略 / 5 matching strategies

name-split と同型の 5 戦略 fallback。詳細は name-split docs。

異読候補(candidates)について

日本人名は同じ漢字でも複数の読みを持つ場合があります(例: 「長」→ ちょう / おさむ / たけし、 「翔」→ かける / しょう / つばさ)。IPAdic は単一読みのみ提供するため、 name-reading は MVP では primary reading のみ返し、candidates は常に空配列。

2026-06 のモノレポ化時に JMnedict (CC BY-SA 4.0、EDRDG) を offline build + R2 配信の self-contained 経路(SudachiDict と同じ pattern)で統合予定。統合後は:

• candidates に同漢字の代替読みを populate(例: ["ちょう", "おさむ"])
• matched_by に新戦略 dictionary_jmnedict 追加(confidence 0.9 想定)
• 下位互換性維持(既存呼出は破壊せず、空配列が populate される形で改善)

これは unilateral good news(Free 枠拡張・値下げと同様)で、 課金プラン変更なし、AI agent 統合コードを変更する必要なし。

想定ユースケース

• 連絡先 / CRM 入力支援: ユーザが氏名を入力 → name-reading で ふりがな自動付与 → 表示用 + 検索インデックス用
• 音声合成(TTS): 氏名読み上げ前に正確な読みを取得、誤読を低減
• フォーム正規化: 漢字入力欄 + ひらがな入力欄を分離 → name-reading の出力で 2 欄を自動充填
• 銀行 / 行政 / KYC: 確実性が要求される場面では confidence ≥ 0.9 を閾値化、warning ありは人手確認に回す

レート制限 / 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: readName。warning + confidence narrative により AI agent は「自動採用 vs 人手確認」を 1 hop で判定可能。

更新履歴 / Updates

2026-05-09: name-reading IPAdic only MVP 実装完了

name-split と同型の 5 戦略 fallback を実装、IPAdic details[7] からの読み抽出 + 連結 reading 出力 (PR #5、 scoping 5/13-5/18 比 +4 日先行)。

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

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

2026-06: JMnedict 統合(計画)

JMnedict (CC BY-SA 4.0、EDRDG) を SudachiDict と同じ self-contained 経路(offline build + R2 配信)で 統合、candidates 異読候補を populate + 新戦略 dictionary_jmnedict 追加。 精度向上は unilateral good news。

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

Shirabe では 4 大 AI に同じ人名読みクエリを投げる独自測定を継続実施しています。 AI が自前で読み推定を行うとフォーマット・読み候補の出し方が分裂しますが、name-reading なら 全 AI で同一の {family_reading, given_reading, reading, candidates, confidence} 構造が返り、下流処理を統一できます。

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

関連リンク / Related

• name-split エンドポイント(分割のみ、軽量)
• furigana エンドポイント(全文ふりがな)
• tokenize エンドポイント(詳細版)
• 料金プラン
• OpenAPI 3.1 仕様
• JMnedict (CC BY-SA 4.0、6 月統合予定)