CosyVoice HTTP API - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

The HTTP API for CosyVoice non-real-time speech synthesis, including non-streaming and SSE requests, request parameters, and response fields.

Endpoints

Replace YOUR_WORKSPACE_ID with the workspace ID for the region and use an API key for the same region.

China (Beijing)

POST https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

Request headers

Parameter	Type	Required	Description
`Authorization`	`string`	Required	The authentication token in the format `Bearer <your_api_key>`.
`Content-Type`	`string`	Required	Set to `application/json`.
`X-DashScope-SSE`	`string`	Optional	Set to `enable` for streaming output. If omitted, the complete result is returned.

Examples

Non-streaming

curl -X POST "https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "我家的后面有一个很大的花园。",
    "voice": "longanyang",
    "format": "wav",
    "sample_rate": 24000
  }
}'

Streaming

curl --no-buffer -X POST "https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-SSE: enable" \
  -d '{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "我家的后面有一个很大的花园。",
    "voice": "longanyang",
    "format": "wav",
    "sample_rate": 24000
  }
}'

NoteAn SSE event may contain multiple data: lines. Combine all data: lines in the event before parsing JSON. Base64-decode and concatenate audio chunks in event order. The final frame has output.finish_reason=stop and returns the complete audio URL.

Request body

Parameter	Type	Required	Default	Description
`model`	`string`	Required	—	The speech synthesis model ID. See Non-real-time speech synthesis for models and regions.
`input`	`object`	Required	—	The input parameters.
`input.text`	`string`	Required	—	Text to synthesize. Set `enable_ssml=true` for SSML input. LaTeX input requires no additional setting. See SSML and LaTeX for supported models, tags, and syntax.
`input.voice`	`string`	Required	—	The voice ID. For system voices, see the voice list. Create a custom voice with voice cloning or voice design, then synthesize with its bound target model.
`input.format`	`string`	Optional	`mp3`	Audio encoding. Valid values: `mp3`, `pcm`, `wav`, and `opus`.
`input.sample_rate`	`integer`	Optional	22050	Audio sample rate in Hz. Valid values: 8000, 12000, 16000, 22050, 24000, 44100, and 48000. With `format=opus`, only 8000, 12000, 16000, 24000, and 48000 are supported.
`input.volume`	`integer`	Optional	50	Volume. Range: [0, 100].
`input.rate`	`float`	Optional	1.0	Speaking rate. Range: [0.5, 2.0].
`input.bit_rate`	`integer`	Optional	32	Audio bitrate in kbps. Range: [6, 510]. Applies only when `format=opus`.
`input.pitch`	`float`	Optional	1.0	Pitch. Range: [0.5, 2.0].
`input.enable_ssml`	`boolean`	Optional	—	Whether to enable SSML. See Usage limits for model, voice, and interface restrictions.
`input.word_timestamp_enabled`	`boolean`	Optional	`false`	Whether to return word-level timestamps. Streaming output only. Supports cloned voices of cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, and cosyvoice-v2, and system voices marked as supported in the voice list. Cloned voices of other models are not supported.
`input.seed`	`integer`	Optional	0	Random seed. Range: [0, 65535]. With the same model version, text, voice, and other parameters, the same seed reproduces the same synthesis result.
`input.language_hints`	`array[string]`	Optional	—	The target synthesis language. Only the first array element is processed. This is independent of the source language of a cloning sample. Set it for unexpected pronunciation of numbers, abbreviations, symbols, or less common languages. Language codes are listed below. For the cloning source language, see the voice cloning API.
`input.instruction`	`string`	Optional	—	An instruction controlling dialect, emotion, or role. See Instruction control for model and voice support and usage.
`input.enable_aigc_tag`	`boolean`	Optional	`false`	Whether to embed an invisible AIGC identifier in WAV, MP3, or Opus audio. Supported only by cosyvoice-v3-flash, cosyvoice-v3-plus, and cosyvoice-v2.
`input.aigc_propagator`	`string`	Optional	Alibaba Cloud UID	The `ContentPropagator` field of the identifier, identifying the distributor. Applies only with `enable_aigc_tag=true`. Supported only by cosyvoice-v3-flash, cosyvoice-v3-plus, and cosyvoice-v2.
`input.aigc_propagate_id`	`string`	Optional	Request ID of this request	The `PropagateID` field of the identifier, identifying this distribution operation. Applies only with `enable_aigc_tag=true`. Supported only by cosyvoice-v3-flash, cosyvoice-v3-plus, and cosyvoice-v2.
`input.hot_fix`	`object`	Optional	—	Text hotfix configuration. `pronunciation` customizes pronunciation for specified words. `replace` replaces specified text before synthesis. Not supported by cosyvoice-v2.
`input.enable_markdown_filter`	`boolean`	Optional	`false`	Whether to filter Markdown markers before synthesis. Supported only for cloned voices of cosyvoice-v3-flash.

Language codes

zh: Chinese
en: English
fr: French
de: German
ja: Japanese
ko: Korean
ru: Russian
pt: Portuguese
th: Thai
id: Indonesian
vi: Vietnamese
es: Spanish
it: Italian
ms: Malay
fil: Filipino
ar: Arabic

Example text hotfix configuration:

{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}

Response body

Parameter	Type	Description
`request_id`	`string`	The unique request identifier.
`output`	`object`	The model output.
`output.finish_reason`	`string`	The stop reason. `null` means synthesis is in progress; `stop` means synthesis is complete.
`output.type`	`string`	Returned only for streaming output. `sentence-begin` marks the start of a sentence; `sentence-synthesis` marks an audio chunk, with multiple chunks possible per sentence; `sentence-end` marks the end and includes usage. Audio chunks and data frames correspond one to one. Append chunks to the same file in order.
`output.original_text`	`string`	A sentence segmented from the input text. May be absent for the final sentence.
`output.sentence`	`object`	Sentence information.
`output.sentence.index`	`integer`	The sentence index, starting at 0.
`output.sentence.words`	`array`	Words in the sentence and their timestamps.
`output.sentence.words[].text`	`string`	A word or character.
`output.sentence.words[].begin_index`	`integer`	The start position in the sentence, starting at 0.
`output.sentence.words[].end_index`	`integer`	The end position in the sentence, starting at 1.
`output.sentence.words[].begin_time`	`integer`	The audio start timestamp of the word, in milliseconds.
`output.sentence.words[].end_time`	`integer`	The audio end timestamp of the word, in milliseconds.
`output.audio`	`object`	The synthesized audio.
`output.audio.data`	`string`	A Base64 audio chunk for streaming output. Empty for non-streaming output.
`output.audio.url`	`string`	The complete audio file URL, valid for 24 hours.
`output.audio.id`	`string`	The synthesized audio identifier.
`output.audio.expires_at`	`integer`	The expiry timestamp of `url`.
`usage`	`object`	Usage information.
`usage.characters`	`integer`	Cumulative billable characters.

Non-streaming

{
  "output": {
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570,
      "url": "https://example.com/output.wav"
    },
    "finish_reason": "stop"
  },
  "usage": {
    "characters": 27
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Streaming

Intermediate result:

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "finish_reason": null,
    "type": "sentence-begin",
    "original_text": "我家的后面有一个很大的花园。",
    "sentence": {
      "index": 0,
      "words": []
    },
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570
    }
  }
}

Final result:

{
  "output": {
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570,
      "url": "https://example.com/output.wav"
    },
    "finish_reason": "stop"
  },
  "usage": {
    "characters": 27
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}