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": ""
  }
}

参数说明：

参数类型必填说明promptstring✅图片描述sizestring❌尺寸，默认 1024x1024nnumber❌生成数量，默认 1stylestring❌风格（见下方风格列表）negative_promptstring❌负面提示词

图生图#

json

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

参数说明：

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

批量生成#

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_BASEAPI 基础 URLhttps://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