ai-cli

ai-cli

ターミナルからあらゆるものを生成できます。テキスト、画像、動画、音声を作成し、組み合わせ可能なコマンドで型付きの判断を行えます。

使用する場面

次のような場合に使用します。

• テキストのプロンプトや既存の画像から画像を生成する
• テキストのプロンプトや画像から動画を生成する
• プロンプトやパイプで渡されたコンテンツからテキスト（要約、説明、コードレビュー）を生成する
• テキストから音声を生成する、または音声ファイルやストリームを書き起こす
• 複数のモデルの出力を並べて比較する
• AI SDK の評価モデルを使用して、Boolean、Choice、Score の質問を行う
• stdin/stdout 経由でコマンドを連結し、組み合わせ可能なメディアパイプラインを構築する

前提条件

環境内に AI_GATEWAY_API_KEY またはプロバイダー固有のキー（例：OPENAI_API_KEY）が必要です。

コマンド

ai text "explain this code"              # generate text
ai image "a sunset over mountains"       # generate an image
ai video "a spinning triangle"           # generate a video
ai video start "a spinning triangle" -o operation.json  # submit a video job
ai video status operation.json --download -o ./clips/    # check and download it
ai audio speak "hello"                   # generate speech
ai audio transcribe recording.mp3        # transcribe audio
ai models --type audio                   # list speech and transcription models

主なフラグ

画像と動画には、次のフラグを使用します。

-m, --model <id>       Model ID (provider/name or short name), comma-separated for multi-model
-o, --output <path>    Output file or directory
-n, --n <n>            Number of outputs per model (default: 1)
-p, --concurrency <n>  Parallel models (image: 4; video: 2)
-q, --quiet            Suppress progress output
--json                 Save artifacts and print a JSON manifest
--timeout <seconds>    Request deadline (image: 300; video: 600)
--provider-options <path> JSON provider settings and Gateway routing
--seed <integer>       Generation seed, including 0
--max-retries <n>      SDK retries (default: 2)

テキストと音声では、--n ではなく、引き続き -n, --count を使用します。--quiet、--json、--timeout、--model、--output もこれらのコマンドで使用できます。

画像オプション

画像参照には繰り返し指定できる --images を、領域の編集には --mask を使用します。画像を stdin から渡すと、参照がもう1つ追加されます。--n はモデルごとに複数の画像を要求し、--max-images-per-call は必要に応じて SDK のバッチを分割します。

ai image --images photo.png --mask mask.png "replace the background" --json -o ./renders/
ai image "a sunset" --n 3 --max-images-per-call 2 --json -o ./renders/

--size <WxH> と --aspect-ratio <W:H> で寸法を指定します。API を明示的に選択するには、--api generateImage または --api generateText を使用します。自動ルーティングでは Gateway の画像カタログを使用します。検出に失敗した場合や、カタログに登録されていない画像モデルを使用する場合は、完全なモデル ID と --api を指定してください。カタログを利用できる場合、Quiver Arrow 2 の SVG 言語画像モデルは、画像リストに含まれていなくても generateText 経由でルーティングできます。--generate-text-options <path> は generateText を選択し、JSON 形式の SDK 設定とプロバイダーツールを受け付けます。この API では、--size、--mask、--max-images-per-call、および1以外の --n は使用できません。Gemini の画像サイズには、--provider-options で {"google":{"imageConfig":{"imageSize":"4K"}}} を指定してください。

プロバイダー固有の品質、スタイル、出力形式は、たとえば --provider-options image-options.json とともに指定する {"openai":{"quality":"high","outputFormat":"webp"}} のような JSON ファイルに記述します。--output はファイルの出力先を選択し、outputFormat はエンコード形式を選択します。

動画オプション

--image を1つ指定するか、画像をパイプで渡すと、prompt.image として使用されます。最初と最後のフレームの役割を指定するには --frame-images を、複数の参照ファイルを指定するには --input-references を使用します。どちらのフラグも JSON ファイルを受け取ります。たとえば、frames.json には次の内容を記述できます。

[
  { "image": "start.png", "frameType": "first_frame" },
  { "image": "end.png", "frameType": "last_frame" }
]

ai video "a smooth camera move" --frame-images frames.json --duration 5
ai video "a cinematic landscape" --resolution 1920x1080 --fps 24
ai video "a scene" --n 2 --max-videos-per-call 1 --json -o ./clips/

--aspect-ratio <W:H|adaptive>、--duration <seconds>、--fps <number>、--generate-audio / --no-generate-audio、--resolution <WxH> は、モデルの機能に応じて使用します。動画はデフォルトでポーリングされます。細かく制御するには、--poll-interval-ms、--poll-timeout-ms、--download-max-bytes を使用します。長時間かかるジョブでは、ai video start は操作の JSON をすぐに返します。ai video status は状態を1回確認し、--download は完了したメディアを保存します。start では、モデルと SDK 操作をそれぞれ1つずつ指定します。プロバイダーのメタデータに Webhook シークレットが含まれる場合があるため、操作の JSON は非公開にしてください。参照用の JSON とすべてのオプションについては、コマンドをご覧ください。

