API 参考

认证

所有 API 请求都需要使用 API Key 认证。你可以在 Settings > API Keys 中获取 API Key。

支持的认证方式：

安全提示：

• 不要在客户端代码中暴露 API Key
• 所有 API 请求都应从服务端发起

接口总览

POST /api/v1/video

根据视频配置创建一个永久任务。这个接口只创建任务，不会立即开始渲染。

主要字段：

常见返回字段：

• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl
• status
• quality
• width
• height
• duration

GET /api/v1/video

获取当前账号下的所有视频任务。

查询参数：

响应中会包含 tasks 列表和 pagination 分页对象。

GET /api/v1/video/:taskId

获取某个视频任务的完整详情。

常用返回字段：

• taskId
• videoTaskId
• status
• videoUrl
• previewUrl
• viewerUrl
• configUrl
• costCredits
• createdAt
• completedAt
• metadata

状态值说明：

DELETE /api/v1/video/:taskId

永久删除一个任务及其本地渲染记录。接口同时会尝试删除上游远端任务。

常见返回字段：

• deleted
• remoteDeleted
• message

如果上游删除失败，本地删除仍然可能成功。

POST /api/v1/video/:taskId/render

对已有任务触发或重新触发渲染。

请求体：

可能结果：

• 返回一个新的渲染任务，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 和 files 至少传一个。

支持的 MIME 范围：

• image/*
• video/*
• audio/*

各套餐存储上限：

成功响应中会包含 count 和 assets 列表。

GET /api/v1/files

获取当前 API Key 所属账号上传的文件列表。

查询参数：

响应中会包含 files 和 pagination。

DELETE /api/v1/files/:fileId

永久删除文件库中的一个文件。删除时会同时移除存储对象和文件记录。

常见返回字段：

• fileId
• deleted
• message

GET /api/v1/credits

获取当前账号积分余额。

典型返回：

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

将临时预览克隆成一个正式视频任务。原来的临时预览仍然可用。

可选请求体：

常见返回字段：

• converted
• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl

POST /api/v1/preview/:tempId/render

将临时预览克隆成正式任务，并立即启动渲染。

请求体：

典型成功响应：

• converted: true
• taskId
• renderTaskId
• status: rendering
• cost
• remainingCredits
• previewUrl
• viewerUrl

积分计算

积分消耗规则：

• 费用 = 视频时长（秒）× 质量系数

质量会根据视频的较短边自动判定。

错误格式

所有错误响应都遵循这个结构：

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