How to connect Fish Audio MCP with Python

Create an ordinary nested folder. Reuse the same UUID request_id and input to recover a lost response.

Create an avatar from one prepared image source, optionally bind an existing voice. Explicit move_existing approval is required for retained images. Reuse identical UUID request_id and arguments to resume; does not generate media.

Create a one-hour workspace-scoped upload slot for an image, video or audio input, only for a file that is not in Fish yet. To reuse a finished generation result as an input, pass its media.object_key to the estimate and generate tools instead; do not download a result and upload it again. When the user will upload through web_upload_url, ask which format the file is (for example png, jpg, webp, mp4, mov, mp3 or wav) before calling this tool and use that extension in file_name: the link only accepts files of that format. For web_upload_url file_size need not be exact (the page re-signs the slot for the real size); when you PUT to upload_url yourself, file_size must be the exact byte size.

Clone a voice from sample audio and get a voice usable with text_to_speech. Provide 1-5 https URLs of clean speech from ONE speaker (for local files call get_upload_url first, keeping the file extension); 10-60 seconds total gives the best results, 270 seconds is the hard maximum. Creation is free. Instead of creating immediately, the response may report quality warnings or require speaker verification — always follow its instructions field. Only clone voices the user owns, has the speaker's consent to use, or is otherwise legally allowed to use; Fish Audio may remove voices that violate these rules.

Estimate image edit or upscale cost and validate the request; pass input_object_key for a single image, or inputs for several. This is read-only and creates no task or quote.

Estimate image generation cost and validate the request. This is read-only and creates no task or quote.

Estimate video generation cost (text/image/reference-to-video, lip sync, talking avatar) and validate the request. Pass operation, or inputs with roles and let the capability follow from them. This is read-only and creates no task or quote.

Submit an image generation with the same parameters used for estimation. The API revalidates price before charging credits.

Submit an image edit with the same parameters used for estimation. The API revalidates price before charging credits.

Submit a video generation with the same parameters used for estimation. The API revalidates price before charging credits.

Read asset original object_key and temporary download URL. Use object_key with compatible generation input roles, never thumbnail_url.

Read folder position or avatar portrait/default voice; list children and images separately.

Internal helper for the Fish Audio player UI: returns the base64-encoded bytes of a fish.audio audio URL. Agents should pass audio URLs around directly instead of calling this.

Get the authenticated user's Fish Audio plan, remaining package credits, and the per-call TTS text budget. Speech generation costs 1 credit per UTF-8 byte of text. Transcription costs 3000 credits per minute with model=pro and 500 credits per minute with model=flash. Top up at https://fish.audio/go-premium/

Get terminal media results and billing; this may reconcile provider state. A finished get_generation_status returns the same results. A result's media.object_key can be passed directly as an input to image edit or video generation in the same workspace.

Poll media status and billing; this may reconcile provider state and credits. While running it returns poll_after_seconds (about 20 for images, 60 for videos): wait that long before calling again. Once finished it also returns the results, so get_generation_result is not needed. Pass generation_id for one generation, or generation_ids (up to 20) to check several at once.

Get one media model's prompt policy and, per capability, its parameter schema, required_roles and accepted inputs (kind, mime_types, max_bytes, max_count, dimension limits). Call it once per model and keep the result for the whole conversation; call it again only after an invalid_arguments error. Accepted inputs can also be a finished generation result's media.object_key.

Get a temporary upload slot for a local audio file: HTTP PUT the raw file bytes to upload_url (within 1 hour), then pass file_url to speech_to_text. Environments that cannot make HTTP uploads (e.g. claude.ai or ChatGPT web chat) should send the user web_upload_url to upload from their browser instead. Uploaded files are deleted automatically after 7 days.

Get details of one Fish Audio voice by its id: description, languages, tags, popularity stats, a sample audio URL and a default demo text.

List direct child folders/avatars/styles; all=true returns a flat tree. Files are listed separately with list_assets.

List direct assets; search without collection_id searches the workspace. Paginate using next_cursor and identical filters.

List available Fish image and video models (video includes lip sync and talking avatars). Capabilities are named as in the Fish web app, e.g. t2i (text-to-image), edit (image edit), upscale, t2v (text-to-video), i2v (image-to-video), first_last, reference, reference_video, video_audio (lip sync), avatar_audio (talking avatar). default_credits is the price of one output with default parameters; capabilities billed by input length report credits_per_input_second instead, with input_seconds_rounding: ceil where every started second is billed.

List the workspaces of the team this connection is authorized for.

Save a completed upload or successful task result. Repeated saves return the existing actual location; use update_asset to move it.

Search public voices (TTS models) on Fish Audio, or list your own with self=true (includes private and team-shared voices). Omit query and set language to browse curated/popular voices for that language. Prefer voices with high task_count; the returned voice ids are what text_to_speech takes.

Transcribe speech audio to text. Provide a public https URL to the audio file (max 20MB) — for local files get one from get_upload_url first. model=pro (default) costs 50 package credits per second and takes an optional language hint. model=flash costs 500 credits per minute. It is cheaper and takes no language hint. Both return plain text without timestamps.

Bind a previous take's audio back to its block (free, no generation). Only adopts cleanly when the take matches the block's current text/voice — see content_matches_current in studio_list_takes.

Add a chapter (optionally after an existing chapter anchor). A new chapter has no blocks. Add its first block with studio_write_blocks append_to.

