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
設定整體指令逾時及最長任務等待時間，預設為 15 分鐘。
--poll-interval
設定任務輪詢的間隔時間，預設為 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 輪詢直至其完成、失敗或達到命令逾時。兩個命令均需要原始服務及操作，以便 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 上傳 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 時，請使用持久檔案生命週期：
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 位元組寫入標準輸出。有關限制、帳戶隔離及 REST 生命週期，請參閱 Files and Uploads。
上傳
使用 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
輪換會使所選金鑰的有效監聽器失效。在重新啟動監聽器之前，請以新列印的密鑰更新每個本地驗證器。
接入
將可攜式 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
任務失敗