Skip to main content
nika:tts_generate is the image pipeline’s sibling for audio: one file lands under a permit-gated output_dir:, sha256-named, manifest beside it, and audio bytes never ride workflow outputs — tasks pass a path and a hash, not megabytes of base64.

The five providers

Keys and the local URL are engine config, never workflow args: OPENAI_API_KEY / ELEVENLABS_API_KEY (or NIKA_-prefixed), NIKA_TTS_LOCAL_URL (+ optional NIKA_TTS_LOCAL_API_KEY). nika doctor prints a tts line naming what’s wired. The system voice needs neither.

Quickstart

Speak with no key: provider: system

Real speech, offline, with nothing to install on a Mac: provider: system uses the host’s own synthesizer, macOS /usr/bin/say or Linux espeak-ng (found in an absolute directory of the engine’s PATH).
  • Nika starts the program itself, as part of the builtin: the workflow needs no permits.exec, and nika check names the program in its plan. Each start is journaled as a permit_checked frame on the builtin plane. The WAV still lands under output_dir: through permits.fs.write.
  • The text is spoken as text. It reaches the synthesizer on standard input, and every [[ (which say reads as an embedded command and espeak-ng as phonemes) is broken by a space, so a script cannot mute the file. The audio is capped at 64 MiB.
  • No model choice. The model is the program (say or espeak-ng); any other model: is refused at check and at run. voice: is a host voice name (say -v '?' lists them on a Mac) and must be installed: a missing voice fails the call rather than reading with the default one.
  • No fallback. A host with no synthesizer fails NIKA-BUILTIN-TTS_GENERATE-002, naming what is missing; Nika never switches to another provider.
  • Unpriced, never free. The voice bills no provider, so its cost is reported as unpriced local work (cost_usd: null with cost_unpriced: local_model), the way a local model’s is. It runs under any cost cap.

Honesty rules

  • The extension follows the bytes. WAV RIFF…WAVE and MP3 headers are sniffed; a mislabel is a format_mismatch: warning, a non-audio payload is a hard error — never a corrupt file on disk.
  • Duration is exact or absent. WAV duration_ms is pure header math over the bytes actually present, so a streamed WAV whose header still carries a placeholder size reports its real length; MP3 duration is honestly null rather than a frame-walking guess.
  • text: caps at 4096 chars (the strictest wire’s limit, held portably) — fan longer scripts out with for_each over paragraphs.
  • Content credentials are detected, not verified: audio C2PA carriage (RIFF C2PA · MP3 GEOB) is surfaced as content_credentials in output and manifest, the same contract as images.
  • Watermarking is declared, never byte-verified. The manifest’s watermark_declared is a catalog fact: elevenlabs → "synthid (provider-declared · not byte-verified)", every other provider → null — no such declaration, honestly absent.
Paid speech is billed per character of the text sent, at the rates of the engine’s dated price table (cost_basis: catalog_rate_x_characters, with the date of the rates in cost_as_of): Under --max-cost-usd, a project ceiling: or a beat’s plafond:, a literal text: is floored at launch, and a text that only the run renders is judged on its rendered characters just before the request: nika check marks it METERED — billed per character of the text the run renders, and only a zero cap refuses it at launch. A call that fails after the provider answered keeps what it billed. OpenAI’s default voice, gpt-4o-mini-tts, has no price Nika can apply: OpenAI prices it per token, and its speech response reports no usage. Nor does a model id the table does not list, such as eleven_multilingual_v1. A capped run refuses them before any request (NIKA-1709, or NIKA-1704 when only the run decides the model), and nika arm shows a beat that uses them UNREADY. Set model: tts-1 or tts-1-hd, use a priced ElevenLabs model, or speak with provider: system, local or mock, which bill no provider. Without a cap the call runs and is counted as unpriced (Cost honesty). The table bills list prices: an ElevenLabs plan’s prepaid characters are not counted, so a cap can refuse speech your plan already covers. OpenAI shuts down tts-1, tts-1-hd and gpt-4o-mini-tts on 2027-01-06.

Cookbook (proven against live APIs)

An LLM writes the script, another model speaks it — one run:
The manifest records the LLM’s exact sentence as the resolved request — the provenance chain covers who wrote the words, not just who spoke them. Retry a local server that’s still loading its model:
Local CPU synthesis gets a 300s default timeout (timeout_ms: up to 600000); clouds default to 120s. Sub-second values are refused — under 1s is a typo’d unit.