cnAPI 语音接口：STT 与 TTS

音频（Audio）

cnAPI 提供两条彼此独立的语音能力。请根据输入和输出方向选择接口，不要混用模型名或请求格式。

当前上线状态（2026-08-11）

STT 已在生产可用。TTS 适配器已经部署，真实 WAV 请求也已通过生产验证，但公开模型价格尚未配置。 正式价格启用前，普通 API Key 会收到 400 model_price_error；目前请勿把 TTS 接入生产业务。

能力总览

两条能力的共同基础地址与鉴权方式如下：

Base URL: https://cnapi.vip/v1
Authorization: Bearer $API_KEY

语音转文字（STT）

推荐请求

使用 multipart/form-data 上传音频。让 cURL 或 SDK 自动生成 multipart boundary，不要手写 Content-Type: multipart/form-data 请求头。

curl --fail-with-body https://cnapi.vip/v1/audio/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./meeting.wav;type=audio/wav" \
  -F "model=gemini-2.5-stt" \
  -F "prompt=这是一段产品评审会议录音，请准确识别人名和技术术语"

成功响应固定为 JSON：

{
  "text": "这里是识别后的完整文字。"
}

模型选择

以下名称是 cnAPI 对外模型名，四个模型均已完成生产真实请求验证。不要改填内部上游模型名。

cnAPI 不承诺不同模型在所有语言、口音和噪声环境下的固定准确率排序。正式选型前，请用自己的真实音频做对比测试。

请求字段

当前仅保证基础 JSON 文本响应。请不要依赖 language、response_format、temperature、分段时间戳、逐词时间戳或说话人分离字段。

文件格式

文件扩展名必须与真实编码一致。WAV 已完成端到端生产回归；遇到不兼容的编码器或容器时，优先转成标准 PCM WAV 后重试。

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_cnAPI_KEY",
    base_url="https://cnapi.vip/v1",
)

with open("meeting.wav", "rb") as audio_file:
    result = client.audio.transcriptions.create(
        model="gemini-2.5-stt",
        file=audio_file,
        prompt="产品评审会议；术语包括 Vertex AI、cnAPI、cnAPI",
    )

print(result.text)

STT 能力边界

• 单次同步上传，文件不超过 15 MB。
• 自动识别输入语言并返回原语言文字；不提供 /audio/translations 英译接口。
• 不支持 WebSocket、实时双向流、分片上传、异步长音频任务。
• 不提供说话人分离、逐词对齐、SRT/VTT 或时间戳输出。
• STT 与下方 TTS 是不同后端；STT 模型不能用于 /audio/speech。

文字转语音（TTS）

等待公开价格

下列协议已经部署，并通过真实 WAV 生产回归。gemini-3.1-tts 正式价格配置前，普通 API Key 仍会收到 400 model_price_error。

请求示例

curl --fail-with-body https://cnapi.vip/v1/audio/speech \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-tts",
    "input": "欢迎使用 cnAPI 语音合成服务。",
    "voice": "Kore",
    "response_format": "wav",
    "instructions": "使用自然、沉稳、清晰的普通话播报，数字要读得准确"
  }' \
  --output speech.wav

成功响应是音频二进制，不是 JSON。客户端必须把响应体直接写入文件或音频缓冲区。

请求字段

input、instructions 和适配器生成的语速指令合并后不得超过 8000 字节。中文通常每个汉字占 3 个 UTF-8 字节，请按字节而不是字符估算。

输出格式

本站的 Vertex TTS 适配层目前不提供 MP3、Opus、AAC 或 FLAC。Google 上游其他 API 支持的格式不等于 cnAPI /audio/speech 已支持的格式。

可用音色

请使用下列官方预设名的准确拼写。完整音色与语言更新以 Google Gemini-TTS 官方文档 为准。

建议先用短句试听 2–3 个音色，再固定到生产配置。音色名不能使用 OpenAI 的 alloy、nova、shimmer 等名称。

风格和语速控制

Gemini TTS 的主要控制方式是自然语言 instructions。例如：

{
  "instructions": "像专业纪录片旁白一样，语气克制、有温度，专有名词逐字清晰发音"
}

speed 会被适配器转成类似 “Speak at 1.2x normal speed” 的指令，因此模型会尽量遵循，但结果不是后期变速器的数学精确倍率。要求稳定风格时，优先写清楚 instructions，并用真实文案回归。

Python（HTTPX）

import httpx

payload = {
    "model": "gemini-3.1-tts",
    "input": "欢迎使用 cnAPI 语音合成服务。",
    "voice": "Kore",
    "response_format": "wav",
    "instructions": "自然、沉稳、清晰的普通话播报",
}

response = httpx.post(
    "https://cnapi.vip/v1/audio/speech",
    headers={"Authorization": "Bearer YOUR_cnAPI_KEY"},
    json=payload,
    timeout=120,
)
response.raise_for_status()

with open("speech.wav", "wb") as audio_file:
    audio_file.write(response.content)

TTS 能力边界

• 当前 /audio/speech 只支持单音色合成，不支持多说话人对话编排。
• 不支持 SSE、WebSocket 或流式音频返回。
• 不支持自定义克隆音色、参考音频或 SSML。
• 不支持 mp3、opus、aac、flac 输出。
• 音色、语言和表达效果由 Gemini TTS 模型决定；cnAPI 只保证本文列出的接口转换与输出封装。

常见错误

生产代码应记录 HTTP 状态码和 cnAPI 返回的请求 ID，但不要记录 API Key、完整私密音频或敏感转录内容。