Skill: anpupil/seedream-img-gen (version 1.0.0)

--- name: seedream-img-gen description: "This skill should be used when the user wants to generate images using Seedream, the image generation model from ByteDance on Volcengine platform. Triggers include requests like 用Seedream生成图片, seedream画图, generate image with seedream, 调用seedream, 用豆包画图, or any request to create, draw, or generate images via the Seedream API." --- # Seedream 图片生成 Skill ## 概述 本 Skill 帮助通过火山引擎方舟平台（Volcengine Ark）的 Seedream 系列模型生成图片，支持文生图（text-to-image）和图生图（image-to-image，Seedream 4.0+）。 --- ## 前置条件 1. **获取 API Key**：前往 https://console.volcengine.com/ark 注册并获取 `ARK_API_KEY` 2. **开通模型**：在方舟平台「开通管理」页面开通所需模型 3. **安装依赖**（二选一）： - 官方 SDK：`pip install 'volcengine-python-sdk[ark]'` - OpenAI 兼容：`pip install openai` --- ## 核心工作流 ### 1. 收集必要信息 在生成图片前，需要明确： - **提示词**（prompt）：图片内容描述，支持中英文 - **模型选择**：默认使用 `doubao-seedream-3-0-t2i-250415`（详细模型列表见 `references/api_reference.md`） - **图片尺寸**（可选）：如 `1024x1024`、`1792x1024` - **输出路径**（可选）：保存图片的本地路径 如果用户未明确提到模型，默认使用 Seedream 4.0（`doubao-seedream-4-0-250828`）。 ### 2. 检查环境 To verify the environment is ready, run: ```bash echo $ARK_API_KEY ``` If the API key is missing, instruct the user to set it: ```bash export ARK_API_KEY="your_api_key_here" ``` ### 3. 调用生成脚本 Use the bundled script at `scripts/generate_image.py`: ```bash # 基本用法（文生图） python3 ~/.workbuddy/skills/seedream-image-gen/scripts/generate_image.py \ --prompt "一只可爱的橘猫坐在窗边看夕阳，写实摄影风格" \ --output output.png # 指定模型 python3 ~/.workbuddy/skills/seedream-image-gen/scripts/generate_image.py \ --prompt "a cyberpunk city at night" \ --model doubao-seedream-4-0-250828 \ --output output.png # 指定尺寸 python3 ~/.workbuddy/skills/seedream-image-gen/scripts/generate_image.py \ --prompt "横版风景画，超宽屏" \ --size 1792x1024 \ --output landscape.png # 生成多张 python3 ~/.workbuddy/skills/seedream-image-gen/scripts/generate_image.py \ --prompt "卡通风格的小动物" \ --n 4 \ --output animals.png # 使用 OpenAI 兼容模式 python3 ~/.workbuddy/skills/seedream-image-gen/scripts/generate_image.py \ --prompt "描述内容" \ --sdk openai \ --output result.png ``` ### 4. 处理结果 - 脚本成功执行后会输出图片保存路径 - 生成的图片默认保存到当前工作目录，也可通过 `--output` 指定 - 使用 `url` 格式时，脚本会自动下载图片到本地 --- ## 快速内联调用（不使用脚本） 如果希望直接生成代码调用，可用以下模板： ```python import os from volcenginesdkarkruntime import Ark client = Ark([REDACTED_SECRET]"ARK_API_KEY")) resp = client.images.generate( model="doubao-seedream-3-0-t2i-250415", prompt="YOUR_PROMPT_HERE", response_format="url", ) url = resp.data[0].url print("图片 URL:", url) # 下载图片 import urllib.request urllib.request.urlretrieve(url, "output.png") print("已保存至 output.png") ``` --- ## 模型选择建议 | 场景 | 推荐模型 | |------|---------| | 通用文生图，快速稳定 | `doubao-seedream-3-0-t2i-250415` | | 高质量图片，支持参考图 | `doubao-seedream-4-0-250828` | | 最新最强效果 | `doubao-seedream-4-5-251128` | | 极速轻量 | `doubao-seedream-5-0-lite` | --- ## 参考资源 - 详细 API 参数和代码示例：`references/api_reference.md` - 生成脚本（支持命令行调用）：`scripts/generate_image.py` - 官方文档：https://www.volcengine.com/docs/82379

path: _meta.json
content: name: seedream-img-gen
version: 1.0.0
description: 使用火山引擎 Seedream 模型生成图片，支持文生图和图生图
license: MIT

