---
title: CLI | RunAPI
description: 安裝並使用所有 RunAPI CLI 命令，用於模型動作、Tasks、Files、Uploads、帳戶資訊、定價、回呼及 Harness。
url: https://runapi.ai/zh-HK/docs/resources/cli.md
canonical: https://runapi.ai/zh-HK/docs/resources/cli
locale: zh-HK
---

> HTML 版本: https://runapi.ai/zh-HK/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` | 設定整體指令逾時及最長任務等待時間，預設為 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-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-HK/docs/api/openai/chat-completions.md)中查閱，而本地命令說明則是版本特定欄位的來源。

## 任務生命週期

使用 `get` 在不等待的情況下檢查非同步 Task 的當前狀態。使用 `wait` 輪詢直至其完成、失敗或達到命令逾時。兩個命令均需要原始服務及操作，以便 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 上傳 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 時，請使用持久檔案生命週期：

```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 位元組寫入標準輸出。有關限制、帳戶隔離及 REST 生命週期，請參閱 [Files and Uploads](https://runapi.ai/zh-HK/docs/resources/files.md)。

## 上傳

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

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

## 接入

將可攜式 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-HK/docs/api/openai/chat-completions.md)。若同一工作流程屬於應用程式內部，請使用
[SDKs](https://runapi.ai/zh-HK/docs/resources/sdks.md)。

---

## RunAPI 的更多內容

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

聯絡我們: contact@runapi.ai

## 結構化資料

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