Volc Image Gen

Use Volc Engine AI to generate, edit, batch produce, and create variations of images with customizable styles and sizes.

volc-image-gen - 火山引擎图像生成技能

⚡ 基于火山引擎方舟平台的 AI 图像生成技能，支持文生图、图生图、批量生成和变体生成。

---

🚀 快速开始

1. 安装依赖

bash

cd /home/node/openclaw-skills/volc-image-gen
npm install

2. 配置环境变量

bash

# 添加到 ~/.bashrc 或 ~/.zshrc
export VOLC_API_KEY="your_volc_api_key"
export VOLC_API_BASE="https://ark.cn-beijing.volces.com/api/v3"
export VOLC_IMAGE_MODEL="doubao-image-x"

# 使配置生效
source ~/.bashrc

3. 获取 API Key

访问 火山引擎方舟控制台 获取 API Key。

---

📋 命令列表

文生图

json

{
  "command": "generate",
  "params": {
    "prompt": "一只可爱的猫咪，高清，写实风格",
    "size": "1024x1024",
    "n": 1,
    "style": "realistic",
    "negative_prompt": ""
  }
}

参数说明：

参数	类型	必填	说明
prompt	string	✅	图片描述
size	string	❌	尺寸，默认 1024x1024
n	number	❌	生成数量，默认 1
style	string	❌	风格（见下方风格列表）
negative_prompt	string	❌	负面提示词

图生图

json

{
  "command": "edit",
  "params": {
    "image": "/path/to/image.png",
    "prompt": "将猫咪换成狗狗",
    "strength": 0.7,
    "size": "1024x1024"
  }
}

参数说明：

参数	类型	必填	说明
image	string	✅	输入图片（URL 或本地路径）
prompt	string	✅	编辑描述
strength	number	❌	重绘强度 0-1，默认 0.7
size	string	❌	输出尺寸

批量生成

json

{
  "command": "batch",
  "params": {
    "prompts": ["一只猫咪", "一只狗狗", "一只兔子"],
    "concurrent": 3,
    "size": "1024x1024",
    "style": "realistic"
  }
}

生成变体

json

{
  "command": "variations",
  "params": {
    "image": "/path/to/image.png",
    "n": 5,
    "strength": 0.5,
    "size": "1024x1024"
  }
}

---

🎨 可用风格

风格	说明	适用场景
realistic	写实风格，高清，高质量	产品摄影、人像、风景
anime	动漫风格，二次元，精美	动漫角色、插画
oil	油画风格，艺术感，厚重	艺术作品、装饰画
watercolor	水彩风格，清新，透明感	清新插画、背景
sketch	素描风格，线条感，黑白	草图、线稿
cyberpunk	赛博朋克风格，霓虹灯，未来感	科幻场景、未来城市
fantasy	奇幻风格，魔法，梦幻	奇幻场景、魔法效果

---

📐 支持尺寸

• 512x512
• 512x768
• 768x512
• 768x768
• 1024x1024
• 1024x1536
• 1536x1024

---

💡 使用示例

示例 1：生成写实风格猫咪

javascript

const { execute } = require('./src/index');

const result = await execute({
  command: 'generate',
  params: {
    prompt: '一只可爱的猫咪在阳光下玩耍',
    style: 'realistic',
    size: '1024x1024'
  }
});

console.log(result);

示例 2：生成动漫风格头像

javascript

const result = await execute({
  command: 'generate',
  params: {
    prompt: '一个可爱的女孩，大眼睛，长发',
    style: 'anime',
    n: 4
  }
});

示例 3：批量生成产品图

javascript

const result = await execute({
  command: 'batch',
  params: {
    prompts: [
      '白色 T 恤，简约设计',
      '蓝色牛仔裤，休闲风格',
      '黑色运动鞋，时尚款式'
    ],
    concurrent: 3,
    style: 'realistic'
  }
});

console.log(`成功：${result.successful}, 失败：${result.failed}`);

示例 4：图片编辑

javascript

const result = await execute({
  command: 'edit',
  params: {
    image: 'https://example.com/input.png',
    prompt: '将背景换成海滩',
    strength: 0.6
  }
});

---

📊 返回结果格式

成功响应

json

{
  "success": true,
  "images": [
    {
      "url": "https://xxx.volces.com/xxx.png",
      "local_path": "/tmp/openclaw/volc_1712000000_abc123.png",
      "prompt": "一只可爱的猫咪",
      "size": "1024x1024",
      "style": "realistic",
      "index": 1
    }
  ],
  "usage": {
    "tokens": 100,
    "cost": 0.12,
    "model": "doubao-image-x"
  }
}

错误响应

json

{
  "success": false,
  "error": "鉴权失败 (401) - 请检查 VOLC_API_KEY 是否正确",
  "code": 401
}

---

⚙️ 高级配置

环境变量

变量	说明	默认值
VOLC_API_KEY	火山引擎 API Key（必填）	-
VOLC_API_BASE	API 基础 URL	https://ark.cn-beijing.volces.com/api/v3
VOLC_IMAGE_MODEL	图像模型	doubao-image-x

缓存机制

• 内置 1 小时缓存，相同参数不会重复调用 API
• 缓存键基于 prompt + 参数生成
• 可通过 useCache: false 禁用缓存

重试策略

• 默认最大重试 3 次
• 指数退避：1s → 2s → 4s
• 401/400 错误不重试，429/5xx 错误重试

---

🧪 测试

bash

# 运行单元测试
npm test

# 或手动测试
node tests/image-gen.test.js

---

⚠️ 常见问题

1. 鉴权失败 (401)

原因： API Key 配置错误
解决： 检查 VOLC_API_KEY 环境变量是否正确设置

2. 参数错误 (400)

原因： prompt 或 size 参数不合法
解决： 检查参数格式和取值范围

3. API 限流 (429)

原因： 请求频率过高
解决： 降低并发数或稍后重试

4. 图片下载失败

原因： 网络问题或 URL 失效
解决： 检查网络连接，重试请求

---

📝 更新日志

v1.0.0 (2026-04-01)

• ✨ 初始版本发布
• 🎨 支持文生图、图生图、批量生成、变体生成
• 🎭 7 种预定义风格
• 🔄 智能重试机制（指数退避）
• 💾 自动缓存（1 小时）
• ⚡ 并发控制（p-limit）
• 🧪 完整单元测试

---

🔗 相关链接

• 火山引擎方舟文档
• OpenClaw 文档
• GitHub 仓库

---

版本： 1.0.0
许可： MIT
作者： OpenClaw Skill Master