Zum Inhalt springen
Entwickler-Ressourcen
Entwickler-Ressourcen

CLI

Jeden RunAPI-CLI-Befehl für Modellaktionen, Tasks, Dateien, Uploads, Kontoinformationen, Preise, Callbacks und Harness installieren und verwenden.

Markdown anzeigen

Die RunAPI CLI ist ein JSON-orientierter Terminal-Client für Modellaktionen und Konto-Werkzeuge. Sie schreibt Ergebnisdaten auf die Standardausgabe und operativen Fortschritt auf die Standardfehlerausgabe und eignet sich gleichermaßen für Terminals, Shell-Skripte, CI-Jobs und Harness.

Installieren

Das aktuelle Release auf Linux oder macOS installieren:

SHELL 
curl -fsSL https://runapi.ai/cli/install.sh | sh

Homebrew- und Go-Quellinstallationen sind ebenfalls verfügbar:

SHELL 
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest

Laden Sie unter Windows das passende windows-amd64- oder windows-arm64-Archiv aus dem neuesten CLI-Release herunter, extrahieren Sie runapi.exe und fügen Sie es zum PATH hinzu.

Fixieren Sie den Installer auf eine Version oder ein Installationsverzeichnis, wenn eine Deployment eine reproduzierbare Binärdatei erfordert:

SHELL 
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"

Das Installationsskript akzeptiert außerdem RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE und RUNAPI_SKIP_LIBC_CHECK=1.

Schnellstart

Melden Sie sich auf einer Workstation im Browser an und bestätigen Sie die Anmeldeinformationsquelle:

SHELL 
runapi login
runapi auth status

Eine Modell-Aktion mit einer inline JSON-Eingabe oder einer JSON-Datei ausführen:

SHELL 
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

Die meisten Modellaktionen sind asynchron. Sie warten standardmäßig auf ein Ergebnis im Endzustand; fügen Sie --async hinzu, um den Task sofort zurückzugeben und später wait zu verwenden:

SHELL 
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

Befehlskonventionen

Jeder Befehl gibt JSON auf der Standardausgabe aus, sofern eine Option nicht ausdrücklich einen skalaren Wert anfordert, z. B. files create --url-only oder listen --print-secret. Fortschritts- und Diagnosemeldungen bleiben auf der Standardfehlerausgabe, sodass JSON sicher an jq weitergeleitet werden kann:

SHELL 
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}

Modellaktionen akzeptieren genau eine Anfrage-Eingabequelle:

  • --input '<json object>' stellt inline JSON bereit.
  • --input-file path/to/request.json lädt JSON aus einer Datei.
  • --input-file - liest JSON aus der Standardeingabe.

Verwende runapi <service> <action> --help, bevor du eine Anfrage konstruierst. Die installierte CLI listet die aktuellen Felder der Aktion, akzeptierte Modell- Identifikatoren und Validierungsbeschränkungen auf.

Diese globalen Optionen gelten für jeden Befehl:

Option Zweck --api-key Verwendet einen API-Schlüssel für diesen Aufruf. Überschreibt RUNAPI_API_KEY. --base-url Verwendet einen anderen API-Ursprung für diesen Aufruf. --timeout Legt das gesamte Befehls-Timeout und die maximale Wartezeit für Aufgaben fest. Der Standardwert beträgt 15 Minuten. --poll-interval Legt das Intervall für das Abfragen von Aufgaben fest. Der Standardwert beträgt 3 Sekunden. --async Kehrt sofort nach dem Einreichen einer asynchronen Modell-Aktion zurück. --quiet Unterdrückt Fortschrittsausgaben auf der Standardfehlerausgabe, ohne die JSON-Ausgabe zu verändern.

Modellaktionen

Die Modellbefehlsstruktur lautet runapi <service> <action>. Synchrone Aktionen geben ihre Antwort sofort zurück. Bei asynchronen Aktionen ist das Standardverhalten: Einreichen, Abfragen und Zurückgeben des abschließenden Task-Ergebnisses; --async gibt stattdessen die Erstellungsantwort zurück.

Bei übergeordneten Medien-URL-Feldern wird ein lesbarer lokaler Dateipfad hochgeladen, bevor die Modellaktion ausgeführt wird. Bestehende http://- und https://-URLs werden unverändert gesendet. Verwenden Sie files create, wenn Sie eine wiederverwendbare temporäre URL benötigen, wenn die Quelle eine Remote-URL ist oder wenn die Quelle Base64-Daten sind.

Audio- und Musikaktionen

  • 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-phrase
  • producer: text-to-music
  • gemini-omni: create-audio, create-character, text-to-video
  • openai-tts: text-to-speech
  • fish-audio: text-to-speech
  • gemini-tts: text-to-speech
  • elevenlabs: isolate-audio, speech-to-text, text-to-dialogue, text-to-sound, text-to-speech

