PopNow API

PopNow Developer MCP 服务：通过 Claude Code、Cursor、Codex 和自己的代码调用任意 AI 图像、视频和音频模型

PopNow Developer MCP 服务是面向开发者的托管式模型上下文协议服务，地址为 https://api.popnow.ai/api/v1/mcp。使用 PopNow API 密钥将其添加到 Claude Code、Cursor、Codex、VS Code 或自己的 MCP 客户端后，Agent 即可通过一个连接创建图像、视频、音乐和配音，按 API ID 运行任意模型、跟踪任务并安装 Agent 技能。

无需自行托管。每次付费调用都会先以美元报价，只有在你批准后才会从你的 API 余额中扣费。密钥的模型允许列表、IP 允许列表和支出上限，与 PopNow REST API 完全一致。

此仓库包含设置指南、examples/ 中可直接复制粘贴的客户端配置、MCP 注册表清单，以及 @popnow/mcp——一个供只能启动本地服务的客户端使用的小型 stdio 桥接程序。

想在 ChatGPT 或 Claude 应用中使用 PopNow 账户和网站额度？请改用 popnow-mcp 和 popnow.ai/mcp。

目录

• 概览
• 快速入门
• 连接客户端：Claude Code · Cursor · VS Code · Windsurf · Codex · Cline · Claude Desktop 和仅支持 stdio 的客户端 · 其他客户端 · 在自己的代码中使用
• 工具
• 美元报价与审批
• 结果与长时任务
• 限制
• 从旧地址迁移
• stdio 桥接程序（@popnow/mcp）
• 故障排除
• 常见问题

概览

端点	https://api.popnow.ai/api/v1/mcp
传输方式	Streamable HTTP，无状态（POST；GET 和 DELETE 返回 405）
身份验证	使用来自 API 控制台的密钥，通过 Authorization: Bearer sk-popnow-... 进行身份验证。此端点不支持 OAuth 登录
计费	从你的 API 余额中扣除美元。每次付费调用都会先返回报价，并且只有设置 max_usd 才会执行
密钥规则	密钥的模型允许列表、IP 允许列表，以及每日、每月和终身支出上限
工具	媒体工具、用于任意模型 ID 的 create_task、任务、余额、已保存的配方和 Agent 技能（完整列表）
服务名称	popnow-api

快速入门

1. 创建 API 密钥，前往 API 控制台 操作。为 Agent 单独创建一个设有较低每日限额的密钥是个好习惯：撤销该密钥时不会影响其他集成。如果 API 余额为 $0，请前往 API 账单充值。
2. 将密钥放入环境变量。 以下配置会从 POPNOW_API_KEY 读取密钥，因此它不会出现在你提交的文件中：

   export POPNOW_API_KEY="sk-popnow-..."
   

3. 添加服务。 在 Claude Code 中只需运行一条命令：

   claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
     --header "Authorization: Bearer $POPNOW_API_KEY"
   

4. 提出需求。 让 Agent 生成图像、短片或配乐。它会选择一个 PopNow 工具，向你显示以 USD 计价的价格，并在你批准后运行。

连接客户端

以下每个客户端都会使用 API 密钥连接到同一个远程服务。现成的配置文件位于 examples/。

Claude Code

claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
  --header "Authorization: Bearer $POPNOW_API_KEY"

运行命令时，Shell 会填入 $POPNOW_API_KEY，Claude Code 会将标头保存在本地 MCP 设置中。如果要通过项目的 .mcp.json 与团队共享服务，请改用通用配置：Claude Code 会从每个人的环境中展开 ${POPNOW_API_KEY}。

Cursor

将 PopNow 添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以用于所有项目（examples/cursor.mcp.json）：

{
  "mcpServers": {
    "popnow-api": {
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

VS Code

VS Code 将顶层键命名为 servers。此配置会提示你输入一次密钥，并安全地保存它（examples/vscode.mcp.json）：

{
  "inputs": [
    { "type": "promptString", "id": "popnow-api-key", "description": "PopNow API key (sk-popnow-...)", "password": true }
  ],
  "servers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:popnow-api-key}" }
    }
  }
}

