云声配音开发者 音色查询 API接口对接文档

前言说明

本文档为云声配音开发者专属接口说明，主要用于对接查询平台系统内置音色及用户自主克隆生成的个性化音色，支持开发者通过接口获取音色基础信息、音色分类、音色标识、克隆音色归属及调用状态等数据，实现前端音色展示、音色筛选、配音任务绑定等业务场景对接，助力快速完成音色相关功能集成。

接口信息

• 接口地址：https://www.yuntts.com/api/v1/voice-query
• 请求方法：POST
• Content-Type：application/json

请求头

请求参数

platform 可选值

voiceSource 可选值

响应格式

成功响应

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "totalPages": 5,
    "data": [
      {
        "platform": "openaudio",
        "voice_model": "04b9f0bc-8400-4eb5-8da5-e6f3a629aabe",
        "voice_name": "青年小米-Fish",
        "description": "年轻活力的男声",
        "model": "fish-speech-v1",
        "voice_source": "upload",
        "audio_url": "https://www.yuntts.com/wp-content/uploads/audio-tts/demo.mp3",
        "avatar_url": "https://www.yuntts.com/wp-content/uploads/avatar-tss/ai.webp",
        "created_at": "2026-04-08 12:00:00"
      },
      // 更多模型...
    ]
  }
}

失败响应

{
  "code": 401,
  "message": "认证失败",
  "data": null
}

权限说明

• 管理员：可以查看所有上传的模型（包括其他用户上传的）
• 普通用户：只能查看自己上传的模型

示例代码

JavaScript 示例

const apiKey = 'your_api_key';
const formData = {
  platform: 'openaudio',
  voiceSource: 'upload',
  page: 1,
  page_size: 20
};

fetch('https://www.yuntts.com/api/v1/voice-query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify(formData)
})
.then(response => response.json())
.then(result => {
  console.log('查询结果:', result);
  if (result.code === 200) {
    // 处理成功数据
    console.log('模型总数:', result.data.total);
    console.log('模型列表:', result.data.data);
  } else {
    // 处理失败
    console.error('请求失败:', result.message);
  }
})
.catch(error => {
  console.error('网络错误:', error);
});

Python 示例

import requests
import json

api_key = 'your_api_key'
url = 'https://www.yuntts.com/api/v1/voice-query'

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {api_key}'
}

data = {
    'platform': 'openaudio',
    'voiceSource': 'upload',
    'page': 1,
    'page_size': 20
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()

print('查询结果:', result)
if result.get('code') == 200:
    print('模型总数:', result['data']['total'])
    print('模型列表:', result['data']['data'])
else:
    print('请求失败:', result.get('message'))

错误码说明