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 用于预览
• 执行顶层结构校验
• 生成临时预览链接

请求头

Content-Type: application/json

请求体

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

最小示例：

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

成功响应

{
  "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
• 让你的应用检查当前预览配置

成功响应

{
  "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

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

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

建议 3

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

7. 排查清单

如果输出结果不符合预期，优先检查：

• 是否还在发送旧版顶层 video 对象
• schema 是否包含合法的 meta.version、meta.width、meta.height 和 tracks
• 远程媒体 URL 是否能被播放环境直接访问
• 临时链接是否已经过期

8. 请求示例

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

补充说明：

• 文档中的更多可复制示例见 Examples