Dictionaries let you encode bespoke terminology and substitution rules that are then applied to translation or transcription output. This tutorial starts with type selection and walks through creation, adding terms, bulk creation, and attaching dictionaries to live requests.

Two dictionary kinds

• vocabulary: multilingual vocabulary equivalence. Each term is shaped as { variants: { 'zh-TW': ..., en: ..., 'ja-JP': ... } } and matching entries are passed to the model as preferred wording (soft guidance).
• forced_replacement: per-language forced replacement rules. Each term is shaped as { language, from, to, case_sensitive? } and applies string replacement to the output after translation or transcription (hard post-processing).
• type is fixed at creation time and cannot be changed (PATCH does not accept the type field).

Step 1: Create a dictionary

POST /api/v1/dictionaries with name (unique per owner), type (vocabulary or forced_replacement), and an optional description. A 201 response returns the full dictionary object including the id (used as :id in later calls) and entry_count = 0.

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."
  }'

Step 2: Add terms

Term shape depends on the dictionary's type. Vocabulary terms carry variants keyed by language code; forced_replacement terms carry language, from, to, and an optional case_sensitive flag.

# 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
  }'

Use POST /api/v1/dictionaries/:id/terms/batch for bulk inserts; the body is an array of term objects. Each batch caps at 250 items — exceeding it returns 400 bad_request (details.reason: batch_too_large). Even with partial failure the response is 200; per-item outcomes appear in processed_count / success_count / failed_count / errors[].

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" } }
  ]'

Step 3: Attach the dictionary to a request

Both the translation and speech endpoints accept the vocabulary_dictionary_id and forced_replacement_dictionary_id UUID parameters. Type mismatch (passing a vocabulary id where forced_replacement is expected, or vice versa) returns 400 dictionary_type_mismatch; a missing dictionary returns 404 dictionary_not_found.

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"
  }'