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.

This endpoint is the authoritative source for which voices your account can actually use. Voice IDs from other sources are rejected — see Notes.

Request

Method

GET

Endpoint

GET https://api.stepfun.ai/v1/audio/system_voices

Query parameters

Parameter	Type	Required	Allowed values	Description
model	string	Yes	`stepaudio-2.5-tts`	The TTS model whose system voices to query. Any other value — including `stepaudio-2.5-realtime` — returns `400 invalid model`.

Omitting model returns 400 with model is required.

Request example

curl "https://api.stepfun.ai/v1/audio/system_voices?model=stepaudio-2.5-tts" \
  -H "Authorization: Bearer $STEPFUN_API_KEY"

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": {
    "elegantgentle-female": {
      "voice-name": "气质温婉",
      "voice-description": "女，真诚温柔，亲和力强，给人安全感",
      "recommended_scene": "客服与业务办理、口播（解说、新闻）、教育与培训、情感陪伴"
    },
    "lively-girl": {
      "voice-name": "Lively Girl",
      "voice-description": "女，英文音色，亲和感，有活力",
      "recommended_scene": "有声书、视频配音、语音助手"
    },
    "livelybreezy-female": {
      "voice-name": "活力轻快",
      "voice-description": "女，音色具有感染力、说服力和亲和力，有活力",
      "recommended_scene": "情感陪伴、教育与培训、营销"
    },
    "magnetic-voiced-male": {
      "voice-name": "Magnetic-voiced Male",
      "voice-description": "男，英文音色，强烈的沉稳厚重感",
      "recommended_scene": "有声书、视频配音"
    },
    "soft-spoken-gentleman": {
      "voice-name": "Soft-spoken Gentleman",
      "voice-description": "男，英文音色，沉稳温柔，给人安全感",
      "recommended_scene": "情感陪伴、有声书"
    },
    "vibrant-youth": {
      "voice-name": "Vibrant Youth",
      "voice-description": "男，英文音色，温柔亲和",
      "recommended_scene": "有声书、视频配音、语音助手"
    },
    "zixinnansheng": {
      "voice-name": "自信男声",
      "voice-description": "男，真诚亲和，有活力",
      "recommended_scene": "有声书、情感陪伴、教育与培训、营销"
    }
  }
}

voice-description and recommended_scene are returned in Chinese as-is from the service, and voice-name is Chinese for voices that do not have an English name. Use the voice ID (the key under voices-details) when calling the TTS API. See the table below for an English reference.

Voice reference

The same seven voices in English, in the order returned by the API. Four of them (lively-girl, magnetic-voiced-male, soft-spoken-gentleman, vibrant-youth) are purpose-built English voices.

Voice ID	Voice	Recommended use cases
`elegantgentle-female`	Elegant, gentle female voice — sincere and reassuring	Customer service, voice-over, education, emotional companionship
`lively-girl`	Bright, lively female voice (English)	Audiobook, video dubbing, voice assistant
`livelybreezy-female`	Light, breezy female voice — engaging and persuasive	Emotional companionship, education, marketing
`magnetic-voiced-male`	Deep, magnetic male voice (English)	Audiobook, video dubbing
`soft-spoken-gentleman`	Calm, gentle male voice (English)	Emotional companionship, audiobook
`vibrant-youth`	Warm, approachable young male voice (English)	Audiobook, video dubbing, voice assistant
`zixinnansheng`	Confident male voice — sincere, warm, energetic	Audiobook, emotional companionship, education, marketing

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.
Only the voice IDs returned by this endpoint (or one of your own cloned voice IDs) are accepted by the TTS and Realtime APIs. Any other value is rejected with 400 voice_id_invalid. To list your cloned voices, see List cloned voices.

Chat

Realtime

Audio

Image

Models

Files

Account

Tool Call

Token Count

Error Codes

Overview

Request

Method

Endpoint

Query parameters

Request example

Response

Format

Response fields

Response example

Voice reference

Notes

​Overview

​Request

​Method

​Endpoint

​Query parameters

​Request example

​Response

​Format

​Response fields

​Response example

​Voice reference

​Notes

Overview

Request

Method

Endpoint

Query parameters

Request example

Response

Format

Response fields

Response example

Voice reference

Notes