CLI
Installeer en gebruik alle RunAPI CLI-opdrachten voor modelacties, Tasks, Bestanden, Uploads, accountinformatie, prijzen, callbacks en Harness.
De RunAPI CLI is een JSON-eerste terminalclient voor modelacties en accountbeheer. Resultaatdata wordt naar standaarduitvoer geschreven en operationele voortgang naar standaardfout, waardoor het goed werkt in een terminal, in shellscripts, CI-taken en Harness.
Installeren
Installeer de huidige release op Linux of macOS:
curl -fsSL https://runapi.ai/cli/install.sh | sh
Installaties via Homebrew en Go-bron zijn ook beschikbaar:
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
Download op Windows het bijpassende windows-amd64- of windows-arm64-archief uit de nieuwste CLI-release, pak runapi.exe uit en voeg het toe aan PATH.
Vergrendel het installatieprogramma op een versie of een installatiedirectory wanneer een implementatie een reproduceerbaar binair bestand vereist:
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"
Het installatieprogramma accepteert ook RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE en RUNAPI_SKIP_LIBC_CHECK=1.
Snelstart
Meld u op een werkstation aan via de browser en bevestig de referentiebron:
runapi login
runapi auth status
Voer een modelactie uit met een inline JSON-invoer of een JSON-bestand:
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json
De meeste modelacties zijn asynchroon. Ze wachten standaard op een eindresultaat; voeg --async toe om de taak direct te retourneren en gebruik later wait:
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music
Opdrachtconventies
Elk commando geeft JSON weer op standaarduitvoer, tenzij een optie expliciet
om een scalaire waarde vraagt, zoals files create --url-only of listen
--print-secret. Voortgangs- en diagnostische berichten blijven op standaardfout,
zodat JSON veilig naar jq kan worden doorgestuurd:
runapi nano-banana text-to-image --input-file request.json \
| jq -r '.images[].url' \
| xargs -I{} curl -OL {}
Modelacties accepteren precies één invoerinvoerbron voor het verzoek:
--input '<json object>'levert inline JSON aan.--input-file path/to/request.jsonlaadt JSON vanuit een bestand.--input-file -leest JSON vanuit de standaardinvoer.
Gebruik runapi <service> <action> --help voordat u een verzoek opstelt.
De geïnstalleerde CLI toont de huidige velden van de actie, geaccepteerde model-
identifiers en validatiebeperkingen.
Deze globale opties zijn van toepassing op elke opdracht:
--api-key
Gebruik een API-sleutel voor deze aanroep. Het overschrijft RUNAPI_API_KEY.
--base-url
Gebruik een andere API-origin voor deze aanroep.
--timeout
Stel de algemene opdrachttimeout en de maximale Task-wachttijd in. De standaard is 15 minuten.
--poll-interval
Stel het interval voor Task-polling in. De standaard is 3 seconden.
--async
Keer onmiddellijk terug na het indienen van een asynchrone modelactie.
--quiet
Onderdruk voortgang op standaardfout zonder de JSON-uitvoer te wijzigen.
Modelacties
De modelopdrachtvorm is runapi <service> <action>. Synchrone acties retourneren hun antwoord onmiddellijk. Voor asynchrone acties is het standaardgedrag indienen, pollen en het eindresultaat van de taak retourneren; --async retourneert in plaats daarvan het aanmaakreactie.
Voor URL-velden van media op het hoogste niveau wordt een leesbaar lokaal bestandspad geüpload voordat de modelactie wordt uitgevoerd. Bestaande http://- en https://-URL’s worden ongewijzigd verzonden. Gebruik files create wanneer u een herbruikbare tijdelijke URL nodig hebt, wanneer de bron een externe URL is, of wanneer de bron Base64-gegevens zijn.
Audio- en muziekacties
suno:add-instrumental,add-vocals,blend-lyrics,boost-style,check-voice,convert-audio,cover-audio,create-mashup,extend-music,generate-artwork,generate-lyrics,generate-midi,generate-persona,generate-voice,get-timestamped-lyrics,regenerate-validation-phrase,replace-section,separate-audio-stems,text-to-music,text-to-sound,visualize-music,voice-to-validation-phraseproducer:text-to-musicgemini-omni:create-audio,create-character,text-to-videoopenai-tts:text-to-speechfish-audio:text-to-speechgemini-tts:text-to-speechelevenlabs:isolate-audio,speech-to-text,text-to-dialogue,text-to-sound,text-to-speech
Afbeeldingsacties
nano-banana:edit-image,text-to-imageimagen-4:remix-image,text-to-imageseedream:decompose-layers,edit-image,text-to-imageflux:remix-image,text-to-imageflux-2:remix-image,text-to-imageflux-kontext:text-to-imageqwen-2:edit-image,text-to-imageqwen-3:edit-image,text-to-imageqwen-image:edit-image,remix-image,text-to-imagerecraft:remove-background,upscale-imagez-image:text-to-imageideogram-v3:edit-image,reframe-image,remix-image,text-to-imagegpt-image:edit-image,text-to-imagegpt-image-2:edit-image,text-to-imagegpt-4o-image:text-to-imagemidjourney:edit-image,get-seed,image-to-prompt,shorten-prompt,text-to-image
Video- en animatieacties
veo-3-1:extend-video,text-to-video,upscale-videoseedance:text-to-videorunway:extend-video,text-to-videorunway-aleph:edit-videokling:avatar,edit-video,extend-video,image-to-video,motion-control,text-to-videoinfinitetalk:audio-to-videoomnihuman:audio-to-video,human-identification,subject-detectionwan:animate,edit-video,image-to-video,speech-to-video,text-to-image,text-to-videoluma:modify-videohailuo:image-to-video,text-to-videovolcengine-lip-sync:lip-sync-videohappyhorse:edit-video,image-to-video,text-to-videogrok-imagine:edit-image,extend,image-to-video,text-to-image,text-to-video,upscale-imagetopaz:upscale-image,upscale-videomidjourney:extend-video,image-to-video
De bovenstaande lijst is de volledige actieinventaris in deze CLI-release. Het exacte verzoek- en antwoordcontract van elke actie is beschikbaar in de API-referentie, en de lokale opdrachthelp is de bron voor versiespecifieke velden.
Taaklevenscyclus
Gebruik get om de huidige staat van een asynchrone Task te inspecteren zonder
te wachten. Gebruik wait om te pollen totdat deze is voltooid, mislukt of de
opdrachttimeout bereikt. Beide opdrachten vereisen de oorspronkelijke service en actie
zodat de CLI de juiste Task-resultaatvorm kan selecteren.
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
Bestanden
runapi files create behoudt de tijdelijke File Upload URL-stroom. Het uploadt één lokaal pad, externe URL of Base64-bron en retourneert een URL die na één uur verloopt.
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png
De bronkeuzes sluiten elkaar uit. --url-only drukt alleen de URL af; laat het weg om het volledige JSON-antwoord te ontvangen.
Gebruik de persistente bestandslevenscyclus wanneer u een stabiele file_id
nodig heeft in plaats van een URL:
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123
content vereist --output; geef - op om exacte File-bytes naar de standaarduitvoer te schrijven. Zie Files and Uploads voor limieten, accountisolatie en de REST-levenscyclus.
Uploads
Gebruik Uploads om een of meer Parts te verzenden voordat u het definitieve File samenstelt.
Create declareert het definitieve byteaantal en de metagegevens; herhaal --part-id in
samenstellingsvolgorde bij het voltooien:
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123
Account en prijzen
Inspecteer de geauthenticeerde gebruiker en het geselecteerde account, en bevraag vervolgens het saldo en de bestedingstellers:
runapi account info
runapi account balance
pricing list leest de huidige prijsschema’s. Filter op service, actie of model. pricing quote schat de Task-reservering voor een vereiste service en actie; voeg --model toe wanneer de actie modelspecifiek is en geef prijsinvoer op met --params of --params-file.
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
--params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json
Prijsopdrachten vereisen geen inloggegevens, tenzij de offerte verwijst naar een taak die eigendom is van een account.
Authenticatie en configuratie
runapi login opent een browserautorisatiestroom en slaat de resulterende referentie op. Voor servers en CI accepteert auth import-token een API-sleutel van de standaardinvoer, verifieert deze standaard en slaat deze op zonder de waarde bloot te stellen in de proceslijst of shellgeschiedenis:
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
auth import-token --skip-verify ondersteunt offline image-installatie. Gebruik dit alleen wanneer verificatie niet kan worden uitgevoerd tijdens de installatie; auth status verifieert de actieve referentie achteraf.
Prioriteitsvolgorde voor de API-sleutel: --api-key, dan RUNAPI_API_KEY, dan het lokale CLI-configuratiebestand. Prioriteitsvolgorde voor de basis-URL: --base-url, dan RUNAPI_BASE_URL, dan de opgeslagen basis-URL, dan https://runapi.ai. Het configuratiebestand is ~/.config/runapi/config.json, of $XDG_CONFIG_HOME/runapi/config.json wanneer XDG_CONFIG_HOME is ingesteld.
Lokale callback-listener
runapi listen ontvangt Task-callbacks voor één geselecteerde API-sleutel en stuurt elke ondertekende callback optioneel door naar een lokaal HTTP-eindpunt. Browseraanmelding is vereist voordat luisterbewerkingen kunnen worden gebruikt.
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
De positionele URL en --forward-to zijn alternatieven. De listener schrijft elke ondertekende callback-body naar standaarduitvoer. Een taak met callback_url blijft leveren aan die URL en wordt ook naar de lokale listener gekopieerd.
Na ontvangst van een geldige listenergebeurtenis bevestigt de CLI deze voordat de lokale HTTP-aanvraag wordt geprobeerd. Elke gebeurtenis wordt één keer lokaal doorgestuurd: niet-2xx-responsen en verbindingsfouten worden gerapporteerd in de terminal, maar ze zorgen er niet voor dat de listener de gebeurtenis opnieuw afspeelt. Dit lokale debuggedrag heeft geen invloed op de bezorgingspogingen voor de callback_url van een taak.
Elk account kan tot 100 actieve listeners per Callback-abonnementssleutel uitvoeren en in totaal 1.000 actieve listeners. Wanneer een limiet is bereikt, stopt u een inactieve listener of wacht u en probeert u het opnieuw. De API-respons geeft aan of de geselecteerde sleutel, uw account of de algehele servicecapaciteit vol is.
Een inactieve listener controleert elke 15 tot 30 seconden op nieuwe gebeurtenissen. Gebeurtenissen worden normaal gesproken binnen ongeveer 15 seconden gevonden en worden onmiddellijk gelezen zodra ze beschikbaar zijn. Als een limiet wordt bereikt, stop dan een inactieve listener of wacht en probeer het opnieuw. Bestaand bezorg- en bevestigingsgedrag blijft ongewijzigd.
Sleutelselectie verloopt in volgorde: --callback-api-key-id voor één opdracht, callback_api_key_id in de project-.runapi.toml, dan een interactieve selector. De projectconfiguratie wordt opgeslagen in de Git-root, of de huidige map buiten een Git-repository, en bevat alleen de stabiele ID:
callback_api_key_id = "token_abc123"
Druk het Listen Signing Secret van een geselecteerde sleutel af zonder een luisteraar te starten, of roteer het na blootstelling:
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
Rotatie maakt actieve listeners voor de geselecteerde sleutel ongeldig. Werk elke lokale verificator bij met het nieuw gegenereerde geheim voordat u de listener opnieuw opstart.
Harness
Installeer de draagbare RunAPI CLI-vaardigheid in een ondersteunde Harness, inspecteer ondersteunde doelen of verwijder een geïnstalleerde vaardigheid:
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
Ingebouwde doelen zijn claude, codex, gemini, openclaw en hermes. install-skill accepteert --version om een skill-release vast te zetten, --target-dir voor een aangepaste bestemming, --source voor een bronrepository en --force om een bestaande skill-map te overschrijven.
Shell-aanvulling en versie
Genereer voltooiingsscripts voor Bash, Zsh, Fish of PowerShell. Laad bijvoorbeeld Bash-voltooiing in de huidige shell:
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
Gebruik runapi --help om opdrachten weer te geven, runapi <command> --help voor de
opties van een opdracht, en runapi <service> <action> --help voor de velden van een
modelactie.
Afsluitcodes
Opdrachten eindigen met een niet-nulcode die scripts kunnen afhandelen:
0
Geslaagd
2
Authenticatiefout of niet-ondersteund platform
3
Onvoldoende tegoed of een vereiste lokale afhankelijkheid ontbreekt
4
Validatie-, niet-gevonden- of manifestparseerfout
5
Time-out, downloadfout of controlesomafwijking
6
Snelheidslimiet bereikt
7
Taak mislukt
Ga voor aanvraagvelden, Task-statuswaarden, callback-payloads, foutberichten en afhandeling van snelheidslimieten verder met de API-referentie. Gebruik SDK’s wanneer dezelfde workflow binnen een applicatie thuishoort.