SDK, CLI i narzędzia open source

Wszystko, co PopNow publikuje dla programistów, ma otwarty kod na licencji MIT w organizacji popnow-ai na GitHubie. SDK to nakładki na to samo REST API, które opisuje ta dokumentacja, więc wszystkie strony nadal mają zastosowanie: te same ID modeli, pola input i saldo API w USD.

Pakiety są opublikowane w PyPI, npm, Packagist, Maven Central i Comfy Registry. Zainstalujesz je poleceniami z tej strony. Zwykłe HTTP też nadal działa; wszystkie przykłady w dokumentacji korzystają z curl, fetch lub requests.

Przegląd

Każde narzędzie wymaga klucza API z konsoli API. Umieść go w POPNOW_API_KEY; SDK i CLI odczytują go z tej zmiennej:

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

SDK dla Pythona

popnow-python udostępnia klienta synchronicznego (PopNow) i asynchronicznego (AsyncPopNow), typowane wyniki, automatyczne nagłówki Idempotency-Key, ponowienia po 429 i 503, przesyłanie plików, bibliotekę zasobów i sprawdzanie podpisów webhooków. Wymaga Pythona 3.9 lub nowszego i zależy tylko od 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 tworzy zadanie, czeka na wynik i zgłasza TaskFailedError, jeśli zadanie nie zakończy się sukcesem. Metody niższego poziomu client.jobs.quote(), create(), get() i wait() odpowiadają bezpośrednio endpointom zadań.

SDK dla JavaScriptu i TypeScriptu

popnow-js nie ma zależności wykonawczych i korzysta z globalnego fetch, więc działa w Node.js 18+, Deno, Bun, Cloudflare Workers i innych środowiskach edge. Udostępnia wersje ESM i CommonJS z definicjami typów.

npm install popnow

Dla Deno i Bun jest też dostępny w JSR: deno add jsr:@popnow/popnow lub 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 automatycznie wysyła Idempotency-Key i odpytuje zadanie do stanu końcowego. Jeśli chcesz najpierw pobrać wycenę lub czekać w innym miejscu, masz do dyspozycji jobs.quote, jobs.create i jobs.wait.

Wiersz poleceń

popnow-cli instaluje polecenie popnow do skryptów, zadań CI i szybkich testów w terminalu. Wymaga Node.js 22.12 lub nowszego:

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

Jednorazowe uruchomienie bez instalacji: npx @popnow/cli status.

Go i PHP

popnow-go to zwykły moduł Go (Go 1.23+):

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

popnow-php (PHP 8.1+) jest dostępny jako popnow/popnow w Packagist:

composer require popnow/popnow

Java

popnow-java to klient dla Javy 17+, Kotlina i innych języków JVM, opublikowany w Maven Central jako ai.popnow:popnow-java. Jego jedyną zależnością jest Jackson databind; do HTTP używa wbudowanego w 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 tworzy zadanie z przekazanym Idempotency-Key i czeka na stan końcowy. Metody createTask i waitForTerminal pozwalają wykonać te kroki osobno.

MCP i Agent Skills

Zdalny serwer MCP nie wymaga pakietu: dodaj https://api.popnow.ai/mcp do ChatGPT, Claude, Cursor, VS Code lub Claude Code. popnow-mcp zawiera gotowe konfiguracje dla każdego klienta i mały most stdio dla klientów, które potrafią uruchamiać tylko lokalne serwery. Most jest dostępny w npm jako @popnow/mcp, więc npx -y @popnow/mcp uruchamia go bez osobnej instalacji.

popnow-skills uczy agentów programistycznych tworzenia wideo, obrazów, muzyki i nagrań lektorskich przez REST API oraz korzystania z dokumentacji API. W Claude Code:

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

README opisuje też Codex, aplikacje Claude i innych agentów.

Przykłady i integracje

• popnow-api zawiera plik OpenAPI, gotowe do uruchomienia przykłady curl, Python i Node.js oraz workflow n8n do importu. Jeśli potrzebujesz klienta w innym języku, wskaż generatorowi kodu plik OpenAPI.
• popnow-blender to kod dodatku do Blendera. Aby go zainstalować, pobierz ZIP z popnow.ai/blender; repozytorium pozwala też zbudować ten sam ZIP.
• popnow-comfyui to pakiet węzłów ComfyUI w Comfy Registry: po jednym węźle na model oraz PopNow Generate i PopNow LoRA. W ComfyUI Manager otwórz Custom Nodes Manager, wyszukaj PopNow i kliknij Install albo uruchom comfy node install popnow-comfyui. Strona ComfyUI zawiera pełną instrukcję i węzeł w jednym pliku, jeśli wolisz plik, który można przeczytać w minutę.
• n8n-nodes-popnow to węzeł społecznościowy n8n w npm, przeznaczony do własnej instalacji n8n. Otwórz Settings > Community Nodes > Install i wpisz n8n-nodes-popnow albo zainstaluj go z terminala i uruchom n8n ponownie. Nie jest jeszcze zweryfikowany, więc nie można go zainstalować w n8n Cloud; workflow HTTP Request nie wymaga instalacji i działa również tam.
• popnow-proxy to niewielki endpoint serwerowy dla Next.js, Express i innych środowisk z fetch. Aplikacja przeglądarkowa, mobilna lub desktopowa wywołuje twój serwer, a proxy dodaje klucz API po jego stronie, więc klucz nigdy nie trafia do klienta. Wymaga Node.js 22.12 lub nowszego.
• popnow-bot to bot Telegram i Discord, który uruchamiasz samodzielnie przez Docker: obrazy, wideo i efekty wideo na czacie, z wyceną przed płatnym uruchomieniem i dziennymi limitami wydatków. Sklonuj repozytorium i uruchom docker compose up -d --build albo pobierz gotowy obraz popnow/popnow-bot z Docker Hub.

# 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

Czy istnieje oficjalne SDK PopNow?

Tak. SDK dla Pythona i JavaScriptu, CLI oraz klienci Go, PHP i Java z tej strony są utrzymywane przez PopNow i mają otwarty kod pod github.com/popnow-ai.

Czy SDK są w npm lub PyPI?

Tak. pip install popnow instaluje SDK dla Pythona z PyPI, a npm install popnow — SDK dla JavaScriptu z npm. CLI to @popnow/cli w npm, klient PHP to popnow/popnow w Packagist, klient Java to ai.popnow:popnow-java w Maven Central, a pakiet ComfyUI to popnow-comfyui w Comfy Registry. Plik CHANGELOG.md każdego repozytorium zawiera listę wydań.

Czy używać SDK, czy wywoływać REST API bezpośrednio?

Obie opcje są dobre. SDK dodają ponowienia, klucze idempotencji, odpytywanie i typowane wyniki. Zwykłe HTTP nie wymaga instalacji i jest używane we wszystkich przykładach w tej dokumentacji.

Czy SDK są płatne?

Nie. Kod jest bezpłatny na licencji MIT; generowanie przez API zużywa osobne saldo API w USD według tych samych cen modeli co strona. Doładuj je w rozliczeniach API. MCP przez OAuth korzysta z kredytów strony; MCP z kluczem API — z USD w API.

Gdzie zgłosić błąd?

Otwórz zgłoszenie w odpowiednim repozytorium. W przypadku problemu z bezpieczeństwem postępuj zgodnie z plikiem SECURITY.md w tym repozytorium zamiast tworzyć publiczne zgłoszenie.

Powiązane