---
description: "语音转写、语音合成与 Gemini 原生语音生成接口。"
---

# 音频与语音

在问 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 示例

```bash
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 示例

```python
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` 格式如下：

```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 示例

```bash
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>` |

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

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

建议把标签放在自然停顿处，并用包裹标签覆盖完整短语。不要连续堆叠大量标签，否则表达效果可能不稳定。完整标签定义可参考 [xAI Text to Speech 官方文档](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech)。

### OpenAI Python SDK 示例

```python
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 原生文档](./api-gemini.md)。

```bash
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 分别计费。