1
Controleer je omgeving en start de CLI
Node.js 20 of nieuwer is vereist. Als node --version v20 of hoger toont, start je de CLI direct via npx, zonder globale installatie.
node --version
npx -y @poyoapi/cli helpPoYo CLInpm-pakket beschikbaar
Elk PoYo-model — vanuit je terminal, scripts en agents.
Bekijk de invoerschema's en openbare prijzen van de modellen die nu in de live PoYo Catalog staan, zonder API-sleutel. Voeg pas een sleutel toe als je een model uitvoert. Duurt een job langer dan de CLI wacht, dan blijf je hem volgen met dezelfde task_id.
$npx -y @poyoapi/cli helpDrie stappen van ontdekken tot resultaat
Geen globale installatie nodig. Controleer Node.js, bekijk het model, authenticeer en rond je eerste run af.
2
Zoek een model en bekijk het
Dit voorbeeld zoekt het momenteel beschikbare model gpt-image-2 op en leest daarna het live invoerschema en de openbare prijs. Voor geen van beide opdrachten heb je een API-sleutel nodig.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Log in, controleer en voer uit
Maak een API-sleutel aan en voer daarna de drie onderstaande opdrachten in volgorde uit. Controleer vóór de betaalde run de prijs met describe; mislukte generaties kosten geen credits.
API-sleutel aanmaken1. Sla je API-sleutel op
Verwacht: de CLI vraagt om de sleutel zonder die te tonen en meldt daarna keyring of config als opslaglocatie. Is de credentialopslag van het systeem niet beschikbaar, dan valt de CLI terug op je PoYo-configuratiebestand.
npx -y @poyoapi/cli auth login2. Controleer het account en het saldo
Verwacht: accountgegevens en het beschikbare saldo. Bij een 401 ontbreekt de sleutel of is die ongeldig.
npx -y @poyoapi/cli account3. Bevestig de prijs en voer uit
Dit is een betaald verzoek. Een geslaagd JSON-resultaat bevat de task_id, de eindstatus en de uitvoerbestanden.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonGebouwd voor echte multimodale workflows
De live Catalog vertelt de CLI welke modellen er zijn, welke invoer ze accepteren, hoe lang jobs worden bijgehouden en welk uitvoerformaat scripts krijgen.
Zoek voordat je uitvoert
models toont de openbare catalogus. describe geeft het exacte schema, de ondersteunde protocollen, de uitvoermodus, de callback-ondersteuning en de factureringsmetadata van één model.
Voor deze twee opdrachten heb je geen API-sleutel nodig.
Schema wordt opdrachtvlaggen
De CLI leest het live schema van elk model en biedt de velden aan als modelspecifieke opdrachtregelopties.
Onbekende modelvlaggen mislukken lokaal. Controle op verplichte velden en volledige JSON Schema-validatie gebeurt nog steeds op de API.
Eén keer versturen, verdergaan met task_id
submit geeft direct een task_id terug. task get leest de huidige status, terwijl task wait blijft controleren tot de taak klaar is of de time-out is bereikt.
Gebruik bij voorkeur submit voor video, audio, 3D en andere langlopende jobs.
Gestructureerde uitvoer voor scripts en CI
Kies tabeluitvoer voor mensen; gebruik JSON, JSONL of CSV voor scripts en CI. Opdrachten zonder streaming kunnen resultaten ook naar een bestand schrijven.
Gebruik --output FILE bij opdrachten zonder streaming. Gestreamde tekst en JSONL blijven op stdout.
Zo ziet een echte PoYo-sessie eruit
Blader door de openbare catalogus, bekijk de huidige invoer en prijs van één model en vraag daarna gestructureerde uitvoer op voor je scripts.
~/projects/poyo-demo
# 1. Zoek een model en bekijk het
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Bekijk het live schema
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Log in, controleer en voer uit
$ 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"]
}Levenscyclus van een taak
Lange jobs hoeven niet opnieuw te beginnen
Verstuur video-, audio-, 3D- en ander langlopend werk één keer. Bewaar de task_id en wacht verder vanuit een andere terminal of CI-stap.
Een time-out van de CLI annuleert de job in de backend niet. Ga verder met dezelfde task_id in plaats van hetzelfde werk opnieuw te versturen.
Gebruik submit als de terminal niet hoeft te wachten
$ 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
Gebruik run als 90 seconden genoeg is
run controleert de taak elke twee seconden en wacht standaard maximaal 90 seconden. Je kunt een andere time-out instellen.
Gebruik submit als de terminal niet hoeft te wachten
Kopieer de task_id die submit teruggeeft en vervang TASK_ID in de wait-opdracht. Je kunt verdergaan vanuit een andere terminal of CI-stap.
Kies de juiste interface voor wie aanroept
Gebruik de CLI voor mensen en shellscripts, MCP voor toolaanroepen door agents, REST binnen applicaties en Skill om een agent herbruikbare PoYo-stappen en veiligheidsregels te geven.
PoYo CLI
Ontwikkelaars, terminals en CI
Een persoon of shellscript moet modellen ontdekken, uitvoeren, taken hervatten en reageren op exitcodes van processen.
CLI installerenMCP
AI-agents en codeerclients
Een agent moet via één verbinding schema's, prijzen en uitvoertools kunnen ontdekken.
MCP bekijkenREST-API
Applicaties en services
Je applicatie heeft directe HTTP-controle nodig over verzoeken, streaming, herhalingen en callbacks.
Documentatie openenPoYo Skill
Herhaalbare agentworkflows
Een agent heeft naast toegang via CLI, MCP of REST herbruikbare werkstappen en veiligheidsregels nodig.
Skill bekijkenVeelgestelde vragen over PoYo CLI
Nog onzeker over een opdracht? Neem contact op met PoYo Support→
PoYo CLI is een opdrachtregelclient om de chat-, afbeeldings-, video-, audio- en 3D-modellen van PoYo te ontdekken en aan te roepen. De CLI leest de actuele modeldefinities uit de openbare Capability Catalog, zet schemavelden om in opdrachtopties en gebruikt dezelfde PoYo API-endpoints voor uitvoering en taakstatus.
models en describe lezen de openbare Capability Catalog zonder inloggegevens. Chat-, generatie-, taak- en accountopdrachten en betaalde uitvoeropdrachten vereisen een API-sleutel.
run wacht standaard 90 seconden. Een time-out stopt het lokale controleren, maar annuleert de taak in de backend niet. Ga verder met npx -y @poyoapi/cli task wait TASK_ID.
Bewaar de sleutel in de secretmanager van je CI en stel hem beschikbaar als POYO_API_KEY. Pin @poyoapi/cli@VERSION voor reproduceerbare runs, vraag --format json aan en beschouw elke exitcode die niet nul is als een mislukking. Zet nooit inloggegevens in je opdrachtgeschiedenis of in repositorybestanden.
Nee. De CLI roept dezelfde endpoints aan. describe toont de openbare prijs van het gekozen model en account toont je huidige saldo. run en submit zijn betaald; credits worden pas afgeschreven als een generatie slaagt. Een 401 betekent dat de sleutel ontbreekt of ongeldig is, terwijl 402 betekent dat het account te weinig credits heeft.
Die voert een stdio-brug uit die JSON-RPC-berichten doorstuurt naar https://api.poyo.ai/mcp. De uitvoering van het model blijft plaatsvinden op de remote service van PoYo.
Open source. Klaar vanuit elke terminal.
De CLI met MIT-licentie staat op npm en wordt ontwikkeld op GitHub. Bekijk eerst de openbare Catalog en maak daarna een API-sleutel aan zodra je een model wilt uitvoeren.