runapi-cli

RunAPI CLI

runapi CLI 仅对其已安装命令目录中的服务执行一次性制品或结果。应用、后端、工作进程、库或生产代码集成应改用 RunAPI SDK。

选择方式

一次性制品或结果请使用 CLI。应用、后端、工作进程、库或生产代码请使用 SDK。编写服务命令前，先通过 runapi --help 查看已安装的命令目录；只有其中列出了该服务时才继续。如果服务未列出，应改用其 SDK 或公共 API 合约，不要猜测 CLI 命令。

安装

目标	命令
macOS / Linux（交互式）	brew install runapi-ai/tap/runapi
服务器 / CI（无头模式）	curl -fsSL https://runapi.ai/cli/install.sh | sh

安装程序会检测操作系统和架构（Linux 和 macOS，amd64 和 arm64），从 https://runapi.ai/cli/latest.json 验证 SHA-256 校验和，并在验证失败时拒绝写入二进制文件。

身份验证

先检查当前状态：

runapi auth status

来源	方式
环境（Agent / 无头模式默认）	从环境中读取 RUNAPI_API_KEY
已保存的配置（Agent / 服务器 / CI）	printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -（以 0600 模式写入 ~/.config/runapi/config.json）
浏览器登录（交互式备用方式）	在终端中运行 runapi login，或在 MCP 主机上使用 MCP login 工具

RUNAPI_BASE_URL 可覆盖默认基础 URL。

RunAPI MCP Server 与 CLI 读取同一个 ~/.config/runapi/config.json。runapi login 或 MCP login 工具完成后，经过身份验证的 MCP 工具即可使用已保存的凭据；如有需要，请让主机重新加载配置。

避免直接运行 runapi auth import-token --token "$KEY"——在共享主机上，该值会显示在 ps -ef 中。请使用标准输入（--token -）或在环境中设置 RUNAPI_API_KEY。

查看服务、命令和字段

CLI 以 JSON 为核心：每个服务都提供类型化命令，每个命令通过 --help 说明其请求字段。编写请求前务必先检查，不要猜测标志。

runapi --help
runapi suno --help
runapi suno text-to-music --help

按以下顺序选择功能：使用 runapi --help 选择其中列出的服务，然后检查 runapi <service> --help。仅从服务帮助中选择 <action>，然后检查 runapi <service> <action> --help，以了解当前请求合约，包括嵌套字段和规则。只能使用列出的服务、操作、模型、字段和条件组合。

运行模型

将有效 JSON 写入文件，并通过 --input-file 传入。默认命令会同步等待并轮询，直到任务完成。只有调用方明确需要该传输方式时，才使用内联 --input 或标准输入。

# Synchronous: submit and poll until done
runapi suno text-to-music --input-file request.json

# Asynchronous: submit and return immediately, then poll separately
runapi suno text-to-music --async --input-file request.json
runapi wait <task-id> --service suno --action text-to-music

# Inspect a task without waiting
runapi get <task-id> --service suno --action text-to-music

只有用户明确要求后台执行、轮询或 Webhook 集成时，才使用 --async。保留返回的任务 ID，并在执行 get 或 wait 时使用所提交命令中的确切服务 / 操作组合。

JSON 响应会输出到 stdout；进度行会输出到 stderr。使用 jq 管道处理下游数据。

账户

runapi account info
runapi account balance

实时定价

定价命令会返回付费任务的当前估算值。pricing list 和普通的 pricing quote 调用无需 API 密钥。使用账户所有的 source_task_id 获取报价时，需遵循常规 API 密钥身份验证规则。

runapi pricing list --service suno
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 --model suno-v4 \
  --params-file pricing-inputs.json

自费 x402 REST 调用（无需 API 密钥）

当 Agent 拥有钱包，且必须直接为受支持的 Task 端点付费时，使用此方式。此方式仅支持 REST；CLI 和 MCP 服务不会添加 x402 传输方式。付款前不要注册、创建 API 密钥、购买额度或创建 Task。

使用 Agent 运行时或钱包平台提供的 x402 v2 客户端。必须具备可用的钱包签名器和 x402 v2 客户端；否则请停止操作并报告缺少的前提条件。使用标准 x402 签名；API 密钥方式仍是独立的身份验证途径。

前置条件和发现

