跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

本接口基于 Fish Audio 官方 Model API，用于分页检索 Fish 公共音色库或当前账号下的克隆音色。地址为 GET https://api.xhuoapi.ai/v1/fish/model。
创建音色请参考 Fish Model Create API；按 _id 查询单个音色详情请参考 Fish Model Get API。

​
申请流程

要使用 API，需要先到 Fish Model API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮。 如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。 在首次申请时会有免费额度赠送，可以免费使用该 API。

​
查询参数

参数类型默认说明
page_sizeinteger10每页条数。
page_numberinteger11 起的页码。
titlestring—按标题模糊搜索。
tagstring—按单个标签过滤。
selfboolean—true 时仅返回当前账号创建的音色，无需任何额外条件。
author_idstring—按上游用户 _id 过滤。
languagestring—按音色语种过滤，如 en、zh、es。
title_languagestring—按标题语种过滤。
sort_bystring—排序字段，与上游一致，如 created_at、task_count。
参数命名与上游 GET https://api.fish.audio/model 完全一致，详见 Fish 官方文档。

​
示例 1：默认翻页（按 page_size）

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'
返回（实测，公共库总量约 180 万条；为可读性下例省略了部分长字段）： 
{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

​
示例 2：按标题模糊搜索（title）

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'
返回（实测）： 
{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}
注意 title 是「全局模糊匹配」，会同时命中 Fish 公共库的所有音色（不仅是自己的）。

​
示例 3：只列出自己创建的音色（self=true）

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'
返回（实测，当前账号下只有 1 个音色）： 
{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.xhuoapi.ai",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "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",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}
self=true 等价于在过滤里限定 author_id == 当前账号上游 ID，是常用的「我自己的音色列表」入口。

​
示例 4：按语种 + 标签过滤

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'
上游对未在标签字典里的 tag 也会返回结果，但匹配相对宽松；如果命中数为 0，建议改用 title 模糊匹配。

​
响应字段

items[] 中的每一项是一个完整 ModelEntity 对象，常用字段：
字段类型说明
_idstring音色 ID，作为 /fish/tts 中 reference_id 的值。
typestring模型类型，通常为 tts。
titlestring音色名称。
descriptionstring音色描述。
statestring训练状态：trained 表示可用。
tagsstring[]公共库标签。
languagesstring[]音色擅长的语种。
visibilitystringpublic 或 private。
samplesobject[]预置样本（含 audio 直链）。
like_countinteger公共库点赞数。
task_countinteger历史合成次数。
authorobject上游作者信息：_id / nickname / avatar。
total（顶层）integer满足条件的总条数。
has_moreboolean?上游分页指示，可能为 null。建议改用 total / page_size 计算总页数。

​
计费说明

本接口不计费——分页查询音色列表是免费操作，仅 Fish Model Create 在请求体携带 voices 字段创建新音色时计费。

​
错误处理

  • 400 token_mismatched：请求参数缺失或不合法。
  • 401 invalid_token：鉴权 token 不存在或无效。
  • 429 too_many_requests：触发账号速率限制。
  • 500 api_error：服务器内部错误。
错误响应示例： 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

要从 Fish 公共库挑选音色喂给 /fish/tts 的 reference_id，先用本接口配合 title / tag / language 检索，定位到目标 _id，再用 Fish Model Get 拿样本试听。要列出自己创建的音色，传 self=true 即可。