1
Avvia la CLI
Usa npx senza installazione globale. Il pacchetto pubblicato richiede Node.js 20 o successivo.
node --version
npx -y @poyoapi/cli helpPoYo CLIpacchetto npm disponibile
Scopri ed esegui i modelli PoYo dal tuo terminale.
Cerca nel catalogo live e consulta gli Schema senza API Key. Autenticati quando vuoi trasmettere chat, inviare una generazione o riprendere un’attività tramite task_id.
$npx -y @poyoapi/cli helpInizia a usare PoYo CLI in tre passaggi
Esegui la CLI e scegli un modello con models e describe. Aggiungi una API Key solo per eseguire un modello o leggere i dati dell’account.
2
Scegli un modello
Questo esempio trova il modello gpt-image-2 attualmente disponibile, quindi ne legge lo Schema di input aggiornato e il prezzo pubblico. Nessuno dei due comandi richiede una chiave API.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Autenticati ed esegui
Crea una API Key, quindi esegui in ordine i tre comandi seguenti. Controlla il prezzo con describe prima dell’esecuzione a pagamento; le generazioni non riuscite non consumano crediti.
Crea API Key1. Salva la API Key
Risultato previsto: la CLI richiede la Key senza mostrarla, quindi indica keyring o config come posizione. Se l’archivio credenziali di sistema non è disponibile, usa il file di configurazione PoYo dell’utente corrente.
npx -y @poyoapi/cli auth login2. Verifica account e saldo
Risultato previsto: dati dell’account e saldo disponibile. Un errore 401 indica che la Key manca o non è valida.
npx -y @poyoapi/cli account3. Conferma il prezzo ed esegui
Questa è una richiesta a pagamento. Un risultato JSON riuscito include task_id, stato finale e file di output.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonConverti lo Schema del modello in argomenti CLI
Prima di chat, run o submit, la CLI legge lo Schema del modello scelto e converte i campi in argomenti specifici.
Cerca prima di eseguire
models elenca il catalogo pubblico. describe restituisce Schema, protocolli, modalità, callback e fatturazione.
Questi due comandi non richiedono API Key.
Prompt di generazione
Un campo stringa dello Schema viene accettato come valore da riga di comando.
Le opzioni sconosciute falliscono in locale. La validazione completa del JSON Schema resta sull’API.
Torna subito e riprendi dopo
submit restituisce subito un task_id. task get legge lo stato, task wait continua ad attendere.
Adatto a video, audio, 3D e altri job lunghi.
Controlla l’output della CLI
La chat in streaming scrive testo o JSONL in stdout. I comandi non streaming possono restituire table, JSON, JSONL o CSV e scrivere il risultato in un file.
La CLI usa gli stessi endpoint e la stessa fatturazione della REST API.
Scegli il comando adatto a ogni attività
Comandi separati gestiscono ricerca dei modelli, chat, generazione, ripresa delle attività e bridge MCP locale.
~/projects/poyo-demo
# 1. Scegli un modello
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Input comando generato
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Autenticati ed esegui
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
"task_id": "task_7f31b2",
"status": "succeeded",
"files": ["https://storage.poyo.ai/.../image.png"]
}Ciclo dell’attività
Riprendi i task lunghi con task_id
PoYo restituisce direttamente lo stato pubblico esistente del task. Se la CLI va in timeout o si chiude, interroga lo stesso task invece di inviarlo di nuovo.
Un timeout della CLI non annulla l’attività backend. Riusa lo stesso task_id invece di pagare una richiesta duplicata.
Usa submit per i job lunghi
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format jsontask_id task_7f31b2
$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format jsonstatus succeeded
Usa run per un’attesa limitata
run controlla ogni due secondi e attende fino a 90 secondi per impostazione predefinita.
Usa submit per i job lunghi
Conserva il task_id e usa task get o task wait da un altro terminale o passaggio CI.
Scegli tra CLI, MCP, REST e Skill
Usa CLI nel terminale e in CI, MCP per le chiamate agli strumenti dell’Agent, REST API nelle applicazioni e Skill per workflow dell’Agent ripetibili.
PoYo CLI
Sviluppatori, terminale e CI
Una persona o script deve scoprire, eseguire, riprendere e leggere i codici di uscita.
Installa CLIMCP
Agent IA e client di coding
Un Agent deve scoprire Schema, prezzi e strumenti tramite una connessione.
Vedi MCPREST API
Applicazioni e servizi
Il prodotto controlla orchestrazione, streaming, retry e traffico.
Apri docsPoYo Skill
Workflow Agent ripetibili
Un Agent richiede istruzioni e regole di sicurezza oltre alle interfacce.
Vedi SkillFAQ PoYo CLI
Hai ancora dubbi su un comando? Contatta il supporto PoYo→
PoYo CLI è un client da riga di comando guidato dal catalogo per scoprire e chiamare i modelli PoYo di chat, immagini, video, audio e 3D. Legge il Capability Catalog in tempo reale, converte i campi Schema in opzioni di comando e usa gli stessi endpoint PoYo per esecuzione e stato delle attività.
models e describe leggono il Capability Catalog pubblico. Chat, generazione, attività, account ed esecuzione a pagamento richiedono una API Key.
run attende 90 secondi per impostazione predefinita. Il timeout non annulla il backend. Continua con npx -y @poyoapi/cli task wait TASK_ID.
Salvala nel gestore dei segreti CI ed esponila come POYO_API_KEY. Fissa @poyoapi/cli@VERSION, richiedi --format json e considera errore ogni codice di uscita diverso da zero. Non inserirla nel repository.
No. La CLI usa gli stessi endpoint. describe mostra il prezzo pubblico e account il saldo corrente. run e submit sono a pagamento; i crediti vengono detratti solo dopo una generazione riuscita. 401 indica una Key mancante o non valida e 402 un saldo insufficiente.
Un bridge stdio inoltra JSON-RPC a https://api.poyo.ai/mcp. L’esecuzione del modello resta remota.
Esegui il tuo primo modello PoYo dal terminale
Esplora prima il catalogo pubblico e crea una API Key quando sei pronto a eseguire un modello.