CLI
RunAPI CLI のすべてのコマンド（モデルアクション、タスク、ファイル、アップロード、アカウント情報、価格、コールバック、Harness）をインストールして使用します。
RunAPI CLIはモデルアクションとアカウントツール向けのJSONファースト端末クライアントです。結果データを標準出力に、運用上の進捗を標準エラーに書き込むため、端末、シェルスクリプト、CIジョブ、Harnessのいずれでも同様に機能します。
インストール
Linux または macOS に最新リリースをインストールします:
curl -fsSL https://runapi.ai/cli/install.sh | sh
Homebrew および Go ソースインストールも利用可能です:
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
Windowsの場合は、最新のCLIリリースから対応するwindows-amd64またはwindows-arm64アーカイブをダウンロードし、runapi.exeを展開してPATHに追加してください。
再現性のあるバイナリが必要なデプロイでは、インストーラーをバージョンまたはインストールディレクトリに固定してください:
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も受け付けます。
クイックスタート
ワークステーションでは、ブラウザでサインインし、認証情報ソースを確認してください：
runapi login
runapi auth status
インラインJSON入力またはJSONファイルでモデルアクションを実行します：
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を使用できます：
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にパイプできます：
runapi nano-banana text-to-image --input-file request.json \
| jq -r '.images[].url' \
| xargs -I{} curl -OL {}
モデルアクションは、リクエスト入力ソースをちょうど1つ受け付けます：
--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-phraseproducer:text-to-musicgemini-omni:create-audio,create-character,text-to-videoopenai-tts:text-to-speechfish-audio:text-to-speechgemini-tts:text-to-speechelevenlabs:isolate-audio,speech-to-text,text-to-dialogue,text-to-sound,text-to-speech
画像アクション
nano-banana:edit-image,text-to-imageimagen-4:remix-image,text-to-imageseedream:decompose-layers,edit-image,text-to-imageflux:remix-image,text-to-imageflux-2:remix-image,text-to-imageflux-kontext:text-to-imageqwen-2:edit-image,text-to-imageqwen-3:edit-image,text-to-imageqwen-image:edit-image,remix-image,text-to-imagerecraft:remove-background,upscale-imagez-image:text-to-imageideogram-v3:edit-image,reframe-image,remix-image,text-to-imagegpt-image:edit-image,text-to-imagegpt-image-2:edit-image,text-to-imagegpt-4o-image:text-to-imagemidjourney:edit-image,get-seed,image-to-prompt,shorten-prompt,text-to-image
動画とアニメーションのアクション
veo-3-1:extend-video,text-to-video,upscale-videoseedance:text-to-videorunway:extend-video,text-to-videorunway-aleph:edit-videokling:avatar,edit-video,extend-video,image-to-video,motion-control,text-to-videoinfinitetalk:audio-to-videoomnihuman:audio-to-video,human-identification,subject-detectionwan:animate,edit-video,image-to-video,speech-to-video,text-to-image,text-to-videoluma:modify-videohailuo:image-to-video,text-to-videovolcengine-lip-sync:lip-sync-videohappyhorse:edit-video,image-to-video,text-to-videogrok-imagine:edit-image,extend,image-to-video,text-to-image,text-to-video,upscale-imagetopaz:upscale-image,upscale-videomidjourney:extend-video,image-to-video
上記のリストは、このCLIリリースにおける完全なアクションインベントリです。各アクションの正確なリクエストおよびレスポンスコントラクトはAPIリファレンスで確認でき、ローカルコマンドヘルプはバージョン固有のフィールドの情報源です。
タスクのライフサイクル
非同期Taskの現在の状態を待機せずに確認するには get を使用してください。完了・失敗・コマンドタイムアウトに達するまでポーリングするには wait を使用してください。どちらのコマンドも、CLIが正しいTaskの結果形式を選択できるよう、元のサービスとアクションの指定が必要です。
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ソースのいずれか1つをアップロードし、1時間後に期限切れとなるURLを返します。
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レスポンスを受け取るには省略してください。
URLの代わりに安定した file_id が必要な場合は、永続的なファイルライフサイクルを使用します:
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 を参照してください。
アップロード
最終的なFileを構成する前に、Uploadsを使用して1つ以上のPartを送信してください。
Createは最終的なバイト数とメタデータを宣言します。完了時には、構成順に
--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 account info
runapi account balance
pricing list は現在の価格スケジュールを読み取ります。サービス、アクション、またはモデルでフィルタリングできます。pricing quote は指定したサービスとアクションのタスク予約額を見積もります。アクションがモデル固有の場合は --model を追加し、--params または --params-file でPricing Inputsを指定してください。
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キーを受け取り、デフォルトで検証を行い、プロセスリストやシェル履歴に値を露出させることなく保存します：
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 設定ファイルの順です。ベース URL の優先順位は --base-url、次に RUNAPI_BASE_URL、次に保存済みのベース URL、次に https://runapi.ai の順です。設定ファイルは ~/.config/runapi/config.json、または XDG_CONFIG_HOME が設定されている場合は $XDG_CONFIG_HOME/runapi/config.json です。
ローカルコールバックリスナー
runapi listen は選択した1つのAPIキーに対するTaskコールバックを受信し、オプションで各署名済みコールバックをローカルのHTTPエンドポイントに転送します。リスナー操作を使用する前にブラウザログインが必要です。
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 リクエストを試みる前にそれを確認します。各イベントはローカルに 1 回転送されます。2xx 以外のレスポンスや接続エラーはターミナルに報告されますが、リスナーがイベントを再送することはありません。このローカルデバッグ動作は、タスクの callback_url への配信の再試行には影響しません。
各アカウントは、1つのCallback Subscription Keyにつき最大100個のアクティブなリスナーを実行でき、合計で1,000個のアクティブなリスナーを実行できます。制限に達した場合は、アイドル状態のリスナーを停止するか、待機してから再試行してください。APIレスポンスは、選択したキー、アカウント、またはサービス全体のキャパシティが満杯であるかを示します。
アイドル状態のリスナーは約 15〜30 秒ごとに新しいイベントを確認します。イベントは通常約 15 秒以内に検出され、利用可能になるとすぐに読み取られます。制限に達した場合は、アイドル状態のリスナーを停止するか、しばらく待ってから再試行してください。既存の配信と確認の動作は変わりません。
キーの選択順序は次のとおりです: 1 つのコマンドに対する --callback-api-key-id、プロジェクトの .runapi.toml 内の callback_api_key_id、次にインタラクティブセレクター。プロジェクト設定は Git ルート、または Git リポジトリ外の場合は現在のディレクトリに保存され、安定した ID のみが含まれます:
callback_api_key_id = "token_abc123"
選択したキーの Listen Signing Secret をリスナーを起動せずに表示する、または漏洩後にローテーションする:
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
ローテーションにより、選択されたキーのアクティブなリスナーが無効化されます。リスナーを再起動する前に、新たに発行されたシークレットですべてのローカル検証器を更新してください。
Harness
ポータブルな RunAPI CLI スキルをサポートされている Harness にインストールし、サポートされているターゲットを確認するか、インストール済みスキルを削除します:
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を受け付けます。
シェル補完とバージョン
Bash、Zsh、Fish、または PowerShell の補完スクリプトを生成します。たとえば、現在のシェルで Bash 補完を読み込むには:
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
タスク失敗
リクエストフィールド、タスクステータス値、コールバックペイロード、エラー本文、およびレート制限の処理については、API リファレンスに進んでください。同じワークフローがアプリケーション内に属する場合は、SDKを使用してください。