Get system voices

Overview

Use this API to retrieve the system default voices available for a given model. The response includes a list of voice IDs and detailed information (name, description, recommended scenarios) for each voice.

When exposed to an agent, the agent can use this catalog to pick the most appropriate voice for a given scenario.

Request

Method

GET

Endpoint

/v1/audio/system_voices

Query parameters

Parameter	Type	Required	Allowed values	Description
model	string	Yes	step-tts-2	The model whose system voices to query. Currently only step-tts-2 is supported.

Request example

GET /v1/audio/system_voices?model=step-tts-2

Response

Format

JSON

Response fields

Field	Type	Description
voices	array[string]	List of system voice IDs available under this model.
voices-details	object	Details per voice, keyed by voice ID.
voices-details.<id>.voice-name	string	Voice display name. May be empty for some voices.
voices-details.<id>.voice-description	string	Voice description, including gender and character.
voices-details.<id>.recommended_scene	string	Recommended use cases, separated by 、.

Response example

{
  "voices": [
    "elegantgentle-female",
    "lively-girl",
    "livelybreezy-female",
    "magnetic-voiced-male",
    "soft-spoken-gentleman",
    "vibrant-youth",
    "zixinnansheng"
  ],
  "voices-details": {
    "vibrant-youth": {
      "voice-name": "Vibrant Youth",
      "voice-description": "男，英文音色，温柔亲和",
      "recommended_scene": "有声书、视频配音、语音助手"
    },
    "elegantgentle-female": {
      "voice-name": "气质温婉",
      "voice-description": "女，真诚温柔，亲和力强，给人安全感",
      "recommended_scene": "客服与业务办理、口播（解说、新闻）、教育与培训、情感陪伴"
    }
  }
}

voice-name, voice-description, and recommended_scene are returned in Chinese as-is from the service. Use the voice ID (the key under voices-details) when calling the TTS API.

Notes

• Each ID in voices has a matching entry in voices-details; use the voice ID to look up its details.
• recommended_scene is informational only — pick the voice that best fits your use case.