# 实时视频 API 接入指南

本服务只向用户提供**实时摄像头接口**。管理员会给你登录账号、密码及一把或多把 API 密钥；每把密钥拥有自己的专属接口地址。

```text
用户工作台：https://wechatmerit.com/user/
接口地址示例：https://wechatmerit.com/api/ep_你的入口编号/v1
```

请替换实际入口编号。公开模型为 **Ly1.0**，参考图决定目标人物或形象，摄像头提供实时动作。**服务端预设效果，无需传提示词**，不要传入 `prompt`。

## 1. 用户工作台与并发额度

工作台只支持用户名与密码登录，包含概览、API 密钥、实时会话、操作记录和接入文档。

概览中的「累计使用时长」汇总账号下所有密钥的实时会话，管理员在「用户管理」可查看相同数字。每路会话从服务端确认建立时起计时。各路实际秒数相加后换算为分钟，显示两位小数。例如，两路各运行 20 秒，累计显示 0.67 分钟。升级前已结算的整数分钟原样计入总时长。

本机预览计 0 分钟。停止请求到达服务端后，该会话的时长固定；断线时最迟计至心跳有效期结束。撤销或删除密钥后，已累计的分钟数仍保留在账号下。统计从此功能上线时开始，旧版已结束的会话缺少完整的起止记录。

### 第一次试用摄像头

1. 登录工作台，在「API 密钥」找到要使用的密钥，点击这一行的「试用摄像头」。页面自动带入该密钥的专属地址与模型 `Ly1.0`。
2. 先打开本机摄像头预览，确认浏览器已获得权限、画面和取景正常。预览只在本机运行，不会创建生成会话，也不会占用并发名额。可以在试用页输入管理员发放的密钥，检查接口与当前名额。
3. 准备好参考图后点击「开始生成」。看到生成画面后，点击「停止」结束本次试用，等待页面确认此会话已释放名额。
4. 如果点击停止后遇到断网或刷新，在同一标签页回到试用页核实上一次操作。工作台仍登录时可以直接查询或重试关闭；登录过期时，可重新登录工作台或在试用页重新输入同一把密钥。要查看账号下所有会话，打开工作台的「实时会话」。

### 密钥与名额

- 登录后，概览的「API 密钥」卡片和「API 密钥」列表都会显示完整的 `vg_…` 密钥。点击旁边的「复制密钥」即可复制。在密钥列表中点击同一行的「复制接口地址」，即可取得配套地址。管理员也可在该用户的密钥面板查看和复制。
- 每把有效密钥最多同时运行 **4 路**。多个程序共用同一把密钥时，也合计占用这 4 路。
- **用户总额度 = 有效密钥数量 × 4**，没有有效密钥时额度为 0。每把密钥的名额不能借用，实际可用同时受服务池容量限制，额度不代表预留算力。
- 创建中、运行中、待关闭和待核实会话都可能占位，只有服务端确认关闭后才释放名额。
- 旧密钥若提示需要验证，点击该行的「验证原密钥」，输入原值并验证，即可在列表中查看和复制。验证不创建生成会话。如果原密钥已经遗失且系统只有摘要，请联系管理员发放新密钥。

工作台每 5 秒同步状态，相同数据不会重建列表；正在输入、选中文字或打开弹窗时会推迟后台更新。列表支持搜索、状态筛选及每页 10、20、50 条，切换页面或刷新会保留选择，退出登录后清除。操作记录展示最近 50 条。

工作台登录 Cookie 不能替代程序调用密钥。API 密钥不能登录网页；旧 `/user/ep_...` 入口会转到统一 `/user/`，不会改变账号身份。请勿向其他使用者提供你的登录密码。

## 2. 专属地址与鉴权

每个 HTTP 请求使用对应密钥的专属 `API_BASE`，并携带请求头：

```http
L-API-KEY: 你的用户密钥
```

不要把密钥放入 URL、公开仓库或公开网页。浏览器集成只使用管理员交付的用户密钥，不使用上游账号密钥；不要持久保存到浏览器本地存储。服务端集成可从环境变量读取。以下终端示例使用 Bash：

