Bytedance Ai Image Gen

SKILL.md

---
name: bytedance-ai-image-gen
description: >
  ByteDance AI Image Gen — 调用豆包/ByteDance Seedream 模型生成/编辑图片。
  用户通过火山「协作奖励计划」免费使用顶级模型。
  支持文生单图、文生组图、图生单图、图生组图、多图融合、图片编辑。
  智能调度 4.5→5.0Lite→4.0，每模型每日18次，超限拒绝。
  ⏱️ 生成需30-60秒，触发后请耐心等待。
summary: "ByteDance AI Image Gen — 调用豆包 Seedream 生成/编辑图片，支持文生图、图生图、组图、多图融合，免费使用"
tags:
  image-generation: "2.1.0"
  byteimage: "2.1.0"
  seedream: "2.1.0"
  text-to-image: "2.1.0"
  image-to-image: "2.1.0"
  volcengine: "2.1.0"
version: 2.3.0
trigger_patterns:
  - "生成图片"
  - "画一张图"
  - "创建图片"
  - "制作图片"
  - "画图"
  - "帮我画"
  - "帮我生成"
  - "我想生成"
  - "搞个图"
  - "来张图"
  - "做张图"
  - "generate image"
  - "create image"
  - "txt2img"
  - "please generate"
  - "please draw"
  - "图生图"
  - "图片编辑"
  - "编辑图片"
  - "改图"
  - "换背景"
  - "换风格"
  - "img2img"
  - "image to image"
  - "edit this image"
  - "edit image"
  - "融合"
  - "合成"
  - "两张图片"
  - "多张图片"
  - "拼合"
  - "合图"
  - "blend"
  - "fuse"
  - "merge"
  - "combine"
  - "文生图"
  - "生图"
  - "图片生成"
  - "图像生成"
  - "生成图像"
metadata:
  openclaw:
    requires:
      bins:
        - python
      env:
        - ARK_API_KEY
        - DOUBAO_MODEL_45_ID
        - DOUBAO_MODEL_50L_ID
        - DOUBAO_MODEL_40_ID
    primaryEnv: ARK_API_KEY
    envVars:
      - name: ARK_API_KEY
        required: true
        description: 火山方舟 API Key，在 console.volcengine.com/ark → API Key 管理 创建
      - name: DOUBAO_MODEL_45_ID
        required: true
        description: Seedream-4.5 接入点 ID，在 console.volcengine.com/ark → 在线推理 获取
      - name: DOUBAO_MODEL_50L_ID
        required: true
        description: Seedream-5.0-Lite 接入点 ID
      - name: DOUBAO_MODEL_40_ID
        required: true
        description: Seedream-4.0 接入点 ID
      - name: VOLCENGINE_ACCESS_KEY
        required: false
        description: 火山 IAM Access Key，在 console.volcengine.com/iam 创建，用于自动同步用量
      - name: VOLCENGINE_SECRET_KEY
        required: false
        description: 火山 IAM Secret Key，与 ACCESS_KEY 配套
    emoji: "🎨"
    homepage: https://www.volcengine.com/docs/82379/1541523
    install:
      - kind: uv
        package: requests
---

# ByteDance AI Image Gen — 豆包/ByteDance Seedream 图片生成