path: scripts/generate_image.py
content: #!/usr/bin/env python3
"""
Seedream Image Generator
使用火山引擎方舟平台 Seedream 模型生成图片

用法:
    python3 generate_image.py --prompt "一只可爱的猫咪" [options]

依赖:
    pip install volcengine-python-sdk[ark]
    # 或者使用 openai 兼容方式:
    pip install openai
"""

import argparse
import base64
import os
import sys
import time
from pathlib import Path


def generate_with_volcengine_sdk(prompt, model, size, output_path, response_format="url", n=1):
    """使用官方 volcengine SDK 调用"""
    try:
        from volcenginesdkarkruntime import Ark
    except ImportError:
        print("缺少依赖，请运行: pip install 'volcengine-python-sdk[ark]'", file=sys.stderr)
        sys.exit(1)

    [REDACTED_SECRET]"ARK_API_KEY") or os.environ.get("VOLCENGINE_API_KEY")
    if not [REDACTED_SECRET]"错误: 请设置环境变量 ARK_API_KEY（方舟平台 API Key）", file=sys.stderr)
        sys.exit(1)

    client = Ark([REDACTED_SECRET])

    kwargs = dict(
        model=model,
        prompt=prompt,
        response_format=response_format,
    )
    if size:
        kwargs["size"] = size

    print(f"正在调用 Seedream 模型: {model}")
    print(f"提示词: {prompt}")

    resp = client.images.generate(**kwargs)
    return resp


def generate_with_openai_sdk(prompt, model, size, output_path, response_format="url", n=1):
    """使用 openai 兼容方式调用"""
    try:
        from openai import OpenAI
    except ImportError:
        print("缺少依赖，请运行: pip install openai", file=sys.stderr)
        sys.exit(1)

    [REDACTED_SECRET]"ARK_API_KEY") or os.environ.get("VOLCENGINE_API_KEY")
    if not [REDACTED_SECRET]"错误: 请设置环境变量 ARK_API_KEY（方舟平台 API Key）", file=sys.stderr)
        sys.exit(1)

    client = OpenAI(
        [REDACTED_SECRET],
        base_url="https://ark.cn-beijing.volces.com/api/v3",
    )

    kwargs = dict(
        model=model,
        prompt=prompt,
        response_format=response_format,
    )
    if size:
        kwargs["size"] = size

    print(f"正在调用 Seedream 模型 (OpenAI 兼容模式): {model}")
    print(f"提示词: {prompt}")

    resp = client.images.generate(**kwargs)
    return resp


def save_image(resp, output_path, response_format):
    """保存生成的图片"""
    saved_files = []
    for i, item in enumerate(resp.data):
        if response_format == "url":
            url = item.url
            print(f"\n图片 {i+1} URL: {url}")
            # 下载图片
            import urllib.request
            suffix = ".png"
            if output_path:
                save_to = output_path if len(resp.data) == 1 else f"{Path(output_path).stem}_{i+1}{Path(output_path).suffix}"
            else:
                timestamp = int(time.time())
                save_to = f"seedream_output_{timestamp}_{i+1}{suffix}"

            print(f"正在下载图片到: {save_to}")
            urllib.request.urlretrieve(url, save_to)
            saved_files.append(save_to)
            print(f"✅ 已保存: {save_to}")

        elif response_format == "b64_json":
            b64_data = item.b64_json
            if output_path:
                save_to = output_path if len(resp.data) == 1 else f"{Path(output_path).stem}_{i+1}{Path(output_path).suffix}"
            else:
                timestamp = int(time.time())
                save_to = f"seedream_output_{timestamp}_{i+1}.png"

            with open(save_to, "wb") as f:
                f.write(base64.b64decode(b64_data))
            saved_files.append(save_to)
            print(f"✅ 已保存: {save_to}")

    return saved_files


