远程 MCP 服务

为确保技术标识和代码可直接复制，详细协议参考及代码示例保留英文。

byheai 远程 MCP server 让 Claude、Cursor、Codex 和 ChatGPT 等 Agent 能原生生成和查看图片——无需自行处理 HTTP、无需客户端库，也无需胶水代码。只需将 Agent 指向一个 URL 并填入 API key，REST API 提供的五项能力就会以可由 Agent 自主调用的一等工具形式出现。

端点：

https://www.byheai.com/api/mcp

这是一个使用 streamable HTTP 的远程 MCP server。该路径的 GET、POST 和 DELETE 都由同一个 handler 响应——客户端无需关心其中区别。

连接信息

• URL: https://www.byheai.com/api/mcp
• Transport: streamable HTTP（不使用 stdio 或 SSE）
• Auth: Authorization: Bearer YOUR_API_KEY header
• Tool prefix: getimages_

可用工具：

• getimages_generate_image — 根据 Prompt 生成图片，会消耗 credits。
• getimages_list_images — 分页列出你生成过的图片。
• getimages_get_image — 按 id 获取单张图片，可选择是否带字节。
• getimages_get_account — 获取你的 user id、email 和 credit balance。
• getimages_list_usage — 分页列出 credit transaction history。

MCP 与 REST API 使用同一组 API key。可在 Dashboard 创建和管理它们。

获取 API key

1. 登录 byheai。
2. 打开 Dashboard > API keys。
3. 点击 Create key，设置便于识别的名称，并复制完整密钥。完整密钥只会显示一次。

key 的形式为 sk_...。请像对待密码一样保管它。你可以在同一页面单独撤销任意 key，而不会影响其他 key。

配置客户端

所有客户端的配置结构相同：一个位于 https://www.byheai.com/api/mcp 的 HTTP MCP server，并带有 Authorization: Bearer YOUR_API_KEY header。不同之处仅在外围文件格式和配置键名。请将 YOUR_API_KEY 替换为你在 Dashboard 创建的密钥。

在下方选择你的客户端——每个部分都会展开精确的配置片段及其放置位置。

claude mcp add --scope user --transport http get-images https://www.byheai.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

[mcp_servers.get-images]
url = "https://www.byheai.com/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
enabled = true

[mcp_servers.get-images]
url = "https://www.byheai.com/api/mcp"
bearer_token_env_var = "GET_IMAGES_API_KEY"
enabled = true

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "context_servers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "get-images": {
      "type": "http",
      "url": "https://www.byheai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

验证连接

客户端重新加载后，可以尝试两个快速 Prompt：

1. 询问 Agent：“Get my account balance from get-images.” Agent 应调用 getimages_get_account，并报告你的 email 和 credit balance。
2. 询问 Agent：“Generate an image of a corgi at sunset.” Agent 应以合理的 model 和 aspect ratio 调用 getimages_generate_image，然后内联显示图片。

如果两项都能正常完成，说明配置已生效。

将图片保存到磁盘

getimages_generate_image 和 getimages_get_image 都会在 structuredContent 中包含 imageUrl field。它是带 15 分钟 TTL 的 absolute signed URL。任意 HTTP client 都可以获取它——无需 Authorization header 或 API key。过期或签名被篡改后，URL 会返回 404。

方案 A — 通用 HTTP client（curl、PowerShell 等）

# After calling getimages_generate_image:
# 1. Read structuredContent.imageUrl from the response
# 2. Fetch and save:
curl -o my-image.jpg "<imageUrl>"

PowerShell 等效命令：

Invoke-WebRequest -Uri "<imageUrl>" -OutFile my-image.jpg

方案 B — 使用 WebFetch-style tool 的 AI agents

1. 调用 getimages_generate_image 并记录 structuredContent.imageUrl。
2. 使用 HTTP-fetch tool 下载 URL（不需要 auth header）。
3. 将字节写入磁盘。

请在原始调用后的 15 分钟内获取 URL。之后请针对相同 image id 使用 getimages_get_image 请求新的 URL。

故障排除

• 401 Unauthorized — API key 缺失、无效、已被撤销，或你的账户短暂触发了 rate limit（默认 60 requests/minute）。稍后重试；若仍持续，请在 Dashboard 中检查 key，必要时重新签发。
• Moderation rejection — OpenAI 的 models 会拒绝引用真实公众人物、受版权保护角色或其他受限内容的 Prompt。请将 Prompt 改写得更通用后重试。
• “Tool not found” — 编辑 config 后客户端尚未重新加载。请完全退出并重新打开 app，或从 command palette 运行客户端的 “reload MCP servers” command。
• 图片没有显示在 chat 中 — 某些 client 只渲染 text content block，无法内联显示 MCP image block。图片仍在 response 内，也可通过 structuredContent 与 getimages_get_image 获取。如果内联预览很重要，请尝试支持 image rendering 的 client（Claude Desktop、Cursor、Claude Code、Zed）。
• 生成似乎很慢 — 大型 model（Gemini 3 Pro Image、GPT Image 2）和 deep-thinking mode 耗时更长。fast tier（Gemini 2.5 Flash Image、GPT Image 1.5）明显更快。
• “Operation timed out” 但图片出现在 Dashboard — MCP client 在 server 响应前已放弃。server 每次调用最多等待约 13 分钟，并每 10s 发送一次 notifications/progress；更新的 MCP client 会在每次进度消息后重置 timeout。若仍超时，请提高客户端 MCP timeout（Claude Code：export MCP_TIMEOUT=900000，即 15 分钟）。即使原始 generate_image 调用在 client 端看似失败，图片始终可以通过 getimages_get_image 获取。

