name: 圖片生成skill description: 可對接中轉站的圖片生成技能，一句描述直接出高畫質圖。 基於 OpenAI 相容 images API 的通用生圖技能，可靈活搭配各種生圖模型。支援文生圖、圖生圖參考、多圖融合與 2K 高畫質輸出。源頭優質模型：https://uniapi.thingo.com.cn。v1.1.0新增本地圖片自動上傳、本地圖與 URL 混搭及多圖融合支援;v1.1.1增加版本更新日誌，修復版本更新後技能名稱和簡介混亂的問題； agent_created: true

圖片生成 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

發現更多技能外掛，請訪問7w4.net。

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）

增加版本更新日誌，修復版本更新後技能名稱和簡介混亂的問題。

整體質量較好，文件詳細、程式碼規範且無需額外安裝依賴，上手友好。功能覆蓋全面（文生圖、圖生圖、融合圖等），配置靈活，支援本地圖片自動上傳。安全性和錯誤處理考慮周全。不足是初次配置時需要手動填寫 API 金鑰，缺少更直觀的引導提示，中文文件對小部分使用者可能偏長。