# ViewMax 开发者文档

ViewMax 视频、图片、音乐和音频生成的 API、MCP、CLI 和 Agent Skill 参考。

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

机器可读契约见 [OpenAPI](https://viewmax.studio/openapi.json)（YAML：`/api/openapi.yaml`）。面向人的入口是 [ViewMax Studio 开发者资源](https://viewmax.studio/developers)。

- [API](https://viewmax.studio/zh/docs/api): 创建并轮询视频、图片、音乐和音频任务。
- [MCP](https://viewmax.studio/zh/docs/mcp): 连接 MCP 客户端。
- [CLI](https://viewmax.studio/zh/docs/cli): 视频任务命令行客户端（尚未发布到 npm）。
- [Skills](https://viewmax.studio/zh/docs/skills): 安装 ViewMax Agent Skill。

## 30 秒快速开始

1. 在 [设置 -> API Keys](https://viewmax.studio/settings/apikeys) 创建 API key。API key 以 `sk-` 开头。
2. 从公开模型目录中选择模型。每种模式都列出可用取值、`defaults` 和积分价格：

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

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

```bash
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`：

```bash
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 总览](https://viewmax.studio/zh/docs/api)。
- **MCP：** 适合 Claude、Cursor、Codex、VS Code 和其他 MCP 客户端。参见 [MCP](https://viewmax.studio/zh/docs/mcp)。
- **CLI：** 用于视频任务的 `viewmax` 命令，尚未发布到 npm；发布前请使用 REST API。参见 [CLI](https://viewmax.studio/zh/docs/cli)。
- **Agent Skill：** 适合能运行 `curl` 但没有 MCP 连接的 Agent。参见 [Skills](https://viewmax.studio/zh/docs/skills)。

## 面向 AI Agent

- 任何文档页都可以读取 Markdown 版本：在 URL 后加 `.md`（例如 `https://viewmax.studio/zh/docs/mcp.md`），或请求时带上 `Accept: text/markdown`。
- [llms.txt](https://viewmax.studio/llms.txt) 说明何时以及如何调用 ViewMax。[OpenAPI](https://viewmax.studio/openapi.json) 是 REST 契约。MCP server card 位于 [`/server-card`](https://viewmax.studio/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`）。按提示处理，详见 [错误](https://viewmax.studio/zh/docs/api/errors)。