Non-real-time speech synthesis CosyVoice Python SDK reference

Use the CosyVoice non-real-time speech synthesis Python SDK to generate audio from text in non-streaming or streaming mode.

Prerequisites

• Obtain an API key completed, and API key configured as an environment variable.
• DashScope Python SDK 2.0.1 or later installed. Install the latest version.

Core resource (client.audio.tts.http)

Resource path: client.audio.tts.http

Description: HTTP-based speech synthesis. The synthesize method performs a non-streaming call (audio is returned as a URL), and the stream method performs a streaming call (audio data is returned chunk by chunk over SSE).

synthesize() / stream() - speech synthesis

Method signature:

def synthesize(self,
               text: str,
               *,
               model: str,
               voice: str,
               format: str = None,
               sample_rate: int = None,
               language_type: str = None,
               parameters: Dict = None,
               extra_input: Dict = None,
               timeout: float = None,
               ...) -> HttpSynthesis

def stream(self,
           text: str,
           *,
           model: str,
           voice: str,
           format: str = None,
           sample_rate: int = None,
           language_type: str = None,
           parameters: Dict = None,
           extra_input: Dict = None,
           timeout: float = None,
           ...) -> HttpSynthesisStream

Parameters (model, text, voice, format, and sample_rate are named parameters; pass other input parameters via the extra_input dictionary):

"hot_fix": {
  "pronunciation": [
    {"weather": "tian1 qi4"}
  ],
  "replace": [
    {"today": "gold day"}
  ]
}

Return values:

• Non-streaming mode (synthesize): Returns a result object (HttpSynthesis) with the following properties:

  • audio_url: The audio download URL (expires after a limited time).
  • audio_id: The audio ID.
  • expires_at: The URL expiration time.
  • usage: Usage information.

• Streaming mode (stream): Returns an iterator (HttpSynthesisStream). Each element (HttpSynthesisChunk) contains the following properties:

  • audio: The audio binary data (bytes) for the current chunk, already decoded.
  • sentence: Sentence-level synthesis information (if available).
  • is_final: Indicates whether this is the final chunk (finish_reason == "stop").
  • usage: Usage information (carried on the final chunk).
  ImportantIn streaming mode, the final chunk (is_final is True) additionally carries audio_url (the download URL of the complete audio), audio_id, and expires_at. When concatenating audio from the iterator, write only chunks with non-empty chunk.audio to avoid playing the same content twice.

Sample code

The following examples show non-streaming and streaming calls to CosyVoice speech synthesis. Set the DASHSCOPE_API_KEY environment variable before running the code.

# -*- coding: utf-8 -*-
import os
import dashscope

# The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. Regions differ in configuration.
client = dashscope.Client(
    # If the API key is not configured as an environment variable, replace the next line with your API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Non-streaming call, returns an audio URL
result = client.audio.tts.http.synthesize(
    "Today is a great day to build products that people love!",
    model="cosyvoice-v3-plus",  # When switching models, you must also switch to the corresponding voice for that version
    voice="longanyang",
    format="wav",
    sample_rate=24000,
)

# Get the audio URL
print(f"Audio URL: {result.audio_url}")
print(f"Audio ID: {result.audio_id}")
if result.audio_id:
    request_id = result.audio_id.removeprefix("audio_")
    print(f"Request ID: {request_id}")
print(f"Expiration time: {result.expires_at}")

# -*- coding: utf-8 -*-
import os
import dashscope

# The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. Regions differ in configuration.
client = dashscope.Client(
    # If the API key is not configured as an environment variable, replace the next line with your API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Streaming call, returns audio data chunk by chunk
stream_result = client.audio.tts.http.stream(
    "Today is a great day to build products that people love!",
    model="cosyvoice-v3-plus",  # When switching models, you must also switch to the corresponding voice for that version
    voice="longanyang",
    format="wav",
    sample_rate=24000,
)

# Iterate over the iterator, receiving audio data chunk by chunk
audio_chunks = []
for chunk in stream_result:
    if chunk.audio:  # Write only non-empty audio chunks to avoid duplicated audio
        audio_chunks.append(chunk.audio)
        print(f"Received audio data chunk, size: {len(chunk.audio)} bytes")

    if chunk.sentence:
        print(f"Sentence info: {chunk.sentence}")

    if chunk.is_final:  # Final chunk: carries the download URL of the complete audio and usage information
        print(f"Audio ID: {chunk.audio_id}")
        request_id = chunk.audio_id.removeprefix("audio_")
        print(f"Request ID: {request_id}")
        print(f"Audio URL: {chunk.audio_url}")
        print(f"Usage: {chunk.usage}")

# Merge all audio data and save
full_audio = b"".join(audio_chunks)
print(f"Total audio size: {len(full_audio)} bytes")

with open("output.wav", "wb") as f:
    f.write(full_audio)
print("Audio saved to output.wav")