小马良-豆包生图 / Maliang Doubao Image Gen#

🖌️ 关于「马良」: 名字源自中国神话故事《神笔马良》—— 马良拥有一支神笔，画什么就会变成真的。这个 skill 就是你的「神笔」，用文字描绘，让 AI 为你生成图像。

🖌️ About "Maliang": Named after the Chinese legend Shenbi Maliang (Magic Brush Ma Liang) — who possessed a magic brush that brought drawings to life. This skill is your magic brush: describe with words, let AI generate the image.

基于火山引擎方舟 ARK 平台的豆包 Seedream 文生图服务。

Powered by Doubao Seedream text-to-image service via Volcano Engine ARK platform.

默认模型 / Default Model: doubao-seedream-5-0-260128 (Seedream 5.0)

---

✨ 核心特色 / Key Features#

1. 一键生图，自动回传 / One-Click Generation, Auto-Reply

   在聊天窗口直接呼唤马良，描述你想要的图片，生成完成后 自动将图片发送回聊天界面，无需手动查找文件。

   Simply invoke Maliang in chat, describe what you want, and the generated image is automatically sent back to the chat window — no need to manually locate files.

2. 本地备份 + 画廊 / Local Backup + Gallery

   图片同时保存到本地，并生成可视化画廊页面，方便管理和回顾。

   Images are also saved locally with a visual gallery page for easy management and review.

---

🚀 快速开始 / Quick Start#

1. 配置 API Key / Configure API Key#

推荐：使用 Skill 环境变量 / Recommended: Skill Environment Variables

在 OpenClaw 配置中为该 skill 设置环境变量： Set environment variables in OpenClaw config for this skill:

json

