# ElevenLabs API：Eleven v4 语音合成与 Scribe v2 语音转录

Source: https://ofox.io/zh/docs/develop/models/elevenlabs

ElevenLabs 的语音模型，共两款：**Eleven v4** 用于语音合成，**Scribe v2** 用于语音转录。均通过 OpenAI 兼容的音频接口调用。

**模型 ID（调用时原样复制）**

- Eleven v4（语音合成）: `elevenlabs/eleven_v4` — POST /v1/audio/speech
- Scribe v2（语音转录）: `elevenlabs/scribe_v2` — POST /v1/audio/transcriptions

接口的通用参数见 [Audio Speech API](https://ofox.io/zh/docs/api/openai/audio-speech) 与 [Audio Transcriptions API](https://ofox.io/zh/docs/api/openai/audio-transcriptions)。实时价格请参阅[模型页](https://ofox.io/zh/models/elevenlabs/eleven_v4)：语音合成按字符计费，语音转录按音频时长计费。

## Eleven v4 语音合成

**要点**:voice 需传入音色 ID，而非音色名称；不支持 OpenAI 的 alloy 等音色。

**Python**

```python filename="eleven_tts.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])

with client.audio.speech.with_streaming_response.create(
    model="elevenlabs/eleven_v4",
    voice="21m00Tcm4TlvDq8ikWAM",
    input="你好，欢迎使用 OfoxAI 语音合成。",
    response_format="mp3",
) as resp:
    resp.stream_to_file("speech.mp3")
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/v1/audio/speech \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/eleven_v4",
    "voice": "21m00Tcm4TlvDq8ikWAM",
    "input": "你好，欢迎使用 OfoxAI 语音合成。",
    "response_format": "mp3"
  }' \
  --output speech.mp3
```

| 参数 | 说明 |
|---|---|
| `voice` | **必填**，ElevenLabs 的音色 ID（20 位字符），如 `21m00Tcm4TlvDq8ikWAM`。音色 ID 可在 [ElevenLabs 音色库](https://elevenlabs.io/app/voice-library)中查找。传入音色名称（如 `Rachel`）会返回 404 |
| `response_format` | `mp3`（默认，44.1 kHz）、`opus`（48 kHz，Ogg 封装）、`wav`（16 kHz）、`pcm`（16 kHz，16 位单声道）。`aac`、`flac` 不支持 |
| `language_code` | 语言代码，如 `zh`、`en`，不传时自动判断 |
| `provider_options` | 透传 ElevenLabs 专有参数，如 `{"elevenlabs": {"voice_settings": {"stability": 0.3}}}`，参数定义见 [ElevenLabs 官方文档](https://elevenlabs.io/docs/api-reference/text-to-speech/convert) |

实测一句约 20 字的中文约 2 秒返回，生成的音频约 4 秒。

## Scribe v2 语音转录
Scribe v2 除转录文字外，还返回逐词的起止时间，并可识别不同的说话人。

**Python**

```python filename="scribe.py"
import json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="elevenlabs/scribe_v2",
        file=f,
        extra_body={"provider_options": json.dumps({"elevenlabs": {"diarize": True}})},
    )

print(result.text)
for w in (result.model_extra or {}).get("words", [])[:10]:
    print(w.get("speaker"), w["start"], w["end"], w["word"])
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/v1/audio/transcriptions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -F model=elevenlabs/scribe_v2 \
  -F 'provider_options={"elevenlabs": {"diarize": true}}' \
  -F file=@meeting.mp3
```

响应结构：

| 字段 | 说明 |
|---|---|
| `text` | 完整转录文字 |
| `words[]` | 逐词结果，含 `word`、`start`、`end`（秒）；开启说话人分离后另含 `speaker`（如 `speaker_0`、`speaker_1`） |
| `language` | 识别出的语言，如 `zho`、`eng` |
| `duration` | 音频时长（秒） |
| `usage` | `{"type": "duration", "seconds": ...}`，按时长计费 |

- 说话人分离需通过 `provider_options` 开启：`{"elevenlabs": {"diarize": true}}`，以 JSON 字符串作为表单字段传入。
- `response_format` 支持 `json` 与 `verbose_json`，两者返回内容相同。需要字幕文件时，可根据 `words` 中的时间戳自行生成。

## 常见报错
| HTTP | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 404 | `A voice with voice_id 'Rachel' was not found.` | `voice` 传入了音色名称或不存在的 ID | 改用音色 ID |
| 400 | `unsupported ElevenLabs response_format: aac` | 格式不受支持 | 改用 `mp3`、`opus`、`wav` 或 `pcm` |
| 400 | `Unsupported response_format 'srt'. Only 'json' and 'verbose_json' are supported on this gateway` | 转录使用了 `text`、`srt`、`vtt` | 改用 `json` |

更多报错见 [Audio Speech API](https://ofox.io/zh/docs/api/openai/audio-speech#errors) 与 [Audio Transcriptions API](https://ofox.io/zh/docs/api/openai/audio-transcriptions#errors)。

## 官方文档
- [ElevenLabs · 文字转语音](https://elevenlabs.io/docs/capabilities/text-to-speech)
- [ElevenLabs · 语音转文字](https://elevenlabs.io/docs/capabilities/speech-to-text)
- [ElevenLabs · 音色库](https://elevenlabs.io/app/voice-library)

## 常见问题

**ElevenLabs 的 voice 填什么？**

填音色 ID（20 位字符），如 21m00Tcm4TlvDq8ikWAM，可在 ElevenLabs 音色库中查找。填音色名称（如 Rachel）或 OpenAI 的 alloy 会返回 404 voice_id not found。

**Eleven v4 支持哪些音频格式？**

mp3（默认）、opus、wav、pcm。aac 与 flac 不支持。

**Scribe v2 能区分说话人吗？**

能。通过 provider_options 传入 {"elevenlabs": {"diarize": true}}，响应的 words 中每个词会带有 speaker 字段，如 speaker_0、speaker_1。

**Scribe v2 能直接输出 srt 字幕吗？**

不能，response_format 仅支持 json 与 verbose_json。可根据响应 words 中的 start、end 时间戳自行生成字幕。

**ElevenLabs 语音怎么计费？**

Eleven v4 按输入字符数计费，Scribe v2 按音频时长计费，单价见模型页。