# 友泰华算力运营平台 · API 说明

OpenAI 兼容北向网关。本文档供 Agent / 脚本直接读取，无需渲染门户 SPA。

## 概述

- 门户：https://token.heiyutv.com
- Base URL：`https://token.youtaihua.com/v1`
- 鉴权：`Authorization: Bearer sk-relay-<your-key>`
- 模型 id 清单：[https://token.heiyutv.com/models.md](https://token.heiyutv.com/models.md)

## 鉴权

所有北向请求须携带 Header：

```
Authorization: Bearer sk-relay-xxxxxxxx
Content-Type: application/json
```

API Key 在门户「密钥管理」创建；请勿将真实 Key 写入仓库或公开文档。

## Base URL

```
https://token.youtaihua.com/v1
```

北向调用以部署配置的 Base URL 为准（可能与访问门户的 Host 不同）。

## 端点

| 模态 | 方法 | 路径 |
|------|------|------|
| 模型目录 | GET | `/v1/models` |
| Chat | POST | `/v1/chat/completions` |
| Text | POST | `/v1/completions` |
| Image | POST | `/v1/images/generations` |
| Video | POST | `/v1/videos/generations` |
| Embedding | POST | `/v1/embeddings` |
| Rerank | POST | `/v1/rerank` |
| Audio | POST | `/v1/audio/transcriptions` |
| 异步任务 | GET | `/v1/tasks/{task_id}` |

`GET /v1/models` 须 API Key，返回 OpenAI 兼容 `{ object: "list", data: [{ id }] }`（无 modality 等扩展字段）；列表受用户模型白名单约束，可能比 models.md 更短。

## 流式（SSE）

Chat 等接口支持 `stream: true`，响应为 `text/event-stream`。

## 异步任务

部分图/视频模型返回 `task_id`，请轮询 `GET https://token.youtaihua.com/v1/tasks/{task_id}` 直至完成。

## OpenAI SDK 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-relay-xxxxxxxx",
    base_url="https://token.youtaihua.com/v1",
)
resp = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}],
)
```

## 参数与选模

- 无 Key 浏览公开目录：见 `/models.md`（或 llms-full.txt 内「模型清单」）。
- 带 Key 编程/SDK：`GET /v1/models` 列出当前 Key 可调用的 model id。
- 各模型北向参数见模型详情页，或 `GET /app-api/relay/model/detail?modelId=` 的 `experience.apiDocParams`（与网关 inputSchema 同源）。
- 已安装 CLI / 配置 WorkBuddy 连接器的用户：MCP `list_models`（含模态）→ `get_model_schema` → `generate_*`（见 [https://token.heiyutv.com/docs#clients](https://token.heiyutv.com/docs#clients)）。

## Agent / WorkBuddy 接入

1. 安装 Relay CLI：[https://token.heiyutv.com/cli/youtaihua-relay-latest.tgz](https://token.heiyutv.com/cli/youtaihua-relay-latest.tgz) 或 [https://token.heiyutv.com/docs#clients](https://token.heiyutv.com/docs#clients)。
2. 运行 `relay setup workbuddy` 写入 MCP 配置。
3. chat 由 `models.json` 直连（可用 `GET /v1/models` 或 `model/page?modality=chat` 选模）；生图/生视频用 MCP：`list_models` → `get_model_schema` → `generate_image` / `generate_video` → `get_task`。

## 错误形态

失败时返回 JSON，常见字段：`error.message`、`error.type`、`error.code`（与 OpenAI 风格兼容）。

## 相关链接

- [llms.txt 索引](https://token.heiyutv.com/llms.txt)
- [模型清单](https://token.heiyutv.com/models.md)
- [计价口径](https://token.heiyutv.com/pricing.md)