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

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

🚀 快速开始

1. 安装依赖

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

2. 配置环境变量

# 添加到 ~/.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。

📋 命令列表

文生图

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

参数说明：

图生图

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

参数说明：

批量生成

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

生成变体

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

🎨 可用风格

📐 支持尺寸

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

💡 使用示例

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

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

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

console.log(result);

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

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

示例 3：批量生成产品图

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

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

示例 4：图片编辑

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

📊 返回结果格式

成功响应

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

错误响应

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

⚙️ 高级配置

环境变量

缓存机制

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

重试策略

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

🧪 测试

# 运行单元测试
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