def main():
    parser = argparse.ArgumentParser(description="使用 Seedream 生成图片")
    parser.add_argument("--prompt", "-p", required=True, help="图片生成提示词（支持中英文）")
    parser.add_argument(
        "--model", "-m",
        default="doubao-seedream-4-0-250828",
        help="模型 ID，默认: doubao-seedream-4-0-250828"
    )
    parser.add_argument(
        "--size", "-s",
        default=None,
        help="图片尺寸，如 1024x1024、1792x1024 等（可选）"
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        help="输出文件路径，默认自动命名"
    )
    parser.add_argument(
        "--format", "-f",
        choices=["url", "b64_json"],
        default="url",
        help="响应格式，默认 url"
    )
    parser.add_argument(
        "--n",
        type=int,
        default=1,
        help="生成图片数量，默认 1"
    )
    parser.add_argument(
        "--sdk",
        choices=["ark", "openai"],
        default="ark",
        help="使用的 SDK，ark=官方 SDK，openai=OpenAI 兼容方式，默认 ark"
    )

    args = parser.parse_args()

    try:
        if args.sdk == "openai":
            resp = generate_with_openai_sdk(
                args.prompt, args.model, args.size,
                args.output, args.format, args.n
            )
        else:
            resp = generate_with_volcengine_sdk(
                args.prompt, args.model, args.size,
                args.output, args.format, args.n
            )

        saved = save_image(resp, args.output, args.format)
        print(f"\n生成完成，共保存 {len(saved)} 张图片")
        for f in saved:
            print(f"  📁 {os.path.abspath(f)}")

    except Exception as e:
        print(f"❌ 生成失败: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()


path: references/api_reference.md
content: # Seedream API 参考文档

## 平台信息

- **平台**: 火山引擎 方舟大模型服务平台
- **API Endpoint**: `https://ark.cn-beijing.volces.com/api/v3`
- **鉴权方式**: API Key（环境变量 `ARK_API_KEY`）
- **官方文档**: https://www.volcengine.com/docs/82379

---

## 可用模型

| 模型名称 | Model ID | 能力 | 说明 |
|---------|---------|------|------|
| Seedream 3.0 | `doubao-seedream-3-0-t2i-250415` | 文生图 | 推荐，高质量，中英双语 |
| Seedream 4.0 | `doubao-seedream-4-0-250828` | 文生图 + 图生图 | 支持多图融合 |
| Seedream 4.5 | `doubao-seedream-4-5-251128` | 文生图 + 图生图 | 最新，能力最强 |
| Seedream 5.0 Lite | `doubao-seedream-5-0-lite` | 文生图 | 极速，轻量 |

---

## 请求参数

### POST `/images/generations`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | ✅ | Model ID |
| `prompt` | string | ✅ | 提示词，支持中英文，建议 ≤300 汉字或 600 英文单词 |
| `n` | integer | ❌ | 生成图片数量，默认 1 |
| `size` | string | ❌ | 图片分辨率，如 `1024x1024`、`1792x1024`、`2048x2048`（4.0+支持 4K） |
| `response_format` | string | ❌ | `url`（默认，24h有效）或 `b64_json` |
| `image` | string/array | ❌ | 参考图（URL 或 Base64），3.0 不支持，4.0+ 支持图生图 |
| `watermark` | boolean | ❌ | 是否添加水印，默认 false |

---

## 响应格式

```json
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://...",           // response_format=url 时返回，24h有效
      "b64_json": "...",              // response_format=b64_json 时返回
      "size": "1024x1024"
    }
  ],
  "usage": {
    "total_tokens": 100
  }
}
```

---

## 安装依赖

### 方式一：官方 SDK（推荐）
```bash
pip install 'volcengine-python-sdk[ark]'
```

### 方式二：OpenAI 兼容
```bash
pip install openai
```

---

## 代码示例

### 官方 SDK（Python）
```python
import os
from volcenginesdkarkruntime import Ark

client = Ark([REDACTED_SECRET]"ARK_API_KEY"))

resp = client.images.generate(
    model="doubao-seedream-3-0-t2i-250415",
    prompt="一只可爱的橘猫坐在窗边看夕阳",
    n=1,
    response_format="url",
    # size="1024x1024",  # 可选
)

print(resp.data[0].url)
```

### OpenAI 兼容（Python）
```python
import os
from openai import OpenAI

client = OpenAI(
    [REDACTED_SECRET]"ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

resp = client.images.generate(
    model="doubao-seedream-3-0-t2i-250415",
    prompt="一只可爱的橘猫坐在窗边看夕阳",
)

print(resp.data[0].url)
```

### cURL
```bash
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-3-0-t2i-250415",
    "prompt": "一只可爱的橘猫坐在窗边看夕阳",
    "n": 1,
    "response_format": "url"
  }'
```

---

## 提示词建议

- **中英文均支持**，中文描述更直接，英文描述细节控制力更强
- **描述主体**：先描述主要内容，再描述风格、光线、构图
- **字数建议**：≤300 汉字或 600 英文单词，过长反而影响效果
- **风格关键词**：`电影感`、`赛博朋克`、`水彩画`、`写实摄影`、`动漫风格`、`油画`
- **质量关键词**：`高清`、`8K`、`超细节`、`photorealistic`

---

## 获取 API Key

1. 前往 https://console.volcengine.com/ark
2. 注册/登录火山引擎账号
3. 在「API Key」页面创建 Key
4. 在「开通管理」页面开通所需模型


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)