Bildaktionen

  • nano-banana: edit-image, text-to-image
  • imagen-4: remix-image, text-to-image
  • seedream: decompose-layers, edit-image, text-to-image
  • flux: remix-image, text-to-image
  • flux-2: remix-image, text-to-image
  • flux-kontext: text-to-image
  • qwen-2: edit-image, text-to-image
  • qwen-3: edit-image, text-to-image
  • qwen-image: edit-image, remix-image, text-to-image
  • recraft: remove-background, upscale-image
  • z-image: text-to-image
  • ideogram-v3: edit-image, reframe-image, remix-image, text-to-image
  • gpt-image: edit-image, text-to-image
  • gpt-image-2: edit-image, text-to-image
  • gpt-4o-image: text-to-image
  • midjourney: edit-image, get-seed, image-to-prompt, shorten-prompt, text-to-image

Video- und Animationsaktionen

  • veo-3-1: extend-video, text-to-video, upscale-video
  • seedance: text-to-video
  • runway: extend-video, text-to-video
  • runway-aleph: edit-video
  • kling: avatar, edit-video, extend-video, image-to-video, motion-control, text-to-video
  • infinitetalk: audio-to-video
  • omnihuman: audio-to-video, human-identification, subject-detection
  • wan: animate, edit-video, image-to-video, speech-to-video, text-to-image, text-to-video
  • luma: modify-video
  • hailuo: image-to-video, text-to-video
  • volcengine-lip-sync: lip-sync-video
  • happyhorse: edit-video, image-to-video, text-to-video
  • grok-imagine: edit-image, extend, image-to-video, text-to-image, text-to-video, upscale-image
  • topaz: upscale-image, upscale-video
  • midjourney: extend-video, image-to-video

Die obige Liste ist das vollständige Aktionsinventar in diesem CLI-Release. Der genaue Anfrage- und Antwortvertrag jeder Aktion ist in der API-Referenz verfügbar, und die lokale Befehlshilfe ist die Quelle für versionsspezifische Felder.

Task-Lebenszyklus

Verwende get, um den aktuellen Zustand eines asynchronen Tasks zu prüfen, ohne zu warten. Verwende wait, um so lange abzufragen, bis er abgeschlossen ist, fehlschlägt oder das Befehlstimeout erreicht. Beide Befehle erfordern den ursprünglichen Service und die Aktion, damit die CLI die korrekte Task-Ergebnisstruktur auswählen kann.

SHELL 
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s

Dateien

runapi files create behält den temporären File-Upload-URL-Ablauf bei. Es lädt einen lokalen Pfad, eine Remote-URL oder eine Base64-Quelle hoch und gibt eine URL zurück, die nach einer Stunde abläuft.

SHELL 
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

Die Quellenoptionen schließen sich gegenseitig aus. --url-only gibt nur die URL aus; lassen Sie diese Option weg, um die vollständige JSON-Antwort zu erhalten.

Verwenden Sie den persistenten Datei-Lebenszyklus, wenn Sie eine stabile file_id anstelle einer URL benötigen:

SHELL 
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 erfordert --output; übergeben Sie -, um die genauen File-Bytes in die Standardausgabe zu schreiben. Siehe Files and Uploads für Limits, Account-Isolierung und den REST-Lebenszyklus.

Hochladen

Verwende Uploads, um einen oder mehrere Parts zu senden, bevor die endgültige File zusammengestellt wird. Create deklariert die endgültige Byte-Anzahl und Metadaten; wiederhole --part-id in der Kompositionsreihenfolge beim Abschließen:

SHELL 
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

Konto und Preisgestaltung

Den authentifizierten Benutzer und das ausgewählte Konto prüfen, dann Guthaben und Ausgabenzähler abfragen:

SHELL 
runapi account info
runapi account balance

pricing list liest aktuelle Preispläne. Filtern Sie nach Service, Action oder Modell. pricing quote schätzt die Task-Reservierung für einen erforderlichen Service und eine Action; fügen Sie --model hinzu, wenn die Action modellspezifisch ist, und geben Sie Pricing Inputs mit --params oder --params-file an.

SHELL 
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

Preisabfragen erfordern keine Anmeldedaten, es sei denn, das Angebot bezieht sich auf einen kontoeigenen Quell-Task.

Authentifizierung und Konfiguration

runapi login öffnet einen Browser-Autorisierungsablauf und speichert die resultierende Anmeldeinformation. Für Server und CI akzeptiert auth import-token einen API-Schlüssel von der Standardeingabe, verifiziert ihn standardmäßig und speichert ihn, ohne den Wert in der Prozessliste oder dem Shell-Verlauf preiszugeben:

SHELL 
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout

auth import-token --skip-verify unterstützt die Offline-Image-Einrichtung. Verwenden Sie es nur, wenn die Verifizierung während der Einrichtung nicht möglich ist; auth status verifiziert die aktive Anmeldeinformation zu einem späteren Zeitpunkt.

