图片生成 Skill (Doubao Image Gen)

Overview

Call Doubao (豆包) Seedream image generation API through an OpenAI-compatible third-party relay service (中转站), returning locally-saved image files. Designed for end users of Doubao relay services (not the official Volcengine Ark direct API), so it requires only two configurations: the relay URL and the relay API key. Supports text-to-image, image-to-image, sequential image generation, and multi-image fusion in one skill.

When To Use This Skill

Use this skill when the user:

• Requests image generation through a configured Doubao relay (the skill's ARK_BASE_URL points to a relay, not the official volces.com)
• Wants text-to-image (画一张图, 生成一张海报, draw a cat)
• Wants image-to-image or multi-image fusion (基于这张参考图, 把这几张图融合一下, edit this image)
• Wants a set/batch of related images (生成 4 张图, 一组连续图, generate a set of 4)
• Needs the generated image saved to a local path for downstream tools (such as 小龙虾/OpenClaw, PowerPoint slides, blog cover generation, etc.)

Do NOT use this skill when:

• The user is calling the official Volcengine Ark API directly (use the existing volc-image skill — that one hardcodes ark.cn-beijing.volces.com)
• The user only wants to read, edit, or analyze an existing image
• The task is video generation, speech, or any non-image task

Quick Start

1. Configure the relay (one-time setup)

Environment variables (recommended):

export ARK_BASE_URL="https://uniapi.thingo.com.cn/v1"   # the relay's OpenAI-compatible base
export ARK_API_KEY="sk-relay-xxxxxx"                     # the relay's API key

Or write config.json in the same directory as the skill (overrides env only if env is empty):

{
  "base_url": "https://uniapi.thingo.com.cn/v1",
  "api_key": "sk-relay-xxxxxx",
  "model": "doubao-seedream-5-0-260128",
  "api_path": "images/generations",
  "save_dir": "./output",
  "download": true,
  "retry": 1
}

Run python scripts/init.py for an interactive setup that writes config.json for you.

2. Invoke

From a natural-language request inside WorkBuddy / OpenClaw / 小龙虾:

> "用 doubao-image-api 画一只橘猫，要求卡通风格"

The agent (me) will read this skill's scripts, build the request, and return the result.

From a command line:

# Images saved to current working directory by default (follows WorkBuddy workspace)
python scripts/gen.py "一只橘猫，卡通风格" --size 2K

# Explicit save directory (if you want a custom location)
python scripts/gen.py "一只橘猫，卡通风格" --size 2K --save-dir /path/to/output

As a Python function (used by agent tools):

from scripts.gen import generate_image
result = generate_image(prompt="一只橘猫", size="2K")
# result = {"model": "...", "images": [{"url": "...", "local_path": "<save_dir>/xxx.jpg"}], "usage": {...}}

Configuration Reference

All keys resolve in this priority: CLI flag > env var > config.json > built-in default.

Core Capabilities

1. Text-to-image

The simplest path. Pass only prompt (and size):

generate_image(prompt="星际穿越，黑洞，电影感", size="2048x2048")

If size is omitted, the relay's default applies (commonly 1024x1024 or 2K). The size field is required by the API, so the script always sends it; users should set it explicitly when in doubt.

2. Image-to-image (single reference)

> 参考图支持两种形式：① 公网 URL（http(s)://）；② 本地文件路径（如 C:/path/to/photo.jpg）——脚本会自动读取并转成 data:image/...;base64,... 上传，无需手动转码或上传图床。两者可混搭（如一张本地图 + 一张 URL）。重复 --image 可传入多张进行融合。

Pass one image URL via image:

generate_image(
    prompt="把这张图改成赛博朋克风格",
    image="https://example.com/photo.jpg",
    size="2K"
)

3. Sequential image generation (一组图 / 多图)

The relay supports generating multiple related images in one call. Use n to set the count (1–15):

generate_image(
    prompt="同一只柯基在四个季节，温馨插画",
    size="2K",
    n=4
)

The output images array will contain 4 entries; the script downloads all of them and returns a list of local paths.

4. Multi-image fusion (多图融合)

Pass multiple images as a list and the model will fuse their features into a single output. Combine with n > 1 for a fused series. 支持本地文件路径与公网 URL 混搭（见上文图生图说明）：

generate_image(
    prompt="把这三张图里的元素融合成一张新图",
    image=[
        "https://example.com/cat.jpg",
        "https://example.com/dog.jpg",
        "https://example.com/bird.jpg",
    ],
    size="2K"
)

Output Format

The script always prints a single JSON object to stdout (so agent tools can json.loads it) and a one-line summary to stderr. Example:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1765250822,
  "images": [
    {
      "url": "https://ark-content-generation-xxx.tos-cn-beijing.volces.com/abc.jpeg",
      "size": "2048x2048",
      "local_path": "C:\\path\\to\\output\\2026-07-03_abc.jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "total_tokens": 16464
  }
}

• images[].local_path is null when download=false
• usage.total_tokens is omitted if the relay doesn't return it
• On error, the script exits with code 1 and prints {"error": "...", "status": 4xx/5xx} to stdout

Error Handling

Bundled Resources

scripts/

• gen.py — Main entry. Exposes both CLI (python gen.py "prompt") and a Python function generate_image(**kwargs) -> dict. The agent should call generate_image directly when using this skill from inside a tool.
• init.py — Interactive setup wizard. Walks the user through base_url, api_key, and writes config.json. Use when neither env var is set.

references/

• api-spec.md — Full Doubao Seedream API parameter reference (size presets, recommended aspect ratios, all model IDs). Load only when the agent needs to look up a specific parameter.

assets/

(empty — no template files needed)

Notes for the Calling Agent

⚠️ Pre-flight Checklist (MANDATORY before every call)

The agent MUST perform this check before invoking gen.py:

1. Read config.json from the skill root directory.
2. Check api_key: if empty / missing / "" / placeholder → DO NOT call gen.py. Instead, ask the user to provide it (or set ARK_API_KEY env var), and offer to run python scripts/init.py for an interactive setup. The agent may also accept api_key from the current conversation context and pass it via --api-key.
3. Check model: if empty / missing / "" → fall back to doubao-seedream-5-0-260128 (the built-in default). If the user explicitly specified a model, pass it via --model. Only ask the user if the relay's model naming is unknown.
4. Check save_dir: if empty / unset (defaults to CWD) and the user wants images in a specific location, pass --save-dir explicitly. Otherwise the default CWD behavior is fine.

Example of an agent-side pre-flight:

# 1. Read config
config = json.load(open("config.json"))
# 2. Validate api_key
if not config.get("api_key"):
    # Ask user: "api_key is empty, please provide or run init.py"
    return
# 3. Fallback model
model = config.get("model") or "doubao-seedream-5-0-260128"
# 4. Call with explicit args
run(f"python scripts/gen.py '{prompt}' --size {size} --model {model} --api-key {config['api_key']}")

Other Notes

• The relay may rename the model (e.g. doubao-image-v5 instead of doubao-seedream-5-0-260128). If the user reports "model not found", ask which model names the relay exposes and update DOUBAO_MODEL / model in config.
• size is a required field at the API level. If the user didn't specify it, default to 2K (2048×2048) — never omit it, and never default to 1024×1024: for the default model (Seedream 5.0) the upstream rejects anything below 1920×1920 (3,686,400 px). The minimum safe value is 1920x1920; 2048x2048 is the recommended default. When the configured model changes, re-verify upstream's size constraints — different Doubao models (or other vendors' models behind the same relay) may have different minimums.
• Generated image URLs from Doubao expire in ~24 hours. If the caller needs persistence, ensure download=true so the local file is captured.
• The skill never logs the API key. Avoid printing the full config; redact api_key when echoing it back to the user.

Installation

Unpack the zip into ~/.workbuddy/skills/doubao-image-api/, then run once:

python scripts/init.py        # 交互式写入 config.json
python scripts/gen.py "测试 prompt" --size 2K

Or skip the file entirely and use env vars only:

export ARK_BASE_URL="https://uniapi.thingo.com.cn/v1"
export ARK_API_KEY="sk-relay-xxxxxx"
python scripts/gen.py "测试 prompt"

版本更新日志

v1.0.0（发布时间：2026.7.16）

可对接中转站的图片生成技能，一句描述直接出高清图。基于 OpenAI 兼容 images API 的通用生图技能，可灵活搭配各种生图模型。支持文生图、图生图参考、多图融合与 2K 高清输出。源头优质模型：https://uniapi.thingo.com.cn。

v1.1.0（发布时间：2026.7.25）

修复图生图仅支持公网 URL 的问题，新增本地图片自动上传、本地图与 URL 混搭及多图融合支持。

v1.1.1（发布时间：2026.7.26）

增加版本更新日志，修复版本更新后技能名称和简介混乱的问题。