Create a studio project from structured chapters (max 200 blocks — use studio_import_document for whole books). roster maps speaker names to voice_ids from search_voices; block.voice takes a roster name or a voice_id. Free. Retrying may duplicate — check studio_list_projects first. First time operating the studio? Call studio_help.

Platform-tuned text polish for TTS: expands numbers, phone numbers, dates and symbols into spoken words and adds delivery tags at the density the studio voices are tuned for. Pass one block's text, write the result back with studio_write_blocks. Free.

Export the project (or selected chapters) to a downloadable audio file. Two phases: without confirmed_credits it returns a quote {blocks_to_generate, credits} — show it to the user; then call again with confirmed_credits=<that number> to start the background job (poll studio_project). The quote bills each block that has no audio or changed since its last generation. Requires a paid plan.

Search block text across the project (case-insensitive substring, or regex=true). Returns matching anchors with snippets and revs — the entry point for fixing something everywhere without reading every chapter.

Synthesize audio for blocks: pass blocks (anchors) or chapter, or neither for the whole project. By default only dirty blocks run (unchanged audio is free/cached). Costs 1 credit per UTF-8 byte of spoken text (2x for another team's professional clone voices); ALWAYS dry_run=true first and show the user the quote. force=true re-rolls already-generated blocks (paid; requires explicit blocks — prefer free studio_adopt_take). A dirty block whose exact text/voice/settings already have a take reuses it for free (reused_take=true). Each done result has take_id (null if the take cannot be found). Runs up to ~45s. Blocks that are not done by then continue in the background and are listed in remaining_anchors. Poll them with studio_read_blocks (include_audio=true). Do not call studio_generate for them again: that charges them a second time.

The operating manual for Story Studio (multi-speaker audio projects). Call this before your first studio operation. Topics: quickstart (default), editing, tags, billing, errors, workflows.

Import a document or long text (novel, script, article — up to 1.5M chars) into a new studio project. A background LLM splits chapters, casts voices per speaker and adds delivery tags (auto_tags) or rewrites for naturalness (rewrite). Free. Returns immediately; poll studio_project. For files, upload via get_upload_url first and pass storage_key. First time operating the studio? Call studio_help.

List the user's Story Studio projects (name, chapter count, importing flag), newest first. First time operating the studio? Call studio_help.

List a block's generated takes (audio history): audio URL, duration, the exact text/voice each take was generated from, and whether it still matches the block (content_matches_current). Adopting an old take is free — check here before paying for a re-roll.

Project overview: chapter outline (anchors, titles, block/dirty counts, durations), speaker roster, and live import/export job state. This is the polling verb for imports and exports (poll_after_seconds tells you when to check again). First time operating the studio? Call studio_help.

Read blocks: pass chapter (anchor) for a whole chapter (paginated) or blocks (list of anchors) for specific ones. Returns anchor, rev, voice, text, kind, dirty, duration per block; include_audio adds audio URLs. format=script renders a read-only script view for showing the user.

Swap every block using one voice to another voice across the whole project (e.g. change a character's voice after import). Free; affected blocks become dirty and regenerate at the normal rate. Voice ids come from the roster in studio_project or search_voices.

Rename a chapter.

Project-wide settings: rename, default voice/backend for new blocks, audio settings defaults, scene_preset (off|studio adds room ambience), chapter_order (list of chapter anchors) to reorder chapters. default_voice_id and default_backend apply only to blocks created later. To change the voice of existing blocks, use studio_recast_speaker or studio_write_blocks. Existing blocks keep their backend. audio_settings also changes existing blocks that use the project value: those blocks become dirty and cost credits again at the next generation or export. Quote first with studio_generate dry_run=true.

Edit blocks with up to 100 ops, applied in order. Op shapes: {"block", "rev", "text"?, "voice"?, "kind"?, "delay"?, "audio_settings"?} updates in place (rev required when changing text/voice/settings); {"insert_after": anchor, "text", ...} / {"append_to": chapter, "text", ...} insert; {"move": block, "after": anchor} reorders; {"delete": block} removes. Per-op results report ok, noop, conflict or failed; a conflict includes the current text and rev. An unknown block anchor, voice or a missing rev stops the call, and the ops before it stay applied: re-read the chapter before you retry. Free — writing never bills; edits show up live in the user's web editor. dry_run validates without writing. See studio_help topic=editing.

Send feedback about these Fish Audio tools to the team — friction, bugs, missing capabilities, confusing behavior, or things that worked well. Please send one short note whenever something surprised you or took more steps than it should; every message is read.

Generate speech audio from text with one Fish Audio voice, or a multi-speaker dialogue with several, and return a permanent audio URL. Costs 1 package credit per UTF-8 byte of text (audio and speaker tags included; a professional voice cloned by another team costs double). Fish refunds a failed call. For identical calls (same text, voices and model) within 5 minutes, the second call is free, so a retry after a timeout costs nothing. Other repeats cost credits. Set dry_run=true for a free cost quote, including PVC surcharges, without generating audio or spending credits. Omit it or set false to generate.

Rename/move an asset. Omitted collection_id leaves its location; explicit null moves to root. No delete.

Rename/move ordinary folders or edit avatar name/default voice/portrait. Portrait must already be inside the avatar; use update_asset to add reference images. No delete or style creation.

Complete speaker verification for a voice clone that returned verification_required: the actual speaker records themselves reading the exact prompt sentence, the recording is uploaded (use get_upload_url), and its URL is passed here. On success the voice is created. Call without recording_url to check the session status and get the current prompt.