Pronunciation API — Reference

The Pronunciation API gives your application programmatic access to NameDrop’s pronunciation database — search names, generate phonetic guides, and fetch or synthesize pronunciation audio. It is the authenticated developer surface of the same service behind the public Names API.

New here? Two short guides come first:

• Quickstart — start a free trial and generate a key from your dashboard.
• Using your API key — already have an nd_live_… key? Make your first call.

This page is the complete endpoint reference.

Base URL

https://names-api.namedropiome.workers.dev

Branded host is planned, not live yet

A short branded host (e.g. api.pronounce.namedrop.io) is on the roadmap but not active — do not point production traffic at it. Use the …workers.dev URL above today.

Authentication

Send your key in the x-api-key header on every request:

curl -H "x-api-key: nd_live_xxxxxxxx" \
  "https://names-api.namedropiome.workers.dev/search?q=smith"

Keys are issued per organization and managed from the dashboard — generate, restrict to specific domains, and revoke. Requests from your registered first-party origins may be served without a key; everyone else must send one.

Keep your key secret

Treat nd_live_… keys like passwords — use them server-side. You can restrict a key to specific domains and revoke it any time from the dashboard.

Tiers & limits

Tier	Requests / day	API keys	Audio generation	How to get it
Trial	200 (and 200 total over 14 days)	2	—	Self-serve, 14-day free trial
Starter	5,000	5	—	Paid
Pro	25,000	20	✓	Paid
Enterprise	100,000	100	✓	Paid

During the trial, keys are also capped at 200 total calls across the 14 days. Daily limits reset at 00:00 UTC. Audio generation (/generate-audio) is available on Pro and Enterprise only. To raise limits or unlock audio generation, contact us to upgrade.

The Name object

/search returns one or more Name objects in data:

{
  "id": "abc123",
  "name": "Smith",
  "gender": "Unisex",
  "cultural_origin": "English",
  "country_origin": ["United Kingdom", "United States"],
  "phonetic_simple": "smith",
  "phonetic_variants": { "es": "smiz" },
  "meaning": "occupational name for a metalworker",
  "audio_file": "Smith.mp3"
}

country_origin is an array. phonetic_variants is an object keyed by culture code (present when culture-specific phonetics exist). Fields may be null when unknown.

---

Endpoints

All endpoints require the x-api-key header. The base URL https://names-api.namedropiome.workers.dev is omitted from the paths below.

GET /search — smart name search

Parses honorifics (Dr., Mr., Mrs., …) and extracts the first name from full-name queries, then returns the best matches. If nothing matches, it generates a phonetic on the fly.

Param	Type	Required	Notes
q	string	yes	Name to search (may include honorifics / a full name).
country	string	no	ISO-2 code (e.g. BR, US). With it, returns up to 5 matches from that country; without it, up to 3 best matches.

curl -H "x-api-key: nd_live_xxxxxxxx" \
  "https://names-api.namedropiome.workers.dev/search?q=Dr.%20Maria%20Gomes&country=BR"

const res = await fetch(
  "https://names-api.namedropiome.workers.dev/search?q=Maria&country=BR",
  { headers: { "x-api-key": "nd_live_xxxxxxxx" } }
);
const { data, parsed } = await res.json();

{
  "success": true,
  "data": [ { "name": "Maria", "cultural_origin": "Portuguese", "phonetic_simple": "mah-REE-ah", "audio_file": "Maria.mp3" } ],
  "query": "Dr. Maria Gomes",
  "parsed": { "original": "Dr. Maria Gomes", "matched": "maria", "type": "first_name_country" },
  "country": "BR"
}

parsed.type is one of exact_full_name, first_name_country, first_name, or generated.

GET /phonetic — phonetic guide for any name

Returns a human-friendly phonetic respelling for any name — including names not in the database — without a lookup. The optional culture hint selects a native-language ruleset (e.g. Indian → Hindi); otherwise English rules apply.

