SDK, CLI, 오픈소스 도구

PopNow가 개발자용으로 공개하는 것은 모두 GitHub의 popnow-ai 조직 아래 MIT 라이선스 오픈소스입니다. SDK는 이 문서에서 설명하는 것과 같은 REST API를 감싸므로 모든 페이지가 그대로 적용됩니다. 같은 모델 ID, 같은 input 필드, 같은 API USD 잔액을 씁니다.

패키지는 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에 대한 재시도, 파일 업로드, 에셋 라이브러리, 웹훅 서명 검증을 제공합니다. 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는 터미널에서 스크립트, CI 작업, 빠른 테스트를 위한 popnow 명령을 설치합니다. 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 서버는 패키지가 필요 없습니다. ChatGPT, Claude, Cursor, VS Code, Claude Code에 https://api.popnow.ai/mcp를 추가하면 됩니다. 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

Codex, Claude 앱, 기타 에이전트 설정은 README에 있습니다.

예제와 연동

• 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를 실행하세요. 전체 절차와 1분이면 읽을 수 있는 단일 파일 노드가 필요하다면 ComfyUI를 보세요.
• n8n-nodes-popnow는 직접 설치한 n8n용 n8n 커뮤니티 노드이며 npm에 있습니다. Settings > Community Nodes > Install을 열고 n8n-nodes-popnow를 입력하거나, 셸에서 설치한 뒤 n8n을 다시 시작하세요. 아직 인증된 노드가 아니므로 n8n Cloud에서는 설치할 수 없습니다. HTTP Request 워크플로는 설치가 필요 없으며 n8n Cloud에서도 작동합니다.
• 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 USD 잔액을 씁니다. API billing에서 입금하세요. OAuth MCP는 웹사이트 크레딧, API 키 MCP는 API USD를 씁니다.

버그는 어디에 신고하나요?

해당 저장소에 이슈를 여세요. 보안 문제라면 공개 이슈를 여는 대신 그 저장소의 SECURITY.md 파일을 따르세요.

관련 문서