Create Dictionary Entry

curl -X POST https://api.onepin.ai/api/v1/dictionary \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "word": "Hyperloop",
  "method": "spelled",
  "language": "en-us"
}'

{
  "data": {
    "id": "d4f5a8b2-3c9e-4f1a-9b7e-2a1f3c4d5e6f",
    "word": "Hyperloop",
    "method": "spelled",
    "language": "en-us",
    "uses_count": 42,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "description": "Brand name for a high-speed transportation concept",
    "pronunciation": "Hai-per-loop",
    "audio_url": "https://audio.onepin.ai/dictionary/d4f5a8b2-3c9e-4f1a-9b7e-2a1f3c4d5e6f.mp3",
    "ipa": "ˈhaɪpərˌluːp",
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "meta": {
    "request_id": "req_7f8e9d6c-1234-5678-abcd-9f0e1d2c3b4a",
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

Create a pronunciation dictionary entry in the current workspace.

Dictionary entries teach the synthesis pipeline how to pronounce words that it would otherwise handle incorrectly — brand names, acronyms, technical terms, proper nouns, and foreign loanwords. Each entry is scoped to a single BCP-47 locale and is applied during workflow execution when that locale is the synthesis target.

Three methods are supported via the method field:

spelled — provide a phonetic respelling in pronunciation (e.g. "Poh-doh-nohs"). pronunciation is required for this method.
recorded — attach a reference audio clip by supplying an upload_id from a completed /uploads staging upload with category dictionary. The audio is copied to permanent storage on create; the upload slot is consumed and cannot be reused for a different entry.
ipa — supply an IPA transcription in ipa. pronunciation is optional as a human-readable gloss alongside the IPA.

Returns 409 if a (word, language) pair already exists in the workspace. Requires editor workspace role and the dictionary:write scope.

Create a pronunciation dictionary entry in the current workspace. Dictionary entries teach the synthesis pipeline how to pronounce words that it would otherwise handle incorrectly — brand names, acronyms, technical terms, proper nouns, and foreign loanwords. Each entry is scoped to a single BCP-47 locale and is applied during workflow execution when that locale is the synthesis target. Three methods are supported via the `method` field: - `spelled` — provide a phonetic respelling in `pronunciation` (e.g. `"Poh-doh-nohs"`). `pronunciation` is required for this method. - `recorded` — attach a reference audio clip by supplying an `upload_id` from a completed `/uploads` staging upload with category `dictionary`. The audio is copied to permanent storage on create; the upload slot is consumed and cannot be reused for a different entry. - `ipa` — supply an IPA transcription in `ipa`. `pronunciation` is optional as a human-readable gloss alongside the IPA. Returns 409 if a `(word, language)` pair already exists in the workspace. Requires `editor` workspace role and the `dictionary:write` scope.

Authentication

AuthorizationBearer

Clerk JWT token

AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Headers

X-Workspace-Idstring or nullOptional

Request

This endpoint expects an object.

wordstringRequired1-255 characters

The surface form of the word or phrase as it appears in a script.

methodenumRequired

Pronunciation method: spelled (phonetic respelling), recorded (reference audio clip), or ipa (IPA transcription).

languagestringRequiredformat: "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,4})?$"1-10 characters

BCP-47 locale this entry applies to (e.g. ko-kr). Case-insensitive; stored lowercase.

descriptionstring or nullOptional<=500 characters

Optional human-readable note about the entry (e.g. context, source).

pronunciationstring or nullOptional<=500 characters

Phonetic respelling. Required when method is spelled.

upload_idstring or nullOptionalformat: "uuid"

ID of a completed staging upload (category dictionary). Required when method is recorded; consumed on create.

ipastring or nullOptional<=500 characters

IPA transcription of the word. Supplied by the caller; automatic generation is a planned enhancement.

Response

Successful Response

dataobject

metaobject

Errors

422

Unprocessable Entity Error

Create a pronunciation dictionary entry in the current workspace.

Three methods are supported via the method field:

spelled — provide a phonetic respelling in pronunciation (e.g. "Poh-doh-nohs"). pronunciation is required for this method.
recorded — attach a reference audio clip by supplying an upload_id from a completed /uploads staging upload with category dictionary. The audio is copied to permanent storage on create; the upload slot is consumed and cannot be reused for a different entry.
ipa — supply an IPA transcription in ipa. pronunciation is optional as a human-readable gloss alongside the IPA.

Returns 409 if a (word, language) pair already exists in the workspace. Requires editor workspace role and the dictionary:write scope.