# EVA Gateway 接入文档

EVA Gateway 为不同模型提供统一的 OpenAI Compatible 接口。使用一套鉴权信息，即可调用 LLM（大语言模型）、ASR（语音识别）和 TTS（语音合成）三类能力。

本页将帮助你在几分钟内完成首次调用。不同模型支持的参数、取值范围和能力可能不同，具体信息请参阅[模型广场](https://eva.autoarkai.com/models)中对应模型的信息页。

---

## 前置准备

### 1. Base URL

`https://eva-gateway.autoarkai.com`

> **注意：LLM 与音频服务使用不同的路径前缀。**
>
> - **LLM**：`https://eva-gateway.autoarkai.com/llm/v1`
> - **ASR/TTS（音频）**：`https://eva-gateway.autoarkai.com/v1`
>
> 使用 OpenAI SDK 时，需要分别为 LLM 和音频服务初始化客户端，详见下文。

### 2. 获取 API Key

在[控制台](https://eva.autoarkai.com/console/api-keys)创建并获取 API Key，格式如 `ak-xxxxxxxx...`。

### 3. 鉴权

所有请求均须通过 HTTP 请求头携带 API Key。三种接入方式的鉴权方法完全一致：

```http
Authorization: Bearer <你的 API_KEY>
```

### 4. 请求追踪

EVA Gateway 会为每个请求自动生成 Trace ID，并通过以下响应头返回：

```http
autoark-trace-id: <TRACE_ID>
```

---

## 方式一：EVA API

无需安装任何 SDK，使用任意 HTTP 客户端即可调用。以下分别提供每项能力的 Shell、Python 和 TypeScript 示例。

### LLM

调用接口：`POST /llm/v1/chat/completions`。LLM 请求体、响应体和错误格式均使用标准 OpenAI 格式，不同模型保持一致的调用体验。不同 LLM 模型支持的参数和取值范围可能不同，具体信息请参阅[模型广场](https://eva.autoarkai.com/models)中对应模型的信息页。在请求体中添加 `"stream": true`，即可使用标准 OpenAI SSE 流式响应。

<CodeGroup labels={['Shell', 'Python', 'TypeScript']}>

```bash
curl https://eva-gateway.autoarkai.com/llm/v1/chat/completions \
  -H "Authorization: Bearer $EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine-doubao-seed-2.0-mini",
    "messages": [{"role": "user", "content": "你好，用一句话介绍你自己"}]
  }'
```

```python
import requests

resp = requests.post(
    "https://eva-gateway.autoarkai.com/llm/v1/chat/completions",
    headers={"Authorization": f"Bearer {EVA_API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "volcengine-doubao-seed-2.0-mini",
        "messages": [{"role": "user", "content": "你好，用一句话介绍你自己"}],
    },
)
print(resp.json())
```

```typescript
const resp = await fetch(
  'https://eva-gateway.autoarkai.com/llm/v1/chat/completions',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.EVA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'volcengine-doubao-seed-2.0-mini',
      messages: [{ role: 'user', content: '你好，用一句话介绍你自己' }],
    }),
  },
);
console.log(await resp.json());
```

</CodeGroup>

### ASR（语音识别）

调用接口：`POST /v1/audio/transcriptions`。请求类型为 `multipart/form-data`，其中 `file` 为音频文件，`model` 为 ASR 模型名。参数说明与响应格式，请参阅 [EVA Gateway 参数说明：ASR](./models-and-parameters#asr)。

<CodeGroup labels={['Shell', 'Python', 'TypeScript']}>

```bash
curl https://eva-gateway.autoarkai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $EVA_API_KEY" \
  -F "model=ark-asr-flash" \
  -F "file=@sample.wav" \
  -F "audio_format=wav" \
  -F "sample_rate=16000"
```

```python
import requests

with open("sample.wav", "rb") as f:
    resp = requests.post(
        "https://eva-gateway.autoarkai.com/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {EVA_API_KEY}"},
        files={"file": ("sample.wav", f, "audio/wav")},
        data={"model": "ark-asr-flash", "audio_format": "wav", "sample_rate": 16000},
    )
print(resp.json())
```

```typescript
import fs from 'fs';

const form = new FormData();
form.append('model', 'ark-asr-flash');
form.append('audio_format', 'wav');
form.append('sample_rate', '16000');
form.append('file', new Blob([fs.readFileSync('sample.wav')]), 'sample.wav');

const resp = await fetch(
  'https://eva-gateway.autoarkai.com/v1/audio/transcriptions',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.EVA_API_KEY}` },
    body: form,
  },
);
console.log(await resp.json());
```

</CodeGroup>

### TTS（语音合成）

调用接口：`POST /v1/audio/speech`，默认返回**原始音频字节流**。参数说明与返回格式，请参阅 [EVA Gateway 参数说明：TTS](./models-and-parameters#tts)。

<CodeGroup labels={['Shell', 'Python', 'TypeScript']}>

```bash
curl https://eva-gateway.autoarkai.com/v1/audio/speech \
  -H "Authorization: Bearer $EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ark-tts-flash",
    "input": "你好，欢迎使用 EVA Gateway。",
    "voice": "longjielidou_v3",
    "response_format": "pcm"
  }' \
  --output output.pcm
