# ViewMax MCP 将 MCP 客户端连接到 ViewMax——工具、参数、积分成本、任务轮询、幂等重试，以及视频、图片、音乐和音频生成的错误处理。 想先了解这个 Server 能做什么？请从 [ViewMax MCP 主页](https://viewmax.studio/zh/mcp) 开始；本页详细说明接入和配置。 ## 端点与认证 ViewMax 提供名为 `viewmax` 的远程 MCP Server： ```text https://viewmax.studio/api/mcp ``` 仅支持 Streamable HTTP：`GET` 返回 405，没有旧版 SSE 端点。 **OAuth（claude.ai 与 Claude 桌面版）。** 使用上方 URL 添加自定义连接器，点击 Connect 并用 ViewMax 账号登录。客户端会通过 `/.well-known/oauth-protected-resource` 发现授权流程，无需 API key。 **API key（Claude Code、Cursor、Codex、VS Code、SDK）。** 在 [设置 → API Keys](https://viewmax.studio/settings/apikeys) 创建 key，并在每个请求中发送： ```http Authorization: Bearer sk-your-api-key ``` 没有 `Authorization` 请求头时，Server 仍会响应 `initialize`、`tools/list` 和目录类工具（`list_video_models`、`get_video_model`、`list_image_models`、`get_image_model`、`list_music_models`、`list_voices`）。`get_task`、`wait_for_task`、`get_credits` 以及所有 `generate_*` 工具会返回 `unauthorized` 错误。如果 bearer token 既不是有效的 API key，也不是有效的 OAuth access token，会得到带 OAuth challenge 的 HTTP 401；因此配置了已吊销 key 的客户端可能会转而要求你登录，请创建新 key。 ## 连接客户端 以下配置都指向同一个端点。请把 key 放在 `VIEWMAX_API_KEY` 环境变量中，不要写进会提交的文件。这些配置按各客户端文档中的格式编写；客户端语法会随版本变化，如果某个字段被拒绝，请按客户端自己的 MCP 指南，填写上面的 URL 和请求头。 **claude.ai 与 Claude 桌面版。** 设置 → Connectors → Add custom connector。命名为 ViewMax，粘贴 `https://viewmax.studio/api/mcp`，点击 Connect 并登录。 **Claude Code。** ```bash claude mcp add --transport http viewmax https://viewmax.studio/api/mcp \ --header "Authorization: Bearer $VIEWMAX_API_KEY" ``` 如需在项目中共享，提交 `.mcp.json`。Claude Code 会从每位开发者的环境中展开 `${VIEWMAX_API_KEY}`： ```json { "mcpServers": { "viewmax": { "type": "http", "url": "https://viewmax.studio/api/mcp", "headers": { "Authorization": "Bearer ${VIEWMAX_API_KEY}" } } } } ``` **Cursor。** 添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`），然后重新加载 Cursor： ```json { "mcpServers": { "viewmax": { "url": "https://viewmax.studio/api/mcp", "headers": { "Authorization": "Bearer ${env:VIEWMAX_API_KEY}" } } } } ``` **Codex（ChatGPT）。** Codex 从指定的环境变量读取 key： ```bash codex mcp add viewmax --url https://viewmax.studio/api/mcp \ --bearer-token-env-var VIEWMAX_API_KEY ``` 等价的 `~/.codex/config.toml` 配置： ```toml [mcp_servers.viewmax] url = "https://viewmax.studio/api/mcp" bearer_token_env_var = "VIEWMAX_API_KEY" ``` **VS Code。** 添加 `.vscode/mcp.json`；VS Code 会提示输入一次 key 并安全保存： ```json { "inputs": [ { "type": "promptString", "id": "viewmax-api-key", "description": "ViewMax API key", "password": true } ], "servers": { "viewmax": { "type": "http", "url": "https://viewmax.studio/api/mcp", "headers": { "Authorization": "Bearer ${input:viewmax-api-key}" } } } } ``` **其他客户端。** 能修改自身 MCP 配置的 Agent 可以自行接入。粘贴这句话：“把 ViewMax MCP Server 添加到这个客户端：Streamable HTTP 传输，URL 为 https://viewmax.studio/api/mcp，HTTP 请求头 `Authorization: Bearer <我的 API key>`。然后调用 `get_credits` 验证连接。” `list_video_models` 无需认证，只能证明 Server 可达；`get_credits` 才能证明连接已认证。 ## 工具 该 Server 可生成**视频、图片、音乐和音频**。生成会消耗所连接账户的积分。在 Pro/Ultra 上，旗舰图片（GPT Image 2、GPT Image 2.5、Nano Banana 2、Grok Imagine）使用共用的每日公平使用额度，Ultra 上的 ViewMax C1 也是如此；额度覆盖任务时 `cost_credits` 为 `0`。 每个工具结果都是一个包含 JSON 的文本块。目录类工具、`get_task`、`wait_for_task` 和 `get_credits` 标记为只读（`readOnlyHint`），客户端可以不经确认直接运行。`generate_*` 工具标记为非只读、非破坏性、非幂等、会访问外部服务（open-world）。 ### 任务与账户 | 工具 | 参数 | 结果 | | --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_task` | `task_id` | `task_id`、`status`、`media_type`、`cost_credits`；有结果后返回 `output_urls`（视频任务还有 `video_urls`）；`failed` 或 `canceled` 时返回 `error_code` 和 `error_message` | | `wait_for_task` | `task_id`、可选 `timeout_seconds`（整数 1–50，默认 45） | 每 5 秒检查一次，直到任务结束或超时；返回 `get_task` 的字段，任务仍在运行时另带 `poll_hint` | | `get_credits` | 无 | `remaining_credits` | ### 视频 | 工具 | 参数 | 结果 | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `list_video_models` | 无 | 每个模型的 `id`、`label`、`vendor`、各模式的时长和分辨率，以及 `credits_label` | | `get_video_model` | `model` | 完整目录条目：各模式的时长、分辨率、宽高比、`audio_toggle`、积分、`defaults`，以及模型设置时的 `max_prompt_length` | | `generate_video` | `model`、`prompt`；可选 `mode`、`image_urls`、`video_urls`、`duration`、`resolution`、`aspect_ratio`、`audio`、`source_video_duration_seconds`（> 0）、`idempotency_key` | `task_id`、`status`、`cost_credits`、`poll_hint` | - 省略 `mode` 时：设置了 `image_urls` 则为 `image-to-video`，设置了 `video_urls` 则为 `video-to-video`，否则为 `text-to-video`。 - 省略的 `duration`、`resolution` 和 `aspect_ratio` 会在计价前按该模式的 `defaults` 填充，因此 `cost_credits` 与实际渲染一致。 - 仅当模式的 `audio_toggle` 为 `true` 时才发送 `audio: true`。 - 按秒计费的模型（Seedance 2.x、Seedance 2.5、MiniMax H3）使用 `video_urls` 时需要 `source_video_duration_seconds`。 - 媒体 URL 必须是服务商无需认证即可访问的公开 `http(s)` URL。 ### 图片 | 工具 | 参数 | 结果 | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `list_image_models` | 无 | 每个模型的 `id`、`label`、`vendor`、各模式的宽高比和质量，以及 `credits_label` | | `get_image_model` | `model` | 单个图片模型完整的能力和积分价格 | | `generate_image` | `model`、`prompt`；可选 `scene`（`text-to-image` 或 `image-to-image`）、`image_urls`、`aspect_ratio`、`quality`、`idempotency_key` | `task_id`、`status`、`cost_credits`、`poll_hint` | 省略 `scene` 时，设置了 `image_urls` 则为 `image-to-image`。GPT Image 2.5 会拒绝未知的 `quality` 或尺寸；其他模型会把未知的 `aspect_ratio` 或 `quality` 替换为默认值并按该值计费，因此只发送模型列出的取值。 ### 音乐 | 工具 | 参数 | 结果 | | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `list_music_models` | 无 | 音乐模型、控制项和积分成本 | | `generate_music` | `prompt`；可选 `duration_seconds`（3–300，默认 60）、`instrumental`、`style`、`lyrics`、`idempotency_key` | `task_id`、`status`、`cost_credits`；通常已包含 `output_urls` | 音乐在 60 秒以内消耗 60 积分，超出部分每秒 1 积分；套餐额度不覆盖音乐。描述一首曲子时，把描述写在 `prompt` 中并省略 `style`。发送 `style` 会让服务商把 `prompt` 当作歌词，因此使用 `style` 时不要再发送 `lyrics`。 ### 音频 | 工具 | 参数 | 结果 | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_voices` | 无 | `default_model`、`characters_per_credit`（20）、`minimum_credits`（1）和 `voices`（`id`、`name`、`gender`、`language`、`languages`、`accent`、`use_case`、`description`、`preview_url`、`recommended_model`） | | `generate_speech` | `text`、`voice_id`；可选 `model_id`（默认使用音色的 `recommended_model`）、`speed`（0.25–4）、`stability`（0–1）、`similarity_boost`（0–1）、`idempotency_key` | `task_id`、`status`、`cost_credits`；通常已包含 `output_urls` | | `generate_sound_effect` | `prompt`；可选 `duration_seconds`（0.5–22）、`prompt_influence`（0–1）、`idempotency_key` | `task_id`、`status`、`cost_credits`；通常已包含 `output_urls` | 语音按 `ceil(字符数 / 20)` 积分计费，最少 1 积分。每个音效消耗 5 积分。 模型校验、计价和退款规则与 [v1 API](https://viewmax.studio/zh/docs/api) 相同。 ## Agent 工作流 1. **选择模型。** 调用对应的 `list_*` 工具，再对选定的模型调用 `get_video_model` 或 `get_image_model`，读取其模式、可用取值、`defaults` 和 `max_prompt_length`。 2. **确认成本。** 根据目录价格和将要发送的取值（或模式的 `defaults`）算出积分，告诉用户将使用的模型和成本，并在调用任何 `generate_*` 前等待确认。`get_credits` 可查看余额。 3. **只创建一次。** 调用 `generate_*` 工具时带上新的 `idempotency_key`，例如为本次请求生成的 UUID。 4. **轮询。** 如果 `status` 为 `pending` 或 `processing`，用 `task_id` 调用 `wait_for_task`；只要结果中还有 `poll_hint` 就继续调用。视频可能需要几分钟。Server 没有任务超时，任务也不会丢失：请自行设定截止时间，之后可用 `get_task` 继续查询。音乐、语音和音效通常在创建调用中即完成。 5. **返回结果。** `success` 时把 `output_urls` 交给用户；`failed` 或 `canceled` 时报告 `error_message`，积分会自动退回。 ## 幂等重试 每个 `generate_*` 工具都接受 `idempotency_key`（1–200 个可见 ASCII 字符，不含空格）。如果调用超时或连接中断，用同一个 key 再次调用：ViewMax 会返回首次调用创建的任务及其原始 `cost_credits`，不会再次扣费。参数不会被比对，所以每个新请求都要使用新 key。不带 key 时，每次调用都会创建并扣费一个新任务。MCP 的 key 与 REST 的 `Idempotency-Key` 相互独立。 ## 错误与恢复 失败的工具调用带有 `isError: true`，并返回一个包含 JSON 的文本块： ```json { "error": "minimax-h3 prompt must be 7000 characters or fewer, got 7412", "error_type": "invalid_request", "hint": "Fix the arguments using this message, then call the tool again. Re-read the model with get_video_model or get_image_model before repeating an unsupported model or option." } ``` `error_type` 的取值与 REST 的 `error.type` 相同，`hint` 说明下一步操作。调用在失败前已创建任务时，会额外带上 `task_id`。 | `error_type` | 常见原因 | 处理方式 | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `unauthorized` | 连接上没有 OAuth token 或 API key | 使用 OAuth 连接，或发送 `Authorization: Bearer sk-...`，key 可在 [设置 → API Keys](https://viewmax.studio/settings/apikeys) 创建 | | `invalid_request` | 未知或已下线的模型（`video model temporarily unavailable: ...`）、不支持的模式或选项、prompt 超过 `max_prompt_length`、未知 `voice_id`、已禁用的模型（`This capability is unavailable.`） | 按 `error` 修正参数，并重新读取 `get_video_model` 或 `get_image_model`。带 `task_id` 时表示服务商拒绝了这些设置，任务已退款 | | `content_rejected` | prompt 提到了禁止的用途（deepfake、换脸、冒充他人），即使出现在否定指令中也会命中；或服务商审核拒绝了 prompt 或素材 | 修改内容。原样重试仍会失败 | | `insufficient_credits` | 余额低于成本，未创建任务 | 告知用户。在 [定价页](https://viewmax.studio/zh/pricing) 充值前不要重试 | | `not_found` | `task_id` 不存在或属于其他账户 | 使用本账户返回的 `task_id` | | `internal_error` | 服务商或服务器故障 | 按 `hint` 处理：任务已失败并退款时重试一次；服务商可能仍会完成时，用 `task_id` 调用 `wait_for_task`，不要新建任务 | 超出工具输入 schema 的参数（例如 `timeout_seconds: 120`）会在工具运行前被拒绝，返回纯文本 `Input validation error: ...`。共享的错误分类见 [API 错误](https://viewmax.studio/zh/docs/api/errors)。