Agent 平台负责管理钱包和签名操作。钱包必须在 Base 主网上持有 USDC（eip155:8453），且签名密钥必须留在平台的安全钱包边界内。v1 资产为 USDC 合约 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913。

在花费前，发现模型和无需身份验证的公开价格：

BASE_URL="${RUNAPI_BASE_URL:-https://runapi.ai}"
curl -fsS "$BASE_URL/api/v1/models"
curl -fsS "$BASE_URL/api/v1/price_schedules?service=suno&action=text_to_music&model=suno-v4"
curl -fsS -X POST "$BASE_URL/api/v1/price_quotes" \
  -H 'Content-Type: application/json' \
  -d '{
  "service":"suno",
  "action":"text_to_music",
  "model":"suno-v4",
  "params":{
    "prompt":"A chill lo-fi beat"
  }
}'

只有计费方式为 per_call、具有 unit_price_cents，且价格不超过 10 USDC 的端点才会自动符合条件。价格响应是发现数据；支付金额、资产、收款方和网络仅来自实际 Task 请求返回的 PAYMENT-REQUIRED 挑战中的 accepts 条目。该挑战有效期为 300 秒。

完成标准：钱包位于 Base 主网且有足够的 USDC，端点根据实时价格契约符合条件，并且保留了确切的 Task 请求以供签名和重放。

标准 x402 v2 请求

发送不带 API 密钥的常规 JSON 请求，并保留确切的方法、URL 和正文，以便在需要时重试：

curl -i -X POST "$BASE_URL/api/v1/suno/text_to_music" \
  -H 'Content-Type: application/json' \
  --data @request.json

对于受支持的付费 Task 端点，首次响应为 402，并带有标准的 PAYMENT-REQUIRED 标头。将该标头传递给连接 Agent 钱包的现有 x402 v2 客户端。客户端会对支付要求进行签名，并使用 PAYMENT-SIGNATURE 重放同一请求；不要自行设计选择加入标头、202 支付协议、Capability、Payment Attempt 或专用 RunAPI 标头。概念上：

request = {method: POST, url: task_url, json: payload}
response = x402_client.send(request, wallet=agent_wallet)
# The client handles 402, PAYMENT-REQUIRED, signing, and the retry:
#   retry request header: PAYMENT-SIGNATURE: <client-generated value>
assert response.status == 200
# settlement evidence is in PAYMENT-RESPONSE; keep it with the task record

成功后，RunAPI 会返回端点常规的 200 正文和标准的 PAYMENT-RESPONSE 标头。只能使用 x402 客户端解码该标头；切勿记录或公开 PAYMENT-SIGNATURE。200 正文可能说明 Task 仍在处理中：异步结果交付属于 RunAPI Task 契约，而非 x402 协议状态。付款前，RunAPI 只会验证参数和价格；不会下载或处理媒体。

完成标准：重试返回 HTTP 200，保留结算凭证，且日志中不含已签名的支付值。

此身份验证划分是有意设计的：有效 API 密钥仍使用额度；不带凭据的受支持付费 Task 端点使用 x402 并返回 402；其他不带凭据的端点仍返回 401。支付验证失败也仍返回 402。x402 不会创建 API 密钥、额度余额、登录信息或 MCP 能力。

读取绑定的 Task

成功的 200 正文会在端点常规响应中增加一个访问授权；其他端点专属字段仍然存在：

{
  "task_id": "task_123",
  "access_token": "tat_abc...",
  "poll_url": "https://runapi.ai/api/v1/tasks/task_123?access_token=tat_abc..."
}

完成标准：Agent 已从同一成功响应中保存 task_id、access_token 和原样的 poll_url。

原样保存 poll_url 并反复对其执行 GET；查询字符串中的令牌是预期的身份验证机制。它是仅针对一个 Task 的只读授权，不能读取账户、列出 Task 或写入任何内容：

curl -fsS "$POLL_URL"

完成标准：轮询仅在 Task 状态达到终态，或发生已定义的 404/传输故障时结束；绝不会将处理中响应视为最终结果。

查询响应为：

{"id":"task_123","status":"processing"}

当返回的状态不是终态时，以有界延迟继续轮询。到达终态后，completed 会包含 response，其中包括结果的 HTTP 状态、内容类型、标头和正文；如果保留了终态错误响应，failed 会包含该响应。不要将轮询 URL 替换为 API 密钥请求，也不要假设支付本身就是任务结果。

