用途
ai-gateway CLI 是 Vercel AI Gateway(https://vercel.com/ai-gateway)的轻量命令行封装,用于一次性(one-shot)生成文本、图像和视频。当一次 CLI 调用比编写 SDK 代码更合适时,可以使用它。它通过一个 API Key 访问数百个模型。
主要能力
- 文本生成:结果流式输出到 stdout。
- 图像生成:保存到磁盘并打印路径。
- 视频生成:保存 .mp4 到磁盘,属于多分钟任务,会打印带已用时间的 spinner。
默认模型:
- 文本:xai/grok-4.1-fast-non-reasoning(便宜且能力强)
- 图像:google/imagen-4.0-fast-generate-001
- 视频:xai/grok-imagine-video
可通过 -m <model-id> 按次覆盖模型。使用 ai-gateway models --type image|language|video 浏览模型。
资料中列出的 notable models:
- 仅图像:bfl/flux-2-pro、bfl/flux-pro-1.1、openai/gpt-image-2、google/imagen-4.0-generate-001、xai/grok-imagine-image。
- 多模态 LLM(通过 chat completions 自动路由):google/gemini-2.5-flash-image(Nano Banana)、google/gemini-3.1-flash-image-preview(Nano Banana 2)、google/gemini-3-pro-image。
- 文本质量:anthropic/claude-opus-4.6、openai/gpt-5.4、xai/grok-4.3。
- 视频:xai/grok-imagine-video(便宜)、bytedance/seedance-v1.0-lite-t2v、google/veo-3.1-fast-generate-001(高级,带音频)、klingai/kling-v2.6-t2v。
使用方式
1. 确认 CLI 已安装
运行 which ai-gateway。如果缺失,安装:npm install -g @vesely/ai-gateway-cli。
成功标准:which ai-gateway 返回一个路径。
2. 确认 API Key 可用
CLI 按以下顺序查找 key:--key 参数 → AI_GATEWAY_API_KEY 环境变量 → ~/.config/ai-gateway-cli/config.json。如果 AI_GATEWAY_API_KEY 未设置且配置文件缺失或为空,向用户询问一次:告诉用户要么 export AI_GATEWAY_API_KEY=...,要么运行 ai-gateway config set key <value>。可在 https://vercel.com/ai-gateway 获取 key。
成功标准:ai-gateway config 显示 key(掩码)或 $AI_GATEWAY_API_KEY 已设置。
3. 运行生成
文本(流式输出到 stdout):
ai-gateway "<prompt>" # 默认模型 ai-gateway -m anthropic/claude-opus-4.6 "<prompt>" ai-gateway --json "<prompt>" # 完整 JSON 响应(.text、.usage) cat file.md | ai-gateway "<prompt>" # 管道 stdin 会作为上下文前置
图像(保存到磁盘,打印路径):
ai-gateway image "<prompt>" # ./ai-image-<timestamp>.png ai-gateway image -o output.png "<prompt>" # 自定义路径 ai-gateway image -n 4 "<prompt>" # 4 张图像,自动加后缀 ai-gateway image -m bfl/flux-2-pro -o cover.png "<prompt>" # 指定仅图像模型 ai-gateway image -m google/gemini-2.5-flash-image "<prompt>" # Nano Banana(通过 chat completions 自动路由)
视频(保存 .mp4 到磁盘,多分钟任务,打印带已用时间的 spinner):
ai-gateway video "<prompt>" # 默认模型,./ai-video-<timestamp>.mp4
ai-gateway video -o clip.mp4 --duration 5 "<prompt>" # 5 秒片段
ai-gateway video -m google/veo-3.1-fast-generate-001
--aspect 9:16 --resolution 1080p -o vertical.mp4 "<prompt>" # 竖屏 1080p Veo
ai-gateway video --json --duration 5 "<prompt>" # 带 cost 和 elapsed 的 JSON
成功标准:
- 文本:流式输出以换行结束,退出码 0。
- 图像:stdout 包含 Saved: <absolute path>,且文件存在于磁盘。
- 视频:stdout 包含 Saved: <absolute path>,指向非空 .mp4(或 .webm)。
4. 回报结果
- 文本:把模型输出转达给用户(它已在 stdout 上)。
- 图像:报告 CLI 打印的绝对路径。除非被要求,不要重新编码或打开文件。
成功标准:用户拿到答案或文件路径。
规则
- 绝不要在脚本中硬编码 API key。解析顺序是 env > config;agent 不应直接读写 ~/.config/ai-gateway-cli/config.json。
- 对多模态 LLM(Nano Banana 等)进行多图像批量生成时,CLI 会针对 /v1/chat/completions 循环 n 次,因为 chat 没有原生批量——使用 -n 4 时需要耐心。
- 视频生成很慢(通常 1-5 分钟),且要求 AI Gateway 账户最低余额 $10。不要终止 spinner——等它完成。
- 如果模型 id 未知,运行 ai-gateway models --search <substring> 来发现,而不是猜测。
- 如果用户想要人类可读的结果,不要给 image/video 命令传 --json;它会抑制友好的 "Saved: ..." 行。
- 默认文本模型是非推理且快速的;对于更难的推理任务,通过 -m 选择 xai/grok-4.1-fast-reasoning、anthropic/claude-opus-4.6 或 openai/gpt-5.4。
故障排查
- Unauthorized (401) → key 错误或过期。用 ai-gateway config set key <value> 重置。
- Not found (404)。未知模型?→ 运行 ai-gateway models --search <hint>。
- Model "<id>" does not support image generation → 所选模型不是仅图像模型,且缺少图像生成标签。从 ai-gateway models --type image 中选择,或使用上面列出的多模态 LLM。
- Video generation requires a minimum balance of $10 → 在重试前到 https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up 充值。
适用场景
适合需要从命令行快速完成一次性文本、图像或视频生成,而不想编写 SDK 代码的场景;也适合在脚本或 agent 流程中调用单一命令完成生成任务。
限制
- 视频生成较慢(通常 1-5 分钟),且要求 AI Gateway 账户最低余额 $10。
- 多模态 LLM 的多图像批量生成通过循环调用实现,没有原生批量。
- 图像/视频命令使用 --json 会抑制人类可读的 "Saved: ..." 输出。
- 需要有效的 API Key,否则会返回 401。
- 模型 id 未知时需先查询,不能猜测。