API 接口文档

本文档描述视频生成服务的 API 接口。

基础信息

基础 URL: http://localhost:8787（开发环境）
内容类型: application/json
响应格式: JSON

POST /api/json

提交视频 Schema 并生成视频预览。

请求

Headers:

Content-Type: application/json

Body: 完整的 VideoSchema JSON 对象。

{
  "meta": {
    "version": "2.0.0",
    "title": "我的视频"
  },
  "video": {
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "duration": 30,
    "background": "#000000"
  },
  "tracks": [...]
}

响应

成功 (200):

{
  "success": true,
  "taskId": "abc123",
  "url": "/v/abc123"
}

字段说明:

字段	类型	描述
success	boolean	是否成功
taskId	string	任务 ID
url	string	预览页面路径

失败 (400):

{
  "success": false,
  "error": "Invalid JSON schema"
}

示例

curl -X POST http://localhost:8787/api/json \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "version": "2.0.0" },
    "video": { "width": 1920, "height": 1080, "fps": 30, "duration": 10 },
    "tracks": [
      {
        "type": "visual",
        "clips": [
          {
            "type": "text",
            "text": "Hello World",
            "start": 0,
            "duration": 5
          }
        ]
      }
    ]
  }'

GET /v/:id

获取视频预览页面。

请求

路径参数:

id: 任务 ID（从 POST /api/json 响应中获取）

响应

返回 HTML 页面，包含 Revideo 播放器。

HTML 内容:

<!DOCTYPE html>
<html>
<head>
  <title>Video Preview</title>
</head>
<body>
  <div id="root"></div>
  <script>
    window.__SCHEMA__ = { /* Schema 数据 */ };
  </script>
  <script src="/client.js"></script>
</body>
</html>

示例

curl http://localhost:8787/v/abc123

或在浏览器中打开: http://localhost:8787/v/abc123

Schema 验证

必填字段

字段	类型	描述
meta.version	string	Schema 版本
video.width	number	视频宽度
video.height	number	视频高度
video.fps	number	帧率
video.duration	number	总时长
tracks	array	轨道列表

验证规则

meta.version - 必须是有效的版本字符串
video.width/height - 正整数
video.fps - 正整数，通常为 24、30、60
video.duration - 正数，单位秒
tracks - 至少包含一个轨道
clips - 每个轨道至少包含一个 clip

常见错误

错误	原因	解决方案
Invalid JSON	JSON 格式错误	检查 JSON 语法
Missing required field	缺少必填字段	添加缺失字段
Invalid clip type	未知的 clip 类型	使用支持的类型
Invalid time range	时间范围无效	检查 start/duration

错误响应

400 Bad Request

请求格式错误或验证失败。

{
  "success": false,
  "error": "Missing required field: video.duration"
}

404 Not Found

资源不存在。

{
  "success": false,
  "error": "Task not found"
}

500 Internal Server Error

服务器内部错误。

{
  "success": false,
  "error": "Internal server error"
}

开发环境

启动开发服务器

pnpm dev

服务器将在 http://localhost:8787 启动。

环境变量

变量	描述	默认值
PORT	服务端口	8787
R2_BUCKET	R2 存储桶名称	-
R2_ACCESS_KEY	R2 访问密钥	-
R2_SECRET_KEY	R2 密钥	-

速率限制

开发环境无速率限制。

生产环境建议配置：

每分钟最多 60 次请求
单个 IP 每小时最多 100 次请求

最佳实践

资源预加载：使用 assets 字段预加载资源
错误处理：始终检查响应中的 success 字段
超时设置：建议设置 30 秒超时
重试机制：对于 5xx 错误，可以重试 2-3 次
缓存利用：相同的 Schema 会返回相同的 taskId

API 接口文档

On this page