Use cases
For developers putting voice inside a product
Bearer token, POST, bytes. The rest is detail.
Last checked 2026-08-14
In short
Developers use Naadly's HTTP API for synchronous renders, streaming for anything the user is waiting on, and queued jobs with signed webhooks for long work. Keys are per integration and revocable, usage is visible per key, and the same account also exposes an MCP server so an assistant can speak without glue code. API access starts at $15 a month.
What to build against
- Synchronous for short, immediate audio: notifications, prompts, a single line.
- Streaming when a human is waiting: first audio arrives before the rest is rendered.
- Jobs plus webhook for chapters, batches, dubs and transcription; HMAC-signed, retried with backoff, every attempt logged.
- MCP when your client is a model rather than your code.
Operational facts you will want
- Five output formats: MP3, WAV, OGG, FLAC and u-law for telephony.
- Characters per request are capped by plan; engines have finite concurrency and tell you when a render queued.
- Every render is watermarked and served with a synthetic-media header - plan for both in your own terms.
- Keys are hashed at rest: revoke and reissue, never recover.
Designing for the failure cases
Speech is a remote call that costs real machine time, so the integrations that age well treat it like one: cache by a hash of text, voice and speed, because the same prompt rendered twice is money for an identical file; render the fixed strings in your product once at build time rather than per user; and keep a text fallback path, since a queue that is briefly full should degrade your feature rather than break your screen.
- Idempotency: derive your own key from the text and voice, and you get retry safety for free.
- Backoff on a queued or rate-limited response instead of hammering; the header tells you what happened.
- Store the returned audio yourself if your users will replay it - re-rendering to avoid a cache is the most common way people overspend.
- Log the voice slug with the audio, so a report of "the voice changed" is answerable.
What it is not
Not a realtime conversational voice stack - renders are seconds, not milliseconds, so it belongs behind production and asynchronous features rather than inside a live phone call.
Questions
- Is there a sandbox?
- Use a key on the free plan's limits to build against, then upgrade when you need API volume - API access itself starts at $15.
- How do you handle long jobs?
- Queue them and receive a signed webhook, or poll the job endpoint.
- Can I meter my own customers?
- Usage is reported per key and per month, which is the hook most people build their own metering on.