SDK、命令行工具与开源工具

PopNow 为开发者发布的工具都在 GitHub 的 popnow-ai 组织下开源，采用 MIT 许可证。SDK 封装的就是这些文档描述的 REST API，所以每一页仍然适用：同样的模型 ID、同样的 input 字段、同一份 API 美元余额。

这些包已发布到 PyPI、npm、Packagist、Maven Central 和 Comfy Registry；请使用本页给出的命令安装。原生 HTTP 调用同样可用，本文档中的每个示例都使用 curl、fetch 或 requests。

概览

每个工具都需要一把来自 API 控制台的 API 密钥。把它放进 POPNOW_API_KEY；SDK 和命令行工具都从这里读取：

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

Python SDK

popnow-python 提供同步客户端（PopNow）和异步客户端（AsyncPopNow），返回带类型的结果，自动附带 Idempotency-Key 请求头，在 429 和 503 时自动重试，并支持文件上传、素材库以及 Webhook 签名校验。它需要 Python 3.9 或更新版本，仅依赖 httpx。

pip install popnow

from popnow import PopNow

client = PopNow()  # reads POPNOW_API_KEY

task = client.images.generate(
    model="alibaba/z-image-turbo/text-to-image",
    prompt="A small red fox curled up in a teacup, soft morning light",
)
print(task.state, task.cost, "USD", task.urls[0])

images.generate 会创建任务、等待其完成；如果任务没有成功，则抛出 TaskFailedError。更底层的 client.jobs.quote()、create()、get() 和 wait() 与任务接口一一对应。

JavaScript 和 TypeScript SDK

popnow-js 没有运行时依赖，使用全局的 fetch，因此可以在 Node.js 18+、Deno、Bun、Cloudflare Workers 以及其他边缘运行时上运行。它同时提供 ESM 和 CommonJS 构建，并附带类型定义。

npm install popnow

在 Deno 和 Bun 上，它也发布在 JSR 上：deno add jsr:@popnow/popnow 或 npx jsr add @popnow/popnow。

import { PopNow } from 'popnow';

const popnow = new PopNow(); // reads POPNOW_API_KEY

const task = await popnow.jobs.createAndWait({
  model: 'alibaba/z-image-turbo/text-to-image',
  input: { prompt: 'A small red fox curled up in a teacup, soft morning light' },
});
console.log(task.state, task.output?.assets?.[0]?.url);

createAndWait 会替你发送 Idempotency-Key，并轮询直到任务进入终态。如果你想先报价，或者想在别处等待，可以使用 jobs.quote、jobs.create 和 jobs.wait。

命令行

popnow-cli 会安装一个 popnow 命令，适用于脚本、CI 任务以及在终端中快速测试。它需要 Node.js 22.12 或更新版本：

npm install -g @popnow/cli
popnow --help

如果只想临时运行一次而不安装：npx @popnow/cli status。

Go 和 PHP

popnow-go 是一个普通的 Go 模块（需要 Go 1.23+）：

go get github.com/popnow-ai/popnow-go

popnow-php（需要 PHP 8.1+）即 Packagist 上的 popnow/popnow：

composer require popnow/popnow

Java

popnow-java 是面向 Java 17+、Kotlin 及其他 JVM 语言的客户端，以 ai.popnow:popnow-java 的形式发布在 Maven Central 上。它唯一的依赖是 Jackson databind；HTTP 通过 JDK 自带的 HttpClient 发送。

<dependency>
  <groupId>ai.popnow</groupId>
  <artifactId>popnow-java</artifactId>
  <version>0.1.0</version>
</dependency>

dependencies {
    implementation("ai.popnow:popnow-java:0.1.0")
}

import ai.popnow.*;
import java.util.Map;
import java.util.UUID;

PopNowClient client = PopNowClient.builder().apiKeyFromEnvironment().build(); // POPNOW_API_KEY

CreateTaskRequest request = CreateTaskRequest.of("alibaba/z-image-turbo/text-to-image",
        Map.of("prompt", "A small red fox curled up in a teacup, soft morning light"));

TaskRecord task = client.run(request, UUID.randomUUID().toString()); // createTask + waitForTerminal
System.out.println(task.state() + " for " + task.cost() + " USD");

run 会使用你传入的 Idempotency-Key 创建任务，并等待其进入终态；如果你想把这两步分开，可以使用 createTask 和 waitForTerminal。