```bash
export API_BASE='https://wechatmerit.com/api/ep_你的入口编号/v1'
read -r -s -p 'API key: ' API_KEY; echo
export API_KEY

curl --fail-with-body "$API_BASE/me" \
  -H "L-API-KEY: $API_KEY"
```

`GET /me` 查询当前密钥的公开信息与额度，不返回密钥明文。正常 JSON 响应使用 `success`、`code`、`message`、`data`；错误响应包含 `error.type`。

## 3. 上传参考图

调用 `POST {API_BASE}/files`，使用 `multipart/form-data`，文件字段名为 `file`。只上传本次实时生成使用的参考图，让 HTTP 库自动生成 multipart boundary。

```bash
curl --fail-with-body "$API_BASE/files" \
  -H "L-API-KEY: $API_KEY" \
  -F 'file=@reference.png;type=image/png'
```

保存返回的 `data.url`，用于 SDK 的 `referencePath`：

```json
{"success":true,"code":200,"message":"","data":{"url":"同一密钥可用的参考图地址"}}
```

参考图必须由**创建会话的同一把密钥**上传，不能填写任意外部图片地址或复用其他密钥的素材。SDK 的 `await api.uploadImage(imageFile)` 会完成相同上传并返回含 `url` 的对象。

HTTP 上传、查询身份或关闭会话本身不会产生实时画面。实时媒体需要浏览器 RTC SDK 参与推流与接收，不能仅靠 Python 或普通 HTTP 请求播放视频。

## 4. 浏览器 RTC SDK 接入

客户自己的 HTTPS 网页可直接加载下面的 SDK，用专属接口地址和密钥跨域调用，无需登记域名或登录工作台。请让使用者输入自己的密钥。网页需获得摄像头权限，本机开发可使用 localhost。自行托管 SDK 时须保留完整 `dist/` 与 `chunks/`。以下示例使用统一控制器，假定页面有 keyInput、referenceInput、preview、statusText 和 stopButton 元素。

```javascript
import { VideoClient } from 'https://wechatmerit.com/client/dist/video-client.js';

const api = new VideoClient({
  baseURL: 'https://wechatmerit.com/api/ep_你的入口编号/v1',
  apiKey: keyInput.value,
});
const realtime = api.createRealtimeController({
  container: preview, // 设置实际尺寸，例如 height: 480px
  model: 'Ly1.0',
  onStateChange(state) {
    statusText.textContent = state.state;
    stopButton.disabled = ['idle', 'stopping', 'stopped'].includes(state.state);
    // close_pending：保留停止重试入口和 state.operationId，不允许新开始。
  },
});
stopButton.onclick = () => realtime.stop().catch(error => {
  console.error('关闭尚未确认', error.type, error.operationId);
});
window.addEventListener('pagehide', () => {
  void realtime.stop({ keepalive: true }).catch(() => {});
});
try {
  // 自动上传参考图、打开摄像头、连接 RTC；显示首帧后才 resolve。
  await realtime.start({ imageFile: referenceInput.files[0] });
} catch (error) {
  console.error(error.type, error.status, error.retryAfter, error.operationId);
  // 控制器已请求清理；若 state 是 close_pending，应重试 stop()。
}
```

`start({imageFile})` 会自动上传参考图；已上传时可用 `start({referencePath: reference.url})`。图片仍必须属于同一把密钥。服务端预设效果，不传提示词。

## 5. 展示画面与维护心跳

控制器负责播放器绑定，只有检测到实际生成帧才进入 `generating`，并使 start 成功返回。连接建立本身不算出画。状态依次为 `starting`、`waiting_for_frame`、`generating`、`stopping`、`stopped`；异常关闭未确认时为 `close_pending`。

默认连续 30 秒没有可显示的生成帧、远端轨道结束或连接失败时会自动停止。SDK 自动维护会话心跳。停止按钮应在 start 等待过程中保持可用，关闭未确认前不能开始另一会话。

