查询可用音色

该 API 支持查询当前账号下可调用的全部音色（voice_id）。

包括系统音色、快速克隆音色，以及已在平台侧生成并保存成功的文生音色。

接口概览

接口地址: https://api.senseaudio.cn/v1/get_voice
请求方式: POST
Content-Type: application/json
鉴权方式: Bearer Token

请求配置

请求头 (Request Headers)

参数名	必填	说明	示例
Authorization	是	鉴权 Token。格式：Bearer SENSEAUDIO_API_KEY	Bearer sk-123456…
Content-Type	是	内容类型。固定为 application/json	application/json

请求参数 (Request Body)

参数名	类型	必填	描述	示例值
voice_type	string	是	希望查询的音色类型。 system: 系统音色 voice_clone: 快速复刻的音色，仅在成功用于语音合成后才可查询 voice_generation: 平台侧生成并保存成功的文生音色，仅在可调用后可查询 all: 以上全部	all

响应结构

成功响应

参数名	类型	描述
system_voice	array	系统预定义的音色列表
voice_cloning	array	快速复刻的音色列表
voice_generation	array	平台侧生成并可调用的文生音色列表
base_resp	object	本次请求的状态码和详情

system_voice 数组元素

参数名	类型	描述
voice_id	string	音色 ID
voice_name	string	音色名称，非调用的音色 ID
description	array	音色描述
created_time	string	创建时间，格式 yyyy-mm-dd

voice_cloning 数组元素

参数名	类型	描述
voice_id	string	快速复刻音色 ID
description	array	复刻时填写的音色描述
created_time	string	创建时间，格式 yyyy-mm-dd

voice_generation 数组元素

参数名	类型	描述
voice_id	string	音色 ID
description	array	生成音色时填写的音色描述
created_time	string	创建时间，格式 yyyy-mm-dd

base_resp 对象

参数名	类型	描述
status_code	int64	状态码。0: 请求结果正常；2013: 输入参数信息不正常
status_msg	string	状态详情

错误响应

HTTP 401 - 鉴权失败

json

复制

{
  "code": "authentication_error",
  "message": "invalid authorization"
}

HTTP 200 - 业务错误

无权访问指定音色

json

复制

{
  "base_resp": {
    "status_code": 403,
    "status_msg": "no access to the specified voice"
  }
}

合成失败

json

复制

{
  "base_resp": {
    "status_code": 500,
    "status_msg": ""
  }
}

代码示例

CURL

bash

复制

curl -X POST https://api.senseaudio.cn/v1/get_voice \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_type": "all"
  }'

Python

python

复制

"""
本示例用于查询可用音色。注意：需要先将密钥信息写入环境变量 `SENSEAUDIO_API_KEY`。
"""
import requests
import os
 
api_key = os.environ.get("SENSEAUDIO_API_KEY")
 
url = 'https://api.senseaudio.cn/v1/get_voice'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}
 
data = {
    'voice_type': 'all'
}
 
response = requests.post(url, headers=headers, json=data)
result = response.json()
 
if result.get('base_resp', {}).get('status_code') == 0:
    print(f"✅ 查询成功!")
    print(f"系统音色数量: {len(result.get('system_voice', []))}")
    print(f"克隆音色数量: {len(result.get('voice_cloning', []))}")
else:
    print(f"❌ 查询失败: {result.get('base_resp', {}).get('status_msg')}")

JavaScript

javascript

复制

const axios = require('axios');
 
const apiKey = process.env.SENSEAUDIO_API_KEY;
const url = 'https://api.senseaudio.cn/v1/get_voice';
 
const data = {
  voice_type: 'all'
};
 
axios.post(url, data, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => {
  const result = response.data;
  if (result.base_resp?.status_code === 0) {
    console.log('✅ 查询成功!');
    console.log(`系统音色数量: ${result.system_voice?.length || 0}`);
    console.log(`克隆音色数量: ${result.voice_cloning?.length || 0}`);
  } else {
    console.error(`❌ 查询失败: ${result.base_resp?.status_msg}`);
  }
})
.catch(error => {
  console.error('❌ 请求出错:', error.message);
});

Go

复制

package main
 
import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)
 
type GetVoiceRequest struct {
    VoiceType string `json:"voice_type"`
}
 
type GetVoiceResponse struct {
    SystemVoice     []Voice      `json:"system_voice"`
    VoiceCloning    []Voice      `json:"voice_cloning"`
    VoiceGeneration []Voice      `json:"voice_generation"`
    BaseResp        BaseResponse `json:"base_resp"`
}
 
type Voice struct {
    VoiceID     string   `json:"voice_id"`
    VoiceName   string   `json:"voice_name,omitempty"`
    Description []string `json:"description"`
    CreatedTime string   `json:"created_time"`
}
 
type BaseResponse struct {
    StatusCode int    `json:"status_code"`
    StatusMsg  string `json:"status_msg"`
}
 
func main() {
    apiKey := os.Getenv("SENSEAUDIO_API_KEY")
    url := "https://api.senseaudio.cn/v1/get_voice"
 
    payload := GetVoiceRequest{
        VoiceType: "all",
    }
 
    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
 
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("❌ 请求出错:", err)
        return
    }
    defer resp.Body.Close()
 
    body, _ := io.ReadAll(resp.Body)
    var result GetVoiceResponse
    json.Unmarshal(body, &result)
 
    if result.BaseResp.StatusCode == 0 {
        fmt.Println("✅ 查询成功!")
        fmt.Printf("系统音色数量: %d\n", len(result.SystemVoice))
        fmt.Printf("克隆音色数量: %d\n", len(result.VoiceCloning))
    } else {
        fmt.Printf("❌ 查询失败: %s\n", result.BaseResp.StatusMsg)
    }
}

