API Reference

同声传译 WebSocket

使用 Protobuf 二进制帧进行同声传译。

GET https://api.tu-zi.com/v1/realtime?model={model}

预览指南

粘贴给 AI，帮助理解文档并完成接入。仅包含文档与示例，不包含真实密钥。

# 同声传译 WebSocket

使用 Protobuf 二进制帧进行同声传译。

## 接口与鉴权

`GET https://api.tu-zi.com/v1/realtime?model={model}`

传输方式: websocket

使用模型调用 API Key。示例凭证为占位符，请从环境变量读取真实密钥。

```http
Authorization: Bearer YOUR_API_KEY
```

## 查询参数

| 字段 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- |
| model | string | 是 | 精确模型名，通过 URL 查询参数传入。 |

## 请求体参数

| 字段 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- |
| request_meta.session_id | string | 是 | 会话 UUID。 |
| event | integer | 是 | 按 AST 协议发送会话事件；100 为开始。 |
| source_audio | object | 是 | 输入音频格式配置，16 kHz、单声道、16-bit PCM。 |
| request | object | 是 | 模式 s2t/s2s 和源、目标语言。 |

## 最小请求示例

```json
{
  "request_meta": {
    "session_id": "YOUR_SESSION_UUID"
  },
  "event": 100,
  "source_audio": {
    "format": "wav",
    "rate": 16000,
    "bits": 16,
    "channel": 1
  },
  "request": {
    "mode": "s2t",
    "source_language": "zh",
    "target_language": "en"
  }
}
```

## 运行前准备

将 https://api.tu-zi.com 替换为本站地址（不要重复追加 /v1），YOUR_MODEL 替换为模型广场中的完整模型名。Python 示例需要先安装 requests；JavaScript 示例使用 Node.js 20+ 并保存为 .mjs 文件。WebSocket 示例按代码注释安装专用依赖。

先在本站令牌页面创建模型调用密钥，并设置 API_KEY 环境变量；cURL 中的 YOUR_API_KEY 需要替换。上传示例中的 input.png/input.wav 是本地文件，必须提前准备。

首次运行使用最小请求；成功后对照下方响应字段读取结果。异步接口返回任务 ID 后仍需查询，任务提交成功不代表生成已完成。

## 代码示例

### curl

```bash
# Requires a Protobuf WebSocket client. Download the official AST demo and replace its URL and headers with the values below.
```

### python

```python
# pip install "websockets>=14" "protobuf>=6.31.1"
# Copy python_protogen/ from the official AST Python demo beside this script.
import asyncio, os, uuid, wave
from websockets.asyncio.client import connect
from python_protogen.products.understanding.ast.ast_service_pb2 import TranslateRequest, TranslateResponse

async def main():
    async with connect("wss://api.tu-zi.com/v1/realtime?model=YOUR_MODEL", additional_headers={
        "Authorization": "Bearer " + os.environ["API_KEY"]
    }, max_size=2**21, open_timeout=15) as ws:
        sid = str(uuid.uuid4())
        req = TranslateRequest(event=100)
        req.request_meta.SessionID = sid
        req.source_audio.format = "wav"
        req.source_audio.rate, req.source_audio.bits, req.source_audio.channel = 16000, 16, 1
        req.request.mode, req.request.source_language, req.request.target_language = "s2t", "zh", "en"
        await ws.send(req.SerializeToString())
        async def send_audio():
            with wave.open("input.wav", "rb") as audio:
                assert (audio.getframerate(), audio.getnchannels(), audio.getsampwidth()) == (16000, 1, 2)
                while chunk := audio.readframes(1280):
                    req = TranslateRequest(event=200)
                    req.source_audio.binary_data = chunk
                    await ws.send(req.SerializeToString())
                    await asyncio.sleep(0.08)
            await ws.send(TranslateRequest(event=102).SerializeToString())
        sender = None
        try:
            async for frame in ws:
                event = TranslateResponse.FromString(frame)
                if event.event == 150: sender = asyncio.create_task(send_audio())
                if event.text: print(event.event, event.text)
                if event.event == 154: print(event.response_meta.Billing)
                if event.event in (152, 153): break
        finally:
            if sender:
                sender.cancel()
                await asyncio.gather(sender, return_exceptions=True)

asyncio.run(main())
```

### javascript

```javascript
// Use the official Go/Python AST Protobuf demo or protobufjs.
// URL: wss://api.tu-zi.com/v1/realtime?model=YOUR_MODEL
// Authorization: Bearer YOUR_API_KEY
// Send TranslateRequest as binary; wait for event 150 before audio, finish with event 102.
// See the complete Python example.
```

## 响应字段

| 字段 | 类型 | 说明与约束 |
| --- | --- | --- |
| event | integer | AST 响应事件类型。 |
| text | string | 字幕内容（按事件提供）。 |
| data | binary | 音频数据（按事件提供）。 |

## 流式响应

示例 JSON 表示 Protobuf 消息内容，不能直接把 JSON 文本发送到 WebSocket。需要官方 AST .proto 生成的客户端；参考模型快速上手的 Python 完整示例。

## 错误处理与重试

检查 HTTP 状态与该协议的错误对象；不要将不同协议的错误字段混用。401/403 检查凭证与权限，429 退避等待，5xx 检查网关或上游状态。错误正文可能含 error/message/code 等字段，以实际协议为准。

查询可采用有上限的指数退避；创建任务、生成内容、创建或删除密钥等操作不要盲目重试，以免重复计费或重复执行。

## 适用限制

本页是协议基础结构。模型可用参数、枚举、上限和异步行为以该模型“快速上手”为准；示例中的 YOUR_MODEL 必须替换。表中表单初始值不代表上游默认值。

## 文档依据

定义版本: 1

