---
title: CLI | RunAPI
description: 安裝並使用每個 RunAPI CLI 指令，涵蓋模型動作、Tasks、Files、Uploads、帳號資訊、定價、回呼及 Harness。
url: https://runapi.ai/zh-TW/docs/resources/cli.md
canonical: https://runapi.ai/zh-TW/docs/resources/cli
locale: zh-TW
---

> HTML 版本: https://runapi.ai/zh-TW/docs/resources/cli
> 代理程式網站索引: https://runapi.ai/llms.txt

# CLI

RunAPI CLI 是一個以 JSON 為優先的終端機用戶端，適用於模型操作與帳戶工具。它將結果資料寫入標準輸出，並將操作進度寫入標準錯誤，因此無論是在終端機、Shell 腳本、CI 作業還是 Harness 中，都能同樣良好地運作。

## 安裝

在 Linux 或 macOS 上安裝目前版本：

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

Homebrew 和 Go 原始碼安裝方式也可使用：

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

在 Windows 上，請從 [最新 CLI 版本][1] 下載對應的 `windows-amd64` 或 `windows-arm64` 壓縮檔，解壓縮 `runapi.exe`，並將其加入 `PATH`。



[1]: https://github.com/runapi-ai/cli/releases/latest

當部署需要可重現的二進位檔時，可將安裝程式固定至特定版本或安裝目錄：

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

安裝程式還接受 `RUNAPI_VERSION`、`RUNAPI_INSTALL_DIR`、`RUNAPI_INSTALL_BASE`、`RUNAPI_DOWNLOAD_BASE` 及 `RUNAPI_SKIP_LIBC_CHECK=1`。

## 快速入門

在工作站上，於瀏覽器中登入並確認憑證來源：

```shell
runapi login
runapi auth status
```

以內嵌 JSON 輸入或 JSON 檔案執行模型動作：

```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
```

大多數模型動作均為非同步。預設情況下會等待終止結果；加上 `--async` 可立即回傳任務，並稍後使用 `wait`：

```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
```

## 指令慣例

每個指令預設在標準輸出上輸出 JSON，除非某個選項明確
要求純量值，例如 `files create --url-only` 或 `listen
--print-secret`。進度與診斷訊息會保留在標準錯誤中，
因此 JSON 可以安全地傳遞給 `jq`：

```shell
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-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`

### 圖片動作

* `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`

### 影片與動畫動作

* `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`

上方列表是此 CLI 版本的完整操作清單。每個操作的確切請求與回應合約可在 [API 參考](https://runapi.ai/zh-TW/docs/api/openai/chat-completions.md)中查閱，其本機命令說明是版本特定欄位的依據來源。

## 任務生命週期

使用 `get` 檢視非同步 Task 的當前狀態而無需等待。使用 `wait` 持續輪詢，直到 Task 完成、失敗或達到命令逾時為止。兩個命令均需指定原始服務與動作，以便 CLI 選取正確的 Task 結果格式。

```shell
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。

```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
```

來源選項互斥。`--url-only` 僅列印 URL；省略此選項則接收完整 JSON 回應。

當您需要穩定的 `file_id` 而非 URL 時，請使用持久性 File 生命週期：

```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` 需要 `--output`；傳入 `-` 可將確切的 File 位元組寫入標準輸出。請參閱 [Files and Uploads](https://runapi.ai/zh-TW/docs/resources/files.md) 以了解限制、帳戶隔離及 REST 生命週期。

## 上傳

使用 Uploads 在組合最終 File 之前傳送一個或多個 Parts。
Create 宣告最終位元組數與中繼資料；完成時請依組合順序重複指定 `--part-id`：

```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
```

## 帳戶與定價

檢查已驗證的使用者與所選帳號，然後查詢餘額與消費計數器：

```shell
runapi account info
runapi account balance
```

`pricing list` 讀取目前的價格方案。可依服務、動作或模型篩選。`pricing quote` 估算所需服務和動作的任務保留金額；當動作與模型相關時請加上 `--model`，並透過 `--params` 或 `--params-file` 提供定價輸入。

```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
```

定價指令無需憑證，除非報價涉及帳戶自有的來源任務。

## 身分驗證與設定

`runapi login` 開啟瀏覽器授權流程並儲存所產生的憑證。對於伺服器和 CI，`auth import-token` 從標準輸入接受 API 金鑰，預設會進行驗證，並在不於程序清單或 Shell 歷史紀錄中暴露其值的情況下儲存：

```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 端點。使用監聽器操作前需先完成瀏覽器登入。

```shell
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：

```toml
callback_api_key_id = "token_abc123"
```

列印所選金鑰的 Listen Signing Secret 而不啟動監聽器，或在金鑰外洩後進行輪換：

```shell
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
```

輪換作業會使所選金鑰的有效監聽器失效。在重新啟動監聽器之前，請以新產生的密鑰更新每個本機驗證器。

## Harness

將可攜式 RunAPI CLI 技能安裝至支援的 Harness，檢查支援的目標，或移除已安裝的技能：

```shell
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 自動補全：

```shell
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` | 任務失敗 |

如需請求欄位、Task 狀態值、回呼酬載、錯誤主體及速率限制處理，請繼續閱讀 [API 參考](https://runapi.ai/zh-TW/docs/api/openai/chat-completions.md)。當相同的工作流程需要整合於應用程式內時，請使用 [SDK](https://runapi.ai/zh-TW/docs/resources/sdks.md)。

---

## RunAPI 的更多內容

- [首頁](https://runapi.ai/zh-TW/.md)
- [模型目錄](https://runapi.ai/zh-TW/models.md)
- [價格](https://runapi.ai/zh-TW/pricing.md)
- [提供商](https://runapi.ai/zh-TW/models)
- [文件](https://runapi.ai/zh-TW/docs/guides)
- [SDK](https://runapi.ai/zh-TW/sdk.md)
- [CLI](https://runapi.ai/zh-TW/cli.md)
- [MCP Server](https://runapi.ai/zh-TW/mcp.md)
- [Claude Code 與 Cursor](https://runapi.ai/zh-TW/claude-code-vs-cursor.md)
- [Cursor API 設定](https://runapi.ai/zh-TW/cursor-api-setup.md)
- [RunAPI 與 OpenRouter](https://runapi.ai/zh-TW/openrouter-alternative.md)
- [企業版](https://runapi.ai/zh-TW/contact.md)
- [聯絡我們](https://runapi.ai/zh-TW/contact.md)
- [服務條款](https://runapi.ai/zh-TW/terms.md)
- [隱私權](https://runapi.ai/zh-TW/privacy.md)
- [代理程式網站索引](https://runapi.ai/llms.txt)

聯絡我們: contact@runapi.ai

## 結構化資料

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "zh-TW",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/zh-TW",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/zh-TW/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "zh-TW",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/zh-TW",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/zh-TWicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "zh-TW",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "安裝並使用每個 RunAPI CLI 指令，涵蓋模型動作、Tasks、Files、Uploads、帳號資訊、定價、回呼及 Harness。",
    "url": "https://runapi.ai/zh-TW/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/zh-TW/docs/resources/cli"
  }
]
```