Windsurf

远程服务在 ~/.codeium/windsurf/mcp_config.json 中使用 serverUrl（examples/windsurf.mcp_config.json）。保存后，在 MCP 面板中点击 Refresh。

{
  "mcpServers": {
    "popnow-api": {
      "serverUrl": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

Codex

编辑 ~/.codex/config.toml（examples/codex.config.toml）；bearer_token_env_var 会从环境变量中读取密钥：

[mcp_servers.popnow-api]
url = "https://api.popnow.ai/api/v1/mcp"
bearer_token_env_var = "POPNOW_API_KEY"

Cline

打开 MCP Servers → Configure，并将 PopNow 添加到 cline_mcp_settings.json。请明确将 type 设为 streamableHttp；否则 Cline 会回退到旧版 SSE 传输方式（examples/cline_mcp_settings.json）：

{
  "mcpServers": {
    "popnow-api": {
      "type": "streamableHttp",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk-popnow-..." },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop 和仅支持 stdio 的客户端

只能启动本地 stdio 服务的客户端可以通过 npx 运行 @popnow/mcp 桥接程序。从 0.2.0 版本起，它默认连接到开发者端点。在 Claude Desktop 中，编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json），然后重启应用（examples/claude-desktop.json）：

{
  "mcpServers": {
    "popnow-api": {
      "command": "npx",
      "args": ["-y", "@popnow/mcp"],
      "env": { "POPNOW_API_KEY": "sk-popnow-..." }
    }
  }
}

桥接程序需要 Node.js 18 或更高版本。

其他客户端

大多数支持远程 MCP 服务的客户端都接受此格式。这也是 Claude Code 项目 .mcp.json 的格式（examples/generic.json）。在将密钥粘贴到任何会被提交的文件之前，请先确认客户端如何读取环境变量。

{
  "mcpServers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${POPNOW_API_KEY}" }
    }
  }
}

从自己的代码调用

使用官方 Python SDK（pip install mcp）：

import asyncio, os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['POPNOW_API_KEY']}"}
    async with streamablehttp_client("https://api.popnow.ai/api/v1/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("check_balance", {})
            for part in result.content:
                print(part.type, getattr(part, "text", ""))

asyncio.run(main())

使用官方 TypeScript SDK（npm install @modelcontextprotocol/sdk）：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.popnow.ai/api/v1/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.POPNOW_API_KEY}` } },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({ name: 'check_balance', arguments: {} });
console.log(result.content[0].text);
await client.close();

也可以只用 curl。该服务是无状态的，因此每个请求都可独立处理；请在 Accept 中发送这两种媒体类型。此调用会请求报价，不会产生费用：

curl -X POST "https://api.popnow.ai/api/v1/mcp" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_task", "arguments": {"model": "google/nano-banana-2.1/text-to-image", "input": {"prompt": "A paper boat on a rainy window sill, soft morning light", "aspect_ratio": "4:5"}}}}'

对于直接调用模型的生产代码，REST API 可让你更好地控制：Webhook、幂等键和按任务设置的保留策略。SDK：Python · JavaScript / TypeScript · Go · Java · PHP。

工具

典型价格基于默认模型和设置，以 USD 计价。每项付费工具都会在运行前报出确切金额。完整参数参考见 开发者 MCP 文档。

工具	功能	默认值	典型价格
create_image	根据描述生成新图片	Nano Banana 2.1、1K、正方形	约 $0.048
edit_image	用文字修改照片：风格、服装、背景，以及添加或移除内容	Nano Banana 2.1	约 $0.048
create_video	根据描述生成短视频，或让照片动起来	MiniMax H3、768p、5 秒	约 $0.185
create_music	创作原创歌曲或纯音乐	Suno v6	约 $0.072
create_speech	用多种声音和语言朗读文本	Gemini 3.8 Flash TTS，声音 Kore	按长度计费，不到一美分
apply_effect	将照片制作成特效视频，或美化照片	特效专用模型	视频 $0.125 至 $0.34，照片 $0.03 至 $0.05
remove_background	抠出主体并生成透明 PNG	Background Remover	$0.0048
upscale	提高清晰度并放大照片或视频	照片 4K、视频 1080p	照片约 $0.012；视频按长度计费
add_sound	为静音视频添加匹配的音效和环境音	工具专用模型	运行前报价
extend_video	延续视频最后一帧之后的内容	minimax-h3	运行前报价
edit_video	用文字编辑视频，同时保留其动态效果	kling-o3	运行前报价
copy_motion	根据视频中的动作让角色图片动起来	kling-3-0	运行前报价
create_video_from_references	生成保留参考图片中主体的视频	minimax-h3	运行前报价
transcribe_audio	将录制的语音转换为文本	grok-stt	运行前报价
create_sound_effects	根据描述生成音效、环境音和语音台词	seed-audio-1-0	运行前报价
split_layers	将图片拆分为可编辑的透明 PNG 图层	seedream-5-0-pro	运行前报价
erase_object	移除物体或人物并填补空缺	object-eraser-v1	运行前报价
expand_image	将照片扩展至原有边缘之外	image-expander-v1	运行前报价
change_camera_angle	从不同视角展示场景	camera-angle-changer-v1	运行前报价
change_pose	使人物姿势与参考图片一致	pose-changer-v1	运行前报价
relight_photo	改变照片的光照	relight-v1	运行前报价
remove_shadow	移除照片中的生硬阴影	shadow-remover-v1	运行前报价
anime_to_real	将动漫或卡通图片转换为照片级写实图像	anime-to-real-v1	运行前报价
compose_video	将先前的结果剪辑成一段完整的 MP4，可选添加音乐、旁白、字幕和标题		免费
get_job	检查仍在运行的任务，并在任务就绪时返回结果	最多等待 30 秒	免费
list_my_creations	使用此密钥创建的最近任务及其链接	最近 10 项	免费
check_balance	可用的 API 余额，以及运行中任务占用的资金，单位为 USD		免费
list_models	图片、视频和音频模型及其准确的 API ID，或所有特效；指定 model 时，返回该模型的输入参数	image	免费

只有公开 model 参数的工具才接受来自 list_models 的模型；省略该参数则使用默认模型。所有工具都带有标准 MCP 提示（readOnlyHint、destructiveHint、openWorldHint），且没有工具会删除任何内容。

开发者工具。 此端点上仅有四项工具：

工具	功能	参数
create_task	使用模型的准确 API 模型 ID 和模型自身的 input 运行任意模型，类似 REST API 中的 createTask	model（必填，例如 google/nano-banana-2.1/text-to-image）、input、max_usd、currency
get_task	与 get_job 相同：检查任务并获取结果	job_id（必填）、wait_seconds（0 到 50，默认 30）
list_tasks	与 list_my_creations 相同：列出使用此密钥创建的近期任务	kind（image、video、audio）、limit（1 到 20，默认 10）
install_skill	获取你选定的 Agent 技能：操作手册、短时有效的下载链接，以及适用于你的 Agent 的安装命令	slug（必填）、agent

调用 list_models 并传入 category，即可查看每个模型的准确 ID；再传入 model，即可查看该模型的输入参数。create_task 会在报价前根据模型的架构验证 input，因此缺少或未知的字段会以消息形式返回，不会产生费用。

已保存的配方和技能。 list_my_recipes、run_my_recipe、get_recipe_run、resume_recipe_run、list_my_skills 和 use_my_skill 可访问你在 popnow.ai 上保存的配方、画布工作流和技能，并采用相同的 USD 报价和审批流程。请参阅你的配方、工作流和技能。

Agent 技能。 find_skills 会返回一些符合请求的 Agent 技能（预览视频、封面图片，以及每项技能所需的内容）；install_skill 会返回所选技能的 SKILL.md、短时间内有效的软件包链接、适用于你的 Agent 的安装命令，以及该技能使用哪些 PopNow 工具生成媒体。这两项操作均免费且只读。查看更多技能：popnow-skills。

以 USD 报价并审批

1. 报价。 不带 max_usd 调用付费工具。任务不会启动，也不会冻结余额。结果中会包含 needs_confirmation: true、currency: "USD"、cost_usd 和 available_usd。
2. 审批。 向用户展示价格。用户批准后，使用相同参数再次调用工具，并将报价中的 cost_usd 设为 max_usd。
3. 运行。 如果当前价格不超过 max_usd，任务就会启动。如果价格上涨，则会返回新的报价供审批；不会扣款。

max_usd 必须是非负十进制字符串，最多包含九位小数，例如 "0.012345678"。JSON 数字、指数表示法和负值均会被拒绝。currency 为可选参数，且只能是 USD。每次付费调用都需要审批，包括价格为零的报价；没有自动审批阈值。

如果余额不足以支付报价，工具会返回 "Not enough API balance"，并注明费用和可用余额，不会扣款。任务遵循与 REST 任务相同的规则：任务启动时会冻结可能产生的最高费用，实际费用按实际用量计算（不会超过冻结金额）；任务失败或过期时会释放冻结金额。同一密钥在十秒内发起的相同调用只会创建一个任务，因此 Agent 重试也不会重复付费。

You:    Make a 9:16 clip of a vintage car cruising along the coast at golden hour, 10 seconds.
Agent:  (calls create_video → "Needs confirmation, nothing started yet. This costs $0.37 USD; API balance available: $12.40 USD.")
        That's $0.37 from your PopNow API balance. Go ahead?
You:    Yes.
Agent:  (calls create_video again with max_usd: "0.37" → job_id, then get_task)
        Done: coast.mp4. It's in your API logs too.

结果和长时间任务

• 图片会以预览和下载链接的形式返回。视频和音频会以链接的形式返回。
• 下载链接经过签名，会在一段时间后过期。每个结果还包含一个永不过期的 popnow://g/<job>/<n> 链接，可传递给其他工具，因此“现在为那张图片添加动画”这样的操作可以直接使用。
• 工具最多等待约 40 秒以获取结果。视频通常耗时更长，因此回复中会附带 job_id，由 Agent 调用 get_task 获取结果。
• 每个任务都会显示在 API 控制台的日志中，其中包含密钥、模型和 USD 金额。

限额

项目	限额
每个账户的工具调用次数（包括 get_task 轮询）	每分钟 240 次
每个账户的新任务数	每分钟 20 个
每个账户的 find_skills / install_skill 调用次数	每小时 240 / 120 次

超过限额的任务不会收费；工具会告知需要等待多少秒。密钥的支出上限适用于每次调用。REST API 的限额彼此独立，详见速率限制。

从旧地址迁移

在 2026 年 11 月 1 日之前，API 密钥连接到 https://api.popnow.ai/mcp。该地址会继续接受 API 密钥，直到 2027 年 1 月 31 日（00:00 UTC），并提供相同的开发者工具；每个响应都会包含 Deprecation、Sunset 和 Link 标头。此后，该地址会对 API 密钥返回 401。

如需迁移，请将 MCP 配置中的 URL 改为 https://api.popnow.ai/api/v1/mcp。密钥、工具和 USD 计费方式均保持不变。如果你运行 stdio 桥接程序，请升级到 @popnow/mcp 0.2.0 或更高版本（npx -y @popnow/mcp 会自动获取该版本），或将 POPNOW_MCP_URL 设置为新地址。

stdio 桥接程序（@popnow/mcp）

packages/popnow-mcp 是一个精简的 TypeScript 软件包（可执行文件为 popnow-mcp），供只能启动本地 stdio 服务的 MCP 客户端使用。它将 StdioServerTransport 连接到官方 MCP SDK 提供的 StreamableHTTPClientTransport，并原样转发每条消息，因此工具和价格始终与实时服务一致。该软件包以 @popnow/mcp 的名称发布在 npm 上；配置请参阅 Claude Desktop 和仅支持 stdio 的客户端。

环境变量	必需	说明
POPNOW_API_KEY	是	PopNow API 密钥（sk-popnow-...），以 Bearer 令牌形式发送
POPNOW_MCP_URL	否	远程端点，默认值为 https://api.popnow.ai/api/v1/mcp

如需改为从源代码构建并运行（Node.js 18 或更高版本）：

git clone https://github.com/popnow-ai/popnow-api-mcp.git
cd popnow-api-mcp
npm --prefix packages/popnow-mcp install
npm --prefix packages/popnow-mcp test    # builds with tsc, then runs an end-to-end test against a local fake server
node packages/popnow-mcp/dist/cli.js --help

MCP 注册表清单

server.json 按照 MCP 注册表格式（架构版本 2025-12-11），将此服务描述为 io.github.popnow-ai/popnow-api-mcp：包含必需的 Authorization 标头的远程 Streamable HTTP 端点，以及 @popnow/mcp npm 软件包。

故障排查

你看到的内容	原因	解决方法
401 "This endpoint takes PopNow API keys"	没有 Authorization 标头，或使用了登录令牌而非 API 密钥	使用有效的 sk-popnow- 密钥发送 Authorization: Bearer
401 "This API key isn't valid"	密钥错误、已撤销或已过期	在 API 控制台中创建密钥
403 或关于密钥的工具错误	密钥的模型或 IP 允许列表阻止了此次调用	在 API 控制台中调整密钥限制
Needs confirmation, nothing started yet	工具正在先行报价	批准后，使用 max_usd 重复调用
"Not enough API balance"	API 余额不足以支付报价	在 API 计费中充值，或选择更便宜的模型或更短的视频
支出上限提示	此次调用将超出某项密钥上限	提高上限或等待其重置
"Too many creations at once. Nothing was charged."	一分钟内创建了超过 20 个新任务	等待提示中所示的秒数
405 Method Not Allowed	向端点发送了 GET 或 DELETE；该服务是无状态的	使用 POST
Cline 已连接但无法正常工作	缺少 type，因此 Cline 使用了旧版 SSE	设置 "type": "streamableHttp"

常见问题

MCP 服务需要额外付费吗？

不需要。连接是免费的，list_models、get_task 和 find_skills 等读取工具也免费。媒体任务会按与 REST API 相同的模型价格扣除 API 余额，并且每项任务都会先报价。

我可以使用 OAuth 而不是 API 密钥连接吗？

不可以。此端点仅接受 API 密钥，因此每次调用都会从 API 余额中扣费，并受密钥的限制和额度上限约束。要在 ChatGPT 或 Claude 应用中使用 PopNow 账户，请参阅 popnow-mcp。

我可以调用哪些模型？

list_models 中的所有图像、视频和音频模型，包括 Kling、Seedance、Wan、Vidu、MiniMax、Nano Banana、GPT Image、Flux 和 Suno。create_task 可使用其中任意模型的准确 API ID，并传入该模型专属的输入；命名工具则以合理的默认值覆盖常见任务。

需要安装什么吗？

不需要。该服务是远程服务，你只需添加其地址即可。只能启动本地 stdio 服务的客户端可以通过 npx -y @popnow/mcp 运行桥接程序。

结果会到哪里？

结果会以链接的形式返回在工具响应中。每项任务也会显示在 API 控制台的日志中，list_tasks 则会列出此密钥最近的任务。

链接

• 开发者 MCP：popnow.ai/api/mcp · 文档 · API 控制台 · API 计费
• REST API：快速入门 · API 参考 · 模型
• 其他 PopNow 开发者仓库：popnow-skills · popnow-cli · popnow-python · popnow-js · popnow-api

参与贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。有关安全问题，请参阅 SECURITY.md。

许可证

MIT © PopNow