辞書操作の手順

包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。

チュートリアル

辞書の作成、term の追加と一括作成、翻訳・音声認識エンドポイントへの連携まで、辞書の実戦フローをまとめます。

辞書を使うと、固有の語彙や置換ルールを翻訳・音声認識結果に適用できます。本章では類型選択から始め、作成、term 追加、一括作成、実リクエストへの連携までを順に説明します。

2 種類の辞書

vocabulary：多言語対訳用語集。term 構造は { variants: { 'zh-TW': …, en: …, 'ja-JP': … } }。一致語はモデルへの好適語として渡される（ソフトヒント）。
forced_replacement：単一言語の強制置換ルール。term 構造は { language, from, to, case_sensitive? }。翻訳・認識完了後の出力に文字列置換を適用（後処理の確定的反映）。
type は作成時に確定し、以降変更不可（PATCH は type を受け付けない）。

選び方

モデルが用語を理解し文脈に織り込んでほしい場合は vocabulary、出力に特定文字列（ブランド名、固定略語展開など）を必ず含めたい場合は forced_replacement を使います。両方同時に掛けることも可能ですが、forced_replacement は SSE モードでは利用できません。

ステップ 1：辞書を作成する

POST /api/v1/dictionaries に name（同一所有者で一意）、type（vocabulary または forced_replacement）、任意の description を送信します。成功時は 201 と完全な辞書オブジェクト（id は以降の :id、entry_count は 0）が返ります。

vocabulary 辞書の作成例。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Glossary",
    "type": "vocabulary",
    "description": "Term equivalence for marketing copy."
  }'

重複名は 409

同一 API キー保有者で重複名は不可で、衝突時は 409 duplicate_name が返ります。日付・言語・用途などのサフィックスで回避してください。

ステップ 2：term を追加する

term 構造は辞書の type で決まります。vocabulary は variants（言語コードをキー）を持ち、forced_replacement は language、from、to、任意の case_sensitive を持ちます。

両類型の term 追加例。

bash

# Single term — vocabulary dictionary
curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variants": { "zh-TW": "行銷", "en": "marketing", "ja-JP": "マーケティング" }
  }'

# Single term — forced_replacement dictionary
curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "from": "AI",
    "to": "Artificial Intelligence",
    "case_sensitive": false
  }'

一括投入は POST /api/v1/dictionaries/:id/terms/batch を使い、body に term 配列をそのまま渡します。1 バッチ最大 250 件で、超過時は 400 bad_request（details.reason: batch_too_large）。一部失敗でも応答は 200、結果は processed_count / success_count / failed_count / errors[] で確認します。

term の一括作成（vocabulary 例）。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms/batch" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "variants": { "zh-TW": "行銷", "en": "marketing" } },
    { "variants": { "zh-TW": "業務", "en": "sales" } }
  ]'

ステップ 3：リクエストで辞書を有効化

翻訳・音声認識エンドポイントは vocabulary_dictionary_id と forced_replacement_dictionary_id の 2 つの UUID 引数を受け付けます。型不一致（vocabulary と forced_replacement の取り違え）は 400 dictionary_type_mismatch、辞書が存在しない場合は 404 dictionary_not_found。

翻訳エンドポイントで vocabulary と forced_replacement を同時に指定（JSON モード）。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "請把這份合約交給法務組長確認。",
    "target_language": "en",
    "vocabulary_dictionary_id": "f3c1e9a2-9c2b-4f7a-9d3a-7e2b8a1c4d5e",
    "forced_replacement_dictionary_id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a"
  }'

SSE モードは forced_replacement 非対応

stream=true と forced_replacement_dictionary_id は排他で、同時送信は 400 validation_error。SSE モードでは meta の forced_replacement_count は恒常 0 です。

詳細情報

2 類型の設計トレードオフと適用シーンは「辞書の概念」を、フィールド・エラーコード・ページング規則は API リファレンスの辞書モジュールを参照してください。