Skip to main content
Builtins catalog / nika:tts_generate

Media

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Teaching shape · 17-tts-self (provider: mock · a real WAV · offline). The image family’s contract, applied to audio: ONE audio file lands under output_dir: (permit-gated per final path BEFORE I/O · atomic write · content-hash-named {stem}-{provider}-{model}-{sha8}.{ext} so identical re-runs are idempotent), the output carries { provider, model, voice, created_at, endpoint_host, audio: { path, filename, format, mime_type, size_bytes, sha256, duration_ms }, cost_usd, warnings, manifest_path, output_dir } — audio bytes NEVER ride outputs, and a sidecar provenance manifest (manifest: true default) echoes the resolved request. Validation (engine MUST) · the payload is sniffed (WAV RIFF…WAVE · MP3 ID3/frame-sync) — a non-audio payload is a hard -007; WAV duration_ms is exact header math, MP3 duration is honestly null (never a guess). Empty payloads are -004. Security (engine MUST) · endpoints are engine-fixed constants (the local base URL is engine config at the composition root — the same sanction as image_generate and infer:) · keys are engine-configured (OPENAI_API_KEY · ELEVENLABS_API_KEY · NIKA_TTS_LOCAL_API_KEY or the NIKA_-prefixed forms), never workflow args, never logged · a verbose local server reflecting the Bearer into an error body MUST be scrubbed (the image family’s rule). Throws · NIKA-BUILTIN-TTS_GENERATE-001 invalid arguments (validation_error) · -002 provider unavailable (validation_error) · -003 request failed (network_error · transient: true for 5xx/408/429 + timeout/connection) · -004 empty audio (tool_error) · -005 content policy (security_error · never transient) · -006 save failed (tool_error) · -007 payload validation (tool_error) — the image twin’s category ladder, code for code.

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:tts_generate. Specification revision: f8c5df2127c7. The Lab language identity is language:tool:tts_generate; the registry view is ecosystem:tool/nika:tts_generate. They refer to this contract without merging their graph identities.