パイプのパターン

エージェントのワークフローでは、コマンドを連結します。

# Pipe content in for summarization
cat file.txt | ai text "summarize this"
git diff | ai text "write a commit message"

# Image-to-video pipeline
ai image "a dragon" | ai video "animate this"

# Image editing via stdin
cat photo.png | ai image "make it a watercolor"

# Audio workflows
echo "Ship the changelog" | ai audio speak -o changelog.mp3
cat recording.mp3 | ai audio transcribe -o transcript.txt

判断

AI SDK の評価モデルを使用して、名前付きの Boolean、Choice、Score の質問で判断を行います。

cat ticket.txt |
  ai decide \
    --boolean "refund=Refund requested?" \
    --choice "team=Which team?" \
    --choices "team=billing,support" \
    --score "tone=How positive?" \
    --levels "tone=angry,neutral,happy"

すべての質問には、変更されない同じ入力が渡されます。テキストは改行を保持し、JSON オブジェクトと配列は構造を保持します。各質問には明示的な型と一意の ID が設定されます。選択肢とレベルは、フラグの順序にかかわらず、その ID に紐付けられます。同じリクエストで質問を追加するには、フラグを繰り返し指定します。

• Boolean は probability を返します。これは0から1までの P(true) で、強い否定の回答では0に近い値になります。
• Choice は、指定された選択肢のうち1つと、利用可能な場合はその分布を返します。
• Score は、順序付けられたレベル上の小数位置を0から数えて返し、利用可能な場合は分布も返します。Jev は確率加重平均を使用します。 コマンドは AI SDK の experimental_evaluate を呼び出します。標準入力は state に割り当てられ、型付きフラグによって名前付きの questions が構築されます。--choices は Choice の criteria マップを作成し、--levels は Score の criteria 配列を作成します。ファイル形式では、SDK の質問スキーマを直接使用します。デフォルトの評価モデルは Jev です。その他の対応する評価モデルも同じインターフェースを使用します。

より詳細な基準を設定するには、名前付きの質問マップを triage.json に保存します。

{
  "refund": {
    "type": "boolean",
    "instructions": "Is the customer requesting money back?"
  },
  "team": {
    "type": "choice",
    "instructions": "Which team should handle this request?",
    "criteria": {
      "billing": "Payments, charges, and refunds",
      "support": "Other requests"
    }
  },
  "impact": {
    "type": "score",
    "instructions": "How much is the customer prevented from using the product?",
    "criteria": ["Cosmetic issue", "A workaround exists", "Unusable; no workaround"]
  }
}

ai decide --questions triage.json < ticket.json
ai decide --boolean "refund=Refund requested?" < ticket.txt |
  jq -e '.answers.refund.probability >= 0.9'

質問ファイルでは、文字列、JSON オブジェクト、または配列の指示と説明を使用できます。説明には null も指定できます。Boolean 基準では true と false の説明を任意で指定できます。Choice 基準はオプションのマップで、Score 基準は順序付きのレベルです。暗黙の評価基準はありません。モデル固有の制限は SDK とプロバイダーによって適用されます。インラインのカンマ区切りの選択肢では、各ラベルが名前と説明として使われます。カンマを含むラベルや、名前と説明を別々に指定する場合は、ファイルを使用してください。ファイルの質問とインラインの質問は組み合わせられます。同じ ID が重複するとエラーになります。

--boolean <id=question>    P(true) question (repeatable)
--choice <id=question>     Categorical question (repeatable)
--choices <id=a,b,...>     Choices for the named question (repeatable)
--score <id=question>      Ordered-score question (repeatable)
--levels <id=low,...,high> Score levels for the named question (repeatable)
--questions <path>        JSON file of named typed questions
-m, --model <id>          One evaluation model (default: typesafe-ai/jev)
--input <format>          auto, text, or json (default: auto)
--provider-options <path> JSON object of provider names to option objects
--max-retries <n>         Transient-error retries, including 0 (default: 2)
--timeout <seconds>       Evaluation deadline including retries (default: 30)

出力は常に標準出力上の JSON です。--json フラグは不要で、ファイルは作成されません。出力は SDK の結果を JSON にシリアライズしたもので、answers、usage、warnings、response、および任意の rounding と providerMetadata が含まれます。フィールドと値はそのまま保持されます。スコアのインデックスは、指定した基準を参照します。 ネイティブの信頼度は選択肢の確率とは別のもので、プロバイダーメタデータに保持されます。欠落している分布や信頼度が生成されることはありません。 usage には inputTokens、outputTokens、totalTokens が含まれます。不明な値は省略され、既知のゼロ値はゼロのまま保持されます。response には、利用可能な場合、モデル情報、プロバイダーのヘッダーと本文、および ISO 形式のタイムスタンプが保持されます。コマンドの経過時間を測定するには、シェルの time を使用してください。