调用火山方舟 Seedream [API 文档](https://www.volcengine.com/docs/82379/1541523?lang=zh) 生成/编辑图片，自动选择模型并限制用量。

> ⏱️ 图片生成通常需要 **30-60 秒**，其间无额外反馈。触发后请耐心等待，不要重复发送。

## ⚡ 调用方式 — 触发后必须立即执行命令

> **这是操作手册，不是参考文档。检测到触发词后，直接复制对应命令执行，禁止只回复文字。**

确认 Skill 目录后，先 `cd` 进去，再执行对应命令。Skill 安装在: `.openclaw/workspace/skills/bytedance-ai-image-gen/`

执行成功后，脚本会输出 `✅ 生成成功!` 及本地文件路径。**你必须把以下信息告知用户**:
- 模型、分辨率、比例
- 本地文件路径（`文件: .../Image/xxx.png`）← 这行一定要报
- 可以不报临时 CDN URL（会过期）

### 文生图
```bash
python doubao_image_gen.py gen "用户描述" [尺寸] [--ratio 比例] [--no-watermark]
```
示例: `python doubao_image_gen.py gen "洪崖洞夜景" 4K --ratio 16:9`

### 图生图
```bash
python doubao_image_gen.py img2img "用户描述" "图片路径或URL" [尺寸] [--no-watermark]
```
示例: `python doubao_image_gen.py img2img "换成夜景风格" "photo.jpg" 4K`

### 组图（一次多张）
```bash
python doubao_image_gen.py seq "用户描述" [--num 数量] [尺寸] [--no-watermark]
```

### 多图融合
```bash
python doubao_image_gen.py seq "融合描述" --refs img1.jpg img2.jpg [--no-watermark]
```

⚠️ **严禁**: 只回复"正在生成..."而不执行命令。必须跑 `python doubao_image_gen.py ...`。

---

## 功能

| 模式 | 说明 | 支持 |
|------|------|------|
| 文生单图 | 纯文本描述生成 1 张图片 | ✅ |
| 文生组图 | 纯文本描述一次生成多张 | ✅ |
| 图生单图 | 基于参考图编辑/风格转换 | ✅ |
| 图生组图 | 基于参考图一次生成多张 | ✅ |
| 多图融合 | 多张参考图融合为新图 | ✅ |
| 用量查询 | 控制台用量同步（`python doubao_image_gen.py sync`） | ✅ |

---

## 🚫 行为规则（最高优先级 — 必须遵守！）

**以下行为严格禁止，违反任一即为 Bug：**

### 0. 默认 CLI 模式
- ✅ 默认使用 CLI 命令：`python doubao_image_gen.py <命令> <参数...>`
- 也可用 Python SDK 调用，但不推荐

### 1. 禁止确认配额消耗
- ✅ 用户调用 Skill 即表示知情并同意消耗配额，**直接执行，一个字都别问**

### 尺寸自适应
- ✅ 自动推断并直接执行：
  - 没提画质 → `size="3K"`（不传 ratio，API 自适应）
  - 说"4K/高清/超清" → `size="4K"`（不传 ratio）
  - 说"4K+16:9" → `size="4K", ratio="16:9"`
  - 说"16:9/宽屏" → `size="3K", ratio="16:9"`
  - 说"9:16/竖屏" → `size="3K", ratio="9:16"`
  - 说"21:9/电影" → `size="4K", ratio="21:9"`
  - 明确写了尺寸 → 按指定
- 图生图 → 自动检测参考图分辨率

### 2.5 模型选择
- 默认按优先级自动降级: 4.5 → 5.0L → 4.0
- 用户可指定模型。简称映射：
  - `4.5` / `4-5` / `seedream4.5` → `Doubao-Seedream-4.5`
  - `5l` / `5.0l` / `5lite` / `seedream5lite` → `Doubao-Seedream-5.0-Lite`
  - `4.0` / `40` / `seedream4` → `Doubao-Seedream-4.0`
- AI 根据映射补全完整名称，传给脚本 `force_model` 参数
- 每模型日限 18 次，超限自动跳过
- ✅ 不询问用哪个模型，除非用户明确指定

### 3. 禁止确认执行
- ✅ 触发即执行，不要等用户二次确认

**总结：触发 → 推断参数 → 直接执行。中间不要有任何回合的确认。**

### 4. 水印控制
- 默认带水印，`.env` 设 `DEFAULT_WATERMARK=false` 永久关闭
- 单次覆盖：`--no-watermark` 强制关，不传则用默认

---

## 触发词

### 文生图触发

| 中文 | 英文 |
|------|------|
| `生成图片` `画一张图` `创建图片` `制作图片` | `generate image` `create image` `txt2img` |
| `画图` `帮我画` `帮我生成` `我想生成` | `please generate` `please draw` `I want to generate` |
| `搞个图` `来张图` `做张图` `出个图` | `draw` `make an image` `create a picture` |

### 图生图 / 图片编辑触发

| 中文 | 英文 |
|------|------|
| `图生图` `图片编辑` `编辑图片` `改图` | `img2img` `image to image` `edit this image` |
| `换背景` `换风格` `风格转换` `图片处理` | `edit image` `modify image` `transform image` |

### 多图融合 / 合成触发

| 中文 | 英文 |
|------|------|
| `融合` `合成` `两张图片` `多张图片` | `blend` `fuse` `merge` `combine` |
| `拼合` `合图` `融图` `图片混合` | `composite` `mix images` |

### 带风格前缀

`极致生成:` `快速草稿:` `艺术风格:` `4K高清:`

## 工作流程

调用 `doubao_image_gen.py` 脚本：

1. **检测触发词** — 从用户输入提取 prompt、size、style、图生图标记
2. **模型选择** — 按 4.5 → 5.0Lite → 4.0 降级，满 18 次跳过
3. **尺寸自动推断** — 不再询问用户，直接按规则确定
4. **图片规范化** — 本地路径自动 base64 编码，URL 原样通过
5. **调用 API** — 请求火山方舟 Seedream 图片生成接口
6. **保存图片** — 下载到 `Image/`，命名：`内容分辨率-模型-时间.png`
7. **记录历史** — 写入 `image_gen_history.json`，7 天自动清理

## 命令参考

运行 `python doubao_image_gen.py --help` 查看完整参数列表和调用示例。

## 模型

| 模型 | 优先级 | 日限 | 文生图 | 图生图 | 组图/融合 |
|------|--------|------|--------|--------|-----------|
| Seedream-4.5 | 1 | 18 | ✅ | ✅ | ✅ |
| Seedream-5.0-Lite | 2 | 18 | ✅ | ✅ | ✅ |
| Seedream-4.0 | 3 | 18 | ✅ | ❌ 自动降级 | ❌ 自动降级 |

> **已知限制**: 4.0 仅支持文生单图，其他模式自动降级到 4.5/5.0L。多图融合时注意参考图累计大小，base64 后超过 ~15MB 会被 API 拒绝。组图上限为 15 张 (参考图 + 输出)。

超限返回 `{"success":false,"error":"..."}`。

## 🎁 火山「协作奖励计划」

注册火山方舟即可**免费使用** Seedream-4.5、5.0-Lite、4.0 等顶级生图模型，**无需预充值**。详情见 [火山方舟文档](https://www.volcengine.com/docs/82379/1391869)。

## 配置（.env 文件）

在 Skill 目录下创建 `.env` 文件：

```bash
# 必填
ARK_API_KEY=ark-your-key-here
DOUBAO_MODEL_45_ID=ep-xxxxxxxxxxxx
DOUBAO_MODEL_50L_ID=ep-xxxxxxxxxxxx
DOUBAO_MODEL_40_ID=ep-xxxxxxxxxxxx

# 可选
VOLCENGINE_ACCESS_KEY=AKLTxxx          # 控制台用量同步
VOLCENGINE_SECRET_KEY=your-secret       # 控制台用量同步
```

> MODEL_ID 既是 API 调用 ID 也是控制台端点 ID，一个变量两用。

脚本启动时自动加载 `.env`，无需手动 export。

### 获取密钥

- **ARK_API_KEY**: https://console.volcengine.com/ark → API Key 管理
- **MODEL_ID**: https://console.volcengine.com/ark → 在线推理 → 点击接入点名称获取端点ID
- **IAM 密钥**: https://console.volcengine.com/iam → 访问控制 → 密钥管理

## 文件

| 文件 | 说明 |
|------|------|
| `doubao_image_gen.py` | 核心脚本 |
| `.env` | 环境变量配置 |
| `image_gen_history.json` | 调用历史+计数 (7天清理) |
| `Image/` | 生成图片保存目录 |
| `Temp/` | 图生图本地缓存（自动创建/清理） |

---

## 常见错误

| 错误码 | 原因 | 解决 |
|--------|------|------|
| `HTTP 429` | 每分钟调用频率超限 | 等待 1-2 分钟后重试 |
| `HTTP 400` | 参数错误（尺寸/模型不支持） | 检查参数格式 |
| `InvalidEndpointOrModel.NotFound` | 模型 ID 无效 | 检查 .env 中的 MODEL_ID |
| `所有模型调用次数已达上限` | 三个模型都满 18 次 | 等明天重置，或查控制台确认 |
| `图片文件不存在` | 图生图参考图路径有误 | 检查文件路径，确保文件存在 |
| `IAM 密钥未配置` | 缺少 VOLCENGINE_ACCESS_KEY | .env 中配置 IAM 密钥 |

## 💬 支持与反馈

如果遇到错误或问题，请在 [clawhub.ai 技能页面](https://clawhub.ai/etmnb/bytedance-ai-image-gen) 下方留言反馈。