日本語テキスト処理 API ドキュメント

全 5 エンドポイントの仕様・レスポンス・エラー・レート制限

ベース URL: https://shirabe.dev。キーなしで月 10,000 回まで利用できます。製品概要と料金はこちら。

クイックスタート

curl -X POST https://shirabe.dev/api/v1/text/name-split \
  -H "Content-Type: application/json" \
  -d '{"name": "山田太郎"}'

有料プランのキーは X-API-Key ヘッダーで渡します(キーなし = 匿名 Free 扱い)。

エンドポイント一覧

メソッド	パス	説明
`POST`	`/api/v1/text/tokenize`	形態素解析(品詞・読み付き)
`POST`	`/api/v1/text/normalize`	表記正規化(全角半角・半角カナ・空白)
`POST`	`/api/v1/text/furigana`	ふりがな付与
`POST`	`/api/v1/text/name-split`	姓名分割
`POST`	`/api/v1/text/name-reading`	人名読み推定

POST /api/v1/text/tokenize

リクエスト: { "text": "日本語の解析" }

レスポンス(実例、抜粋):

{
  "text": "日本語の解析",
  "tokens": [
    {
      "surface": "日本語",
      "byte_start": 0, "byte_end": 9, "position": 0,
      "is_unknown": false,
      "details": ["名詞", "一般", "*", "*", "*", "*", "日本語", "ニホンゴ", "ニホンゴ"]
    },
    { "surface": "の", "details": ["助詞", "連体化", "…"] },
    { "surface": "解析", "details": ["名詞", "サ変接続", "…"] }
  ],
  "attribution": { "dictionary": "IPAdic v3.0.7", "license": "BSD 3-Clause" }
}

details は IPAdic 素性(品詞・活用・原形・読み・発音)の 9 要素配列です。

POST /api/v1/text/normalize

リクエスト(options は省略可、既定は preserve = 変換しない):

{
  "text": "ｶﾀｶﾅとＡＢＣ",
  "options": { "width": "half", "halfwidth_kana": "expand" }
}

レスポンス(実例):

{
  "text": "ｶﾀｶﾅとＡＢＣ",
  "normalized": "カタカナとABC",
  "changes": [
    { "type": "width", "before": "ｶﾀｶﾅとＡＢＣ", "after": "ｶﾀｶﾅとABC" },
    { "type": "halfwidth_kana", "before": "ｶﾀｶﾅとABC", "after": "カタカナとABC" }
  ],
  "attribution": { "service": "shirabe-text-api" }
}

option	値	意味
`width`	`half` / `full` / `preserve`	英数字の全角半角統一
`halfwidth_kana`	`expand` / `preserve`	半角カナ → 全角カナ
`spaces`	`single` / `trim` / `preserve`	連続空白の統一・除去
`sudachi`	`apply` / `preserve`	表記ゆらぎ正規化(辞書ベース)の適用

適用した変換は changes に順番付きで返るため、監査ログにそのまま残せます。

POST /api/v1/text/furigana

リクエスト: { "text": "東京都で会議" }

レスポンス(実例):

{
  "text": "東京都で会議",
  "tokens": [
    { "surface": "東京", "reading": "とうきょう" },
    { "surface": "都", "reading": "と" },
    { "surface": "で", "reading": "で" },
    { "surface": "会議", "reading": "かいぎ" }
  ],
  "attribution": { "dictionary": "IPAdic v3.0.7", "license": "BSD 3-Clause" }
}

POST /api/v1/text/name-split

リクエスト: { "name": "山田太郎" }

レスポンス(実例):

{
  "name": "山田太郎",
  "family": "山田",
  "given": "太郎",
  "confidence": 0.97,
  "matched_by": "dictionary_both",
  "attribution": { "dictionary": "IPAdic v3.0.7", "license": "BSD 3-Clause" }
}

confidence(0〜1)と matched_by(姓・名の辞書一致状況)で分割根拠を判定できます。著名でない人名は信頼度が下がるため、しきい値を決めてフォールバックする使い方を推奨します (精度の目安は辞書収載の姓名で高く、希少姓名で低下します)。

POST /api/v1/text/name-reading

リクエスト: { "name": "山田太郎" }

レスポンス(実例):

{
  "name": "山田太郎",
  "family": "山田", "given": "太郎",
  "family_reading": "やまだ",
  "given_reading": "たろう",
  "reading": "やまだたろう",
  "candidates": [],
  "confidence": 0.97,
  "matched_by": "dictionary_both",
  "attribution": { "dictionary": "IPAdic v3.0.7", "license": "BSD 3-Clause" }
}

読みが複数あり得る場合の代替候補は candidates に入ります。

エラー

エラーは全て次の形で返ります:

{ "error": { "code": "...", "message": "..." } }

HTTP	code(代表)	意味と対処
400	`INVALID_REQUEST_BODY` / `MISSING_TEXT` / `INVALID_OPTIONS`	body・options 不正。カウントされません
401	`INVALID_API_KEY`	形式不正・未登録のキー。キーを外すと匿名 Free で通ります
429	`RATE_LIMIT_EXCEEDED` / `USAGE_LIMIT_EXCEEDED`	秒間または月間上限。`Retry-After` と次プランへの `next_plan.checkout_path`(→ /text/buy)を同梱
503	`SERVICE_UNAVAILABLE`	辞書ロード等の一時障害。カウントされません。リトライしてください

レート制限とカウント規則

プラン	月間上限	秒間レート
Free	10,000 回	1 req/s
Starter	500,000 回	30 req/s
Pro	5,000,000 回	100 req/s
Enterprise	無制限	500 req/s

全エンドポイント均一で 1 リクエスト = 1 カウント
400 系・401・503 はカウントされません(無料枠を消費しない)
残量はレスポンスヘッダー X-RateLimit-Limit / X-RateLimit-Remaining で確認できます
月間カウントは毎月 1 日 0:00 UTC にリセット
初回リクエストは辞書ロードで応答が数秒かかることがあります(以後は数十 ms)

AI 統合・機械可読仕様

OpenAPI 3.1(完全版): https://shirabe.dev/api/v1/text/openapi.yaml
OpenAPI(GPTs Actions 用短縮版): https://shirabe.dev/api/v1/text/openapi-gpts.yaml

→ 製品概要・料金 / → 申し込み / → API キー再発行