# API 参考 ## 认证 使用 [Settings > API Keys](https://renderingvideo.com/settings/apikeys) 中自己的 API Key。请求只能访问该账户拥有的资源。 支持的认证方式： | 方式 | 格式 | | --------------- | ------------------------------ | | Bearer Token | `Authorization: Bearer sk-xxx` | | Token Header | `Authorization: Token sk-xxx` | | X-API-Key | `X-API-Key: sk-xxx` | | Query Parameter | `?api_key=sk-xxx` | 安全提示： - 不要在客户端代码中暴露 API Key - 所有 API 请求都应从服务端发起 --- ## 接口总览 | 方法 | 接口 | 用途 | | ------ | --------------------------------- | ---------------------------- | | POST | `/api/v1/video` | 创建永久视频任务 | | GET | `/api/v1/video` | 获取视频任务列表 | | GET | `/api/v1/video/:taskId` | 获取任务详情 | | DELETE | `/api/v1/video/:taskId` | 删除视频任务 | | POST | `/api/v1/video/:taskId/render` | 触发渲染 | | POST | `/api/v1/upload` | 上传素材文件 | | GET | `/api/v1/files` | 获取文件列表 | | DELETE | `/api/v1/files/:fileId` | 删除文件 | | GET | `/api/v1/credits` | 查询积分余额 | | POST | `/api/v1/preview` | 创建临时预览 | | GET | `/api/v1/preview/:tempId` | 获取预览配置 | | DELETE | `/api/v1/preview/:tempId` | 删除预览 | | POST | `/api/v1/preview/:tempId/convert` | 将预览转成正式任务 | | POST | `/api/v1/preview/:tempId/render` | 将预览转成正式任务并立即渲染 | --- ## POST /api/v1/video 根据视频配置创建一个永久任务。这个接口只创建任务，不会立即开始渲染。 主要字段： | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | ---- | ---------------------------------------------- | | `config` | object | 是 | 符合 [JSON Schema](https://renderingvideo.com/docs/json-spec.md) 的视频配置 | | `metadata` | object | 否 | 绑定到任务上的自定义元数据 | 常见返回字段： - `taskId` - `videoTaskId` - `previewUrl` - `viewerUrl` - `configUrl` - `status` - `quality` - `width` - `height` - `duration` --- ## GET /api/v1/video 获取当前账号下的所有视频任务。 查询参数： | 参数 | 类型 | 默认值 | 说明 | | -------- | ------- | ------ | ------------------ | | `page` | integer | 1 | 页码 | | `limit` | integer | 20 | 每页数量，最大 100 | | `status` | string | - | 按最新任务状态过滤 | 响应中会包含 `tasks` 列表和 `pagination` 分页对象。 --- ## GET /api/v1/video/:taskId 获取某个视频任务的完整详情。 常用返回字段： - `taskId` - `videoTaskId` - `status` - `videoUrl` - `previewUrl` - `viewerUrl` - `configUrl` - `costCredits` - `createdAt` - `completedAt` - `metadata` 状态值说明： | 状态 | 含义 | | ----------- | ------------------------ | | `created` | 任务已创建，尚未开始渲染 | | `rendering` | 正在渲染 | | `completed` | 渲染成功完成 | | `failed` | 渲染失败 | --- ## DELETE /api/v1/video/:taskId 永久删除一个任务及其本地渲染记录。接口同时会尝试删除上游远端任务。 常见返回字段： - `deleted` - `remoteDeleted` - `message` 如果上游删除失败，本地删除仍然可能成功。 --- ## POST /api/v1/video/:taskId/render 对已有任务触发或重新触发渲染。 请求体： | 字段 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ------- | ---- | ------ | ---------------- | | `webhook_url` | string | 否 | - | 渲染完成通知地址 | | `num_workers` | integer | 否 | 5 | 渲染 worker 数量 | 可能结果： - 返回一个新的渲染任务，`status: rendering` - 如果相同尺寸已经渲染完成，会返回 `alreadyRendered: true` 常见错误： - `NOT_FOUND` - `ALREADY_RENDERING` - `INSUFFICIENT_CREDITS` - `RENDER_TRIGGER_FAILED` --- ## Webhook `webhook_url` 支持以下两个渲染启动接口： - `POST /api/v1/video/:taskId/render` - `POST /api/v1/preview/:tempId/render` 工作流程： 1. 渲染请求会把你的 `webhook_url` 和 render task 一起保存 2. 上游渲染器返回 `completed` 或 `failed` 3. 项目先更新本地数据库 4. 然后向你的 `webhook_url` 发起 `POST` 请求 转发的 payload 一般包含： - `taskId` - `renderTaskId` - `status` - `videoUrl` - `error` - `timestamp` 当前限制： - 只转发 `completed` 和 `failed` - `webhook_url` 必须是合法的绝对 URL - 目前没有 webhook 签名 - 目前没有重试队列和投递日志 --- ## POST /api/v1/upload 上传图片、视频或音频文件，供后续视频配置引用。 表单字段： | 字段 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | -------- | | `file` | File | 否\* | 单个文件 | | `files` | File[] | 否\* | 多个文件 | \*`file` 和 `files` 至少传一个。 支持的 MIME 范围： - `image/*` - `video/*` - `audio/*` 各套餐存储上限： | 套餐 | 上限 | | -------- | ------ | | Free | 512 MB | | Starter | 10 GB | | Standard | 20 GB | | Pro | 50 GB | 成功响应中会包含 `count` 和 `assets` 列表。 --- ## GET /api/v1/files 获取当前 API Key 所属账号上传的文件列表。 查询参数： | 参数 | 类型 | 默认值 | 说明 | | ------- | ------- | ------ | --------------------------- | | `page` | integer | 1 | 页码 | | `limit` | integer | 20 | 每页数量 | | `type` | string | - | `image`、`video` 或 `audio` | 响应中会包含 `files` 和 `pagination`。 --- ## DELETE /api/v1/files/:fileId 永久删除文件库中的一个文件。删除时会同时移除存储对象和文件记录。 常见返回字段： - `fileId` - `deleted` - `message` --- ## GET /api/v1/credits 获取当前账号积分余额。 典型返回： ```json { "success": true, "credits": 985, "currency": "credits" } ``` --- ## POST /api/v1/preview 创建一个临时预览，不消耗积分。 主要规则： - 请求体直接传完整的视频 JSON schema - 预览链接有效期为 **7 天** - 预览 **不会** 消耗积分 - 预览 **不会** 生成可下载的视频文件 响应字段： - `tempId` - `previewUrl` - `viewerUrl` - `expiresIn` --- ## GET /api/v1/preview/:tempId 读取临时预览对应的配置。 返回字段： - `tempId` - `config` --- ## DELETE /api/v1/preview/:tempId 删除一个临时预览链接。 返回字段： - `tempId` - `deleted` - `message` --- ## POST /api/v1/preview/:tempId/convert 将临时预览克隆成一个正式视频任务。原来的临时预览仍然可用。 可选请求体： | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | ---- | ------------ | | `category` | string | 否 | 新任务的分类 | 常见返回字段： - `converted` - `taskId` - `videoTaskId` - `previewUrl` - `viewerUrl` - `configUrl` --- ## POST /api/v1/preview/:tempId/render 将临时预览克隆成正式任务，并立即启动渲染。 请求体： | 字段 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ------- | ---- | ------ | ---------------- | | `category` | string | 否 | `api` | 新任务分类 | | `webhook_url` | string | 否 | - | 渲染结果 webhook | | `num_workers` | integer | 否 | 5 | 渲染 worker 数量 | 典型成功响应： - `converted: true` - `taskId` - `renderTaskId` - `status: rendering` - `cost` - `remainingCredits` - `previewUrl` - `viewerUrl` --- ## 积分计算 积分消耗规则： - **费用 = 视频时长（秒）× 质量系数** | 质量 | 短边 | 系数 | | ----- | ------------ | ---- | | 720p | <= 720px | 1.0 | | 1080p | <= 1080px | 1.5 | | 2K | <= 1440px | 2.0 | 质量会根据视频的较短边自动判定。 --- ## 错误格式 所有错误响应都遵循这个结构： ```json { "success": false, "error": "Human-readable error message", "code": "ERROR_CODE", "details": { "field": "additional context" } } ``` 常见错误码： - `MISSING_API_KEY` - `INVALID_API_KEY` - `INVALID_API_KEY_FORMAT` - `API_KEY_INACTIVE` - `USER_NOT_FOUND` - `INVALID_REQUEST` - `INVALID_CONFIG` - `INSUFFICIENT_CREDITS` - `NOT_FOUND` - `ALREADY_RENDERING` - `REMOTE_ERROR` - `RENDER_TRIGGER_FAILED` - `INTERNAL_ERROR` ## SDK 与 API 增强 调用 `GET /api/v1/capabilities` 获取当前部署的 schema 版本、支持的片段／动画／转场类型、渲染质量与功能标记。尚未更新的部署可能返回 404。 创建任务新增可选 `title`（1–255 字符）、`category`（1–100 字符，默认 `api`）和对象 `metadata`。列表与详情响应包含标题、分类。列表默认 `category=api`；使用 `category=all` 可包含网站创建的任务，也可指定某个分类。`all` 仅用于查询。 预览转换和预览渲染支持 `metadata` 与 `category`。`POST /api/v1/preview/:tempId/render` 一次完成转换并启动渲染。渲染参数为 `webhook_url`、正整数 `num_workers`（默认 5）；省略请求体时使用默认值。无效 JSON／参数返回 `INVALID_REQUEST`（400），无效视频 schema 返回 `INVALID_CONFIG`（400）。 认证预览响应提供绝对地址 `previewUrl`、`playerUrl`，以及上游提供时的 `viewerUrl`；保留 `tempId`、`expiresIn`。渲染质量由 schema 尺寸决定，不接收独立 quality 参数。