原 `createRealtime()` 和 `closeRealtimeSession(sessionUid)` 仍兼容已有接入；新接入推荐统一控制器，避免重复编写清理逻辑。实时媒体经过 RTC 网络，浏览器可能看到短期房间凭证与媒体域名，长期上游密钥留在服务端。

## 6. 停止、操作查询与幂等

调用 `await realtime.stop()`。控制器先释放本地摄像头和播放器，有界等待 RTC 清理，再通过服务端 DELETE 确认关闭。失败时进入 `close_pending`，保留操作编号和停止重试入口；不要显示已释放名额。退出页面时使用 `stop({keepalive:true})`，但断网或浏览器退出只能尽力关闭，服务端继续回收。工作台也可关闭已知会话。

每次显式开始生成一个操作 ID，创建请求携带 `Idempotency-Key`。同密钥、同 ID、同请求的重放不会另建会话；不同请求使用同 ID 会返回冲突。直接 HTTP 接入可自行提供 8–128 位字母、数字、下划线或连字符组成的随机 ID。不要使用密钥作为操作 ID。

创建超时后，可调用 `await realtime.getOperation()`，或 `await api.getSessionOperation(operationId)`（HTTP 为 `GET /session-operations/{operationId}`）。响应包含 `operationId/state/model`，已知时包含 `sessionId` 和错误摘要，不含 RTC 凭证。状态为 `creating/active/closing/closed/failed/uncertain`。查询得到会话 ID 后重试停止；`uncertain` 需要管理员核实，不能换一个 ID 自动重新创建。

成功创建结果最多在进程内缓存 5 分钟。缓存丢失或服务器重启后，未关闭会话的 POST 重放返回 `operation_resume_unavailable`；应查询并关闭已有会话。已关闭操作返回 `operation_closed`，不会重新生成。

只有服务端确认关闭后才释放名额。创建中、待关闭和待核实会话均可能占位。`GatewayError` 保留 `status/type/retryAfter/requestId/operationId`；`retryAfter` 单位为秒，requestId 仅在服务端返回时存在。

## 7. 常见错误

| HTTP / `error.type` | 处理方式 |
| --- | --- |
| `401` | 密钥无效、已撤销或登录过期；核对凭据或重新登录。 |
| `403 endpoint_mismatch` | 改用与当前密钥绑定的专属接口地址。 |
| `403 realtime_only` | 用户接口仅支持实时功能，请使用参考图上传与 RTC SDK。 |
| `404 not_found` | 资源不存在或不属于当前密钥，不能跨用户复用参考图或会话。 |
| `409 upload_account_changed` | 素材所属账号已变化，重新上传本次参考图。 |
| `413` / `415` / `422` | 检查图片大小、类型和请求参数；专属接口不接受 `prompt`。 |
| `429 customer_capacity` | 用户总额度已满，等待已有会话确认关闭。 |
| `429 key_capacity` | 当前密钥的 4 路并发已满，等待该密钥的会话确认关闭。 |
| `429 realtime_capacity` / `service_busy` | 服务池繁忙。收到明确拒绝后遵循 `Retry-After` 再尝试。 |
| `409 creation_pending` / `creation_uncertain` | 使用同一操作 ID 查询状态；不自动创建另一个操作。 |
| `409 operation_resume_unavailable` / `session_closing` | 查询已知会话并完成关闭，不能自动换 ID 重建。 |
| `409 operation_closed` / `idempotency_conflict` | 操作已结束或 ID 对应不同请求；核对原操作，避免复用错误的 ID。 |
| `503 session_close_pending` | 关闭尚未确认，名额仍占用；保留编号并重试关闭。 |
| `502` / `503` 或网络超时 | 保留已知会话编号，优先关闭，不自动重复提交创建。 |

```json
{"success":false,"code":429,"message":"服务繁忙","error":{"type":"realtime_capacity"}}
```

网页的 `user_csrf` 错误可尝试刷新后重试，`user_login_limited` 表示登录尝试过多，应按提示等待。向服务提供方报告发生时间、会话编号和错误类型，不发送密钥明文。