tat_ 令牌仅签发一次，但可针对该 Task 重复读取。它会在 Task 达到终态 30 天后过期。无效、过期和与 Task 不匹配的令牌都会返回 404；不要将这些情况作为身份验证或支付失败重试。

完成标准：Agent 已收到终态结果，或已为操作人员记录确切的终态/错误状态。

任务失败与手动退款

如果已结算的 x402 Task 最终进入 failed 状态，RunAPI 会记录一笔全额手动退款义务，金额为实际收到的 USDC 最小单位金额。这属于运维工作流：由获授权的操作员发送链上退款。不提供自动链上退款，也不需要退款页面。请为操作员保留 Task ID、结算交易哈希、付款方钱包、网络、金额和 PAYMENT-RESPONSE。

对于仍在处理中的 Task、结算情况未知或回调投递失败，不要承诺退款；这些状态不会产生此终态失败义务。

完成标准：对于终态 failed，Agent 已保留结算凭证并将退款信息提交给获授权的操作员；不得声称退款已执行。

本地回调监听器

访问监听器需要使用 runapi login 签发的凭据；普通导入的 API 密钥无法列出回调候选项、读取监听签名密钥或打开监听器。此限制仅适用于监听器操作：普通 API 密钥仍可创建和查询任务。

从 Agent 运行监听器之前，请检查已保存的身份验证信息，并列出当前成员的密钥元数据：

runapi auth status
runapi api-keys list --json

如果 API 返回 cli_listen_required，请说明导入的密钥仍保留其现有 API 访问权限，但无法列出或选择监听器密钥。请用户移除任何 --api-key 或 RUNAPI_API_KEY 覆盖设置，然后在其终端中完成 runapi login（或使用 MCP login 工具），再重试 runapi listen。不要使用导入的 API 密钥或管理密钥重试。

每个候选项都包含 id、name、masked_token 和 enabled。请选择已启用且稳定的 id；名称和掩码仅用于显示上下文，因此重命名密钥不会使已保存的选择失效。如果有多个已启用的密钥，且项目未指定其中一个，请向用户展示候选项，而不要默默替用户选择。

选择优先级如下：

1. 本次调用使用 --callback-api-key-id <id>。此操作不会改写项目配置。
2. Git 根目录下 .runapi.toml 中的 callback_api_key_id，或者在 git 仓库之外使用当前目录中的该字段。
3. TTY 选择器。仅当服务端验证监听器会话后，才会写入选定的 ID。

非 TTY 调用不会自动选择。未提供标志或配置时，callback_api_key_required 错误会包含候选项列表，以便 Agent 明确选择。

项目配置只允许一个字段，可以安全地提交：

callback_api_key_id = "token_abc123"

不要将凭据、密钥名称、掩码、签名密钥、转发 URL 或 base_url 添加到 .runapi.toml；未知字段会被拒绝。

从 Agent 明确传入选定的 ID。监听器只会接收使用该 API 密钥创建的任务：

runapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123

CLI 会在尝试本地 HTTP 请求之前确认每个有效的监听器事件。它会将每个事件转发到本地一次；如果响应状态码不是 2xx，或发生连接错误，则会报告错误，但不会请求重放监听器事件。这种本地调试行为不会改变 Task 的 callback_url 的投递重试机制。

每个 Account 在每个 Callback Subscription Key 下最多可运行 100 个活动监听器，总数最多为 1,000 个。达到限制时，请停止空闲监听器或等待后重试；响应会指出已满的限制。CLI 会在服务端提供 Retry-After 延迟时遵循该延迟。空闲轮询大约每 15 到 30 秒检查一次事件。通常会在约 15 秒内发现事件，并在事件可用时立即读取。

启动输出会显示所选密钥的名称、ID 和掩码，打印项目配置的绝对路径，并打印该密钥稳定的监听签名密钥。若要注入密钥但不启动监听器，请勿将其写入日志或项目配置：

RUNAPI_WEBHOOK_SECRET="$(runapi listen --print-secret --callback-api-key-id token_abc123)"

如果密钥泄露，只需轮换所选密钥的监听签名密钥：

RUNAPI_WEBHOOK_SECRET="$(runapi listen --rotate-secret --callback-api-key-id token_abc123)"

此操作会使所有使用所选密钥的活动监听器失效，但不会轮换其业务 API 凭据。请使用打印出的密钥更新每个本地验证器，然后重启这些监听器。

