Metadata

name: doubao-image
description: 使用字节跳动豆包 Doubao SeeDream 模型生成高质量图片。支持文生图、AI 绘图、插画创作等功能。
metadata: {"clawdbot":{"emoji":"🎨","category":"AI 工具","version":"2.0.0"}}

豆包文生图（Doubao SeeDream）Skill

基于字节跳动火山引擎 ARK API，调用豆包 SeeDream 5.0 模型进行 AI 文生图创作。

📋 目录

功能特性
前置条件
安装方式
使用方法
API 参数详解
触发条件
工作流
错误处理
最佳实践
常见问题
技术实现
版本历史

✨ 功能特性

🎨 高质量图像生成 - 基于豆包 SeeDream 5.0 模型，支持 2K/1080P/720P 分辨率
🔧 灵活参数配置 - 支持尺寸、水印、格式等多种参数自定义
📦 双脚本实现 - 提供 Bash 和 Python 两种实现方式，适应不同环境
🛡️ 完善的错误处理 - 详细的错误提示和日志记录
💾 自动保存管理 - 智能图片下载和本地保存
🚀 快速响应 - 优化的 API 调用流程，减少等待时间

🔐 前置条件

环境变量配置

必须设置火山引擎 ARK API Key：

export ARK_API_KEY="your_ark_api_key"

获取 API Key 步骤：

访问火山引擎控制台
登录/注册账号
进入「应用管理」→「创建应用」
选择「图像生成」服务
复制生成的 API Key

系统依赖

Bash 脚本依赖：

Bash 4.0+
curl 7.0+
Python 3.6+（用于 JSON 处理）

Python 脚本依赖：

Python 3.8+
requests 库（可选，已内置 fallback 方案）

环境检查脚本

#!/bin/bash
# 检查运行环境
check_environment() {
  local errors=0
  
  # 检查 ARK_API_KEY
  if [ -z "$ARK_API_KEY" ]; then
    echo "❌ 错误：缺少 ARK_API_KEY 环境变量"
    echo "   请执行：export ARK_API_KEY=your_key"
    errors=$((errors + 1))
  else
    echo "✅ ARK_API_KEY 已配置"
  fi
  
  # 检查 curl
  if ! command -v curl &> /dev/null; then
    echo "❌ 错误：缺少 curl 命令"
    errors=$((errors + 1))
  else
    echo "✅ curl 已安装 ($(curl --version | head -n1))"
  fi
  
  # 检查 Python
  if ! command -v python3 &> /dev/null; then
    echo "❌ 错误：缺少 Python 3"
    errors=$((errors + 1))
  else
    echo "✅ Python 已安装 ($(python3 --version))"
  fi
  
  return $errors
}

check_environment

📦 安装方式

方式一：通过 Clawhub 安装（推荐）

# 在 WorkBuddy 中执行
skill install doubao-image

方式二：手动安装

# 1. 克隆或下载技能到本地
git clone https://github.com/your-username/doubao-image-skill.git ~/.workbuddy/skills/doubao-image

