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, --count，而非 --n。--quiet、--json、 --timeout、--model 和 --output 也适用于这些命令。

图像选项

使用可重复指定的 --images 添加图像参考，并使用 --mask 编辑某个区域。 通过 stdin 输入的图像会作为另一张参考图像。--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 generateImage 或 --api generateText 可显式选择 API。 自动路由使用 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"}}}。

特定提供商的质量、风格和输出格式应放在 JSON 文件中，例如使用 --provider-options image-options.json，并设置 {"openai":{"quality":"high","outputFormat":"webp"}}。 --output 用于指定文件目标位置；outputFormat 用于指定编码格式。

视频选项

使用一个 --image 或通过管道传入的图像作为 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 会检查一次，而 --download 会保存已完成的媒体内容。start 接受一个模型和一个 SDK 操作。请妥善保管操作 JSON， 因为提供商元数据可能包含 webhook 密钥。参考 JSON 和所有选项请参阅命令。

管道用法

链接命令以构建 Agent 工作流：

# 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：P(true) 的取值范围为 0 到 1，也包括接近零的强烈否定回答。
• Choice 返回一个给定选项，并在可用时返回其分布。
• Score 返回有序等级上的小数位置，起始值为零，并在可用时返回分布。Jev 使用按概率加权的平均值。 使用 -i, --images <path-or-url> 添加图像（可重复）；图像会作为文件部分跟在 stdin 后，并处于同一状态中；提供图像时，stdin 可省略。

该命令调用 AI SDK 的 experimental_decide：stdin 映射到 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。布尔标准可选地描述 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
-i, --images <path-or-url> Image after stdin in the state (repeatable)
-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)

输出始终是 stdout 上的 JSON；无需 --json 标志，也不会创建文件。输出是 经过 JSON 序列化的 SDK 结果：answers、usage、warnings、 response，以及可选的 rounding 和 providerMetadata。 字段和值都会保留；分数索引对应你提供的标准。 原生置信度与选项概率不同，并保留在提供商元数据中。 不会合成缺失的分布或置信度。 用量包含 inputTokens、outputTokens 和 totalTokens；未知值 会省略，已知的零值仍保留为零。response 会在可用时保留模型信息、 提供商标头和主体，以及 ISO 时间戳。使用 shell 的 time 计算命令耗时。

stdin 会缓冲至 EOF。自动模式会先尝试读取一个完整的 JSON 值，然后 尝试文本。看起来像 JSON 但格式错误的输入会失败；对于原样日志，请使用 --input text。 JSON 状态必须是字符串、对象或数组。空 stdin 和二进制输入会失败； 显式的空 JSON 对象、数组和字符串均有效。如需将 JSONL 读取为共享数组， 请使用 jq -s . tickets.jsonl | ai decide --questions triage.json。 上下文长度限制由提供商决定；输入和问题绝不会被静默拆分或截断。

有效评估以 0 退出，包括 false 和不确定的答案。输入错误、 提供商故障、超时和无效答案以 1 退出，且不会输出部分 JSON。 请在代码中应用阈值、排序和路由；上方的 jq -e 会决定其退出状态。

提出简短、聚焦的问题，并提供完整指令和有意义的标准。 问题 ID 供你的代码使用，不是给 Jev 的指令。一次调用中的问题彼此独立； 如有依赖关系，请使用后续调用。需要文案、解释或代码时，请使用 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 和任何 failures。如果可用，则会保留用量、提供商元数据和响应。 --json 可确保 stdout 输出可解析，并在 stdout 被管道重定向时仍将生成内容保存到文件。

多模型对比

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

输出行为

• decide：SDK 评估结果以 JSON 形式输出到 stdout，其中包含类型化答案、用量、提供商元数据和响应信息
• 生成，交互式（TTY）：保存到文件，并将路径打印到 stderr
• 管道（非 TTY）：单个图像/视频生成内容会将原始字节写入 stdout；多个生成内容则分别保存到文件。文本/音频保留各自的 stdout 行为
• -o <dir>：使用自动生成的名称保存到目录中

CLI 选择文件名时，会优先使用响应 ID；如果没有，则使用随机的 8 个字符 ID，例如 resp_abc123.png 或 7f3a9c1d.mp3。

面向 Agent 的重要提示：如果需要保存媒体，请使用 --json -o ./renders/ 或指定输出文件，以免二进制 stdout 进入上下文。如果预期只有一张图像，直接将图像管道传递给视频生成很有用。多个图像或视频输出会分别保存，可从 JSON 清单中读取。

超时

• decide：30 秒，包括评估重试
• 文本：120 秒
• 图像：300 秒
• 视频：600 秒
• 音频生成：120 秒
• 音频转录：120 秒

如果提示词确实需要更长时间，可使用 --timeout <seconds> 覆盖，而不是改用会改变输出的更快模型变体：

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

该值以秒为单位，而非毫秒，且上限为 2147483。

退出代码

• 0 — 成功
• 1 — 输入无效或请求失败；没有图像/视频模型结果完全成功，包括已保存部分媒体的结果
• 2 — 部分图像/视频模型结果完全成功，其他结果失败