Fish Audio public API
Use this skill when a video needs Fish narration. The release uses the official POST https://api.fish.audio/v1/tts endpoint. It does not ship a web-session proxy, cookies, an account, or a voice. Node.js 22.20 or later is required. Install FFmpeg/ffprobe for the video audio pipeline.
Configure locally
Copy env.example to the video project's .env, ensure .env is ignored by Git, then fill it locally. Never request that users paste credentials into chat. Existing process environment values take precedence over .env. Scripts never print secret values or upstream error bodies.
| Variable | Meaning |
|---|---|
FISH_API_KEY | API key created in the user's Fish account; required for generation. |
FISH_REFERENCE_ID | A voice ID the user has permission to use; required unless a project explicitly supplies one. |
FISH_MODEL | Defaults to s2.1-pro-free; supported choices also include s1, s2-pro, s2.1-pro. Account access and quotas are provider-controlled. |
No silent model fallback is allowed. An unknown model fails locally, because the provider may otherwise choose a paid default. Availability and pricing can change; check the account before generation. Setting a key does not itself authorize a charge: run synthesis only for the user's requested scope.
Generate and revise
For a scaffolded HyperFrames project, edit scripts/narration.json. Its voice.referenceId and voice.model may be null to use the environment. All other voice settings are explicit in the template. Preview one short paragraph before producing a whole narration.
shnode scripts/tts-fish.mjs --section s0 node scripts/tts-fish.mjs node scripts/tts-fish.mjs --section s2 --para 1 --force
--para requires every unselected paragraph in that section to exist. To start a new project, first generate one short section with --section s0; use --para for a later repair. Matching paragraph text and voice profiles reuse frozen audio. --force makes another API request for the selected speech.
The common helper public-media-api.cjs supports the shared audio engine as well. Its Fish configuration accepts fish.transport: "official-api", fish.reference_id, fish.model, and fish.request. Sampling fields are top-level request fields, such as temperature and top_p; a website-style backend/sampler profile is not this API contract. Never put credentials in JSON project profiles.
Every generation POST is sent once. A timeout can occur after the provider started work; inspect provider usage before deliberately retrying. Redirects are refused. Official endpoints are pinned. FISH_API_URL with HYPERFRAMES_TEST_ALLOW_FISH_LOOPBACK=1 is only for local mock tests.
Optional public media APIs
The same helper supports OpenAI whisper-1 transcription with word timestamps, and GPT Image PNG generation. These are separate account/billing capabilities, not features bundled by an agent subscription. See requirements and transcription. Images require an explicit OPENAI_IMAGE_MODEL or --model; choose a GPT Image model available to the user's account. External image/video tools, including Codex image tools and video-generation plugins, are optional and are not installed or authenticated by this skill package.
Maintainer verification
shnode --test skills/fish-audio-api/tests/public-media-api.test.cjs node --test skills/hyperframes/scripts/tests/fish-tts.test.mjs
These tests use fake keys and loopback HTTP, not paid services. The release verification does not establish that a user's account has model access.
Official references checked on 2026-09-26: Fish TTS API, Fish developer guide.