# 2. 设置执行权限
chmod +x ~/.workbuddy/skills/doubao-image/scripts/*.sh

# 3. 配置环境变量
echo 'export ARK_API_KEY="your_key"' >> ~/.bashrc
source ~/.bashrc

方式三：直接复制

将 doubao-image 文件夹复制到 ~/.workbuddy/skills/ 目录即可。

🚀 使用方法

基础用法

# 使用默认参数生成图片
./scripts/doubao-image-generate.sh "一只在月光下的白色小猫"

# 指定分辨率（2K/1080P/720P）
./scripts/doubao-image-generate.sh "赛博朋克风格的城市夜景" "1080P"

# 关闭水印
./scripts/doubao-image-generate.sh "山水画" "2K" "false"

Python 脚本用法

# 基础用法
python3 scripts/doubao-image-generate.py \
  --prompt "一只在月光下的白色小猫"

# 完整参数
python3 scripts/doubao-image-generate.py \
  --prompt "赛博朋克风格的城市夜景" \
  --size "1080P" \
  --watermark false \
  --output-dir "./my-images" \
  --verbose

在 WorkBuddy 中使用

当用户说以下话语时自动触发：

"生成一张...的图片"
"帮我画一个..."
"AI 绘图：..."
"文生图..."

📊 API 参数详解

核心参数

参数名	类型	必填	默认值	说明
`prompt`	string	✅ 是	-	图片描述文本，支持中英文
`model`	string	❌ 否	`doubao-seedream-5-0-260128`	固定使用 SeeDream 5.0
`size`	string	❌ 否	`2K`	输出分辨率
`watermark`	boolean	❌ 否	`true`	是否添加水印
`response_format`	string	❌ 否	`url`	返回格式（url/base64）
`stream`	boolean	❌ 否	`false`	是否流式输出

尺寸参数说明

值	分辨率	适用场景
`2K`	2048×2048	高质量输出、印刷用途
`1080P`	1920×1080	社交媒体、网页展示
`720P`	1280×720	快速预览、移动端

高级参数（通过环境变量配置）

环境变量	说明	默认值
`DOUBAO_API_TIMEOUT`	API 超时时间（秒）	`60`
`DOUBAO_RETRY_COUNT`	失败重试次数	`3`
`DOUBAO_OUTPUT_DIR`	默认输出目录	`generated-images`

🎯 触发条件

主要触发词

生成图片、生成图像、创建图片
AI 绘图、文生图、画一张
帮我画、画一个、生成一张...的图
doubao image、豆包生图

触发示例

用户：帮我画一只可爱的猫咪
用户：生成一张赛博朋克风格的城市夜景图
用户：AI 绘图：夕阳下的海滩
用户：文生图 - 中国风山水画

🔄 工作流

1. 需求解析

用户输入 → 提取 prompt → 解析参数 → 验证完整性

解析逻辑：

提取引号内或冒号后的描述文本作为 prompt
识别尺寸关键词（2K/1080P/720P）
检测水印相关表述（"不要水印"/"去水印"）

2. 参数验证

验证流程：
├─ 检查 ARK_API_KEY 是否存在
├─ 检查 prompt 是否非空
├─ 验证 size 参数合法性
├─ 检查网络连接状态
└─ 准备 API 调用

3. API 调用

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "用户描述",
    "size": "2K",
    "watermark": true,
    "response_format": "url",
    "stream": false,
    "sequential_image_generation": "disabled"
  }'

4. 响应处理

成功响应：

{
  "data": [{
    "url": "https://example.com/image.png",
    "content": "base64_encoded_string"
  }],
  "usage": {
    "prompt_tokens": 50,
    "total_tokens": 50
  }
}

处理流程：

解析 JSON 响应
提取图片 URL
下载图片到本地
生成唯一文件名（带时间戳）
通过 open_result_view 展示

5. 图片保存

# 保存路径规则
generated-images/
├── doubao-20260409-233045-abc123.png
├── doubao-20260409-233122-def456.png
└── ...

文件名格式： doubao-YYYYMMDD-HHMMSS-random.png

⚠️ 错误处理

错误码对照表

错误类型	HTTP 状态码	处理方式
未授权	401	提示检查 API Key
余额不足	402	提示充值
请求超限	429	自动重试（指数退避）
服务器错误	500/503	重试 3 次后报错
超时	504	延长超时时间重试
内容违规	400	提示修改 prompt

错误处理脚本

handle_error() {
  local status_code=$1
  local error_msg=$2
  
  case $status_code in
    401)
      echo "❌ 认证失败：API Key 无效或已过期"
      echo "   请重新获取：https://console.volcengine.com/ark"
      ;;
    402)
      echo "❌ 账户余额不足，请充值后重试"
      ;;
    429)
      echo "⚠️  请求频率超限，等待 ${retry_after}秒后重试..."
      sleep $retry_after
      ;;
    500|503)
      echo "⚠️  服务器繁忙，正在重试（第 $retry_count 次）..."
      ;;
    400)
      echo "❌ 请求被拒绝：${error_msg}"
      echo "   可能包含敏感词汇，请修改描述后重试"
      ;;
    *)
      echo "❌ 未知错误：${error_msg}"
      ;;
  esac
}

🎨 最佳实践

Prompt 编写技巧

优质 Prompt 公式：

主体描述 + 环境氛围 + 艺术风格 + 技术参数

示例：

✅ 好的 Prompt：
"一只白色波斯猫，坐在古老的图书馆窗台上，
午后阳光透过彩色玻璃，写实风格，4K 超精细细节，
景深效果，温暖色调"

❌ 差的 Prompt：
"一只猫"

风格关键词库

【艺术风格】
写实、油画、水彩、素描、动漫、赛博朋克、蒸汽朋克、
极简、抽象、印象派、超现实主义

【画面质量】
4K、8K、超高清、电影大片、精致细节、杰作

【光影效果】
光线追踪、全局光照、体积光、丁达尔效应、黄金时刻

【构图方式】
对称构图、三分法、引导线、框架构图、鸟瞰视角

性能优化

批量生成：避免并发请求，串行处理更稳定
缓存策略：相同 prompt 可复用历史结果
超时设置：建议设置 60 秒超时
重试机制：指数退避重试（1s, 2s, 4s, 8s）

❓ 常见问题

Q1: 生成的图片质量不佳？

解决方案：

使用更详细的 prompt 描述
添加质量关键词（4K、超精细、杰作）
选择 2K 分辨率
指定具体艺术风格

Q2: API 调用失败？

排查步骤：

检查 ARK_API_KEY 是否正确
验证网络连接
查看账户余额
检查是否触发频率限制

Q3: 图片下载失败？