CLI
安裝並使用每個 RunAPI CLI 指令，涵蓋模型動作、Tasks、Files、Uploads、帳號資訊、定價、回呼及 Harness。
RunAPI CLI 是一個以 JSON 為優先的終端機用戶端，適用於模型操作與帳戶工具。它將結果資料寫入標準輸出，並將操作進度寫入標準錯誤，因此無論是在終端機、Shell 腳本、CI 作業還是 Harness 中，都能同樣良好地運作。
安裝
在 Linux 或 macOS 上安裝目前版本：
curl -fsSL https://runapi.ai/cli/install.sh | sh
Homebrew 和 Go 原始碼安裝方式也可使用：
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
在 Windows 上，請從 最新 CLI 版本 下載對應的 windows-amd64 或 windows-arm64 壓縮檔，解壓縮 runapi.exe，並將其加入 PATH。
當部署需要可重現的二進位檔時，可將安裝程式固定至特定版本或安裝目錄：
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"
安裝程式還接受 RUNAPI_VERSION、RUNAPI_INSTALL_DIR、RUNAPI_INSTALL_BASE、RUNAPI_DOWNLOAD_BASE 及 RUNAPI_SKIP_LIBC_CHECK=1。
快速入門
在工作站上，於瀏覽器中登入並確認憑證來源：
runapi login
runapi auth status
以內嵌 JSON 輸入或 JSON 檔案執行模型動作：
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
大多數模型動作均為非同步。預設情況下會等待終止結果；加上 --async 可立即回傳任務，並稍後使用 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
指令慣例
每個指令預設在標準輸出上輸出 JSON，除非某個選項明確
要求純量值，例如 files create --url-only 或 listen
--print-secret。進度與診斷訊息會保留在標準錯誤中，
因此 JSON 可以安全地傳遞給 jq：
runapi nano-banana text-to-image --input-file request.json \
| jq -r '.images[].url' \
| xargs -I{} curl -OL {}
模型動作恰好接受一個請求輸入來源：
--input '<json object>'提供內嵌 JSON。--input-file path/to/request.json從檔案載入 JSON。--input-file -從標準輸入讀取 JSON。
在建構請求之前，請先執行 runapi <service> <action> --help。已安裝的 CLI 會列出該動作目前的欄位、接受的模型識別碼及驗證限制。
以下全域選項適用於每個命令：
--api-key
為此次呼叫使用 API 金鑰。會覆寫 RUNAPI_API_KEY。
--base-url
為此次呼叫使用不同的 API 來源。
--timeout
設定整體指令逾時時間及最長 Task 等待時間。預設為 15 分鐘。
--poll-interval
設定 Task 輪詢間隔。預設為 3 秒。
--async
提交非同步模型動作後立即返回。
--quiet
在不變更 JSON 輸出的情況下，隱藏標準錯誤的進度資訊。
模型動作
模型命令格式為 runapi <service> <action>。同步操作會立即返回回應。對於非同步操作，預設行為是提交、輪詢並返回終止的任務結果；--async 則返回建立回應。
對於頂層媒體 URL 欄位，在模型動作執行前，可讀取的本機檔案路徑會先上傳。現有的 http:// 與 https:// URL 則原樣傳送。當您需要可重複使用的暫時 URL、來源為遠端 URL，或來源為 Base64 資料時，請使用 files create。
音訊與音樂操作
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
圖片動作
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
影片與動畫動作
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
上方列表是此 CLI 版本的完整操作清單。每個操作的確切請求與回應合約可在 API 參考中查閱，其本機命令說明是版本特定欄位的依據來源。
任務生命週期
使用 get 檢視非同步 Task 的當前狀態而無需等待。使用 wait 持續輪詢，直到 Task 完成、失敗或達到命令逾時為止。兩個命令均需指定原始服務與動作，以便 CLI 選取正確的 Task 結果格式。
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
檔案
runapi files create 保留暫時 File Upload URL 流程。它上傳一個本機路徑、遠端 URL 或 Base64 來源，並回傳一個一小時後到期的 URL。
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
來源選項互斥。--url-only 僅列印 URL；省略此選項則接收完整 JSON 回應。
當您需要穩定的 file_id 而非 URL 時，請使用持久性 File 生命週期：
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 需要 --output；傳入 - 可將確切的 File 位元組寫入標準輸出。請參閱 Files and Uploads 以了解限制、帳戶隔離及 REST 生命週期。
上傳
使用 Uploads 在組合最終 File 之前傳送一個或多個 Parts。
Create 宣告最終位元組數與中繼資料；完成時請依組合順序重複指定 --part-id：
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
帳戶與定價
檢查已驗證的使用者與所選帳號，然後查詢餘額與消費計數器：
runapi account info
runapi account balance
pricing list 讀取目前的價格方案。可依服務、動作或模型篩選。pricing quote 估算所需服務和動作的任務保留金額；當動作與模型相關時請加上 --model，並透過 --params 或 --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
定價指令無需憑證，除非報價涉及帳戶自有的來源任務。
身分驗證與設定
runapi login 開啟瀏覽器授權流程並儲存所產生的憑證。對於伺服器和 CI，auth import-token 從標準輸入接受 API 金鑰，預設會進行驗證，並在不於程序清單或 Shell 歷史紀錄中暴露其值的情況下儲存：
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
auth import-token --skip-verify 支援離線映像設定。僅在設定期間無法執行驗證時才使用此選項；auth status 可在之後驗證目前的有效憑證。
API 金鑰的優先順序為 --api-key，其次為 RUNAPI_API_KEY，最後為本機 CLI 設定檔。Base URL 的優先順序為 --base-url，其次為 RUNAPI_BASE_URL，再其次為已儲存的 base URL，最後為 https://runapi.ai。設定檔路徑為 ~/.config/runapi/config.json，若已設定 XDG_CONFIG_HOME，則為 $XDG_CONFIG_HOME/runapi/config.json。
本機回呼監聽器
runapi listen 接收一個選定 API 金鑰的任務回呼，並可選擇將每個已簽署的回呼轉送至本機 HTTP 端點。使用監聽器操作前需先完成瀏覽器登入。
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
位置 URL 與 --forward-to 為互斥選項。監聽器會將每個已簽署的回呼本體寫入標準輸出。具有 callback_url 的任務會持續傳送至該 URL，同時也會複製一份至本機監聽器。
收到有效的監聽器事件後，CLI 會在嘗試本機 HTTP 請求之前先進行確認。每個事件只會在本機轉發一次：非 2xx 回應與連線錯誤會在終端機中回報，但不會使監聽器重播該事件。此本機除錯行為不會影響任務 callback_url 的傳送重試機制。
每個帳戶在每個回呼訂閱金鑰下最多可執行 100 個活躍監聽器，帳戶總計最多 1,000 個活躍監聽器。達到限制時，請停止閒置的監聽器或稍候再試。API 回應會說明是所選金鑰、您的帳戶，還是整體服務容量已滿。
閒置的監聽器約每 15 至 30 秒檢查一次新事件。事件通常在約 15 秒內被找到，並在可用時立即讀取。若達到限制，請停止閒置的監聽器，或稍等後再試。現有的傳送與確認行為不受影響。
金鑰的選擇順序如下：單一指令使用 --callback-api-key-id，專案 .runapi.toml 中的 callback_api_key_id，最後才是互動式選擇器。專案設定儲存於 Git 根目錄，若不在 Git 儲存庫中則儲存於目前目錄，且僅包含穩定的 ID：
callback_api_key_id = "token_abc123"
列印所選金鑰的 Listen Signing Secret 而不啟動監聽器，或在金鑰外洩後進行輪換：
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
輪換作業會使所選金鑰的有效監聽器失效。在重新啟動監聽器之前，請以新產生的密鑰更新每個本機驗證器。
Harness
將可攜式 RunAPI CLI 技能安裝至支援的 Harness，檢查支援的目標，或移除已安裝的技能：
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
內建目標為 claude、codex、gemini、openclaw 和 hermes。install-skill 接受 --version 以固定技能版本、--target-dir 指定自訂目的地目錄、--source 指定來源儲存庫，以及 --force 覆蓋現有的技能目錄。
Shell 自動補全與版本
為 Bash、Zsh、Fish 或 PowerShell 產生自動補全腳本。例如，在目前的 Shell 中載入 Bash 自動補全：
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
使用 runapi --help 列出所有命令，使用 runapi <command> --help 查看某命令的選項，使用 runapi <service> <action> --help 查看模型動作的欄位。
結束代碼
指令以非零代碼結束，腳本可對此進行處理：
0
成功
2
身分驗證失敗或不支援的平台
3
點數不足或缺少必要的本地相依套件
4
驗證失敗、找不到資源或資訊清單解析錯誤
5
逾時、下載失敗或總和檢查碼不符
6
已達速率限制
7
任務失敗