ViewMax 开发者文档

可通过 ViewMax REST API、MCP Server 或可下载的 Agent Skill 构建视频、图片、音乐和音频生成工作流。Pro/Ultra 旗舰图片与 Ultra 的 ViewMax C1 可使用共用的每日公平使用额度；其他生成消耗积分。选择模型或向用户报价前，应先读取模型目录。

机器可读契约见 OpenAPI（YAML：/api/openapi.yaml）。面向人的入口是 ViewMax Studio 开发者资源。

30 秒快速开始

1. 在 设置 -> API Keys 创建 API key。API key 以 sk- 开头。
2. 从公开模型目录中选择模型。每种模式都列出可用取值、defaults 和积分价格：

curl https://viewmax.studio/api/v1/models

3. 使用该模型列出的取值创建任务。带上 Idempotency-Key 请求头后，重试会返回同一个任务，不会重复扣费：

curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kite-demo-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 积分（ViewMax C1 按每秒 2 积分计费）。响应中的 data.costCredits 是实际扣费。

4. 每 5–10 秒轮询返回的 data.id，直到任务变为 success、failed 或 canceled：

curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/tasks/TASK_ID

成功后，data.taskUrls 是结果 URL 数组。failed 或 canceled 的任务会自动退款，data.taskInfo（JSON 字符串）中包含 errorCode 和 errorMessage。

选择接入方式

• REST API： 适合服务端、脚本和 CI。参见 API 总览。
• MCP： 适合 Claude、Cursor、Codex、VS Code 和其他 MCP 客户端。参见 MCP。
• CLI： 用于视频任务的 viewmax 命令，尚未发布到 npm；发布前请使用 REST API。参见 CLI。
• Agent Skill： 适合能运行 curl 但没有 MCP 连接的 Agent。参见 Skills。

面向 AI Agent

• 任何文档页都可以读取 Markdown 版本：在 URL 后加 .md（例如 https://viewmax.studio/zh/docs/mcp.md），或请求时带上 Accept: text/markdown。
• llms.txt 说明何时以及如何调用 ViewMax。OpenAPI 是 REST 契约。MCP server card 位于 /server-card，发现文档位于 /.well-known/mcp.json。
• 在任何会创建任务的调用之前，告诉用户将使用的模型和成本（来自 GET /api/v1/models，或 MCP 中的 get_video_model 和 get_image_model），并等待用户确认。
• 每次创建调用都带上 Idempotency-Key 请求头（MCP：idempotency_key），超时后重试时复用同一个 key。不带 key 的重试会创建并扣费第二个任务。
• 失败请求带有 error.type 和 error.hint（MCP：error_type 和 hint）。按提示处理，详见 错误。