Fish Model Create API Integration Guide

This API is based on the official Fish Audio Model API and is used to create a clone voice model that can be reused long-term based on an audio sample. The endpoint is POST https://api.fishapi.cloud/fish/model.

When you only need to use a reference voice temporarily, there is no need to create a model. You can directly use the one-time instant cloning through references in the Fish TTS API. For paginated retrieval of existing voices, please refer to the Fish Model Query API; to query details of a single voice by _id, please refer to the Fish Model Get API.

¶ Application Process

To use the Fish Model API, first go to the Fishapi Cloud Console to obtain your API Token and keep it for later use.

If you have not yet logged in or registered, you will be automatically redirected to the login page to register and log in. After completion, you will automatically return to the current page.

One API Token can call all platform services; there is no need to apply separately for each service. Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.

📘 Complete documentation: Fish Model API →

¶ Request Body Fields

Field	Type	Required	Description
title	string	Yes	Voice name, used for identification in the console list.
voices	string	Yes	HTTP(S) URL of the audio sample (a single string, not an array). This API does not support multipart/binary uploads. Please first place the audio in any publicly accessible object storage.
description	string	No	Voice description.
cover_image	string	No	Cover image HTTP(S) URL.
tags	string[]	No	Tags for public library search, for example ["male","narration","zh"].
texts	string[]	No	Reference text corresponding to the samples (used to correct pronunciation).
enhance_audio_quality	boolean	No	Whether to perform audio quality enhancement on the sample before training.
generate_sample	boolean	No	Whether to automatically generate a sample audio clip after training is complete.

For more information about voice models, please refer to the official Fish documentation.

Created voices will be publicly stored long-term, and other users may search for and use them. There is no need to pass visibility; even if private or unlist is passed, the current API will not change the public visibility accordingly.

¶ Example: Create a Public Clone Voice

curl -X POST 'https://api.fishapi.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客录音克隆的中文音色",
    "voices": "https://example.com/sample-voice.mp3",
    "cover_image": "https://cdn.acedata.cloud/e724d7f13d.png"
  }'

Note: voices must be a string (a single audio URL), not an array. The upstream service will reject it if passed as ["..."]. It is recommended to use a publicly downloadable direct link with an .mp3 or .wav suffix.

A successful response directly returns the ModelEntity object from the Fish platform (the following example is the minimum usable voice we have tested, with some long fields removed for readability):

{
  "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
  "type": "tts",
  "title": "copilot-smoke-test",
  "description": "smoke test from api.acedata.cloud",
  "cover_image": "coverimage/e5c6db52c3ed417f9cb2e5a33fb04667",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [
    {
      "title": "Default Sample",
      "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
      "task_id": "6a1bf398dfae49dca0e23159214342a0",
      "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
    }
  ],
  "created_at": "2026-05-10T03:52:55.601000Z",
  "updated_at": "2026-05-10T03:52:55.601000Z",
  "languages": ["zh"],
  "visibility": "public",
  "default_text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "780f2b2f862d41a08c0507bbbda77eb6",
    "nickname": "Penny Conrad",
    "avatar": "avatars/780f2b2f862d41a08c0507bbbda77eb6.jpg"
  }
}

_id can be used as the value of the reference_id field in the subsequent Fish TTS API, for speech synthesis using this clone voice:

Successfully created voices will be publicly stored. You can query voices created by the current calling user through this platform using self=true in the Fish Model Query API. self=true only filters the list and does not restrict other users from using the voice.

curl -X POST 'https://api.fishapi.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "你好，这是一段使用我刚创建的克隆音色合成的语音。",
    "reference_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
    "format": "mp3"
  }'

¶ Sample Requirements

Practical guidance (consistent with upstream; refer to the official Fish documentation):

• A duration of more than 30 seconds is recommended, with the best results within 5 minutes; marginal benefits are limited beyond 10 minutes.
• A sampling rate of 16 kHz or above; both mono and stereo are supported.
• Keep the content as clean as possible: no background music, echo, or obvious ambient noise; use the same speaker.
• Recommended formats: mp3 / wav.

If you are not confident in the sample quality, you can also pass enhance_audio_quality: true to let the upstream service perform audio quality enhancement first.

¶ Billing Information

Creating a voice cloning model (POST /fish/model) is free and does not incur any charges; the voice query endpoints (Fish Model Query, Fish Model Get) are also free of charge. Charges only apply based on usage when subsequently calling Fish TTS to synthesize speech.

¶ Error Handling

• 400 token_mismatched: Request parameters are missing or invalid (most commonly, voices is not a URL, or it is passed as an array).
• 400: When the reference audio cannot be downloaded, is too short, or its format cannot be recognized, please check the audio URL and file format.
• 401 invalid_token: The authentication token does not exist or is invalid.
• 429 too_many_requests: The account rate limit has been triggered.
• 500 api_error: Internal server error.

Example error response:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "voices is required and must be an HTTP(S) URL pointing to an audio file"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

¶ Conclusion

To call this endpoint, you only need to prepare a publicly accessible sample audio URL and place it in the voices field to obtain the _id, then pass it to the reference_id of /fish/tts to complete the end-to-end "cloning → synthesis" process. A common pitfall is that voices must be a string and cannot be an array.