审核日期: 2026-11-02

来源: https://api.tu-zi.com/docs/api/reference-relay-seed-interpretation

关联协议说明: https://api.tu-zi.com/docs/api/audio-realtime

本文只包含接口文档和示例。真实密钥、账号数据及用户请求内容不包含在复制内容中。

更新 2026-11-02 · 审核信息 2026-11-02

接口与鉴权

GET https://api.tu-zi.com/v1/realtime?model={model}

传输方式: websocket

使用模型调用 API Key。示例凭证为占位符，请从环境变量读取真实密钥。

Authorization: Bearer YOUR_API_KEY

最小请求示例

{
  "request_meta": {
    "session_id": "YOUR_SESSION_UUID"
  },
  "event": 100,
  "source_audio": {
    "format": "wav",
    "rate": 16000,
    "bits": 16,
    "channel": 1
  },
  "request": {
    "mode": "s2t",
    "source_language": "zh",
    "target_language": "en"
  }
}

运行前准备

将 https://api.tu-zi.com 替换为本站地址（不要重复追加 /v1），YOUR_MODEL 替换为模型广场中的完整模型名。Python 示例需要先安装 requests；JavaScript 示例使用 Node.js 20+ 并保存为 .mjs 文件。WebSocket 示例按代码注释安装专用依赖。

先在本站令牌页面创建模型调用密钥，并设置 API_KEY 环境变量；cURL 中的 YOUR_API_KEY 需要替换。上传示例中的 input.png/input.wav 是本地文件，必须提前准备。

首次运行使用最小请求；成功后对照下方响应字段读取结果。异步接口返回任务 ID 后仍需查询，任务提交成功不代表生成已完成。

适用限制

本页是协议基础结构。模型可用参数、枚举、上限和异步行为以该模型“快速上手”为准；示例中的 YOUR_MODEL 必须替换。表中表单初始值不代表上游默认值。

查询参数

字段	类型	必填	说明与约束
model	string	是	精确模型名，通过 URL 查询参数传入。

请求体参数

字段	类型	必填	说明与约束
request_meta.session_id	string	是	会话 UUID。
event	integer	是	按 AST 协议发送会话事件；100 为开始。
source_audio	object	是	输入音频格式配置，16 kHz、单声道、16-bit PCM。
request	object	是	模式 s2t/s2s 和源、目标语言。

响应字段

字段	类型	说明与约束
event	integer	AST 响应事件类型。
text	string	字幕内容（按事件提供）。
data	binary	音频数据（按事件提供）。

流式响应

示例 JSON 表示 Protobuf 消息内容，不能直接把 JSON 文本发送到 WebSocket。需要官方 AST .proto 生成的客户端；参考模型快速上手的 Python 完整示例。

错误处理与重试

检查 HTTP 状态与该协议的错误对象；不要将不同协议的错误字段混用。401/403 检查凭证与权限，429 退避等待，5xx 检查网关或上游状态。错误正文可能含 error/message/code 等字段，以实际协议为准。

查询可采用有上限的指数退避；创建任务、生成内容、创建或删除密钥等操作不要盲目重试，以免重复计费或重复执行。

文档信息与来源

文档依据

定义版本: 1

审核日期: 2026-11-02

来源: https://api.tu-zi.com/docs/api/reference-relay-seed-interpretation

关联协议说明: https://api.tu-zi.com/docs/api/audio-realtime

本文只包含接口文档和示例。真实密钥、账号数据及用户请求内容不包含在复制内容中。

请求示例

# Requires a Protobuf WebSocket client. Download the official AST demo and replace its URL and headers with the values below.

# pip install "websockets>=14" "protobuf>=6.31.1"
# Copy python_protogen/ from the official AST Python demo beside this script.
import asyncio, os, uuid, wave
from websockets.asyncio.client import connect
from python_protogen.products.understanding.ast.ast_service_pb2 import TranslateRequest, TranslateResponse

async def main():
    async with connect("wss://api.tu-zi.com/v1/realtime?model=YOUR_MODEL", additional_headers={
        "Authorization": "Bearer " + os.environ["API_KEY"]
    }, max_size=2**21, open_timeout=15) as ws:
        sid = str(uuid.uuid4())
        req = TranslateRequest(event=100)
        req.request_meta.SessionID = sid
        req.source_audio.format = "wav"
        req.source_audio.rate, req.source_audio.bits, req.source_audio.channel = 16000, 16, 1
        req.request.mode, req.request.source_language, req.request.target_language = "s2t", "zh", "en"
        await ws.send(req.SerializeToString())
        async def send_audio():
            with wave.open("input.wav", "rb") as audio:
                assert (audio.getframerate(), audio.getnchannels(), audio.getsampwidth()) == (16000, 1, 2)
                while chunk := audio.readframes(1280):
                    req = TranslateRequest(event=200)
                    req.source_audio.binary_data = chunk
                    await ws.send(req.SerializeToString())
                    await asyncio.sleep(0.08)
            await ws.send(TranslateRequest(event=102).SerializeToString())
        sender = None
        try:
            async for frame in ws:
                event = TranslateResponse.FromString(frame)
                if event.event == 150: sender = asyncio.create_task(send_audio())
                if event.text: print(event.event, event.text)
                if event.event == 154: print(event.response_meta.Billing)
                if event.event in (152, 153): break
        finally:
            if sender:
                sender.cancel()
                await asyncio.gather(sender, return_exceptions=True)

asyncio.run(main())

// Use the official Go/Python AST Protobuf demo or protobufjs.
// URL: wss://api.tu-zi.com/v1/realtime?model=YOUR_MODEL
// Authorization: Bearer YOUR_API_KEY
// Send TranslateRequest as binary; wait for event 150 before audio, finish with event 102.
// See the complete Python example.