# ViewMax Agent Skill

安装 ViewMax Agent Skill，通过 REST API 以积分确认的方式生成视频、图片、音乐和音频。

Agent Skill 教 Agent 用 `curl` 调用 ViewMax REST API。客户端支持 [MCP](https://viewmax.studio/zh/docs/mcp) 时优先使用 MCP；Skill 适合能运行 shell 命令但没有 MCP 连接的 Agent。

## 安装

将视频 Skill 和精简 API 参考下载到 Claude skills 目录：

```bash
curl -fsSL https://viewmax.studio/skills/viewmax-video/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-video/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-video/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-video/reference.md
```

如需在项目中共享，请改为下载到仓库内的 `.claude/skills/<name>/`。其他支持 Agent Skill 的 Agent 可以从各自的 skills 目录加载同样的两个文件。

该 Skill 名为 `viewmax-video`。它的触发描述覆盖生成视频、使用 Seedance、Veo、Kling 或 MiniMax，以及将图片转为视频等请求。

## 工作流

安装后的 Skill 会指导 Agent：

1. 检查 `VIEWMAX_API_KEY` 是否可用。
2. 获取 `GET https://viewmax.studio/api/v1/models`，选择当前可用的模型、合法取值和 `max_prompt_length`。
3. 告诉用户模型和积分成本，并在创建任务前等待确认。
4. 通过 `POST /api/v1/videos` 创建任务并带上 `Idempotency-Key` 请求头，重试时复用同一个 key。
5. 每 5–10 秒轮询 `GET /api/v1/tasks/{taskId}`，直到 `success`、`failed` 或 `canceled`。
6. 成功后返回 `data.taskUrls` 的第一项；失败时报告 `data.taskInfo` 中的 `errorMessage`。

`reference.md` 包含端点表、可用请求字段、任务生命周期，以及各错误类型对应的处理方式。

## 图片、音乐和音频 Skill

其他模态也遵循同样的模式。每个 Skill 按其媒体类型触发，并封装对应的 v1 端点。

```bash
# 图片（文生图与图生图）
curl -fsSL https://viewmax.studio/skills/viewmax-image/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-image/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-image/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-image/reference.md

# 音乐
curl -fsSL https://viewmax.studio/skills/viewmax-music/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-music/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-music/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-music/reference.md

# 音频（文本转语音与音效）
curl -fsSL https://viewmax.studio/skills/viewmax-audio/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-audio/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-audio/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-audio/reference.md
```

- `viewmax-image` —— 通过 `POST /api/v1/images` 实现文生图与图生图。
- `viewmax-music` —— 通过 `POST /api/v1/music` 生成原创音乐（60 秒以内 60 积分，超出部分每秒 1 积分）。
- `viewmax-audio` —— 文本转语音 `POST /api/v1/speech`（`ceil(字符数 / 20)` 积分，最少 1）和音效 `POST /api/v1/sound-effects`（5 积分）。

## 凭证与安全

Skill 使用 `Authorization: Bearer $VIEWMAX_API_KEY`。应将 key 保存在 Agent 的安全环境中，而不是提示词或客户端源码中。用户确认积分成本前，Skill 不得创建会扣费的任务。