Fish Model Query API 对接说明
内容提要
本文介绍Fish Model Query API的对接方法，用于分页检索Fish公共音色库或账号下的克隆音色。接口地址为GET https://api.acedata.cloud/fish/model，支持按标题、标签、语种等参数过滤，并可通过self=true查询自有音色。该接口免费，响应包含音色ID、标签、样本等字段，错误处理涵盖token无效、速率限制等场景。
延伸解读
免费查询，按需付费
本接口用于分页检索音色列表，完全免费，不产生任何费用。但需要注意，创建音色（Fish Model Create）同样免费，真正的费用发生在调用 Fish TTS 合成语音时。因此，在开发或测试阶段，可以放心使用查询接口来筛选和获取音色 ID，而无需担心成本。
参数与上游一致，注意模糊匹配
查询参数与 Fish Audio 官方 API 完全一致，便于开发者参考官方文档。但需注意，title 参数是全局模糊匹配，会搜索公共库中的所有音色，而不仅仅是自己创建的。如果希望只搜索自己的音色，应使用 self=true 参数，它等价于限定 author_id 为当前账号。
分页与错误处理要点
响应中的 has_more 字段可能为 null，建议使用 total 和 page_size 计算总页数，以确保分页逻辑正确。错误处理方面，需注意 401 表示 token 无效，429 表示触发速率限制，400 表示参数缺失或不合法。合理处理这些错误码，可以提升接口调用的稳定性。
Q&A
Fish Model Query API 的接口地址是什么？
接口地址为 GET https://api.acedata.cloud/fish/model，用于分页检索 Fish 公共音色库或当前账号下的克隆音色。
如何使用 Fish Model Query API 查询自己创建的音色？
在请求参数中设置 self=true，即可仅返回当前账号创建的音色，无需其他额外条件。
Fish Model Query API 支持哪些查询参数？
支持 page_size（每页条数，默认10）、page_number（页码，默认1）、title（标题模糊搜索）、tag（标签过滤）、self（是否只返回自己的音色）、author_id（按作者ID过滤）、language（按语种过滤）、title_language（按标题语种过滤）、sort_by（排序字段）等。
Fish Model Query API 如何收费？
该接口免费，不计费。创建音色（Fish Model Create）也免费，费用仅在调用 Fish TTS 合成语音时按用量产生。
Fish Model Query API 返回的 items 中包含哪些常用字段？
常用字段包括 _id（音色ID）、type（模型类型）、title（音色名称）、description（描述）、state（训练状态）、tags（标签）、languages（语种）、visibility（可见性）、samples（样本）、like_count（点赞数）、task_count（合成次数）、author（作者信息）等。
Fish Model Query API 的错误码有哪些？
错误码包括：400 token_mismatched（参数缺失或不合法）、401 invalid_token（token无效）、429 too_many_requests（速率限制）、500 api_error（服务器内部错误）。
如何从 Fish 公共库挑选音色用于 TTS 合成？
先使用 Fish Model Query API 配合 title、tag、language 等参数检索，定位到目标音色的 _id，然后用 Fish Model Get API 获取样本试听，最后将 _id 作为 /fish/tts 的 reference_id 使用。
