SDK、CLI 與開源工具

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 與 CLI 會從那裡讀取：

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 語言的用戶端，發布在 Maven Central，座標為 ai.popnow:popnow-java。它唯一的依賴是 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 Skills

遠端 MCP 伺服器 不需要任何套件：把 https://api.popnow.ai/mcp 加入 ChatGPT、Claude、Cursor、VS Code 或 Claude Code 即可。popnow-mcp 為每個用戶端提供可直接複製貼上的設定，並為只能啟動本機伺服器的用戶端提供一個小型 stdio 橋接器。這個橋接器已發布在 npm 上，名稱為 @popnow/mcp，所以 npx -y @popnow/mcp 不需要安裝步驟就能執行。

popnow-skills 教導程式設計代理使用 REST API 製作影片、圖片、音樂與配音，並查詢 API 參考。在 Claude Code 中：

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

README 說明了 Codex、Claude 應用程式與其他代理的用法。

範例與整合

• 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、CLI，以及 Go、PHP 與 Java 用戶端，都由 PopNow 維護，並在 github.com/popnow-ai 下開源。

SDK 發布在 npm 或 PyPI 上嗎？

是的。pip install popnow 會從 PyPI 安裝 Python SDK，npm install popnow 會從 npm 安裝 JavaScript SDK。CLI 是 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 美元餘額。

要在哪裡回報錯誤？

請在該程式碼所屬的儲存庫中開 issue。若是安全性問題，請依該儲存庫中的 SECURITY.md 處理，不要公開開 issue。

相關頁面