標準入力は EOF までバッファーされます。自動モードでは、完全な JSON 値を 1 つ試し、その後テキストとして処理します。JSON のように見える不正な入力は失敗します。ログをそのまま処理するには、--input text を使用してください。JSON の state は文字列、オブジェクト、または配列である必要があります。空の標準入力とバイナリ入力は失敗します。明示的な空の JSON オブジェクト、配列、文字列は有効です。JSONL を共有配列として読み込むには、jq -s . tickets.jsonl | ai decide --questions triage.json を使用します。プロバイダーのコンテキスト制限が適用されます。入力や質問が、分割または切り詰められることはありません。

有効な評価は、回答が false または不確かな場合も含め、終了コード 0 で終了します。入力エラー、プロバイダーの失敗、タイムアウト、無効な回答は、部分的な JSON を出力せずに終了コード 1 で終了します。しきい値の適用、並べ替え、振り分けはコード内で行ってください。上記の jq -e がその終了ステータスを管理します。

小さく焦点を絞った質問を、完全な指示と意味のある基準とともに提示してください。質問 ID はコード向けであり、Jev への指示ではありません。1 回の呼び出しに含まれる質問は互いに独立しています。依存関係がある場合は、後続の呼び出しを使用してください。文章、説明、コードが必要な場合は ai text を使用します。型付き出力でも、判断の正しさが保証されるわけではありません。

「今日」に関する質問には基準日を含めるなど、各質問に必要なコンテキストを指定してください。CLI は現在の日付を追加しません。正確な算術、数え上げ、年齢の境界値、日付の比較はコード内で行ってください。TypeSafe は、Jev 1.13 における数値と日付の制限について説明しています。コンテキストを追加すると質問が明確になることはありますが、モデルが信頼できる計算機になるわけではありません。引用や否定表現を含む肯定例と否定例で、質問と確率のしきい値を検証してください。確率が高くても、判断が誤っている場合があります。

評価プロバイダーを利用できる AI_GATEWAY_API_KEY が必要です。デフォルトを上書きするには、AI_CLI_EVALUATION_MODEL または -m を使用します。-m jev は typesafe-ai/jev に解決されます。ai models --type evaluation でモデルを確認できます。

完全なインターフェースについては、Decide を参照してください。

構造化出力

生成コマンドでは --json を指定すると、機械可読な結果を取得できます。decide は常に JSON を返します。

ai image "a sunset" --json

主要なフィールドは次のとおりです（SDK の追加診断情報も含まれます）。

{
  "elapsedMs": 3420,
  "results": [
    {
      "model": "openai/gpt-image-2",
      "elapsedMs": 3420,
      "success": true,
      "images": [{ "file": "/path/to/resp_abc123.png", "mediaType": "image/png" }],
      "warnings": []
    }
  ]
}

画像／動画の結果には、すべてのアーティファクトを含む images または videos 配列が含まれます。 generateImage の結果には calls が含まれ、一括画像／動画の結果には batches と失敗した項目が含まれます。利用状況、プロバイダーのメタデータ、レスポンスは、 利用可能な場合に保持されます。--json を指定すると、標準出力をパイプに渡した場合でも、 標準出力を解析可能な状態に保ち、アーティファクトをファイルに保存します。

複数モデルの比較

ai image "a sunset" -m "openai/gpt-image-1,bfl/flux-2-pro,xai/grok-imagine-image"

出力の動作

• decide：型付きの回答、利用状況、プロバイダーのメタデータ、レスポンス情報を含む SDK の評価結果を、標準出力に JSON で出力します
• 生成、対話型（TTY）：ファイルに保存し、パスを標準エラー出力に表示します
• パイプ接続時（非 TTY）：画像／動画のアーティファクトが1つの場合は、生のバイト列を標準出力に書き込みます。複数の場合は、それぞれ別のファイルに保存します。テキスト／音声は、それぞれ独自の標準出力動作を維持します
• -o <dir>：自動生成された名前で、指定したディレクトリ内に保存します

CLI がファイル名を選択する際は、利用可能な場合はレスポンス ID を使用し、利用できない場合はランダムな8文字の ID を使用します。例：resp_abc123.png、7f3a9c1d.mp3。

エージェント向けの重要事項：保存したメディアが必要な場合は、バイナリデータがコンテキストに入らないよう、--json -o ./renders/ または特定の出力ファイルを指定してください。画像が1つ想定される場合は、画像から動画への直接パイプが便利です。複数の画像または動画の出力は個別に保存され、JSON マニフェストから読み取れます。

タイムアウト

• decide：評価の再試行を含めて30秒
• テキスト：120秒
• 画像：300秒
• 動画：600秒
• 音声の合成：120秒
• 音声の文字起こし：120秒

プロンプトで正当により長い時間が必要な場合は、出力が変わる高速なモデルバリアントに切り替えるのではなく、--timeout <seconds> で上書きしてください。

ai image "a 72-cell sprite atlas, detailed" --timeout 600

値の単位はミリ秒ではなく秒で、上限は2147483です。

終了コード

• 0 — 成功
• 1 — 入力またはリクエストが無効です。メディアの一部が保存されていても、画像／動画モデルの結果が1つも完全に成功していません
• 2 — 画像／動画モデルの結果の一部は完全に成功し、ほかは失敗しました