恢复规则：

• 提交的 ID 若归属其他成员，则不可复用。请运行 runapi api-keys list --json，选择该成员的密钥，并明确传入其 ID。仅当项目应采用该成员专属的选择时，才更新单行项目配置。
• callback_api_key_unusable 表示所选密钥已停用、已丢弃或已失去成员资格。监听器会退出，不会回退到其他密钥；请列出密钥并明确选择另一个密钥。
• 从旧版监听器行为升级后，请更新 CLI、重新运行 runapi login、重启监听器，并替换旧的本地 Webhook 密钥。

文件和上传

直接将智能体可读取的本地路径传递给顶层媒体 URL 字段。CLI 会在提交请求前上传文件，并将字段值替换为临时 URL。远程 http:// 和 https:// 值保持不变。

仅在需要可复用的 URL、Base64 输入或契约要求上传时使用 runapi files create。此临时上传命令会返回 URL，且保持不变可用。

runapi files create ./image.png --file-name image.png
runapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png
runapi files create --base64 "$BASE64_IMAGE" --file-name image.png

该命令会返回包含 file_name、url、size_bytes、mime_type、created_at 和 expires_at 的 JSON。返回的 url 是有效期为一小时的临时 File Upload URL。将其用于接受媒体 URL 的端点字段；请查阅模型/操作文档以确认确切的字段名称。如果脚本只需要标准输出中的临时 URL，请添加 --url-only。

如果调用方需要稳定的 File ID，而不是 URL，请使用持久化 Files。 组合命令前，请先检查各命令：

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

使用 multipart Uploads 发送 Parts，然后再组合最终的 File。重试结果不确定的完成响应时，请保留 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 files --help、runapi uploads --help 以及所选各子命令的帮助信息，了解已安装版本的生命周期约定。

将技能安装到其他智能体运行时

runapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/
runapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/
runapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/
runapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/
runapi agent list-targets                     # JSON list with resolved paths
runapi agent install-skill --target-dir <path>  # custom location

CLI/技能版本不一致的故障排查

此技能独立于 runapi 二进制文件安装，通常会跟随最新的 CLI 行为。如果此处描述的命令、操作、标志或输入字段不可用或行为有所不同，请检查已安装的 CLI 版本，并先更新，再更改请求：

runapi version
brew upgrade runapi-ai/tap/runapi
# or reinstall
curl -fsSL https://runapi.ai/cli/install.sh | sh

更新后，请再次查看命令帮助信息：

runapi --help
runapi <service> --help
runapi <service> <action> --help

智能体安全须知

• 切勿将 API 密钥粘贴到示例命令中。请改用 RUNAPI_API_KEY 或 runapi auth import-token。
• 默认情况下，不要让智能体运行交互式 runapi login。在 MCP 主机中，引导用户使用 login 工具；在终端/无头环境中，优先使用 runapi auth status、RUNAPI_API_KEY 和通过标准输入导入令牌，除非用户明确要求使用浏览器进行身份验证。
• 监听器操作是例外：如果返回 cli_listen_required，已导入的密钥无法恢复。请说明该密钥仍可用于现有 API 访问，但无法列出或选择监听器密钥。请用户移除任何 --api-key 或 RUNAPI_API_KEY 覆盖项，并完成基于浏览器的登录；切勿将返回的凭据或 Listen Signing Secret 存储在 .runapi.toml 中。
• CLI 在验证失败、网络错误和超时情况下会以非零状态退出。请先检查退出代码，再判断操作是否成功。
• RunAPI 生成的文件 URL 是临时的。请在 7 天内下载生成的图像、视频、音频或其他文件，并存储到你自己的持久化存储中；不要将返回的 URL 视为长期资产。

验证、恢复或停止

验证每项请求的交付内容：下载每个 URL，确保文件非空，并检查预期的 MIME 类型。任务状态显示成功，但缺少所请求的文件，仍代表任务未完成。

最多进行一次有证据支持的请求格式修正，依据应为当前命令帮助信息或结构化验证错误。只有在未创建任务、未计费且安全可重放时，才对暂时性传输故障重试一次。记录终态服务或提供方故障，然后停止，不要更改模型或操作。

参考资料

• 浏览所有 RunAPI 模型及其 CLI 服务：https://runapi.ai/models.md