跳转到主要内容

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，用于按 _id 查询单个克隆音色的完整详情。地址为 GET https://api.xhuoapi.ai/v1/fish/model/{id}。
创建音色请参考 Fish Model Create API；分页检索请参考 Fish Model Query API。

​
申请流程

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

​
路径参数

参数必填说明
id是音色的 _id（32 位十六进制字符串）。可通过 Fish Model Create 创建时返回，或通过 Fish Model Query 检索得到。
无请求体、无查询参数。

​
示例：拉取一个公开西班牙语音色的完整详情

curl 'https://api.xhuoapi.ai/v1/fish/model/8d2c17a9b26d4d83888ea67a1ee565b2' \
  -H 'authorization: Bearer {token}'
返回（实测，删去了 samples[].audio 中的签名 query string 以便阅读）： 
{
  "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
  "type": "tts",
  "title": "Valentino Narración Biblica Fer",
  "description": "A mature and authoritative male voice with a calm, spiritual tone. It is well-suited for religious narration, educational content, and professional storytelling in Spanish.",
  "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
  "train_mode": "fast",
  "state": "trained",
  "tags": [
    "male", "old", "narration", "calm", "serious",
    "authoritative", "professional", "clear", "Spanish"
  ],
  "samples": [
    {
      "title": "Default Sample",
      "text": "Hermanos míos, recordemos las palabras del Señor en estos tiempos difíciles. Como dice la Escritura, la fe mueve montañas, y el amor de Dios nos guía en cada paso del camino. Mantengamos firme nuestra confianza en Su divina providencia.",
      "task_id": "59ce7df6935c42249759327ddf70f37b",
      "audio": "https://c97f3361a1c971323738e24f451a0225.r2.cloudflarestorage.com/fish-platform-data/task/59ce7df6935c42249759327ddf70f37b.mp3?X-Amz-...signed..."
    }
  ],
  "created_at": "2025-03-13T08:11:10.326000Z",
  "updated_at": "2026-05-03T09:01:41.437000Z",
  "languages": ["es"],
  "visibility": "public",
  "lock_visibility": false,
  "dmca_taken_down": false,
  "default_text": "Hermanos míos, recordemos las palabras del Señor...",
  "quality": null,
  "like_count": 4344,
  "mark_count": 4409,
  "shared_count": 590,
  "task_count": 708461,
  "unliked": false,
  "liked": false,
  "marked": false,
  "author": {
    "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
    "nickname": "Fernando Caicedo",
    "avatar": "avatars/1b82fb6a329c4462b67aa9ee0a42046f.jpg"
  }
}
拿到的 _id 直接喂给 Fish TTS 的 reference_id 即可合成相同音色的语音： 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'

​
与列表接口的差异

字段GET /fish/model（列表）GET /fish/model/{id}（详情）
samples[].audio短期 R2 缓存 URL现签的 R2 直链（含 query 签名）
unliked / liked / marked / dmca_taken_down同样存在同样存在
default_text / lock_visibility同样存在同样存在
如果只是要试听一下，列表接口里的 samples[].audio 已经够用；要更稳定的下载链接，建议改用本接口。

​
响应字段（节选）

字段类型说明
_idstring音色 ID（用于 /fish/tts 的 reference_id）。
typestring模型类型，通常为 tts。
titlestring音色名称。
descriptionstring长描述。
statestring训练状态：trained 表示可用，training 表示还在训练。
tagsstring[]公共库标签。
samplesobject[]预置样本，含 title、text、task_id、audio 直链。
languagesstring[]音色擅长的语种代码。
visibilitystringpublic 或 private。
like_countinteger公共库点赞数。
task_countinteger历史合成次数（可用于人气排序参考）。
authorobject上游作者信息：_id / nickname / avatar。
created_atstringISO 8601 创建时间。
updated_atstringISO 8601 最近更新时间。

​
计费说明

本接口不计费——按 ID 查询单个音色详情是免费操作，仅 Fish Model Create 在请求体携带 voices 字段创建新音色时计费。

​
错误处理

  • 400 token_mismatched：路径中的 id 不是合法格式，或上游报「Model not found」。
  • 401 invalid_token：鉴权 token 不存在或无效。
  • 404 not_found：指定 _id 在 Fish 上游不可见（音色被删除、私密、或属于其他账号）。
  • 429 too_many_requests：触发账号速率限制。
  • 500 api_error：服务器内部错误。
实际请求一个不存在的 ID 时上游会直接返回 400 Model not found（实测）： 
curl 'https://api.xhuoapi.ai/v1/fish/model/test123' \
  -H 'authorization: Bearer {token}'
返回： 
{ "status": 400, "message": "Model not found" }
错误响应示例： 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

知道音色 _id 时直接用本接口拿完整 ModelEntity，最常见的用法是：(1) 试听 samples[].audio，(2) 把 _id 喂给 /fish/tts 的 reference_id 完成合成。如果只有标题或标签，请先用 Fish Model Query 检索。