Zum Inhalt springen
NameDrop Documentation

Pronunciation API — Using your API key

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

This guide is for when you already have an nd_live_… key — for example, one issued to you for a trial. It gets you from a key to a working call in a couple of minutes.

1. Your base URL

Section titled “1. Your base URL”
https://names-api.namedropiome.workers.dev

2. Send your key

Section titled “2. Send your key”

Pass the key in the x-api-key header on every request. Treat it like a password — use it from your server, never ship it in client-side code.

x-api-key: nd_live_xxxxxxxx

3. Make your first call

Section titled “3. Make your first call”

A name search is the simplest place to start.

Terminal window
curl -H "x-api-key: nd_live_xxxxxxxx" \
  "https://names-api.namedropiome.workers.dev/search?q=smith&country=US"
const BASE = "https://names-api.namedropiome.workers.dev";


const res = await fetch(`${BASE}/search?q=smith&country=US`, {
  headers: { "x-api-key": process.env.NAMEDROP_API_KEY },
});


if (!res.ok) {
  throw new Error(`NameDrop API ${res.status}`);
}


const { data } = await res.json();
console.log(data[0]?.phonetic_simple);

4. Read the response

Section titled “4. Read the response”
{
  "success": true,
  "data": [
    {
      "name": "Smith",
      "cultural_origin": "English",
      "phonetic_simple": "smith",
      "audio_file": "Smith.mp3"
    }
  ],
  "query": "smith",
  "parsed": { "original": "smith", "matched": "smith", "type": "first_name_country" },
  "country": "US"
}

Each item in data is a Name object (full shape in the reference). To play audio, call GET /audio/{id} for a fresh signed URL. Need a phonetic guide for a name that isn’t in the database? Call GET /phonetic. Synthesizing new audio with POST /generate-audio requires a Pro or Enterprise plan.

5. Handle limits and errors

Section titled “5. Handle limits and errors”

Check the status code and, for trial limits, branch on the stable code field — not the message text.

StatuscodeWhat to do
401—Key missing or invalid — check the header.
402trial_expiredTrial window ended — upgrade.
402trial_exhausted200-call trial cap reached — upgrade.
403tier_not_allowedEndpoint needs a higher plan (audio generation is Pro/Enterprise).
429—Daily tier limit hit — retry after 00:00 UTC.
const res = await fetch(`${BASE}/search?q=smith`, {
  headers: { "x-api-key": process.env.NAMEDROP_API_KEY },
});


if (res.status === 402) {
  const { code } = await res.json(); // "trial_expired" | "trial_exhausted"
  // surface an upgrade prompt to the user
}

Next steps

Section titled “Next steps”