PUBLIC API · MULTILINGUAL TTS

多语言语音合成 API

为服务端、内容生成、语音助手和实时播报提供租户隔离的语音合成能力，支持七语合成、跨语言音色克隆、HTTP/WebSocket 流式输出和签名音频下载。

开始接入下载完整文档

Base URLs

v4 · https://audio-api2.sonari.dev

v3 · https://audio-api.sonari.dev

新项目建议使用 v4；存量 CosyVoice 集成继续使用 v3。

协议HTTPS / WSSTLS 加密传输

鉴权Bearer API Key租户、Scope 与配额隔离

语言7 Languageszh / en / tl / id / th / ar / hi

流式音频PCM16 LE24 kHz 或 48 kHz

鉴权

业务接口使用租户 API Key，不使用管理台账号密码。

安全提示API Key 仅在签发时显示一次。请放在服务端 Secret，不要写进浏览器、移动端包、Git 或日志。

HTTP Header

Authorization: Bearer cosy_YOUR_API_KEY

v4 Key 可分别授予 synthesize、voices:read、voices:write Scope。Key 缺失、无效、已吊销或租户停用时返回 401；Scope 不足返回 403。

一分钟快速开始

调用 v4 同步合成并获取可下载的音频地址。

1
获取 API Key
由 Sonari 管理员创建租户并签发 cosy_...。
2
选择文本与语言
文本最多 2000 字符；新项目建议明确传入 lang。
3
发送请求
响应中的 audio_url 使用同一 Bearer Key 下载。

curl · v4

curl --request POST "https://audio-api2.sonari.dev/v1/syntheses" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "你好，欢迎使用 Sonari 多语言语音合成。",
    "lang": "zh",
    "output_sample_rate": 24000,
    "share_ttl_seconds": 3600
  }'

200 OK

{
  "data": {
    "id": "abc123",
    "audio_url": "https://audio-api2.sonari.dev/v1/syntheses/abc123/audio",
    "signed_audio_url": "https://audio-api2.sonari.dev/v1/syntheses/abc123/audio?exp=...&sig=...",
    "sample_rate": 24000,
    "audio_s": 2.6,
    "first_chunk_ms": 72,
    "engine": "sonari-3"
  }
}

版本选择

两个版本使用独立域名、模型和 Key 管理。

能力	v4 · 推荐新项目	v3 · 存量兼容
Base URL	`audio-api2.sonari.dev`	`audio-api.sonari.dev`
引擎	sonari-3 / VoxCPM2	CosyVoice 2
语言	七语与跨语言克隆	存量业务兼容
Key	租户、Scope、每日配额	租户 Key
特色	HTTP + WS 流式、签名 URL	指令语气、音色技能

不可混用v3 Key、音色和接口字段不要直接假设可在 v4 使用；迁移时请按本页示例重新验证。

语言支持

GET/v1/langs · v4

zh中文GA · 克隆 / 流式

enEnglishGA · Clone / Stream

tlFilipinoBeta · Clone / Stream

idIndonesianBeta · Clone / Stream

thไทยBeta · Clone / Stream

arالعربيةBeta · Clone / Stream

hiहिन्दीBeta · Clone / Stream

curl

curl "https://audio-api2.sonari.dev/v1/langs" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY"

音色管理

列出系统音色，或上传参考音频创建租户隔离音色。

列出音色 · curl

curl "https://audio-api2.sonari.dev/v1/voices" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY"

上传音色 · curl

curl --request POST "https://audio-api2.sonari.dev/v1/voices" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY" \
  --form "audio=@reference.wav" \
  --form "voice_slug=my_brand_voice" \
  --form "prompt_text=这是参考音频的精确转写。"

上传音色 · Python

import requests

with open("reference.wav", "rb") as audio:
    response = requests.post(
        "https://audio-api2.sonari.dev/v1/voices",
        headers={"Authorization": "Bearer cosy_YOUR_API_KEY"},
        files={"audio": audio},
        data={
            "voice_slug": "my_brand_voice",
            "prompt_text": "这是参考音频的精确转写。",
        },
        timeout=60,
    )
response.raise_for_status()
print(response.json()["data"])

参考音频建议使用 3–15 秒、单人、无背景音乐的清晰音频，并提供精确转写。租户只能修改和删除自己的音色。

同步合成

POST/v1/syntheses

字段	必填	默认	说明
`text`	是	—	1–2000 字符。
`lang`	否	自动	建议传入 v4 语言代码。
`voice_slug`	否	默认音色	系统或当前租户可见音色。
`output_sample_rate`	否	24000	`24000` 或 `48000`。
`share_ttl_seconds`	否	无	60 秒至 30 天，返回签名 URL。

