视频生成 API

创建视频任务

POST /api/v1/videos 会先校验请求、扣除积分并把任务提交给提供方，然后才返回响应。视频随后异步生成：每 5–10 秒轮询一次 GET /api/v1/tasks/{taskId}，直到状态变为 success、failed 或 canceled。服务端没有超时限制，请自行设定截止时间。

POST https://viewmax.studio/api/v1/videos
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Idempotency-Key: kite-001

Idempotency-Key 可选，但建议始终发送；见幂等。

请求体

未传 mode 时：image_urls 非空则为 image-to-video；否则 video_urls 非空则为 video-to-video；否则为 text-to-video。frames-to-video 和 reference-to-video 必须显式传 mode。

options

未传的 duration、resolution 和 aspect_ratio 会在计价前用 GET /api/v1/models 中的 modes.<mode>.defaults 补齐，补齐后的值也会发送给提供方。例如 viewmax-c1 的默认值是 5s、768P 和 16:9。部分模型在某些分辨率下可选时长更少（runway 在 1080p 下只支持 5s）。其他 options 键会原样转发给提供方，不做校验。

输入限制

以下数量不符合时，ViewMax 会在扣费前返回 400。— 表示该模型不提供此模式。

¹ 传视频时还需发送 options.source_video_duration_seconds。

² gemini-omni 只接受 10 秒及以内的源视频；更长的源视频会在提供方处失败（任务失败并退还积分）。

³ gemini-omni-video 接受最长 30 秒的源视频，并使用前 10 秒。

示例

curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kite-001" \
  -d '{
    "model": "viewmax-c1",
    "mode": "text-to-video",
    "prompt": "A paper kite crossing a bright summer sky",
    "options": { "duration": "5s", "resolution": "768P", "aspect_ratio": "16:9" }
  }'

该请求消耗 10 积分（每秒 2 积分 × 5 秒）；Ultra 用户在 ViewMax C1 额度内为 0。

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "3f1c9a2e-5b7d-4c1e-9a0f-2d6e8b4c7a10",
    "userId": "usr_123",
    "mediaType": "video",
    "model": "viewmax-c1/text-to-video",
    "prompt": "A paper kite crossing a bright summer sky",
    "options": "{\"duration\":5,\"resolution\":\"768P\",\"aspect_ratio\":\"16:9\",\"mode\":\"text-to-video\"}",
    "status": "pending",
    "createdAt": "2026-09-29T08:00:00.000Z",
    "updatedAt": "2026-09-29T08:00:01.000Z",
    "deletedAt": null,
    "taskId": "job_abc",
    "taskInfo": null,
    "taskResult": null,
    "taskUrls": [],
    "costCredits": 10,
    "scene": "text-to-video",
    "visibility": "user",
    "creditId": "cr_123",
    "waivedCredits": 0,
    "fairUseKey": null
  }
}

任务字段

所有创建端点和 GET /api/v1/tasks/{taskId} 都返回同一种任务对象。

另外还会返回 userId、taskId（上游任务 ID）、creditId、visibility、createdAt、updatedAt 和 deletedAt。errorCode 取值为 insufficient_credits、auth_required、rate_limited、request_cancelled、provider_unavailable、invalid_input、content_rejected、busy、duplicate_request 或 generic；只有 invalid_input 时 errorMessage 才包含提供方给出的原因。

幂等

每次创建请求都发送 Idempotency-Key 请求头（1–200 个可见 ASCII 字符，不含空格）。重复使用同一个键会返回第一次请求创建的任务及其原始 costCredits，不会再次扣费。服务端不比较请求体；同一账号的所有创建端点共用这些键。

• 超时或连接中断后，用同一个键重试。
• 有意发起新的尝试时（例如任务 failed，或收到带 error.task_id 的 400），换用新的键；旧键会一直返回旧任务。
• 不带该请求头时，每次 POST 都会创建新任务并扣费。
• 键格式无效时返回 400 Idempotency-Key must be 1-200 visible ASCII characters without spaces。

积分与退款

• 任务创建时扣除积分。余额低于费用时返回 402，不创建任务。
• 以 failed 或 canceled 结束的任务会自动退还积分，占用的套餐额度也会归还。
• Ultra 上的 ViewMax C1 使用每日 300 秒输出时长的额度（按 UTC 日计算），与 ViewMax 网页和 MCP 共用。额度内 costCredits 为 0，waivedCredits 为原价，并写入 fairUseKey。请求时长超过剩余额度时按全价扣费。网页中其他视频模型的额度不适用于 API。

估算费用

没有费用预览端点。请根据 GET /api/v1/models 中的 modes.<mode>，用你发送的值或 defaults 计算：

示例：viewmax-c1、5s、768P → 10；seedance-2-0 reference-to-video、8s、720p、5 秒源视频 → ceil(28 × 13) = 364；kling-2-6、5s、audio: true → 110。

错误

校验按以下顺序进行，遇到第一个错误即返回：请求格式、禁止用途措辞、模型、模式、提示词长度、输入、选项、余额。全部通过之前不会扣费。所有错误都使用错误信封。

旧版 /api/ai/* 端点

旧版 POST /api/ai/generate 和 POST /api/ai/query 仍可供已有集成使用，并保持旧的请求形态与响应行为。新集成应使用这里的 v1 资源端点：POST /api/v1/videos 和 GET /api/v1/tasks/{taskId}。