# API 与使用方式

本文档只说明当前 `https://video.renderingvideo.com` 已明确对外暴露的集成流程。

基础域名：
- `https://video.renderingvideo.com`

注意：
- 对外使用应优先使用临时预览链接
- 通过 `POST /api/preview` 创建预览
- 对外播放链接使用 `/t/:id` 或 `/preview/:id`
- 不要依赖未文档化的内部播放器或代理路由

## 1. 临时链接 API

当前对外入口：
- `POST /api/preview`
- `GET /api/temp/:id`
- `GET /t/:id`
- `GET /preview/:id`
- `GET /`

临时链接特性：
- 预览数据存储在 KV
- 默认有效期为 7 天
- 返回的预览页可以直接分享给外部用户

## 2. `POST /api/preview`

用途：
- 提交一份 schema 用于预览
- 执行顶层结构校验
- 生成临时预览链接

### 请求头

```http
Content-Type: application/json
```

### 请求体

请求体直接就是完整的 schema JSON。

最小示例：

```json
{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Temporary Preview"
        }
      ]
    }
  ]
}
```

### 成功响应

```json
{
  "success": true,
  "tempId": "uuid",
  "url": "/t/uuid",
  "viewerUrl": "/preview/uuid",
  "expiresIn": "604800 seconds (7 days)"
}
```

字段说明：
- `url`：纯净播放器页
- `viewerUrl`：预览页变体
- `tempId`：后续读取临时配置时使用的标识

### 常见失败情况

请求可能失败的原因：
- JSON 非法
- 缺少顶层 `meta` 或 `tracks`
- 请求体不符合当前 `VideoSchema`

## 3. `GET /api/temp/:id`

用途：
- 读取临时链接背后的 schema
- 让你的应用检查当前预览配置

### 成功响应

```json
{
  "success": true,
  "config": {
    "meta": {
      "version": "2.0.0",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "tracks": [
      {
        "clips": [
          {
            "type": "text",
            "start": 0,
            "duration": 3,
            "text": "Temporary Preview"
          }
        ]
      }
    ]
  }
}
```

常见失败情况：
- `id` 不是合法 UUID
- 临时链接不存在
- 临时链接已过期

## 4. 预览页面

临时链接对应两个播放页面：
- `GET /t/:id`：纯净播放器页
- `GET /preview/:id`：预览页变体

如果临时链接已过期，这些页面会返回失效提示。

说明：
- 对外公开的是预览 URL，本项目不承诺内部播放器实现细节
- 不要依赖未公开文档说明的资源代理路径、客户端改写逻辑或内部运行时 helper

## 5. 推荐的对外使用流程

推荐顺序：
1. 先组织好 `meta / assets / tracks`
2. 可复用媒体尽量放进 `assets`
3. 在合适场景下通过 `$ref` 引用素材
4. 提交到 `POST /api/preview`
5. 把返回的 `/t/:id` 或 `/preview/:id` 分享出去
6. 如果后续需要正式任务，再在你的业务流程里把临时预览转换成永久任务

## 6. 编写建议

### 建议 1

可复用资源优先用 `$ref`，不要在多个 clip 中重复写 URL。

### 建议 2

如果字幕来自外部服务，推荐返回结构如下：

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### 建议 3

不要依赖未公开文档说明的字段或内部实现细节。

## 7. 排查清单

如果输出结果不符合预期，优先检查：
- 是否还在发送旧版顶层 `video` 对象
- schema 是否包含合法的 `meta.version`、`meta.width`、`meta.height` 和 `tracks`
- 远程媒体 URL 是否能被播放环境直接访问
- 临时链接是否已经过期

## 8. 请求示例

```bash
curl -X POST https://video.renderingvideo.com/api/preview \
  -H "Content-Type: application/json" \
  -d @temp-preview.json
```

补充说明：
- 文档中的更多可复制示例见 [Examples](https://renderingvideo.com/docs/examples.md)