视频生成 API

概览

Viewmax Studio 的视频生成采用异步任务模型：

调用 POST /api/ai/generate 创建任务并立即返回任务 ID
轮询 POST /api/ai/query 获取任务进度与最终结果

鉴权（第三方调用）

第三方调用建议使用 API Key：

请求头：Authorization: Bearer <YOUR_API_KEY>
获取/管理 API Key：控制台 → Settings → API Keys

说明：服务端也支持登录态 Session（用于站内调用），但第三方集成请使用 API Key。

1) 创建视频生成任务

POST /api/ai/generate

请求头

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

请求体字段

provider: 服务商标识
mediaType: 固定为 video
scene: 生成模式
- text-to-video
- image-to-video
- frames-to-video
- reference-to-video
model: 具体模型 ID（与 provider 绑定）
prompt: 文本提示词（部分模式可为空，但建议传）
options: 模型/模式相关参数（不同模型可选项不同）

常用模型（当前工程内置）

Sora 2 Pro
- 文生视频：sora-2-pro-text-to-video
- 图生视频：sora-2-pro-image-to-video
Sora 2
- 文生视频：sora-2-text-to-video
- 图生视频：sora-2-image-to-video
Veo 3.1 / Veo 3.1 Fast
- veo3
- veo3_fast
ByteDance（Seedance / Seedence）
- 文生视频：bytedance/v1-pro-text-to-video、bytedance/v1-lite-text-to-video
- 图生视频：bytedance/v1-pro-image-to-video、bytedance/v1-lite-image-to-video

options 参数说明（常见）

mode: 与 scene 一致（推荐填写）。例如：text-to-video
duration: 时长（秒，数字）。例如：10 / 15
aspect_ratio: 画面比例
- 通用：16:9、9:16、1:1 等
- Sora 2 / Sora 2 Pro：也支持 landscape / portrait（工程会按配置自动映射）
- Veo 的 Auto 可以不传或传空字符串
resolution: 分辨率（字符串）。例如：480p / 720p / 1080p
quality: 质量档位（仅 Sora 2 Pro 使用）
- standard（Standard）
- high（High）
image_input: 图片 URL 列表（数组，字符串 URL）
- 图生视频：通常 1 张
- 帧生视频：2 张（Start/End）
- 参考生视频：最多 3 张
image_url: 单张图片 URL（字符串，等价于 image_input 的第一张；主要用于 bytedance/v1-lite-image-to-video）
end_image_url: 结束帧图片 URL（字符串，可选；主要用于 bytedance/v1-lite-image-to-video）
camera_fixed / fixed_lens: 是否固定镜头（布尔）
seed: 随机种子（数字）
enable_safety_checker: 安全检查开关（布尔）
generate_audio: 是否生成音频（布尔）
has_audio: 是否带音频（布尔，仅用于计费计算；建议与 generate_audio 同步）

示例：Sora 2 Pro（Standard / 10s）

curl -X POST "https://<YOUR_DOMAIN>/api/ai/generate" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaType": "video",
    "scene": "text-to-video",
    "model": "sora-2-pro-text-to-video",
    "prompt": "A dog playing in a park",
    "options": {
      "mode": "text-to-video",
      "duration": 10,
      "aspect_ratio": "landscape",
      "quality": "standard",
      "generate_audio": false,
      "has_audio": false
    }
  }'

示例：Seedence 1.0 Lite（图生视频 / 720p / 5s）

curl -X POST "https://<YOUR_DOMAIN>/api/ai/generate" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaType": "video",
    "scene": "image-to-video",
    "model": "bytedance/v1-lite-image-to-video",
    "prompt": "Multiple shots. A traveler crosses an endless desert toward a glowing archway...",
    "options": {
      "mode": "image-to-video",
      "image_url": "https://file.aiquickdraw.com/custom-page/akr/section-images/17550783375205e9woshz.png",
      "resolution": "720p",
      "duration": 5,
      "camera_fixed": false,
      "seed": -1,
      "enable_safety_checker": true,
      "end_image_url": ""
    }
  }'

响应（成功）

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "YOUR_TASK_ID",
    "mediaType": "video",
    "scene": "text-to-video",
    "model": "sora-2-pro-text-to-video",
    "status": "pending",
    "taskId": "PROVIDER_TASK_ID",
    "costCredits": 75
  }
}

注意：data.id 是 Viewmax Studio 内部任务 ID（用于后续 /api/ai/query），data.taskId 是 上游服务商任务 ID。

失败响应示例

{
  "code": -1,
  "message": "insufficient credits"
}

2) 查询任务状态/结果

POST /api/ai/query

请求体

{
  "taskId": "YOUR_TASK_ID"
}

响应说明

返回的 data 是同一条任务记录，包含最新的：

status: pending / processing / success / failed / canceled
taskInfo: JSON 字符串（需要前端/调用方自行 JSON.parse）
taskResult: JSON 字符串（需要前端/调用方自行 JSON.parse）

计费与积分（重要）

扣费时机：调用 POST /api/ai/generate 创建任务时，会进行积分校验并扣除，扣除数值为返回字段 costCredits
失败退费：任务最终失败（failed）会自动退回本次扣除的积分
价格差异：不同模型/参数可能不同。以 Sora 2 Pro 为例（你提供的规则）：
- Standard：10s=75，15s=135
- High：10s=165，15s=315

视频生成 API

On this page