工具参考

getimages_generate_image

根据文本 Prompt 生成图片，并将其作为 MCP image content block 连同 structured metadata 返回。

Credits cost。 每次成功调用都会不可逆地从调用者账户计费。基础 credit cost 取决于 model：

• openai:gpt-image-1.5 — 3 credits
• openai:gpt-image-2 — 5 credits
• google:gemini-2.5-flash-image — 3 credits
• google:gemini-3.1-flash-image-preview — 5 credits (7 with deep thinking)
• google:gemini-3-pro-image-preview — 12 credits (18 with deep thinking)

输入：

• prompt (string, required) — 1 到 8,000 个字符。
• modelId (string, required) — 上述 model id 之一。
• aspectRatio (string, optional) — 1:1、3:2、2:3、16:9、9:16、4:3、3:4。Gemini 3 Pro Image model 还支持 21:9。
• style (string, optional) — 附加到 Prompt 的简短 style instruction。
• thinkingLevel (default | deep, optional) — 仅 google:gemini-3.1-flash-image-preview 和 google:gemini-3-pro-image-preview 支持。deep 使用上方较高的 credit cost。

返回：

• 一个包含生成字节（base64）及正确 mimeType 的 MCP image content block。
• 一个简短 text content block，用于概述本次 charge 与 remaining balance。
• 一个 structuredContent object，包含 id、modelId、providerId、aspectRatio、style、thinkingLevel、mediaType、credits.charged、credits.remaining、createdAt 和 imageUrl。为降低 context cost，base64 bytes 不会重复出现在 structuredContent 中。
• imageUrl — 指向生成图片的 absolute URL，带 short-lived（15-minute TTL）signed URL。任意 HTTP client 都可以获取它——不需要 authentication header。请将其视为一次性 download link，不要储存或分享。

注意事项：

• Moderation rejection 会以 tool error 及说明性 message 返回——Agent 应读取 message 并改写 Prompt。
• 如果账户没有足够 credits，工具会返回 insufficient_credits error，且不会生成图片。

getimages_list_images

按从新到旧顺序返回调用者此前的 generations。只读。

输入：

• limit (integer, optional) — 1 到 100，默认 20。
• offset (integer, optional) — 非负数，默认 0。

返回带有 images、total、limit 和 offset 的 structuredContent。每个 image entry 包含其 id、prompt、model、aspect ratio、style、thinking level、media type、credit cost 和 creation timestamp。不包含 bytes——需使用 getimages_get_image 并传入 includeBytes:true 获取。

getimages_get_image

按 id 获取一张图片。只读。

输入：

• id (UUID, required) — 来自 getimages_list_images 或 getimages_generate_image 的 image id。
• includeBytes (boolean, optional, default false) — 为 true 时，response 还会包含图片对应的 MCP image content block。

在 structuredContent.image 中返回 metadata，并在 structuredContent.imageUrl 中返回指向图片的 absolute URL。该 URL 是带 short-lived（15-minute TTL）的 signed URL。任意 HTTP client 都可获取它——不需要 authentication header。请将其视为一次性 download link，不要储存或分享。当 includeBytes 为 true 时，response 还会包含 image content block；bytes 不会重复出现在 structuredContent 中。

getimages_get_account

返回已验证调用者的 account info。只读，无输入。

在 structuredContent 中返回 userId、email 和 creditBalance。同时还会提供一条简短的 text summary，供 Agent 展示给用户。

它适合在生成前检查：Agent 可以读取 balance，判断下一次 generation 是否有足够额度，并在必要时提醒用户。

getimages_list_usage

按从新到旧顺序返回调用者的 credit transaction history（generation 扣费、refund、purchase 添加）。只读。

输入：

• limit (integer, optional) — 1 到 100，默认 20。
• offset (integer, optional) — 非负数，默认 0。

返回带有 transactions、total、limit 和 offset 的 structuredContent。每条 transaction 包含 id、amount、type、description、referenceId 和 createdAt。

安全使用

远程 MCP server 会把一组强大的工具交给驱动 session 的 Agent。请注意以下事项：

• 会自动执行 tool 的 Agent 可能在未询问的情况下消耗 credits。 如果你的 client 或 Agent 开启了 “run tools without confirmation” mode，getimages_generate_image 可能被重复调用，且每次调用都会不可逆计费。请配置 Agent 在生成前确认，或只对只读工具启用自动 tool-use。
• Content moderation 可能拒绝某些 Prompt。 OpenAI 的 models 会拒绝引用真实公众人物、受版权保护角色、性内容或其他受限类别的 Prompt。出现这种情况时，tool 会返回明确的 moderation message——改写 Prompt 以避免被标记的内容后重试。
• 不要将 API key 粘贴到共享 chat、公开 repo 或 pastebin。 key 会授予账户完整访问权限，包括消耗 credits。
• 怀疑泄露时轮换 key。 创建新 key、更新客户端配置，然后从 Dashboard 撤销旧 key。
• 支持逐 key 撤销。 每个 client 可使用自己的 key，这样就能撤销单台机器的访问权限而不影响其他机器。
• 每次调用都会记录 credit transaction。 你可以随时通过 getimages_list_usage 或 Dashboard 审计用量。

Credits 和定价

Credit packs 与按 model 计费价格请见定价页面。REST API、MCP server 与 Dashboard UI 共用同一 balance——无论通过何种 transport，所有成功 generation 都会扣除 credits。