Volc Image Gen

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

Security Scan

The skill appears to implement the advertised Volc Engine image-generation functionality, but there are mismatches in declared requirements and a prompt-injection signal; it will also read local image files and upload them to an external API (needs a sensitive API key).

Purpose & Capability

The code, SKILL.md, README, and skill.json consistently implement a Volc Engine image-generation skill that requires a VOLC_API_KEY and calls the Volc Engine API. That capability matches the name/description. However, the registry-level metadata provided to this evaluation (top-level summary) claimed "Required env vars: none" and "Primary credential: none", which contradicts skill.json and the SKILL.md instructions that require VOLC_API_KEY (and optionally VOLC_API_BASE and VOLC_IMAGE_MODEL). This metadata mismatch is an incoherence you should resolve before trusting the listing.

Instruction Scope

Runtime instructions and code are narrowly scoped to image generation and editing. They instruct npm install, setting VOLC_API_KEY in shell rc files, and calling the Volc Engine images endpoint. Important operational behavior: loadImage() will read local file paths and convert them to Base64 and the skill will upload that data to the external Volc API. That file-read/upload behavior is expected for an image-edit feature but is a privacy-sensitive action and should be explicit to users (SKILL.md does not clearly warn that local files will be transmitted to the external service).

Install Mechanism

No external download/install spec is present; this is an instruction-plus-source package with a package.json and normal npm deps (axios, p-limit, node-cache). No surprising or high-risk install URLs, archives, or obfuscated install steps were found.

Credentials

The skill requires a sensitive credential (VOLC_API_KEY) which is appropriate for calling the Volc Engine API. However, the top-level registry metadata in the evaluation stub showing "Required env vars: none" contradicts the skill.json and SKILL.md which declare VOLC_API_KEY as required. This discrepancy is concerning: either the registry entry is incomplete/misconfigured or the skill was published without accurately declaring credentials it needs. Aside from the API key and optional base/model vars, no unrelated secrets are requested.

Persistence & Privilege

The skill does not request always:true or any elevated persistent presence. It does write image files to /tmp/openclaw when saving downloads — that is reasonable for its purpose and scoped to a temporary directory. It does not attempt to modify other skills or global agent settings.

Scan Findings in Context

[unicode-control-chars] unexpected: The SKILL.md triggered a unicode-control-chars detector. There is no need for hidden unicode control characters in a documentation file; this can be used in some attacks to confuse parsers or evaluations. The SKILL.md content visible here looks normal, but you should inspect the file for invisible characters and remove them or request a clean copy from the author.

What to consider before installing

Things to check before installing/using this skill: 1) Confirm the registry metadata: the package clearly requires VOLC_API_KEY (and optionally VOLC_API_BASE/VOLC_IMAGE_MODEL) but the top-level listing claimed no env vars. Ask the publisher or marketplace to correct the listing if necessary. 2) Treat VOLC_API_KEY as sensitive: grant it only if you trust the Volc Engine service and the skill's author. The skill will send images (including local files you supply) to the external Volc API. 3) Be cautious with local file paths: the skill will read local images and upload them (Base64) to the remote API. Do not pass paths to sensitive files or directories you don't want transmitted. 4) Inspect SKILL.md for hidden characters (the pre-scan found unicode control characters). Prefer a clean copy and consider scanning files for invisible/control characters before running. 5) Run tests and initial usage in an isolated environment (container or VM) and with a limited/test API key to avoid accidental data leakage or unexpected costs. 6) If you need stronger assurance, request source provenance: a trustworthy repository URL, maintainer identity, and release signatures. The included GitHub link in docs should be verified manually. Overall: behavior is consistent with an image-generation skill, but the metadata mismatch and the control-character finding merit caution — treat this as suspicious until those issues are resolved.

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

参数说明：

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

图生图

{
  "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	❌	输出尺寸

批量生成

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

---

🎨 可用风格

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

---

📐 支持尺寸

• 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
}

---

⚙️ 高级配置

环境变量

变量	说明	默认值
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 错误重试

---

🧪 测试

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