SDK, CLI e strumenti open source

Tutto ciò che PopNow pubblica per gli sviluppatori è open source nell’organizzazione popnow-ai su GitHub, con licenza MIT. Gli SDK incapsulano la stessa REST API descritta in queste pagine, quindi tutto ciò che qui si applica resta valido: stessi ID di modello, stessi campi input, stesso saldo API in USD.

I pacchetti sono pubblicati su PyPI, npm, Packagist, Maven Central e il Comfy Registry; installali con i comandi di questa pagina. L’HTTP semplice continua a funzionare; ogni esempio di questa documentazione usa curl, fetch o requests.

In sintesi

Ogni strumento richiede una chiave API dalla console API. Mettila in POPNOW_API_KEY: gli SDK e la CLI la leggono da lì:

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

SDK Python

popnow-python offre un client sincrono (PopNow) e uno asincrono (AsyncPopNow), risultati tipizzati, header Idempotency-Key automatici, nuovi tentativi su 429 e 503, caricamenti di file, la libreria asset e la verifica delle firme dei webhook. Richiede Python 3.9 o successivo e dipende solo da 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 crea l’attività, ne attende il completamento e solleva TaskFailedError se non riesce. I metodi di basso livello client.jobs.quote(), create(), get() e wait() corrispondono uno a uno agli endpoint delle attività.

SDK JavaScript e TypeScript

popnow-js non ha dipendenze a runtime e usa il fetch globale, quindi funziona su Node.js 18+, Deno, Bun, Cloudflare Workers e altri runtime edge. Include build ESM e CommonJS con le definizioni di tipo.

npm install popnow

Su Deno e Bun è disponibile anche su JSR: deno add jsr:@popnow/popnow oppure 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 invia per te un Idempotency-Key e controlla lo stato finché l’attività non è finale. jobs.quote, jobs.create e jobs.wait ci sono quando vuoi calcolare prima il prezzo o attendere altrove.

Riga di comando

popnow-cli installa un comando popnow per script, job di CI e test rapidi dal terminale. Richiede Node.js 22.12 o successivo:

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

Per eseguirlo una volta senza installarlo: npx @popnow/cli status.

Go e PHP

popnow-go è un normale modulo Go (Go 1.23+):

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

popnow-php (PHP 8.1+) è popnow/popnow su Packagist:

composer require popnow/popnow

Java

popnow-java è un client per Java 17+, Kotlin e altri linguaggi JVM, pubblicato su Maven Central come ai.popnow:popnow-java. La sua unica dipendenza è Jackson databind; le richieste HTTP passano per l’HttpClient del JDK.

<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 crea l’attività con l’Idempotency-Key che passi e attende che sia finale; createTask e waitForTerminal ci sono quando vuoi tenere separati i due passaggi.

MCP e Agent Skills

Il server MCP remoto non richiede alcun pacchetto: aggiungi https://api.popnow.ai/mcp a ChatGPT, Claude, Cursor, VS Code o Claude Code. popnow-mcp raccoglie configurazioni da copiare e incollare per ogni client e un piccolo bridge stdio per i client che possono avviare solo server locali. Il bridge è su npm come @popnow/mcp, quindi npx -y @popnow/mcp lo esegue senza un passo di installazione.

popnow-skills insegna agli agenti di coding a creare video, immagini, musica e voiceover con la REST API, e a consultare il riferimento API. In Claude Code:

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

Il README copre Codex, le app di Claude e altri agenti.

Esempi e integrazioni

• popnow-api contiene il file OpenAPI, esempi curl, Python e Node.js eseguibili e un workflow n8n importabile. Se ti serve un client in un altro linguaggio, indica al generatore di codice il file OpenAPI.
• popnow-blender è il sorgente dell’add-on Blender. Per installarlo, scarica lo zip da popnow.ai/blender; il repository può anche generare lo stesso zip.
• popnow-comfyui è un pacchetto di nodi ComfyUI sul Comfy Registry: un nodo per modello, più PopNow Generate e PopNow LoRA. In ComfyUI Manager apri Custom Nodes Manager, cerca PopNow e clicca Install, oppure esegui comfy node install popnow-comfyui. ComfyUI riporta i passaggi completi e il nodo a file singolo, se preferisci un solo file che puoi leggere in un minuto.
• n8n-nodes-popnow è un nodo della community per n8n su npm, per n8n self-hosted. Apri Settings > Community Nodes > Install e inserisci n8n-nodes-popnow, oppure installalo da una shell e riavvia n8n. Non è ancora un nodo verificato, quindi n8n Cloud non può installarlo; il workflow HTTP Request non richiede installazione e funziona anche lì.
• popnow-proxy è un piccolo percorso lato server per Next.js, Express e altri runtime con fetch. Un’app browser, mobile o desktop chiama il tuo server, e il proxy aggiunge lì la chiave API, così la chiave non finisce mai nel client. Richiede Node.js 22.12 o successivo.
• popnow-bot è un bot Telegram e Discord che gestisci tu stesso con Docker: immagini, video ed effetti video in chat, con un controllo del prezzo prima delle esecuzioni a pagamento e limiti di spesa giornalieri. Clona il repository e avvialo con docker compose up -d --build, oppure scarica l’immagine già compilata popnow/popnow-bot da 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

Esiste un SDK PopNow ufficiale?

Sì. Gli SDK Python e JavaScript, la CLI e i client Go, PHP e Java di questa pagina sono mantenuti da PopNow e sono open source su github.com/popnow-ai.

Gli SDK sono su npm o PyPI?

Sì. pip install popnow installa l’SDK Python da PyPI e npm install popnow l’SDK JavaScript da npm. La CLI è @popnow/cli su npm, il client PHP è popnow/popnow su Packagist, il client Java è ai.popnow:popnow-java su Maven Central, e il pacchetto ComfyUI è popnow-comfyui sul Comfy Registry. Il file CHANGELOG.md di ogni repository elenca le sue release.

Conviene usare un SDK o chiamare direttamente la REST API?

Sono equivalenti. Gli SDK aggiungono nuovi tentativi, chiavi di idempotenza, polling e risultati tipizzati. L’HTTP semplice non richiede nulla da installare ed è ciò che mostrano tutti gli esempi di questa documentazione.

Gli SDK hanno un costo?

No. Il codice è gratuito con licenza MIT; le generazioni API consumano il saldo API separato in USD allo stesso prezzo del modello sul sito. Aggiungi fondi in Fatturazione API. MCP via OAuth usa i crediti del sito; MCP con chiave API usa gli USD API.

Dove segnalo un bug?

Apri una issue nel repository a cui appartiene. Per un problema di sicurezza, segui il file SECURITY.md di quel repository invece di aprire una issue pubblica.

Correlati