跳到正文
开发者资源
开发者资源

CLI

安装并使用 RunAPI CLI 的全部功能，包括模型操作、Task、File、Upload、账户、报价、回调和 Harness。

查看 Markdown

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 release下载匹配的 windows-amd64 或 windows-arm64 压缩包，解压 runapi.exe 后将其加入 PATH。

需要可复现的部署时，可固定安装版本或安装目录：

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":"一只正在喝咖啡的蜂鸟","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json

多数模型操作是异步的，默认会等待 Task 到达终态；加上 --async 可立即返回 Task，再通过 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

命令约定

除非选项明确要求输出单个值，例如 files create --url-only 或 listen --print-secret，每个命令都会将 JSON 写到标准输出。进度和诊断信息只写到标准错误，因此 JSON 可安全传给 jq：

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

每个模型操作只能通过以下一种方式传入请求 JSON：

  • --input '<json object>' 提供内联 JSON。
  • --input-file path/to/request.json 从文件读取 JSON。
  • --input-file - 从标准输入读取 JSON。

构造请求前运行 runapi <service> <action> --help。已安装的 CLI 会列出该操作当前的字段、可接受的模型 identifier 和校验约束。

以下全局选项适用于每个命令：

选项 用途 --api-key 为本次调用指定 API Key，优先于 RUNAPI_API_KEY。 --base-url 为本次调用指定 API origin。 --timeout 设置命令总超时和 Task 最大等待时间，默认 15 分钟。 --poll-interval 设置 Task 轮询间隔，默认 3 秒。 --async 异步模型操作提交后立即返回。 --quiet 不输出标准错误中的进度信息，不影响 JSON 输出。

模型操作

模型命令的形状是 runapi <service> <action>。同步操作立即返回响应。异步操作默认会提交、轮询并返回终态 Task 结果；--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-image-2.5: 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 release 的完整操作清单。每个操作的精确请求和响应契约请查看 API 参考；版本特定字段以本地命令帮助为准。

Task 生命周期

使用 get 获取异步 Task 的当前状态而不等待。使用 wait 轮询直到 Task 完成、失败或达到命令超时。两者都需要原始 service 和 action，以便 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 source，并返回有效期为一小时的 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 bytes 写到标准输出。限制、Account 隔离和 REST 生命周期请查看 Files 与 Uploads。

Uploads

需要先发送一个或多个 Part 再组装最终 File 时，请使用 Uploads。create 声明最终 byte count 和 metadata；完成时按组装顺序重复传入 --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 读取当前 Price Schedule，可按 service、action 或模型筛选。pricing quote 为必填的 service 和 action 估算 Task 预留额；当操作依赖模型时加上 --model，并通过 --params 或 --params-file 提供 Pricing Inputs。

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

报价命令通常不需要凭据；仅当报价引用账户拥有的源 Task 时需要凭据。

身份验证和配置

runapi login 打开浏览器授权流程并保存获得的凭据。对于服务器和 CI，auth import-token 可以从标准输入接收 API Key，默认会验证并保存，避免在进程列表或 shell history 中暴露密钥：

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

auth import-token --skip-verify 支持离线镜像初始化。仅在初始化期间无法验证时使用它；之后使用 auth status 验证当前凭据。

API Key 的优先级依次为 --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 Key 的 Task callback，并可选择将每个已签名 callback 转发到本地 HTTP endpoint。使用监听功能前必须先通过浏览器登录。

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 body 写入标准输出。带有 callback_url 的 Task 仍会投递到该 URL，同时也会复制到本地监听器。

CLI 收到合法的 listener event 后，会先确认该事件，再尝试发送本地 HTTP 请求。每个事件只向本地转发一次：非 2xx 响应和连接错误会显示在终端，但不会让 listener 重放该事件。这个本地调试行为不会改变 Task callback_url 的投递重试策略。

每个 Account 的同一个 Callback Subscription Key 最多可运行 100 个活动监听器，每个 Account 总计最多可运行 1,000 个活动监听器。达到限制时，请停止空闲监听器或等待后重试；API 响应会说明是选中的 Key、当前 Account 还是服务整体容量已满。

空闲监听器大约每 15 到 30 秒检查一次新事件。事件通常会在约 15 秒内被发现，并在可用时立即读取。如果达到限制，请停止空闲监听器或等待后重试。现有交付和确认行为保持不变。

Key 的选择顺序为：一次命令使用的 --callback-api-key-id、项目 .runapi.toml 中的 callback_api_key_id、交互式选择器。项目配置保存在 Git root；如果不在 Git 仓库，则保存在当前目录，且只包含稳定 ID：

TOML 
callback_api_key_id = "token_abc123"

无需启动监听器即可打印选中 Key 的 Listen Signing Secret；若密钥泄露，可轮换它：

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

轮换会使该选中 Key 的活动监听器失效。重启监听器前，请用新打印的 secret 更新所有本地验证器。

Harness

将可移植的 RunAPI CLI skill 安装到受支持的 Harness，查看支持目标，或移除已安装的 skill：

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 固定 skill release、用 --target-dir 指定自定义位置、用 --source 指定 skill 仓库，以及用 --force 覆盖现有 skill 目录。

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 参数校验、未找到或 manifest 解析错误 5 超时、下载失败或校验和不匹配 6 触发限流 7 Task 失败

请求字段、Task 状态、callback payload、错误响应和限流处理请继续阅读 API 参考。当相同工作流属于应用内部代码时，请使用 SDK。