Python · requests

import requests

response = requests.post(
    "https://audio-api2.sonari.dev/v1/syntheses",
    headers={
        "Authorization": "Bearer cosy_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "text": "Selamat malam semuanya.",
        "lang": "id",
        "voice_slug": "my_brand_voice",
        "output_sample_rate": 24000,
    },
    timeout=120,
)
response.raise_for_status()
result = response.json()["data"]
print(result["audio_url"])

Node.js · fetch

const response = await fetch(
  "https://audio-api2.sonari.dev/v1/syntheses",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer cosy_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      text: "สวัสดีครับ ยินดีต้อนรับ",
      lang: "th",
      output_sample_rate: 24000
    })
  }
);
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).data);

v3 差异v3 同一路径支持 speed、save 和 instruct_text；完整字段请下载 v3 Markdown。

HTTP 流式合成

POST/v1/syntheses/stream_http · v4

响应体是裸 PCM s16le 单声道音频，适合服务端低延迟播放或实时转发。不是 WAV 文件。

curl → PCM

curl --no-buffer --request POST \
  "https://audio-api2.sonari.dev/v1/syntheses/stream_http" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text":"Streaming speech from Sonari.","lang":"en","sample_rate":24000}' \
  --output speech.pcm

# 可选：转换为 WAV
ffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wav

WebSocket 流式合成

WS/v1/syntheses/stream

1连接WSS

→

2首帧 JSONtoken / text / lang

→

3二进制帧PCM16 LE

→

4done性能元数据

Browser WebSocket

const ws = new WebSocket(
  "wss://audio-api2.sonari.dev/v1/syntheses/stream"
);
ws.binaryType = "arraybuffer";

ws.onopen = () => ws.send(JSON.stringify({
  token: "cosy_YOUR_API_KEY",
  text: "Magandang gabi sa inyong lahat.",
  lang: "tl",
  voice_slug: "my_brand_voice",
  sample_rate: 24000
}));

ws.onmessage = (event) => {
  if (typeof event.data === "string") {
    const message = JSON.parse(event.data);
    console.log(message.type, message);
    return;
  }
  // event.data 是 PCM16 LE 音频块，可交给 AudioWorklet 播放。
  consumePcmChunk(event.data, 24000);
};

浏览器安全示例展示协议用法。生产环境不要把长期 API Key 暴露到公开网页；应由自己的后端建立连接或签发短期访问凭证。

音频下载与分享

GET/v1/syntheses/{id}/audio

Bearer 下载

curl "https://audio-api2.sonari.dev/v1/syntheses/abc123/audio" \
  --header "Authorization: Bearer cosy_YOUR_API_KEY" \
  --output speech.wav

如果合成请求传入 share_ttl_seconds，响应会包含无需 Header 的 signed_audio_url。签名 URL 到期后失效，适合浏览器播放或临时分享。

配额与错误处理

v4 按租户共享每日合成配额，并按 Key 记录调用量。

状态码	说明	客户端处理
`400`	文本、语言、采样率或上传字段无效。	修正请求，不重试原参数。
`401`	Key 无效、已吊销或租户停用。	停止请求并检查 Secret。
`403`	Key 缺少所需 Scope。	由管理员补充权限或更换 Key。
`404`	音色或音频不存在，或不属于当前租户。	核对资源 ID。
`409`	音色名称冲突或超过音色上限。	更换 slug 或清理旧音色。
`429`	租户每日合成配额已用完。	等待次日或联系管理员调整。
`503`	模型、鉴权或签名服务暂不可用。	指数退避后重试。

Error JSON

{
  "detail": "daily synthesis quota exceeded"
}

接口清单

以下为主要公开业务接口。

GETv4 /v1/status服务状态需鉴权

GETv4 /v1/me当前租户与 Scope需鉴权

GETv4 /v1/langs语言能力需鉴权

GETv3/v4 /v1/voices音色列表需鉴权

POSTv3/v4 /v1/voices上传克隆音色需写入 Scope

POSTv3/v4 /v1/syntheses同步合成需鉴权

POSTv4 /v1/syntheses/stream_httpHTTP PCM 流式合成需鉴权

WSv3/v4 /v1/syntheses/streamWebSocket 流式合成首帧传 Key

GETv3/v4 /v1/syntheses/{id}/audio音频下载Bearer 或签名 URL

POSTv3 /v1/voice-skills/apply音色技能转换v3 专属

准备开始？

获取租户 API Key 后即可接入

下载完整文档保存到项目，或分别查看 v3 / v4 详细字段说明。

下载整合文档 v4 Markdown v3 Markdown