Die Priorität des API-Schlüssels ist --api-key, dann RUNAPI_API_KEY, dann die lokale CLI-Konfigurationsdatei. Die Priorität der Base URL ist --base-url, dann RUNAPI_BASE_URL, dann die gespeicherte Base URL, dann https://runapi.ai. Die Konfigurationsdatei ist ~/.config/runapi/config.json oder $XDG_CONFIG_HOME/runapi/config.json, wenn XDG_CONFIG_HOME gesetzt ist.

Lokaler Callback-Listener

runapi listen empfängt Task-Callbacks für einen ausgewählten API-Schlüssel und leitet optional jeden signierten Callback an einen lokalen HTTP-Endpunkt weiter. Eine Browser-Anmeldung ist erforderlich, bevor Listener-Operationen verwendet werden können.

SHELL 
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123

Die positionelle URL und --forward-to sind Alternativen. Der Listener schreibt jeden signierten Callback-Body auf die Standardausgabe. Ein Task mit callback_url liefert weiterhin an diese URL und wird zusätzlich an den lokalen Listener kopiert.

Nachdem ein gültiges Listener-Ereignis empfangen wurde, bestätigt die CLI es, bevor sie die lokale HTTP-Anfrage versucht. Jedes Ereignis wird einmal lokal weitergeleitet: Nicht-2xx-Antworten und Verbindungsfehler werden im Terminal gemeldet, führen jedoch nicht dazu, dass der Listener das Ereignis erneut abspielt. Dieses lokale Debugging-Verhalten ändert nichts an den Zustellungswiederholungen für die callback_url einer Task.

Jedes Konto kann bis zu 100 aktive Listener pro Callback-Abonnementschlüssel und insgesamt 1.000 aktive Listener ausführen. Wenn ein Limit erreicht ist, stoppen Sie einen inaktiven Listener oder warten Sie und versuchen Sie es erneut. Die API-Antwort gibt an, ob der ausgewählte Schlüssel, Ihr Konto oder die Gesamtdienstkapazität ausgeschöpft ist.

Ein inaktiver Listener prüft alle 15 bis 30 Sekunden auf neue Ereignisse. Ereignisse werden normalerweise innerhalb von etwa 15 Sekunden gefunden und sofort gelesen, wenn sie verfügbar sind. Wenn ein Limit erreicht wird, beenden Sie einen inaktiven Listener oder warten Sie und versuchen Sie es erneut. Das bestehende Zustellungs- und Bestätigungsverhalten bleibt unverändert.

Die Schlüsselauswahl erfolgt in dieser Reihenfolge: --callback-api-key-id für einen einzelnen Befehl, callback_api_key_id in der Projekt-.runapi.toml, dann eine interaktive Auswahl. Die Projektkonfiguration wird im Git-Stammverzeichnis oder im aktuellen Verzeichnis außerhalb eines Git-Repositorys gespeichert und enthält nur die stabile ID:

TOML 
callback_api_key_id = "token_abc123"

Den Listen-Signing-Secret eines ausgewählten Schlüssels ausgeben, ohne einen Listener zu starten, oder ihn nach einer Offenlegung rotieren:

SHELL 
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123

Die Rotation macht aktive Listener für den ausgewählten Schlüssel ungültig. Aktualisieren Sie jeden lokalen Verifier mit dem neu angezeigten Geheimnis, bevor Sie seinen Listener neu starten.

Testrahmen

Die portable RunAPI-CLI-Skill in einen unterstützten Harness installieren, unterstützte Ziele prüfen oder eine installierte Skill entfernen:

SHELL 
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex

Eingebaute Ziele sind claude, codex, gemini, openclaw und hermes. install-skill akzeptiert --version zum Festlegen einer Skill-Version, --target-dir für ein benutzerdefiniertes Zielverzeichnis, --source für ein Quell-Repository und --force zum Überschreiben eines vorhandenen Skill-Verzeichnisses.

Shell-Vervollständigung und Version

Vervollständigungsskripte für Bash, Zsh, Fish oder PowerShell generieren. Beispiel: Bash-Vervollständigung in der aktuellen Shell laden:

SHELL 
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version

Verwende runapi --help, um Befehle aufzulisten, runapi <command> --help für die Optionen eines Befehls und runapi <service> <action> --help für die Felder einer Modell-Aktion.

Exit-Codes

Befehle enden mit einem Nicht-Null-Code, den Skripte verarbeiten können:

Code Bedeutung 0 Erfolg 2 Authentifizierungsfehler oder nicht unterstützte Plattform 3 Unzureichende Credits oder eine erforderliche lokale Abhängigkeit fehlt 4 Validierungs-, Nicht-gefunden- oder Manifest-Parsing-Fehler 5 Zeitüberschreitung, Download-Fehler oder Prüfsummen-Abweichung 6 Ratenlimit überschritten 7 Aufgabe fehlgeschlagen

Für Anfragefelder, Task-Statuswerte, Callback-Payloads, Fehlerkörper und die Behandlung von Ratenbegrenzungen fahren Sie mit der API Referenz fort. Verwenden Sie SDKs, wenn derselbe Arbeitsablauf innerhalb einer Anwendung stattfindet.