SDKs, CLI e ferramentas de código aberto

Tudo o que o PopNow publica para desenvolvedores é código aberto, sob a organização popnow-ai no GitHub, com licença MIT. Os SDKs envolvem a mesma API REST que estes docs descrevem, então todas as páginas daqui continuam valendo: mesmos IDs de modelo, mesmos campos de input, mesmo saldo da API em USD.

Os pacotes estão publicados no PyPI, npm, Packagist, Maven Central e Comfy Registry; instale-os com os comandos desta página. HTTP puro continua funcionando; todos os exemplos destes docs usam curl, fetch ou requests.

Visão geral

Toda ferramenta precisa de uma chave de API do console da API. Coloque-a em POPNOW_API_KEY; os SDKs e a CLI leem dali:

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

SDK de Python

O popnow-python tem um cliente síncrono (PopNow) e outro assíncrono (AsyncPopNow), resultados tipados, cabeçalhos Idempotency-Key automáticos, novas tentativas em 429 e 503, upload de arquivos, a biblioteca de assets e a verificação de assinatura de webhooks. Ele precisa de Python 3.9 ou mais novo e depende apenas de 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 cria a tarefa, espera por ela e lança TaskFailedError se ela não tiver sucesso. Os métodos de nível mais baixo client.jobs.quote(), create(), get() e wait() correspondem um a um aos endpoints de tarefas.

SDK de JavaScript e TypeScript

O popnow-js não tem dependências de runtime e usa o fetch global, então roda em Node.js 18+, Deno, Bun, Cloudflare Workers e outros runtimes de borda. Ele traz builds ESM e CommonJS com definições de tipos.

npm install popnow

No Deno e no Bun ele também está no JSR: deno add jsr:@popnow/popnow ou 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 envia um Idempotency-Key por você e consulta a tarefa até ela ficar final. jobs.quote, jobs.create e jobs.wait estão disponíveis quando você quer calcular o preço antes ou esperar em outro lugar.

Linha de comando

O popnow-cli instala um comando popnow para scripts, jobs de CI e testes rápidos pelo terminal. Ele precisa de Node.js 22.12 ou mais novo:

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

Para rodar uma vez sem instalar: npx @popnow/cli status.

Go e PHP

O popnow-go é um módulo Go comum (Go 1.23+):

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

O popnow-php (PHP 8.1+) é o popnow/popnow no Packagist:

composer require popnow/popnow

Java

O popnow-java é um cliente para Java 17+, Kotlin e outras linguagens da JVM, publicado no Maven Central como ai.popnow:popnow-java. Sua única dependência é o Jackson databind; o HTTP passa pelo HttpClient do próprio 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 cria a tarefa com o Idempotency-Key que você passar e espera até ela ficar final; createTask e waitForTerminal estão disponíveis quando você quer as duas etapas separadas.

MCP e Agent Skills

O servidor MCP remoto não precisa de pacote: adicione https://api.popnow.ai/mcp ao ChatGPT, Claude, Cursor, VS Code ou Claude Code. O popnow-mcp reúne configurações para copiar e colar em cada cliente, além de uma pequena ponte stdio para clientes que só conseguem iniciar servidores locais. A ponte está no npm como @popnow/mcp, então npx -y @popnow/mcp a executa sem etapa de instalação.

O popnow-skills ensina agentes de programação a criar vídeos, imagens, músicas e narrações com a API REST, e a consultar a referência da API. No Claude Code:

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

O README cobre o Codex, os apps do Claude e outros agentes.

Exemplos e integrações

• O popnow-api traz o arquivo OpenAPI, exemplos executáveis em curl, Python e Node.js e um fluxo do n8n para importar. Aponte um gerador de código para o arquivo OpenAPI se precisar de um cliente em outra linguagem.
• O popnow-blender é o código-fonte do add-on do Blender. Para instalá-lo, baixe o zip em popnow.ai/blender; o repositório também consegue gerar o mesmo zip.
• O popnow-comfyui é um pacote de nós do ComfyUI no Comfy Registry: um nó por modelo, além do PopNow Generate e do PopNow LoRA. No ComfyUI Manager, abra Custom Nodes Manager, procure por PopNow e clique em Install, ou rode comfy node install popnow-comfyui. A página do ComfyUI traz os passos completos e o nó em um único arquivo, se você preferir um arquivo que dê para ler em um minuto.
• O n8n-nodes-popnow é um nó da comunidade do n8n no npm, para n8n self-hosted. Abra Settings > Community Nodes > Install e digite n8n-nodes-popnow, ou instale pelo terminal e reinicie o n8n. Ele ainda não é um nó verificado, por isso o n8n Cloud não consegue instalá-lo; o fluxo com HTTP Request não precisa de instalação e funciona lá também.
• O popnow-proxy é uma pequena rota do lado do servidor para Next.js, Express e outros runtimes com fetch. Um app de navegador, mobile ou desktop chama o seu servidor, e o proxy adiciona a chave de API ali, então a chave nunca vai para o cliente. Ele precisa de Node.js 22.12 ou mais novo.
• O popnow-bot é um bot de Telegram e Discord que você mesmo roda com Docker: imagens, vídeos e efeitos de vídeo num chat, com consulta de preço antes das execuções pagas e limites de gasto diários. Clone o repositório e suba com docker compose up -d --build, ou baixe a imagem pronta popnow/popnow-bot do 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

Existe um SDK oficial do PopNow?

Existe. Os SDKs de Python e JavaScript, a CLI e os clientes em Go, PHP e Java desta página são mantidos pelo PopNow e são de código aberto em github.com/popnow-ai.

Os SDKs estão no npm ou no PyPI?

Estão. pip install popnow instala o SDK de Python do PyPI, e npm install popnow instala o SDK de JavaScript do npm. A CLI é @popnow/cli no npm, o cliente PHP é popnow/popnow no Packagist, o cliente Java é ai.popnow:popnow-java no Maven Central, e o pacote do ComfyUI é popnow-comfyui no Comfy Registry. O CHANGELOG.md de cada repositório lista as suas versões.

Devo usar um SDK ou chamar a API REST diretamente?

Tanto faz. Os SDKs acrescentam novas tentativas, chaves de idempotência, polling e resultados tipados. HTTP puro não precisa de nada instalado e é o que todos os exemplos destes docs mostram.

Os SDKs têm algum custo?

Não. O código é gratuito sob a licença MIT; gerações da API gastam o saldo separado da API em USD pelos mesmos preços dos modelos do site. Adicione fundos em API billing. MCP com OAuth usa créditos do site; MCP com chave de API usa USD da API.

Onde eu relato um bug?

Abra uma issue no repositório ao qual o bug pertence. Para um problema de segurança, siga o arquivo SECURITY.md desse repositório em vez de abrir uma issue pública.

Relacionados