```

```python
import requests

resp = requests.post(
    "https://eva-gateway.autoarkai.com/v1/audio/speech",
    headers={"Authorization": f"Bearer {EVA_API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "ark-tts-flash",
        "input": "你好，欢迎使用 EVA Gateway。",
        "voice": "longjielidou_v3",
        "response_format": "pcm",
    },
)
with open("output.pcm", "wb") as f:
    f.write(resp.content)
```

```typescript
import fs from 'fs';

const resp = await fetch('https://eva-gateway.autoarkai.com/v1/audio/speech', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EVA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'ark-tts-flash',
    input: '你好，欢迎使用 EVA Gateway。',
    voice: 'longjielidou_v3',
    response_format: 'pcm',
  }),
});
fs.writeFileSync('output.pcm', Buffer.from(await resp.arrayBuffer()));
```

</CodeGroup>

### WebSocket API

ASR/TTS 的 WebSocket 双向流式能力正在开发中，预计于 8 月上线，敬请期待。

---

## 方式二：OpenAI SDK

如果已有基于 OpenAI SDK 的代码，只需将 `base_url` 指向 EVA Gateway，即可直接复用，作为直接替代方案（drop-in replacement）。

由于 LLM 与音频服务使用不同的路径前缀，需要分别初始化两个客户端。

### 安装与初始化

安装依赖：

<CodeGroup labels={['Python', 'TypeScript']}>

```bash
pip install openai
```

```bash
npm install openai
```

</CodeGroup>

初始化客户端：

<CodeGroup labels={['Python', 'TypeScript']}>

```python
from openai import OpenAI

# LLM 使用 /llm/v1
llm = OpenAI(api_key="EVA_API_KEY", base_url="https://eva-gateway.autoarkai.com/llm/v1")

# 音频（ASR/TTS）使用 /v1
audio = OpenAI(api_key="EVA_API_KEY", base_url="https://eva-gateway.autoarkai.com/v1")
```

```typescript
import OpenAI from 'openai';

// LLM 使用 /llm/v1
const llm = new OpenAI({
  apiKey: process.env.EVA_API_KEY,
  baseURL: 'https://eva-gateway.autoarkai.com/llm/v1',
});

// 音频（ASR/TTS）使用 /v1
const audio = new OpenAI({
  apiKey: process.env.EVA_API_KEY,
  baseURL: 'https://eva-gateway.autoarkai.com/v1',
});
```

</CodeGroup>

### LLM

<CodeGroup labels={['Python', 'TypeScript']}>

```python
resp = llm.chat.completions.create(
    model="volcengine-doubao-seed-2.0-mini",
    messages=[{"role": "user", "content": "你好，用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)
```

```typescript
const resp = await llm.chat.completions.create({
  model: 'volcengine-doubao-seed-2.0-mini',
  messages: [{ role: 'user', content: '你好，用一句话介绍你自己' }],
});
console.log(resp.choices[0].message.content);
```

</CodeGroup>

### ASR（语音识别）

网关自定义参数通过 `extra_body`（Python）或附加字段（TypeScript）传入。

<CodeGroup labels={['Python', 'TypeScript']}>

```python
with open("sample.wav", "rb") as f:
    result = audio.audio.transcriptions.create(
        model="ark-asr-flash",
        file=f,
        extra_body={"audio_format": "wav", "sample_rate": 16000},
    )
print(result.text)
```

```typescript
import fs from 'fs';

const result = await audio.audio.transcriptions.create({
  model: 'ark-asr-flash',
  file: fs.createReadStream('sample.wav'),
  // @ts-expect-error 网关自定义参数
  audio_format: 'wav',
  sample_rate: 16000,
});
console.log(result.text);
```

</CodeGroup>

### TTS（语音合成）

<CodeGroup labels={['Python', 'TypeScript']}>

```python
resp = audio.audio.speech.create(
    model="ark-tts-flash",
    voice="longjielidou_v3",
    input="你好，欢迎使用 EVA Gateway。",
    response_format="pcm",
)
resp.stream_to_file("output.pcm")
```

```typescript
import fs from 'fs';

const resp = await audio.audio.speech.create({
  model: 'ark-tts-flash',
  voice: 'longjielidou_v3',
  input: '你好，欢迎使用 EVA Gateway。',
  response_format: 'pcm',
});
fs.writeFileSync('output.pcm', Buffer.from(await resp.arrayBuffer()));
```

</CodeGroup>

---

## 下一步

- 查看各接口参数及其含义：**[EVA Gateway 参数说明](./models-and-parameters)**。模型名称、支持的参数、取值范围及能力，请参阅[模型广场](https://eva.autoarkai.com/models)中的模型详情；调用时请使用其中展示的 EVA 模型名称。