Param	Type	Required	Notes
name	string	yes	The name to render phonetically.
culture	string	no	Origin hint (e.g. Indian, Japanese, Arabic).

curl -H "x-api-key: nd_live_xxxxxxxx" \
  "https://names-api.namedropiome.workers.dev/phonetic?name=Hanuman&culture=Indian"

{ "success": true, "name": "Hanuman", "culture": "Indian", "language": "Hindi", "phonetic": "HUH-noo-mahn" }

GET /cultures — list cultural origins

No parameters. Returns each cultural origin with how many names carry it.

curl -H "x-api-key: nd_live_xxxxxxxx" \
  "https://names-api.namedropiome.workers.dev/cultures"

{ "success": true, "data": [ { "cultural_origin": "English", "count": 4213 }, { "cultural_origin": "Japanese", "count": 1180 } ] }

GET /audio/{id} — get a signed audio URL

Returns a fresh presigned URL (valid ~1 hour) for an existing recording. Use the id from a /search result.

Param	Type	Required	Notes
id	string	yes	Path parameter (name id).
culture	string	no	Retrieve a culture-specific variant.

{ "success": true, "audio_url": "https://.../Smith.mp3?signature=...", "audio_file": "Smith.mp3" }

Returns 404 when no audio exists for that id.

POST /generate-audio — synthesize pronunciation audio

Pro / Enterprise only

Audio generation is a paid-compute feature. Trial and Starter keys receive 403 tier_not_allowed — upgrade to Pro or Enterprise to use it.

Generates TTS audio when no human recording exists, and returns a presigned URL (valid ~1 hour).

Body field	Type	Required	Notes
name	string	yes	The name to synthesize.
culture	string	no	Culture code (e.g. es) to influence the accent.

curl -X POST "https://names-api.namedropiome.workers.dev/generate-audio" \
  -H "x-api-key: nd_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Siobhan", "culture": "ga" }'

{ "success": true, "audio_file": "Siobhan.mp3", "audio_url": "https://.../Siobhan.mp3?signature=...", "culture": "ga" }

POST /names/request — request a missing name

Submit a name you’d like added to the database.

Body field	Type	Required	Notes
name	string	yes	The name to request.
gender	string	no	e.g. Female, Male, Unisex.
cultural_origin	string	no	e.g. Arabic.
country	string	no	Country of origin.
meaning	string	no	Meaning of the name.
email	string	no	Contact email.
note	string	no	Additional context.

{ "success": true, "message": "Name request received", "id": "req_..." }

Public endpoints (no key)

These don’t require x-api-key:

• GET / — health check: { "name", "version", "status", "endpoints" }.
• POST /names/{id}/feedback — submit a pronunciation vote. Body: { "vote": "up" | "down", "reason"?: "accurate" | "wrong_pronunciation" | "wrong_language" | "audio_quality" }. Rate-limited to 5 votes per IP per day. Returns 201 { "success": true, "id": "..." }.

Errors

Status	Body code	Meaning
400	—	Missing/invalid parameter (e.g. no name).
401	—	Missing or invalid API key.
402	trial_expired	The 14-day trial window has ended — upgrade.
402	trial_exhausted	The 200-call trial cap is used up — upgrade.
403	tier_not_allowed	Endpoint needs a higher plan (e.g. audio generation on trial/starter).
404	—	Resource (e.g. name id) not found.
429	—	Daily rate limit for your tier exceeded.

Trial 402 and tier 403 responses carry a stable code field — branch on it, not on the message text:

{ "success": false, "error": "Trial period has ended", "code": "trial_expired" }

Interactive reference

The worker serves a live, always-current OpenAPI spec and an interactive explorer:

• Interactive docs (Scalar): https://names-api.namedropiome.workers.dev/docs
• OpenAPI spec (YAML): https://names-api.namedropiome.workers.dev/openapi.yaml

Related

• Quickstart — start a trial and get a key.
• Using your API key — first call with a key you already have.
• Names API — the public lookup surface.
• Developer Portal — the API hub and interactive reference.