音频与语音

在问 OneAPI 同时提供 OpenAI 兼容的语音转写、语音合成接口，以及 Gemini 原生语音生成接口。

能力	端点	模型
语音转写	POST /v1/audio/transcriptions	sencevoice-small、grok-transcribe
语音合成	POST /v1/audio/speech	grok-tts
Gemini 原生语音生成	POST /v1beta/models/{model}:generateContent	Gemini TTS 模型

语音转写

端点: POST https://oneapi.zaiwenai.com/v1/audio/transcriptions

与 OpenAI Audio Transcriptions 接口兼容，将音频文件转写为文本。

请求参数

参数	类型	必填	说明
file	file	是	音频文件
model	string	是	sencevoice-small 或 grok-transcribe
language	string	否	音频语言代码，如 zh、en；省略时由模型自动识别
response_format	string	否	json（默认）或 text

Curl 示例

curl https://oneapi.zaiwenai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=grok-transcribe"

OpenAI Python SDK 示例

from openai import OpenAI

client = OpenAI(
    base_url="https://oneapi.zaiwenai.com/v1",
    api_key="$YOUR_API_KEY",
)

with open("audio.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="grok-transcribe",
        file=audio_file,
    )

print(transcript.text)

设置 response_format=text 时，响应体直接返回纯文本；默认 json 格式如下：

{
  "text": "转写的文本内容"
}

语音转写按输入音频的实际时长计费，计费时长向上取整到秒。音频超过所选模型配置的最大时长时，请求会被拒绝。

OpenAI 兼容语音合成

端点: POST https://oneapi.zaiwenai.com/v1/audio/speech

grok-tts 与 OpenAI Audio Speech 请求格式兼容，响应体是可直接保存或播放的二进制音频。

请求参数

参数	类型	必填	说明
model	string	是	当前使用 grok-tts
input	string	是	需要合成的文本，不能为空
voice	string	否	音色 ID，默认 eve
response_format	string	否	mp3（默认）或 wav
speed	number	否	当前仅支持 1.0

可用音色

所有 Grok TTS 音色均为多语言音色。

类型	音色 ID
女声	ara、carina、celeste、eve、iris、luna、ursa
男声	altair、atlas、castor、cosmo、helios、helix、kepler、leo、lumen、lux、naksh、orion、perseus、rex、rigel、sal、sirius、zagan、zenith

Curl 示例

curl https://oneapi.zaiwenai.com/v1/audio/speech \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-tts",
    "input": "你好，欢迎使用在问。",
    "voice": "luna",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Speech Tags

grok-tts 支持直接在 input 文本中插入 Speech Tags，用于控制停顿、笑声、呼吸、音量、语速和表达风格，不需要额外请求参数。

即时标签放在需要发生效果的位置：

类别	标签
停顿	[pause]、[long-pause]、[hum-tune]
笑声与哭声	[laugh]、[chuckle]、[giggle]、[cry]
口腔音	[tsk]、[tongue-click]、[lip-smack]
呼吸	[breath]、[inhale]、[exhale]、[sigh]

包裹标签用于改变一整段文字的表达方式：

类别	标签
音量与强度	<soft>、<whisper>、<loud>、<build-intensity>、<decrease-intensity>
音高与语速	<higher-pitch>、<lower-pitch>、<slow>、<fast>
表达风格	<sing-song>、<singing>、<laugh-speak>、<emphasis>

包裹标签必须使用匹配的结束标签，例如：

{
  "model": "grok-tts",
  "input": "事情是这样的。[pause] <whisper>接下来这句话是秘密。</whisper> [laugh] 现在你知道了。",
  "voice": "eve",
  "response_format": "mp3"
}

建议把标签放在自然停顿处，并用包裹标签覆盖完整短语。不要连续堆叠大量标签，否则表达效果可能不稳定。完整标签定义可参考 xAI Text to Speech 官方文档。

OpenAI Python SDK 示例

from pathlib import Path

from openai import OpenAI

client = OpenAI(
    base_url="https://oneapi.zaiwenai.com/v1",
    api_key="$YOUR_API_KEY",
)

with client.audio.speech.with_streaming_response.create(
    model="grok-tts",
    input="你好，欢迎使用在问。",
    voice="luna",
    response_format="mp3",
) as response:
    response.stream_to_file(Path("speech.mp3"))

响应与计费

成功响应的 Content-Type 为 audio/mpeg 或 audio/wav。平台还会透传以下用量响应头：

响应头	说明
X-Usage-Type	用量类型
X-Usage-Input-Characters	输入字符数
X-Usage-Audio-Seconds	实际生成音频时长（秒）

语音合成按实际生成的音频时长计费，计费时长向上取整到秒。模型单价以工作台模型目录显示为准。

Gemini 原生语音生成

端点: POST https://oneapi.zaiwenai.com/v1beta/models/{model}:generateContent

端点: POST https://oneapi.zaiwenai.com/v1beta/models/{model}:streamGenerateContent

Gemini TTS 使用 Gemini 原生 generateContent 协议。平台原样转发请求和响应，不会将 Base64 音频转换为 WAV、MP3 或 OpenAI Audio Speech 响应。

支持非流式 generateContent 与流式 streamGenerateContent / ?alt=sse，详见 Gemini 原生文档。

curl -X POST \
  "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "请清晰自然地朗读：你好，欢迎使用在问。"}]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": {"voiceName": "Zephyr"}
        }
      }
    }
  }'

也可以使用 Gemini SDK 风格的 x-goog-api-key 请求头或 ?key= 查询参数。这里填写的始终是在问 API Key，而不是 Google API Key。

音频位于响应的 candidates[0].content.parts[0].inlineData.data，其内容为 Base64；具体格式由同级 mimeType 描述。该接口按照上游返回的 usageMetadata 输入、输出 Token 分别计费。