runapi-cli

RunAPI CLI

runapi CLIは、インストール済みのコマンドカタログにあるサービスに限り、単発の成果物または結果を実行します。アプリ、バックエンド、ワーカー、ライブラリ、または本番コードでの統合には、代わりにRunAPI SDKを使用します。

ルートを選択する

単発の成果物または結果にはCLIを使用します。アプリ、バックエンド、ワーカー、ライブラリ、または本番コードにはSDKを使用します。サービスコマンドを組み立てる前に、runapi --helpでインストール済みのコマンドカタログを確認し、サービスが一覧にある場合にのみ進めてください。サービスがない場合は、推測したCLIコマンドではなく、そのサービスのSDKまたは公開APIの仕様を使用します。

インストール

対象	コマンド
macOS / Linux（対話型）	brew install runapi-ai/tap/runapi
サーバー / CI（ヘッドレス）	curl -fsSL https://runapi.ai/cli/install.sh | sh

インストーラーはOSとアーキテクチャ（LinuxおよびmacOS、amd64およびarm64）を検出し、https://runapi.ai/cli/latest.jsonからSHA-256チェックサムを検証します。検証に失敗した場合、バイナリの書き込みを拒否します。

認証

まず現在の状態を確認します。

runapi auth status

方式	方法
環境（エージェント／ヘッドレスの既定）	環境からRUNAPI_API_KEYを読み取ります
保存済み設定（エージェント／サーバー／CI）	printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -（~/.config/runapi/config.jsonをモード0600で書き込みます）
ブラウザーログイン（対話型の代替手段）	ターミナルで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レスポンスは標準出力に、進行状況の行は標準エラー出力に送られます。後続の解析には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キー不要）

エージェントがウォレットを持ち、対応するTaskエンドポイントに直接支払う必要がある場合は、このルートを使用します。これはREST専用です。CLIとMCPサーバーにはx402トランスポートは追加されません。支払い前に、登録、APIキーの作成、クレジットの購入、またはTaskの作成を行わないでください。

エージェントのランタイムまたはウォレットプラットフォームが提供するx402 v2クライアントを使用します。利用可能なウォレット署名機能とx402 v2クライアントが前提条件です。いずれかがない場合は中止し、不足している前提条件を報告してください。標準のx402署名を使用します。APIキーを使う方法は別の認証ルートです。

前提条件と探索

エージェントプラットフォームがウォレットと署名操作を管理します。ウォレットには Base メインネット（eip155:8453）上の USDC が必要で、署名キーはプラットフォームのセキュアなウォレット境界内に保持する必要があります。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 エンドポイントでは、最初のレスポンスは標準の PAYMENT-REQUIRED ヘッダーを含む 402 です。そのヘッダーを、エージェントのウォレットに接続された既存の 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 本文には、エンドポイントの通常のレスポンスに 1 つのアクセス許可が追加されます。その他のエンドポイント固有のフィールドも引き続き含まれます。

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

完了条件：同じ成功レスポンスから task_id、access_token、poll_url の値をそのまま保存していること。

poll_url をそのまま保存し、繰り返し GET します。クエリ文字列のトークンが意図された認証手段です。これは 1 つの Task のみを対象とする読み取り専用の許可であり、アカウントの読み取り、Task の一覧表示、書き込みはできません。

curl -fsS "$POLL_URL"

完了条件：ポーリングは、Task の終端ステータスに達するか、定義済みの 404／通信エラーが発生した場合にのみ終了します。処理中のレスポンスを最終結果として扱ってはいけません。

クエリのレスポンスは次のとおりです。

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

返されたステータスが終端状態でない間は、上限を設けた待機時間でポーリングを続けます。終端状態になると、completed には結果の HTTP ステータス、コンテンツタイプ、ヘッダー、本文を含む response が含まれます。failed には、保持されている場合、終端エラーレスポンスが含まれます。ポーリング URL を API キーを使ったリクエストに置き換えたり、支払い自体を Task の結果とみなしたりしてはいけません。

tat_ トークンは一度だけ発行され、該当する Task に対して繰り返し読み取ることができます。有効期限は Task が終端状態になってから 30 日後です。無効なトークン、期限切れのトークン、誤った Task のトークンはすべて 404 を返します。これらを認証エラーや支払いエラーとして再試行してはいけません。

完了条件：エージェントが終端結果を受け取るか、オペレーター向けに正確な終端状態／エラー状態を記録していること。

失敗したタスクと手動返金

決済済みの x402 タスクが終端状態 failed に達した場合、RunAPI は実際に受け取った USDC の最小単位の金額に対して、全額の手動返金義務を 1 件記録します。これは運用ワークフローであり、権限を持つオペレーターがオンチェーンで返金を行います。自動のオンチェーン返金はなく、返金ページも必要ありません。オペレーターが確認できるよう、Task ID、決済トランザクションハッシュ、支払者のウォレット、ネットワーク、金額、および PAYMENT-RESPONSE を保持してください。

処理中のタスク、決済が確認できない場合、またはコールバックの配信に失敗した場合は、返金を約束しないでください。これらの状態では、この終端失敗に伴う返金義務は発生しません。

完了条件：終端状態 failed の場合、エージェントが決済の証拠を保持し、返金に関する情報を権限を持つオペレーターに提出していること。返金が実行されたとは主張しません。

ローカルコールバックリスナー

リスナーへのアクセスには、runapi login で発行された認証情報が必要です。通常のインポート済み API キーでは、コールバック候補の一覧表示、Listen Signing Secret の読み取り、リスナーの起動はできません。この制限はリスナー操作にのみ適用されます。通常の API キーでも、引き続きタスクの作成と照会はできます。