{
  "skills": {
    "doubao-maliang-image-gen": {
      "env": {
        "VOLCANO_ENGINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

文件位置 / File location: ~/.openclaw/config.json

替代方式：系统环境变量 / Alternative: System Environment Variables

bash

export VOLCANO_ENGINE_API_KEY="your-api-key-here"

兼容的变量名 / Compatible Variable Names（按优先级 / in priority order）：

• VOLCANO_ENGINE_API_KEY （推荐 / recommended）
• ARK_API_KEY
• SEEDREAM_API_KEY

⚠️ 安全提示 / Security Note: 永远不要将 API key 直接写在命令行参数或脚本里。使用环境变量避免密钥泄露。

Never write API keys directly in command line arguments or scripts. Use environment variables to prevent credential leaks.

2. 获取 API Key / Get API Key#

中文步骤：

1. 访问 火山方舟控制台
2. 创建或进入已有项目
3. 在「API Key 管理」中创建新密钥
4. 开通「图像生成」权限（Doubao Seedream 模型）

English Steps:

1. Visit Volcano Engine ARK Console
2. Create or enter an existing project
3. Create a new key in "API Key Management"
4. Enable "Image Generation" permission for Doubao Seedream model

---

🎯 触发条件 / When to Use#

使用本 skill 的场景（中英文均可触发）： Use this skill when (works in both Chinese and English):

• 用户点名 小马良 / User invokes Maliang
  • 可触发关键词 / Trigger words: "小马良", "马良", "Maliang", "Little Maliang"
• 用户明确要求使用 豆包 / Doubao / Seedream / 火山方舟 / Volcano ARK 生图
  • 可触发关键词 / Trigger words: "豆包", "Doubao", "Seedream", "火山方舟", "Volcano ARK", "Volcano Engine"
• 用户希望图片生成走 Maliang 路径 / User requests the Maliang image generation path

💡 提示 / Tip: 无论用中文还是英文呼唤，马良都能听懂！

Maliang understands both Chinese and English invocations!

---

💬 使用示例 / Usage Examples#

中文示例：

用户：小马良，帮我画一只穿着宇航服的猫咪，在月球上散步，卡通风格

马良：✨ 已为你生成图片！（图片自动发送到聊天窗口）

English Example:

User: Maliang, draw me a cat in an astronaut suit walking on the moon, cartoon style

Maliang: ✨ Here's your image! (Image automatically sent to chat)

更多示例 / More Examples:

场景 / Scenario对话示例 / Chat Example产品设计 / Product Design"马良，帮我生成一个极简风格的咖啡杯产品图，白色背景，柔和光线"插画创作 / Illustration"小马良，画一幅赛博朋克风格的城市夜景，霓虹灯，雨天街道"头像生成 / Avatar"马良，给我生成一张卡通风格的程序员头像，戴眼镜，友善的表情"概念图 / Concept Art"帮我画一片秋日森林，金色阳光透过树叶，风景摄影风格"

---

💡 Prompt 建议 / Prompt Tips#

豆包 Seedream 支持多种风格描述，建议包含： Doubao Seedream supports various style descriptions. Recommended elements:

要素 / Element说明 / Description示例 / Example主体 / Subject画面中有什么 / What's in the imagea vintage sports car场景 / Scene环境、背景 / Environment, backgroundon a coastal highway at dusk风格 / Style摄影、插画、3D 等 / Photography, illustration, 3D, etc.cinematic photography构图 / Composition近景、全景等 / Close-up, wide shot, etc.wide-angle shot光线/色调 / Lighting/Color光线、色彩 / Light, color schemegolden hour lighting, warm tones质感 / Texture材质 / Material qualityglossy metallic finish

示例 / Example:

"Editorial fashion portrait, model in seafoam silk dress, gold jewelry, soft natural window light, clean beige background, high-end magazine style"

---

📤 输出说明 / Output Structure#

图片会同时输出到两个地方： Images are delivered to two places simultaneously:

1. 聊天窗口 / Chat Window — 生成完成后 自动发送 到当前对话 ✨

2. 本地文件夹 / Local Folder：

text

~/.openclaw/workspace/tmp/doubao-maliang-image-gen-<timestamp>/
├── <prompt-slug>-1.png    # 生成的图片 / Generated image
├── manifest.json          # 生成记录（包含 prompt、模型、时间戳）/ Generation record
└── index.html             # 本地画廊页面 / Local gallery page

---

🔧 技术细节 / Technical Details#

命令行生成 / CLI Generation#

如果需要通过命令行直接生成（而非聊天触发）： If you need to generate via command line (instead of chat invocation):

基础用法 / Basic Usage：

bash

python3 "$SKILL_DIR/scripts/gen.py" --prompt "a serene mountain landscape at sunset"

多图生成 / Multiple Images：

bash

python3 "$SKILL_DIR/scripts/gen.py" --prompt "minimalist coffee cup product shot" --count 2

指定尺寸 / Specify Size：

bash

python3 "$SKILL_DIR/scripts/gen.py" --prompt "cyberpunk city street" --size 1K
# 支持 / Supported: 1K (1024x1024), 2K (2048x2048)

切换模型 / Switch Models#

通过环境变量（全局）/ Via Environment Variables (Global)

bash

export SEEDREAM_MODEL="doubao-seedream-5-0-260128"
export SEEDREAM_API_ENDPOINT="https://ark.cn-beijing.volces.com/api/v3/images/generations"

通过命令行参数（单次）/ Via Command Line (One-time)

bash

python3 "$SKILL_DIR/scripts/gen.py" \
  --prompt "abstract art composition" \
  --model "doubao-seedream-5-0-260128" \
  --endpoint "https://ark.cn-beijing.volces.com/api/v3/images/generations"

支持的模型 / Supported Models

模型 ID / Model ID说明 / Descriptiondoubao-seedream-5-0-260128Seedream 5.0 (默认 / default)

如需使用其他模型，请先在方舟控制台开通对应模型的调用权限。

To use other models, please enable the corresponding model permissions in the ARK console first.

API 信息 / API Info#

• API 端点 / API Endpoint: https://ark.cn-beijing.volces.com/api/v3/images/generations
• 协议 / Protocol: OpenAI-compatible HTTP API
• 默认尺寸 / Default Size: 2K (2048x2048)
• 单次最大数量 / Max per Request: 4 张 / images
• 超时设置 / Timeout: 300 秒 / seconds

---

🐛 故障排除 / Troubleshooting#

问题 / Issue解决方案 / Solution"Missing API key"检查 VOLCANO_ENGINE_API_KEY 环境变量是否设置 / Check if VOLCANO_ENGINE_API_KEY env var is set"API failed (401)"API Key 无效或过期，检查密钥是否正确 / API Key invalid or expired"API failed (429)"请求过于频繁，稍后重试 / Too many requests, retry later"no images returned"检查 prompt 是否为空或包含违规内容 / Check if prompt is empty or contains prohibited content

---

License#

MIT