Alibaba: CosyVoice v3 Plus (Text to Audio) API Reference

About

CosyVoice v3 Plus is Alibaba Cloud Model Studio's higher-quality CosyVoice v3 model, served from the China (Beijing) region. System voices accept instructions in the fixed format listed with each voice; cloned and designed voices do not support instructions. Infron serves it through the OpenAI-compatible POST /v1/audio/speech endpoint with mp3, wav, pcm or opus output, adjustable sample rate, speed, pitch and volume, and optional streaming. Requests are billed per character (a Chinese character counts as 2).

1. Calling the API

Setup your API Key

To begin using Infron, create an account and generate your API Key.

export INFRON_KEY="YOUR_API_KEY"

Submit a request

Send JSON to POST https://llm.onerouter.pro/v1/audio/speech with your Infron API key. The request and response follow the OpenAI speech API, so the OpenAI SDKs work with the base URL https://llm.onerouter.pro/v1. The examples use the Alibaba Cloud voice longanyang. Replace YOUR_API_KEY with your key.

curl

curl https://llm.onerouter.pro/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/cosyvoice-v3-plus/text-to-audio",
    "voice": "longanyang",
    "input": "Hello! Welcome to Infron.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://llm.onerouter.pro/v1",
    api_key="YOUR_API_KEY",
)

with client.audio.speech.with_streaming_response.create(
    model="alibaba/cosyvoice-v3-plus/text-to-audio",
    voice="longanyang",
    input="Hello! Welcome to Infron.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

TypeScript (OpenAI SDK)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://llm.onerouter.pro/v1",
  apiKey: "YOUR_API_KEY",
});

const response = await client.audio.speech.create({
  model: "alibaba/cosyvoice-v3-plus/text-to-audio",
  voice: "longanyang",
  input: "Hello! Welcome to Infron.",
  response_format: "mp3",
});
fs.writeFileSync("speech.mp3", Buffer.from(await response.arrayBuffer()));

Response

A successful request returns HTTP 200 with the audio file as the body, not JSON. Content-Type follows response_format: audio/mpeg for mp3, audio/wav for wav, audio/pcm for pcm, audio/opus for opus. The examples above save it as speech.mp3.

Streaming

Add "stream_format": "sse" to receive Server-Sent Events while the audio is generated. Each speech.audio.delta event carries the next base64 chunk of the audio in response_format; decode the chunks and append them in order. The stream ends with a speech.audio.done event that reports usage.

curl https://llm.onerouter.pro/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/cosyvoice-v3-plus/text-to-audio",
    "voice": "longanyang",
    "input": "Hello! Welcome to Infron.",
    "response_format": "mp3",
    "stream_format": "sse"
  }' \
  --no-buffer
data: {"type":"speech.audio.delta","audio":"<base64 audio chunk>"}

data: {"type":"speech.audio.delta","audio":"<base64 audio chunk>"}

data: {"type":"speech.audio.done","usage":{"input_tokens":25,"output_tokens":0,"total_tokens":25}}

In this example input_tokens is the billable character count of the input.

Routing and usage

This model is served by alibaba/cn (Alibaba Cloud Beijing). Billing uses Alibaba Cloud's billable character count (a Chinese character counts as 2, SSML tags are not counted). The audio response carries no usage; with streaming, speech.audio.done reports the billable count as usage.input_tokens.

Errors

Parameters this model does not accept are rejected with HTTP 400 before the request is sent to Alibaba Cloud, and nothing is charged. error.message explains the problem and ends with the request ID:

{
  "error": {
    "message": "voice is required (DashScope voice id) (request id: 20261111221810441285700pZnPkvCJ)",
    "type": "infron_ai_error",
    "param": "",
    "code": "invalid_request_error"
  }
}

Errors reported by Alibaba Cloud, such as an unknown voice ID, are returned with Alibaba Cloud's message. If a stream fails after it has started, an error event is sent instead of speech.audio.done.

2. Schema

Input

ParameterTypeRequiredDefaultRangeDescription
modelstringYes--alibaba/cosyvoice-v3-plus/text-to-audioModel ID.
inputstringYes----Text to synthesize. SSML needs enable_ssml: true.
voicestringYes----Alibaba Cloud voice ID, for example longanyang. Use a system voice listed for this model in Model Studio, or a cloned or designed voice bound to it.
response_formatstringNomp3mp3, wav, pcm, opusAudio format.
speednumberNo10.5 to 2.0Speaking rate. Sent as rate.
instructionsstringNo--Up to 100 characters (a Chinese character counts as 2)For system voices only, the fixed instruction format listed with the voice; cloned and designed voices do not support it. Sent as instruction.
languagestringNo--zh, en, fr, de, ja, ko, ru, pt, th, id, vi, es, it, ms, fil, arLanguage hint. Sent as the first element of language_hints.
sample_rateintegerNo220508000, 12000, 16000, 22050, 24000, 44100, 48000; opus: 8000, 12000, 16000, 24000, 48000Output sample rate.
bit_rateintegerNo326 to 510 (kbps)Opus bitrate; only with response_format opus.
stream_formatstringNoaudioaudio, ssesse streams Server-Sent Events (see Streaming).

Alibaba Cloud fields

These fields are not part of the OpenAI speech API. Put them at the top level of the JSON body; with the OpenAI Python SDK pass them in extra_body.

ParameterTypeRequiredDefaultRangeDescription
volumeintegerNo500 to 100Volume.
pitchnumberNo10.5 to 2.0Pitch multiplier.
seedintegerNo00 to 65535Random seed for synthesis.
enable_ssmlbooleanNo--true, falseTreat input as SSML.
language_hintsarrayNo--One language codeLanguage hint array; only the first element is used. Replaces language.
hot_fixobjectNo----Pronunciation and replacement fixes: pronunciation (word to pinyin) and replace (text to text).

Unsupported fields

FieldBehavior
text_normalizationIgnored.
Other fieldsNot forwarded to Alibaba Cloud (for example word_timestamp_enabled and the AIGC tag fields).

Output

ParameterTypeRangeDescription
Response bodybinarymp3, wav, pcm, opusThe audio file in response_format (without stream_format=sse).
Content-Type headerstringaudio/mpeg, audio/wav, audio/pcm, audio/opusMIME type of the audio.
typestringspeech.audio.delta, speech.audio.done, errorStreaming event type.
audiostringBase64Next chunk of the audio (speech.audio.delta).
usage.input_tokensintegerNon-negativeBillable count of the input (speech.audio.done).
usage.output_tokensinteger0Always 0 for this model.
usage.total_tokensintegerNon-negativeSum of input and output.
errorobject--message, type and code of a failure (error event).

3. Detailed Pricing

ModelEndpointBilling unitPrice
Alibaba: CosyVoice v3 Plusalibaba/cnPer 1M characters$28.6706

Prices are in USD. Billing uses Alibaba Cloud's billable character count (a Chinese character counts as 2, SSML tags are not counted).

Sources: CosyVoice HTTP API, Speech synthesis overview, Pricing.