MCP 与 Agent 技能

远程 MCP 服务器不需要安装任何包：在 ChatGPT、Claude、Cursor、VS Code 或 Claude Code 中添加 https://api.popnow.ai/mcp 即可。popnow-mcp 为每个客户端提供可直接复制粘贴的配置，并为只能启动本地服务器的客户端提供一个小型 stdio 桥接程序。这个桥接程序已发布到 npm，包名为 @popnow/mcp，因此 npx -y @popnow/mcp 无需安装步骤即可运行。

popnow-skills 教编程 Agent 使用 REST API 制作视频、图片、音乐和配音，并查阅 API 参考。在 Claude Code 中：

/plugin marketplace add popnow-ai/popnow-skills
/plugin install popnow@popnow-skills

README 中包含 Codex、Claude 应用及其他 Agent 的说明。

示例与集成

• popnow-api 包含 OpenAPI 文件、可直接运行的 curl、Python 和 Node.js 示例，以及一个可导入的 n8n 工作流。如果你需要其他语言的客户端，可以把 OpenAPI 文件交给代码生成器处理。
• popnow-blender 是 Blender 插件的源码。安装时请从 popnow.ai/blender 下载 zip；该仓库也可以构建出同样的 zip。
• popnow-comfyui 是发布在 Comfy Registry 上的 ComfyUI 节点包：每个模型一个节点，外加 PopNow Generate 和 PopNow LoRA。在 ComfyUI Manager 中打开 Custom Nodes Manager，搜索 PopNow 并点击 Install，或运行 comfy node install popnow-comfyui。如果你更喜欢一个一分钟就能读完的文件，ComfyUI 页面提供了完整步骤和单文件节点。
• n8n-nodes-popnow 是发布在 npm 上的 n8n 社区节点，适用于自托管的 n8n。打开 Settings > Community Nodes > Install 并输入 n8n-nodes-popnow，或在命令行中安装后重启 n8n。它还不是认证节点，所以 n8n Cloud 无法安装；HTTP Request 工作流无需安装，在那里同样可用。
• popnow-proxy 是一个小型服务端路由，适用于 Next.js、Express 以及其他使用 fetch 的运行时。浏览器、移动或桌面应用调用你的服务器，代理在服务器上附加 API 密钥，因此密钥永远不会出现在客户端。它需要 Node.js 22.12 或更新版本。
• popnow-bot 是一个你自己用 Docker 运行的 Telegram 和 Discord 机器人：可以在聊天中生成图片、视频和视频特效，付费运行前会先查询价格，并支持每日消费限额。克隆仓库后运行 docker compose up -d --build 即可启动，也可以直接拉取 Docker Hub 上预构建的 popnow/popnow-bot 镜像。

# n8n community node, from a shell on self-hosted n8n
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install n8n-nodes-popnow

# server-side proxy
npm install @popnow/proxy

有官方的 PopNow SDK 吗？

有。本页提到的 Python 和 JavaScript SDK、命令行工具，以及 Go、PHP 和 Java 客户端，都由 PopNow 维护，并在 github.com/popnow-ai 下开源。

SDK 发布在 npm 或 PyPI 上吗？

是的。pip install popnow 从 PyPI 安装 Python SDK，npm install popnow 从 npm 安装 JavaScript SDK。命令行工具是 npm 上的 @popnow/cli，PHP 客户端是 Packagist 上的 popnow/popnow，Java 客户端是 Maven Central 上的 ai.popnow:popnow-java，ComfyUI 节点包是 Comfy Registry 上的 popnow-comfyui。每个仓库的 CHANGELOG.md 都列出了它的版本发布记录。

应该使用 SDK，还是直接调用 REST API？

两者都可以。SDK 额外提供重试、幂等键、轮询和带类型的结果。原生 HTTP 不需要安装任何东西，也是本文档中每个示例所展示的方式。

SDK 收费吗？

不用。代码免费，采用 MIT 许可证。API 生成使用独立的 API 美元余额，模型价格与网站相同。请在 API 账单充值。OAuth MCP 使用网站积分；API-key MCP 使用 API 美元余额。

在哪里报告 Bug？

请在该功能所属的仓库中提交 issue。遇到安全问题时，请遵循该仓库中的 SECURITY.md 文件，不要公开提交 issue。

相关内容