narrate
Pay-per-use text-to-speech API for AI agents: text or dialogue to spoken audio from $0.0001 a character ($100 per million). No account, no API key.
narrate is dvmkit's pay-per-use text-to-speech API for AI agents. Give it text or a multi-speaker dialogue and it returns spoken audio. It costs from $0.0001 a character, with no account and no API key. It is a Digital Vending Machine (DVM): an HTTPS service an agent finds, pays, and calls on its own.
- What it does: synthesises speech in a choice of voices, with optional captions and chapters.
- Price: $0.0001 per character on the fast tier, $0.00015 per character on the balanced tier, and $0.00025 per character on the expressive tier. A 1,000-character script costs $0.10 to $0.25. See Quality tiers.
- Pays with: USDC on Base, USDC.e on Tempo, or Bitcoin ecash (Cashu), per job or from a prepaid credit, which can also be funded over Lightning.
- Endpoint:
https://narrate.dvmkit.ai, with two capabilities:synthesise(the paid audio job) andlist-voices(free catalog discovery).
A single quality knob sets the trade-off between speed, realism, and expressiveness, and narrate routes the job to match. Outputs are content-hash cached and stored in blob storage when large.
Published reference. This page is the source of truth for narrate's documented inputs, outputs, prices, and errors. The running service publishes its current capability schemas and advertised prices in its live descriptor. Full output envelope shapes are in the dvm CLI reference.
Quality tiers
quality is required on every synthesise call. It determines the voice engine, feature availability, and the per-character price.
| Tier | Optimised for | Best for | USD/char | $/M chars |
|---|---|---|---|---|
fast | Speed: the lowest latency | Notifications, chat replies, real-time agent voices | $0.0001 | $100 |
balanced | Realism: natural long-form delivery | Long-form narration, articles, audiobooks | $0.00015 | $150 |
expressive | Expressiveness: emotion, style, and audio tags | Emotion, audio tags, native multi-speaker dialogue | $0.00025 | $250 |
Quality does not cap input length. Long-form works on every tier. The tier choice is about voice realism, feature availability, and cost, not input size.
Feature gating
Several features are honoured only on expressive; requesting them on fast/balanced rejects up-front with an invalid_input envelope before payment.
| Feature | fast | balanced | expressive |
|---|---|---|---|
| Text + dialogue synthesis | ✓ | ✓ | ✓ |
speaking_rate | ✓ (clamped 0.6–1.5) | ✓ | ✓ |
| Multilingual content | ✓ | ✓ | ✓ |
Markdown structure (input.format) | ✓ | ✓ | ✓ |
output.normalize / output.captions / output.chapters | ✓ | ✓ | ✓ |
style parameter | rejected | rejected | ✓ |
Inline audio tags ([whispering]) | rejected | rejected | ✓ |
| Native multi-speaker dialogue API | per-turn stitch | per-turn stitch | ✓ (≤ 2k chars) |
A raw Cartesia voice UUID is also rejected on expressive: that tier's price covers expressive features those voices can't deliver.
synthesise
Input schema
{
"quality": "balanced",
"input": {
"text": "Hello, world.",
"format": "plain",
"language": "en"
},
"voice": "narrator",
"speaking_rate": 1.0,
"output": { "format": "mp3", "normalize": false, "captions": false, "chapters": false }
}input: exactly one oftext(monologue) ordialogue(array of{ voice?, text, style?, language? }turns; up to 100 turns, ≤ 100,000 chars total).formatdefaults to"plain";"markdown"adds structure-aware prosodic pauses.languageis auto-detected when omitted.voice: persona name (narrator,host,formal,casual,audiobook), a raw ElevenLabs 20-char ID, or a Cartesia UUID. Omitted falls back to the operator default, else thenarratorpersona.style: expressive-only free-form performance direction (≤ 500 chars).output:format(mp3/wav/ogg/opus),normalize(EBU R128),captions(VTT or{ format: "srt" }),chapters(ID3v2 CHAP frames; mp3 only).
Chapters work on every quality tier and require MP3 output. Set output.chapters: true to derive markers from H1/H2 headings in markdown monologue input (input.text with input.format set to markdown). An explicit array of { time, title } markers also works with plain text or dialogue; time is in seconds.
Voice personas
Each persona is a stable voice character. The exact voice behind it varies per tier; list-voices returns it with a sample to audition.
| Persona | Character |
|---|---|
narrator | Warm narrative female, mid-range |
host | Energetic casual male |
formal | Composed authoritative female |
casual | Warm expressive female |
audiobook | Deep weighty male, long-form |
CLI example
dvm request -d dvmkit--narrate/synthesise --data '{"quality":"balanced","input":{"text":"Hello, world."},"voice":"narrator"}'
dvm request -d dvmkit--narrate/synthesise --data '{"quality":"expressive","input":{"text":"Hello [excited] friend!"},"style":"warm and reassuring"}'
dvm quote -d dvmkit--narrate/synthesise --data '{"quality":"fast","input":{"text":"Ping."}}'list-voices
Free. Returns the persona catalog with per-tier voice identity and sample URLs. Optional filters: language (ISO 639-1), quality, query (free-text).
dvm request -d dvmkit--narrate/list-voices --data '{"language":"fr","quality":"expressive"}'Each entry carries persona, character, a quality_tiers map ({ provider, voice_id, model, label, sample_url } per tier; provider names the voice vendor behind that tier, Cartesia or ElevenLabs, not narrate itself), and language_coverage. The per-tier sample_url lets a caller audition the exact voice they'd get on that tier.
Auth
Signed requests are required. Every quote and job carries a secp256k1 + BIP-340 Schnorr signature over the canonical-JSON body, at the descriptor level so all capabilities share one auth slot. Drift window ±5 minutes; replay window 10 minutes. An unsigned, stale or replayed request rejects with a structured 401 auth_error before payment is taken.
The CLI handles this for you: dvm init creates a default signing identity and dvm quote / dvm request sign with it automatically. Pass --as <identity> only when you want to sign as a different one. If you see auth_error, run dvm identity list to check you have one.
Prepaid credit
narrate offers a prepaid balance, so an agent making repeated calls funds once instead of paying per job. The funding menu rides on every quote and every 402.
| Field | Value |
|---|---|
| Minimum funding | $0.10 |
| Maximum residual balance | $20.00 |
| Credit lifetime | 90 days from the most recent funding |
dvm credit fund dvmkit--narrate --amount 2.00
dvm credit balance dvmkit--narrate
dvm credit drain dvmkit--narrate # reclaim it, works after expiry tooA job priced above the maximum still clears: the ceiling binds how much balance you may hold, not what you may spend. And a failed job never takes your money: the charge is released back onto your credit rather than settled. See Prepaid credit for the full model.
Pricing
Per-character, per-tier: see the Quality tiers table. Cost = character_count × tier_rate, converted to sats at the 402 handshake. Content-hash caching (identical inputs from any caller) means cache hits return the same audio at no charge; feature-gate rejections happen before payment, so a bad-tier request never bills.
Error codes
Failures surface via the CLI error envelope with a stable code, kept in lockstep with narrate's error taxonomy. No failure charges you, whatever the code says. A failed job releases its draw back onto your credit. The attribution column says who to chase, never what the failure cost: Caller means change the request and retry; anything else means the fault is ours and the retry needs time or an operator. The provider_* codes below refer to the upstream speech service, not narrate itself; "provider" elsewhere in these docs means narrate.
| Code | Trigger | Attribution |
|---|---|---|
invalid_input | Validation or tier gating: a style param, inline audio tags, or per-turn style on a non-expressive tier; chapters without MP3 output; automatic chapters without markdown monologue input; a raw voice UUID at expressive. Rejected up-front, before payment, with a hint pointing at the fix | Caller |
content_rejected | The vendor's moderation refused the caller's text (a recognized content-policy signature) | Caller |
provider_rejected | The vendor rejected our request shape (an unrecognized 4xx carrying no content-policy signature), so never blamed on the caller's content | Builder/operator |
provider_allowance_exhausted | The operator's own vendor plan is out of credit, whatever status the vendor bills it with. Held distinct from auth_error: a dry plan needs a top-up, a dead key needs rotating | Operator |
rate_limited | Vendor 429. Transient, safe to retry | Operator |
provider_error | Vendor 5xx or network error. Transient, safe to retry | Operator |
auth_error | Either the request signature, clock, or nonce is invalid (rejected before payment; see Auth), or the operator's vendor key is dead or misconfigured | Caller or operator |
See also
- Explore the catalog · dvm CLI reference · Caller quickstart
- Other first-party DVMs: scrape · scribe · cast · discover · satoshi-quotes
discover
Find pay-per-use APIs for AI agents in the catalog of Digital Vending Machines. Keyword search is free, natural-language search $0.01. No account, no API key.
satoshi-quotes
Check a quote or claim against the Satoshi Nakamoto Institute (SNI) public archive. Get a verdict, source passages, and links for $0.005 per check.