# EVA Gateway 参数说明

本页介绍 EVA Gateway 各类模型的调用方式和参数。首次使用时，请先参阅 **[EVA Gateway 接入文档](./gateway-api)**。

---

## 通用约定

- 模型名称、支持的参数、取值范围及能力，请参阅[模型广场](https://eva.autoarkai.com/models)中的模型详情；调用时请使用其中展示的 EVA 模型名称。
- 三类能力使用不同的接口前缀：**LLM 使用 `/llm/v1`，ASR 和 TTS 使用 `/v1`**。
- 所有请求均须使用 `Authorization: Bearer <API_KEY>` 进行鉴权。
- EVA Gateway 会为每个请求自动生成 Trace ID，并通过响应头 `autoark-trace-id` 返回。

---

## LLM

LLM 请求体、响应体和错误格式均使用标准 OpenAI 格式，不同模型保持一致的调用体验。

不同 LLM 模型支持的参数、取值范围和能力可能不同，具体信息请参阅[模型广场](https://eva.autoarkai.com/models)中对应模型的信息页。

### 支持的接口与参数

- `POST /llm/v1/chat/completions`：对话补全
- `POST /llm/v1/responses`：Responses 接口

---

## ASR

语音识别接口为 `POST /v1/audio/transcriptions`，请求类型为 `multipart/form-data`。

### 参数

| 参数           | 类型     | 必填 | 默认值             | 说明                                                                                                                               |
| -------------- | -------- | ---- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `file`         | 文件     | 是   | —                  | 音频文件                                                                                                                           |
| `model`        | `string` | 是   | —                  | ASR 模型名                                                                                                                         |
| `audio_format` | `string` | 否   | 根据文件名后缀推断 | 未传入时，文件名以 `.wav` 结尾则推断为 `wav`，其余情况推断为 `pcm`。各模型支持的格式不同，详见模型广场中对应模型的信息页           |
| `sample_rate`  | `int`    | 否   | `16000`            | 待识别音频的采样率（Hz）                                                                                                           |
| `channels`     | `int`    | 否   | `1`                | 声道数                                                                                                                             |
| `hotwords`     | `string` | 否   | —                  | 热词，使用英文逗号分隔（例如 `无界方舟,奇多多`）；是否生效因模型而异，详见模型广场中对应模型的信息页，不支持该参数的模型会静默忽略 |
| `stream`       | `bool`   | 否   | `false`            | 设置为 `true` 时，以 SSE 流式返回；详见下方“流式返回”                                                                              |

> 使用 OpenAI SDK 时，`audio_format`、`sample_rate`、`channels` 和 `hotwords` 通过 `extra_body`（Python）或附加字段（TypeScript）传入。

### 响应

```jsonc
{
  "text": "识别出的文本",
  "usage": {
    "duration": 8767, // 单位：ms
  },
}
```

### 模型参数说明

不同 ASR 模型支持的音频格式、采样率、热词等可能不同，具体信息请参阅[模型广场](https://eva.autoarkai.com/models)中对应模型的信息页。

### 流式返回

当 `stream=true` 时，接口以 SSE（`text/event-stream`）形式返回：

```text
data: {"type":"transcript.text.delta","delta":"..."}   （0 至多个）
data: {"type":"transcript.text.done","text":"完整文本","usage":{"duration":8767}}
data: [DONE]
```

- **`delta` 的内容因模型而异**：部分模型的每个 `delta` 都包含截至当前的完整文本，其他模型的每个 `delta` 仅包含新增文本。具体信息请参阅模型广场中对应模型的信息页。
- 无论使用哪种模型，`transcript.text.done` 中的 `text` 均为**完整结果**，建议以该字段为准。全量模型的 `delta` 内容相互重叠，不能直接拼接。

---

## TTS

语音合成接口为 `POST /v1/audio/speech`，请求类型为 `application/json`。

### 参数

| 参数              | 类型     | 必填 | 默认值     | 说明                                                                          |
| ----------------- | -------- | ---- | ---------- | ----------------------------------------------------------------------------- |
| `model`           | `string` | 是   | —          | TTS 模型名                                                                    |
| `input`           | `string` | 是   | —          | 要合成的文本；长度上限因模型而异，详见模型广场中对应模型的信息页              |
| `voice`           | `string` | 否   | 因模型而异 | 音色；可选值详见模型广场中对应模型的信息页，不填使用默认音色                  |
| `response_format` | `string` | 否   | `pcm`      | 输出音频格式；可选值因模型而异，详见模型广场中对应模型的信息页                |
| `speed`           | `double` | 否   | 因模型而异 | 语速；范围因模型而异                                                          |
| `sample_rate`     | `int`    | 否   | 因模型而异 | 采样率（Hz）                                                                  |
| `pitch_rate`      | `double` | 否   | 因模型而异 | 音调；部分模型不支持                                                          |
| `stream_format`   | `string` | 否   | `audio`    | `audio` 表示返回原始音频字节流；`sse` 表示返回 SSE 事件流，详见下方“流式返回” |

> **关于 `extra_body`**：OpenAI 语音合成接口仅定义了顶层参数 `speed`，未定义音调、采样率等参数。网关通过 OpenAI SDK 的 `extra_body` 额外接收 `sample_rate` 和 `pitch_rate`。

### 模型参数说明

不同 TTS 模型支持的音色、输出格式、采样率、语速及音调范围可能不同，具体信息请参阅[模型广场](https://eva.autoarkai.com/models)中对应模型的信息页。

### 流式返回

当 `stream_format=sse` 时，接口以 SSE（`text/event-stream`）形式返回，事件格式如下：

```text
data: {"type":"speech.audio.delta","audio":"<base64 音频>"}
data: {"type":"speech.audio.done"}
```

`stream_format` 的默认值为 `audio`，此时接口直接返回原始音频字节流。