Java

java

复制

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;
import org.json.JSONArray;
 
public class GetVoiceAPI {
    public static void main(String[] args) {
        try {
            String apiKey = System.getenv("SENSEAUDIO_API_KEY");
            String apiUrl = "https://api.senseaudio.cn/v1/get_voice";
 
            JSONObject payload = new JSONObject();
            payload.put("voice_type", "all");
 
            URL url = new URL(apiUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Authorization", "Bearer " + apiKey);
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);
 
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = payload.toString().getBytes("utf-8");
                os.write(input, 0, input.length);
            }
 
            try (BufferedReader br = new BufferedReader(
                    new InputStreamReader(conn.getInputStream(), "utf-8"))) {
                StringBuilder response = new StringBuilder();
                String responseLine;
                while ((responseLine = br.readLine()) != null) {
                    response.append(responseLine.trim());
                }
 
                JSONObject result = new JSONObject(response.toString());
                JSONObject baseResp = result.getJSONObject("base_resp");
 
                if (baseResp.getInt("status_code") == 0) {
                    System.out.println("✅ 查询成功!");
                    JSONArray systemVoice = result.optJSONArray("system_voice");
                    JSONArray voiceCloning = result.optJSONArray("voice_cloning");
                    System.out.println("系统音色数量: " + (systemVoice != null ? systemVoice.length() : 0));
                    System.out.println("克隆音色数量: " + (voiceCloning != null ? voiceCloning.length() : 0));
                } else {
                    System.out.println("❌ 查询失败: " + baseResp.getString("status_msg"));
                }
            }
        } catch (Exception e) {
            System.out.println("❌ 请求出错: " + e.getMessage());
        }
    }
}

Swift

swift

复制

import Foundation
 
struct GetVoiceRequest: Codable {
    let voiceType: String
 
    enum CodingKeys: String, CodingKey {
        case voiceType = "voice_type"
    }
}
 
struct GetVoiceResponse: Codable {
    let systemVoice: [Voice]?
    let voiceCloning: [Voice]?
    let voiceGeneration: [Voice]?
    let baseResp: BaseResponse
 
    enum CodingKeys: String, CodingKey {
        case systemVoice = "system_voice"
        case voiceCloning = "voice_cloning"
        case voiceGeneration = "voice_generation"
        case baseResp = "base_resp"
    }
}
 
struct Voice: Codable {
    let voiceId: String
    let voiceName: String?
    let description: [String]
    let createdTime: String
 
    enum CodingKeys: String, CodingKey {
        case voiceId = "voice_id"
        case voiceName = "voice_name"
        case description
        case createdTime = "created_time"
    }
}
 
struct BaseResponse: Codable {
    let statusCode: Int
    let statusMsg: String
 
    enum CodingKeys: String, CodingKey {
        case statusCode = "status_code"
        case statusMsg = "status_msg"
    }
}
 
func getVoiceList() {
    guard let apiKey = ProcessInfo.processInfo.environment["SENSEAUDIO_API_KEY"],
          let url = URL(string: "https://api.senseaudio.cn/v1/get_voice") else {
        return
    }
 
    let request = GetVoiceRequest(voiceType: "all")
    guard let jsonData = try? JSONEncoder().encode(request) else { return }
 
    var urlRequest = URLRequest(url: url)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    urlRequest.httpBody = jsonData
 
    let task = URLSession.shared.dataTask(with: urlRequest) { data, response, error in
        guard let data = data, error == nil else {
            print("❌ 请求出错: \(error?.localizedDescription ?? "Unknown error")")
            return
        }
 
        if let result = try? JSONDecoder().decode(GetVoiceResponse.self, from: data) {
            if result.baseResp.statusCode == 0 {
                print("✅ 查询成功!")
                print("系统音色数量: \(result.systemVoice?.count ?? 0)")
                print("克隆音色数量: \(result.voiceCloning?.count ?? 0)")
            } else {
                print("❌ 查询失败: \(result.baseResp.statusMsg)")
            }
        }
    }
 
    task.resume()
}
 
getVoiceList()

响应示例

json

复制

{
  "system_voice": [
    {
      "voice_id": "Chinese (Mandarin)_Reliable_Executive",
      "description": ["一位沉稳可靠的中年男性高管声音，标准普通话，传递出值得信赖的感觉。"],
      "voice_name": "沉稳高管",
      "created_time": "1970-01-01"
    },
    {
      "voice_id": "Chinese (Mandarin)_News_Anchor",
      "description": ["一位专业、播音腔的中年女性新闻主播，标准普通话。"],
      "voice_name": "新闻女声",
      "created_time": "1970-01-01"
    }
  ],
  "voice_cloning": [
    {
      "voice_id": "test12345",
      "description": [],
      "created_time": "2025-08-20"
    },
    {
      "voice_id": "test12346",
      "description": [],
      "created_time": "2025-08-21"
    }
  ],
  "voice_generation": [
    {
      "voice_id": "ttv-voice-2025082011321125-2uEN0X1S",
      "description": [],
      "created_time": "2025-08-20"
    },
    {
      "voice_id": "ttv-voice-2025082014225025-ZCQt0U0k",
      "description": [],
      "created_time": "2025-08-20"
    }
  ],
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}