AI Media Generation via API | 通过API生成图片和视频。【触发词】帮我生成图片/画个图/做个视频/生成视频/文生图/图生图/AI图片/AI视频/用Sora生成/用Gemini画。使用 Gemini 生成图片(文生图、图生图),使用 Sora/veo 生成视频(文生视频)。支持 Pro...
---
name: api-video-image
description: AI Media Generation via API | 通过API生成图片和视频。【触发词】帮我生成图片/画个图/做个视频/生成视频/文生图/图生图/AI图片/AI视频/用Sora生成/用Gemini画。使用 Gemini 生成图片(文生图、图生图),使用 Sora/veo 生成视频(文生视频)。支持 Prompt 优化建议、错误重试机制、异步任务轮询。
version: 1.4.0
author: lrs
tags:
- image-generation
- video-generation
- gemini
- sora
- ai-media
- api
metadata:
openclaw:
emoji: "🎨"
requires:
bins:
- python3
---
# API Video & Image Generation
# AI 图片与视频生成
## 0. Trigger Words | 触发词
**激活本技能的场景:**
- "帮我生成一张图片" / "画个图"
- "做个视频" / "生成视频"
- "文生图" / "图生图"
- "AI生成" / "用Sora生成" / "用Gemini画"
---
## 决策树
```
收到生成请求
↓
1. 检查 USER.md 中 中转站地址,API端点,API 配置
├─ 配置正确 → 使用配置
└─ 配置缺失/错误 → 要求用户提供 → 自动修复 USER.md 配置
↓
2. 判断类型
├─ 图片生成(文生图/图生图)→ 默认Gemini API → 错误 → 要求用户指定模型
└─ 视频生成 → 默认Sora/veo API → 错误 → 要求用户指定模型
↓
3. 执行生成 → 异步轮询 → 返回结果
```
## ⚙️ 配置要求 | Configuration
### 正确格式(脚本能识别的格式):
```markdown
## 中转站AI生成配置
### 图片生成
- 中转站API 地址: https://jeniya.cn/v1beta/models/gemini-3-pro-image-preview:generateContent
- 模型选择: models/gemini-3-pro-image-preview:generateContent
- API Key: sk-aeXk你的Key
### 视频生成
- 中转站API 地址: https://jeniya.cn/v1/v1/video/create
- 模型选择: models/sora-2-pro-all/veo_3_1-4K
- API Key: sk-0PzKg你的Key
```
---
## 🚀 Quick Start | 快速上手
**用户说:** "帮我画一张科幻风格的未来城市"
**AI 执行:**
1. ✅ 检查配置(USER.md)
2. ✅ 优化 Prompt(结构化)
3. ✅ 执行:`python3 scripts/gen_image.py "prompt"`
4. ✅ 输出:`MEDIA:<绝对路径>` 让 OC 自动附件
---
## 1. 执行检查清单 | Execution Checklist
**每次生成前必须确认:**
- [ ] Step 0:USER.md 配置正确,脚本能读取到 URL 和 Key
- [ ] Step 1:已理解用户需求(图片/视频/风格/场景)
- [ ] Step 2:Prompt 已优化(结构化、有细节)
- [ ] Step 3:输出路径已确认(~/Desktop/)
- [ ] 生成完成后:输出 `MEDIA:<绝对路径>` 让 OC 自动附件
---
## 2. 工作流程
```
Step 0: 检查配置 → Step 1: 理解需求 → Step 2: Prompt优化 → Step 3: 执行生成 → Step 4: 交付用户
```
### Step 0: 检查并修复配置
**首次使用时必须执行此步骤:**
1. 读取 `~/.openclaw/workspace/USER.md` 中的中转站AI生成配置
2. 检查是否包含正确的"图片生成"和"视频生成"区块
3. 检查是否有"中转站API 地址"和"API Key"字段
4. 如果格式不对或缺少配置 → **AI 帮您更新 USER.md 为正确格式**
### Step 1: 理解需求
用户说"帮我生成一张图"或"做个视频"时:
1. 询问具体内容/场景/风格
2. 判断是文生图、图生图、还是视频
3. 整理成结构化 Prompt
### Step 2: Prompt 优化
**Prompt 结构 | Prompt Structure:**
| 组成部分 | 说明 | 示例 |
|---------|------|------|
| Subject | 主体 | 一只猫、未来城市 |
| Style | 风格 | 赛博朋克、宫崎骏、水墨画 |
| Lighting | 光线 | 逆光、柔光、日落 |
| Composition | 构图 | 全身、半身、特写 |
| Details | 细节 | 表情、服装、环境 |
| Quality | 质量 | 4K、高清、电影感 |
**图片 Prompt 示例:**
> 原始:"一只猫"
> 结构化:"橘色英国短毛猫,阳光下慵懒姿态,写实风格,高清摄影,暖色调"
**视频 Prompt 示例:**
> 原始:"日出"
> 结构化:"清晨日出,太阳缓缓升起,金色阳光穿透薄雾,城市天际线,云层缓慢流动,航拍视角,4K"
### Step 3: 执行生成
**图片生成:**
```bash
python3 scripts/gen_image.py "优化后的prompt" [output_path] [ref_image_path]
```
**视频生成:**
```bash
python3 scripts/gen_video.py "优化后的prompt" [model] [size] [output_path]
```
---
## 3. 图片生成
### 使用方法
```bash
python3 scripts/gen_image.py "prompt" [output_path] [ref_image_path]
```
### 参数说明
| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| prompt | ✅ | - | 图片描述/提示词 |
| output_path | ❌ | ~/Desktop/img_*.png | 保存路径 |
| ref_image_path | ❌ | None | 参考图片路径,传参则图生图 |
### 输出
- 成功:输出 `MEDIA:<绝对路径>` 让 OC 自动附件
- 失败:返回错误信息,需要重试
### 重试机制
图片生成失败时,自动重试最多3次
---
## 4. 视频生成
### 使用方法
```bash
python3 scripts/gen_video.py "prompt" [model] [size] [output_path]
```
### 参数说明
| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| prompt | ✅ | - | 视频场景描述 |
| model | ❌ | sora-2-pro-all | 生成模型 |
| size | ❌ | 16:9 | 画面比例 |
| output_path | ❌ | ~/Desktop/vid_*.mp4 | 保存路径 |
### 模型选项
| 模型 | 特点 |
|------|------|
| sora-2-pro-all | Sora 2,视频生成首选 |
| veo_3_1-4K | Veo 3.1,4K高清 |
### 画面比例
| 比例 | 用途 |
|------|------|
| 16:9 | 横版视频(默认) |
| 9:16 | 竖版视频(短视频) |
### 异步处理
视频生成是异步的:
1. 发起请求 → 获取 task_id
2. 轮询查询状态(每5秒)
3. 任务完成 → 下载视频
4. 超时时间:300秒
### 重试机制
视频生成可能失败:
- 网络问题 → 重试
- API限流 → 等待10秒后重试
- 超时 → 提示用户
---
## 5. 交付用户 | Delivery
**生成完成后必须输出:**
```
MEDIA:/Users/lrs/Desktop/xxx.png
MEDIA:/Users/lrs/Desktop/xxx.mp4
```
OC 会自动附件文件到消息中。
---
## 6. 错误处理
| 错误类型 | 处理方式 |
|---------|---------|
| API Key无效 | 检查 USER.md 配置 |
| 网络超时 | 重试3次 |
| 内容审核拒绝 | 提示用户修改 Prompt |
| 任务超时 | 提示用户,重新生成 |
---
## 7. 安全注意 | Security
**Shell 路径清理:**
- 输出文件时确保路径只包含 `A-Za-z0-9._-`
- 使用 `tr -cd 'A-Za-z0-9._-'` 清理特殊字符
- 禁止将未清理的路径传给 shell
---
## 8. 文件结构 | File Structure
```
api-video-image/
├── SKILL.md # 技能核心定义(工作流程、规则、触发词)
└── scripts/
├── gen_image.py # 图片生成脚本(文生图/图生图)
└── gen_video.py # 视频生成脚本(异步任务+轮询)
```
---
## 9. 边界 | Boundaries
- 本技能只负责生成图片/视频
- 不负责发送消息(由 OC 自动附件)
- 不负责内容审核(用户对内容负责)
- 不记录用户生成的图片/视频
---
## 10. 更新日志
- v1.4.0: 增加执行检查清单、Prompt结构表、MEDIA自动附件、安全注释
- v1.3.0: 配置改为从 USER.md 读取中转地址和密钥
- v1.2.0: 增加触发词、Quick Start
- v1.1.0: 增加Prompt优化、错误处理,重试机制
- v1.0.0: 初版发布
don't have the plugin yet? install it then click "run inline in claude" again.