ViewMax MCP

通过远程MCP服务器使用ViewMax生成视频、图像、音乐和音频；检查模型、轮询任务并查看积分。

托管 MCP 服务器

npx add-mcp 'https://viewmax.studio/api/mcp'

可安装到 Claude Code、Codex、Cursor 等客户端

文档

ViewMax MCP

将 MCP 客户端连接到 ViewMax——工具、参数、积分成本、任务轮询、幂等重试，以及视频、图片、音乐和音频生成的错误处理。

想先了解这个 Server 能做什么？请从 ViewMax MCP 主页开始；本页详细说明接入和配置。

端点与认证

ViewMax 提供名为 viewmax 的远程 MCP Server：

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 创建 key，并在每个请求中发送：

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。

claude mcp add --transport http viewmax https://viewmax.studio/api/mcp \
  --header "Authorization: Bearer $VIEWMAX_API_KEY"

如需在项目中共享，提交 .mcp.json。Claude Code 会从每位开发者的环境中展开 ${VIEWMAX_API_KEY}：

{
  "mcpServers": {
    "viewmax": {
      "type": "http",
      "url": "https://viewmax.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VIEWMAX_API_KEY}"
      }
    }
  }
}

Cursor。 添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json），然后重新加载 Cursor：

{
  "mcpServers": {
    "viewmax": {
      "url": "https://viewmax.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VIEWMAX_API_KEY}"
      }
    }
  }
}

Codex（ChatGPT）。 Codex 从指定的环境变量读取 key：

codex mcp add viewmax --url https://viewmax.studio/api/mcp \
  --bearer-token-env-var VIEWMAX_API_KEY

等价的 ~/.codex/config.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 并安全保存：

{
  "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 相同。

Agent 工作流

选择模型。 调用对应的 list_* 工具，再对选定的模型调用 get_video_model 或 get_image_model，读取其模式、可用取值、defaults 和 max_prompt_length。
确认成本。 根据目录价格和将要发送的取值（或模式的 defaults）算出积分，告诉用户将使用的模型和成本，并在调用任何 generate_* 前等待确认。get_credits 可查看余额。
只创建一次。 调用 generate_* 工具时带上新的 idempotency_key，例如为本次请求生成的 UUID。
轮询。 如果 status 为 pending 或 processing，用 task_id 调用 wait_for_task；只要结果中还有 poll_hint 就继续调用。视频可能需要几分钟。Server 没有任务超时，任务也不会丢失：请自行设定截止时间，之后可用 get_task 继续查询。音乐、语音和音效通常在创建调用中即完成。
返回结果。 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 的文本块：

{
  "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 创建
`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`	余额低于成本，未创建任务	告知用户。在定价页充值前不要重试
`not_found`	`task_id` 不存在或属于其他账户	使用本账户返回的 `task_id`
`internal_error`	服务商或服务器故障	按 `hint` 处理：任务已失败并退款时重试一次；服务商可能仍会完成时，用 `task_id` 调用 `wait_for_task`，不要新建任务

超出工具输入 schema 的参数（例如 timeout_seconds: 120）会在工具运行前被拒绝，返回纯文本 Input validation error: ...。共享的错误分类见 API 错误。