エージェントからリスナーを実行する前に、保存済みの認証情報を確認し、現在のメンバーのキーのメタデータを一覧表示します。

runapi auth status
runapi api-keys list --json

API が cli_listen_required を返した場合は、インポート済みのキーでは従来の API アクセスを引き続き利用できますが、リスナーキーの一覧表示や選択はできないことを説明してください。--api-key または RUNAPI_API_KEY による上書きを削除するようユーザーに依頼し、ユーザーのターミナル（または MCP の login ツール）で runapi login を完了してから、runapi listen を再試行してください。インポート済み API キーや管理キーで再試行しないでください。

各候補には id、name、masked_token、enabled が含まれます。有効な安定した id を選択してください。名前とマスクは表示用の情報にすぎないため、キーの名前を変更しても保存済みの選択は無効になりません。有効なキーが複数あり、プロジェクトでそのうちの 1 つが指定されていない場合は、黙って選択せず、候補をユーザーに提示してください。

選択の優先順位は次のとおりです。

1. この実行で指定する --callback-api-key-id <id>。プロジェクト設定は書き換えません。
2. git のルートにある .runapi.toml の callback_api_key_id。Git リポジトリの外では、現在のディレクトリにあるものを使います。
3. TTY セレクター。サーバーがリスナーセッションを検証した後にのみ、選択した ID を書き込みます。

TTY 以外の実行では、自動選択されません。フラグまたは設定が指定されていない場合、callback_api_key_required エラーに候補の一覧が含まれるため、エージェントは明示的に選択できます。

プロジェクト設定で許可されるフィールドは 1 つだけで、安全にコミットできます。

callback_api_key_id = "token_abc123"

認証情報、キー名、マスク、署名シークレット、転送 URL、base_url を .runapi.toml に追加しないでください。不明なフィールドは拒否されます。

エージェントから選択した ID を明示的に渡してください。リスナーが受け取るのは、その API キーで作成されたタスクのみです。

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

CLI は、有効なリスナーイベントをローカル HTTP リクエストとして送信する前に確認応答します。各イベントをローカルに 1 回だけ転送し、2xx 以外の応答や接続エラーが発生した場合は、リスナーへの再送を要求せずに報告します。このローカルデバッグ動作は、Task の callback_url に対する配信再試行には影響しません。

各 Account で実行できるアクティブなリスナーは、Callback Subscription Key ごとに最大 100 個、合計で最大 1,000 個です。上限に達した場合は、アイドル状態のリスナーを停止するか、しばらく待ってから再試行してください。応答には、どの上限に達したかが示されます。CLI は、サーバーから Retry-After が返された場合、その待機時間に従います。アイドル時のポーリングでは、約 15～30 秒ごとにイベントを確認します。イベントは通常約 15 秒以内に検出され、利用可能になり次第読み取られます。

起動時の出力には、選択したキーの名前、ID、マスク、プロジェクト設定の絶対パス、およびそのキーの安定した Listen Signing Secret が表示されます。リスナーを起動せずにシークレットを注入する場合は、ログやプロジェクト設定に含めないでください。

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

シークレットが漏えいした場合は、選択したキーの Listen Signing Secret のみをローテーションしてください。

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

これにより、選択したキーを使用するすべてのアクティブなリスナーが無効になりますが、そのキーの業務用 API 認証情報はローテーションされません。出力されたシークレットを使って各ローカル検証器を更新し、その後、リスナーを再起動してください。

復旧ルール：

• コミット済みの ID が別のメンバーに属している場合は、再利用できません。runapi api-keys list --json を実行し、そのメンバーのキーを選択して、ID を明示的に渡してください。プロジェクトでそのメンバー固有の選択を採用する場合にのみ、1 行のプロジェクト設定を更新してください。
• callback_api_key_unusable は、選択したキーが無効化、破棄されたか、メンバーシップを失ったことを意味します。リスナーはフォールバックせずに終了します。キーを一覧表示し、別のキーを明示的に選択してください。
• 以前のリスナー動作からアップグレードした後は、CLI を更新し、もう一度 runapi login を実行して、リスナーを再起動し、古いローカル Webhook シークレットを置き換えてください。

ファイルとアップロード

エージェントが読み取れるローカルパスを、トップレベルのメディア URL フィールドに直接渡します。 CLI はリクエストを送信する前にファイルをアップロードし、フィールドの値を一時 URL に置き換えます。 リモートの http:// および https:// の値は変更されません。

再利用可能な URL、Base64 入力、または契約上必須のアップロードには、runapi files create のみを使用します。 この一時アップロードコマンドは URL を返し、その 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 は、1 時間有効な一時 File Upload URL です。 メディア URL を受け付けるエンドポイントのフィールドで使用してください。正確なフィールド名はモデル／アクションのドキュメントで確認してください。 スクリプトで標準出力に一時 URL のみが必要な場合は、--url-only を追加します。

呼び出し元が URL ではなく安定した File ID を必要とする場合は、永続的な 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

マルチパート Uploads を使用して、最終的な File を組み立てる前に Parts を送信します。 完了応答が不確かな場合に再試行するときは、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 タイプが想定どおりであることを確認します。要求されたファイルがない場合、タスクのステータスが成功でも不完全です。

現在のコマンドヘルプまたは構造化された検証エラーを根拠として、リクエスト形式の修正は最大 1 回まで行ってください。一時的な通信障害は、タスクが作成されておらず、使用料金が発生しておらず、安全に再実行できる場合に限り、1 回だけ再試行してください。サービスまたはプロバイダーの終端エラーを記録し、モデルやアクションを変更せずに停止してください。

参考資料

• すべての RunAPI モデルとその CLI サービスを参照してください：https://runapi.ai/models.md