diff --git a/.trae/skills/image-tools/SKILL.md b/.trae/skills/image-tools/SKILL.md index 776eb8c..1939817 100644 --- a/.trae/skills/image-tools/SKILL.md +++ b/.trae/skills/image-tools/SKILL.md @@ -1,17 +1,193 @@ --- name: image-tools -description: 阿里云万相2.7图生图工具，用于AI生成产品主图、场景图、电商素材。Invoke when user needs to generate product images, e-commerce visuals, or AI image editing. +description: AI图片生成与编辑工具集。包含豆包万相（Doubao Seedream）和阿里云万相2.7两个AI图片引擎，支持文生图、图生图、多图融合、图片编辑。用于生成产品主图、场景图、电商素材、宣传页等。Invoke when user needs to generate, edit, or transform images for e-commerce or product visuals. --- -# Image Tools - 万相2.7 AI图生图 +# Image Tools - AI图片生成与编辑工具集 -使用阿里云百炼 **wan2.7-image-pro** 模型进行 AI 图生图处理，支持文生图、图生图、图片编辑。 +集成两个AI图片引擎： +1. **豆包万相（Doubao Seedream）** — 火山引擎Ark API，支持文生图、图生图、多图融合、图片编辑、批量生成 +2. **阿里云万相2.7** — 阿里云百炼 wan2.7-image-pro，支持文生图、图生图、图片编辑 -## 前提条件 +--- + +## 引擎1：豆包万相（Doubao Seedream） + +使用火山引擎 Ark API 的 Doubao Seedream 模型，支持文生图、图生图、多图融合、图片编辑。 + +### 前提条件 + +- `curl.exe`（Windows内置） +- Ark API Key: `ark-119a37ed-f123-42fc-aea6-b38d47d47fc0-f7ddf` +- API端点: `https://ark.cn-beijing.volces.com/api/v3/images/generations` + +### 模式一览 + +| 模式 | `image`参数 | 用途 | +|---|---|---| +| 文生图 | 省略或`[]` | 从文字描述生成图片 | +| 图生图 | `["url1"]` | 风格转换、精修、变换 | +| 多图融合 | `["url1","url2",...]` | 最多14张参考图融合 | +| 图片编辑 | `["url1"]` + 编辑提示词 | 移除/替换元素、换背景等 | + +默认模型: `doubao-seedream-5-0-260128` + +### 文生图（Windows PowerShell） + +```powershell +$tmpFile = "$env:TEMP\request.json" +$prompt = "YOUR_PROMPT_HERE" +$json = @" +{"model":"doubao-seedream-5-0-260128","prompt":"$prompt","size":"2k","sequential_image_generation":"disabled","response_format":"url","stream":false,"watermark":false} +"@ +$sw = [System.IO.StreamWriter]::new($tmpFile, $false, (New-Object System.Text.UTF8Encoding $false)) +$sw.Write($json); $sw.Close() + +$response = curl.exe -s -X POST https://ark.cn-beijing.volces.com/api/v3/images/generations ` + -H "Content-Type: application/json" ` + -H "Authorization: Bearer ark-119a37ed-f123-42fc-aea6-b38d47d47fc0-f7ddf" ` + -d "@$tmpFile" | ConvertFrom-Json + +$imageUrl = $response.data[0].url +$outputPath = Join-Path (Get-Location) "output-name.png" +curl.exe -s -o $outputPath $imageUrl +Write-Output $outputPath +``` + +### 图生图/图片编辑（本地文件输入，Windows PowerShell） + +```powershell +$imgBytes = [System.IO.File]::ReadAllBytes((Resolve-Path "path\to\input.png")) +$imgBase64 = [System.Convert]::ToBase64String($imgBytes) + +$tmpFile = "$env:TEMP\request.json" +$prompt = "YOUR_EDIT_INSTRUCTIONS_HERE" +$json = @" +{"model":"doubao-seedream-5-0-260128","prompt":"$prompt","image":["data:image/png;base64,$imgBase64"],"size":"2k","sequential_image_generation":"disabled","response_format":"url","stream":false,"watermark":false} +"@ +$sw = [System.IO.StreamWriter]::new($tmpFile, $false, (New-Object System.Text.UTF8Encoding $false)) +$sw.Write($json); $sw.Close() + +$response = curl.exe -s -X POST https://ark.cn-beijing.volces.com/api/v3/images/generations ` + -H "Content-Type: application/json" ` + -H "Authorization: Bearer ark-119a37ed-f123-42fc-aea6-b38d47d47fc0-f7ddf" ` + -d "@$tmpFile" | ConvertFrom-Json + +$imageUrl = $response.data[0].url +$outputPath = Join-Path (Get-Location) "output-name.png" +curl.exe -s -o $outputPath $imageUrl +Write-Output $outputPath +``` + +### 多图融合 + +```json +{ + "model": "doubao-seedream-5-0-260128", + "prompt": "把图1的人物穿上图2的衣服，站在图3的场景中", + "image": ["url1", "url2", "url3"], + "size": "2k", + "sequential_image_generation": "disabled", + "response_format": "url", + "stream": false, + "watermark": false +} +``` + +### 批量生成（最多15张） + +```json +{ + "model": "doubao-seedream-5-0-260128", + "prompt": "一个女孩和她的布偶牛在过山车上，分别呈现早晨、中午、傍晚的场景", + "sequential_image_generation": "auto", + "sequential_image_generation_options": { "max_images": 3 }, + "size": "2k", + "response_format": "url", + "stream": false, + "watermark": false +} +``` + +### 豆包参数参考 + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `model` | string | 是 | `doubao-seedream-5-0-260128`（默认）或 `doubao-seededit-3-0-i2i`（精确编辑） | +| `prompt` | string | 是 | 文本提示词，最多~300中文字或~600英文词 | +| `image` | string[] | 否 | 参考图片URL或Base64（`data:image/png;base64,...`），最多14张 | +| `size` | string | 否 | `2k`（默认）、`3k`、`4k` 或 `WIDTHxHEIGHT`（如`2048x1024`），必须小写 | +| `response_format` | string | 否 | `url`（下载链接，24h有效）或 `b64_json` | +| `sequential_image_generation` | string | 否 | `disabled`（默认，单图）或 `auto`（模型决定批量数） | +| `sequential_image_generation_options` | object | 否 | `{ "max_images": N }` N为1-15，仅auto模式 | +| `stream` | boolean | 否 | `false`（等待全部）或 `true`（逐张返回） | +| `watermark` | boolean | 否 | 添加"AI Generated"水印，默认`false` | +| `guidance_scale` | float | 否 | 文本遵循度(CFG)，范围[1,10]，仅seededit-3-0-i2i | +| `seed` | int32 | 否 | 可复现种子，仅seededit-3-0-i2i | + +### 豆包尺寸指南 + +| 别名 | 近似分辨率 | 适用场景 | +|---|---|---| +| `2k` | ~2048px | **默认** — 质量与速度平衡 | +| `3k` | ~3072px | 高质量，产品图 | +| `4k` | ~4096px | 最终生产质量 | +| `WIDTHxHEIGHT` | 自定义 | 如`2048x1024`宽幅横幅 | + +像素约束：两个维度必须在[1280, 4096]，最大3:1宽高比。 + +### 豆包提示词技巧 + +- **描述场景**: 主体、动作、环境、氛围 +- **指定风格**: "电影大片感"、"水彩画风"、"赛博朋克"、"oc渲染"、"超现实主义" +- **质量关键词**: "光线追踪"、"景深"、"极致的光影"、"动态模糊" +- **编辑指令**: "把背景换成海滩"、"移除画面中的人物"、"将风格改为水彩画" +- **中文提示词原生支持** — 无需翻译为英文 + +### Windows注意事项 + +| 问题 | 解决方案 | +|---|---| +| PowerShell 5.1给JSON加UTF-8 BOM | **不要**用`Set-Content`或`[System.Text.Encoding]::UTF8`，用`[System.IO.StreamWriter]::new($path, $false, (New-Object System.Text.UTF8Encoding $false))` | +| PowerShell破坏curl中的`"` | **始终**写JSON到临时文件，用`-d "@$tmpFile"` | +| curl别名冲突 | 用`curl.exe`而非`curl` | +| 续行符 | 用反引号`` ` `` | + +### 豆包错误处理 + +- **401**: API Key无效 — 检查Authorization头 +- **400**: 请求错误 — 检查提示词长度、图片格式、尺寸值 +- **429**: 限流 — 等待后重试 +- **500**: 服务器错误 — 稍后重试 + +### 精确编辑模型 + +需要精细编辑时，`doubao-seededit-3-0-i2i`提供额外控制： + +```json +{ + "model": "doubao-seededit-3-0-i2i", + "prompt": "Change the dress color to red", + "image": ["data:image/png;base64,..."], + "guidance_scale": 5.5, + "seed": 42, + "size": "adaptive", + "response_format": "url", + "watermark": false +} +``` + +--- + +## 引擎2：阿里云万相2.7 + +使用阿里云百炼 **wan2.7-image-pro** 模型，支持文生图、图生图、图片编辑。 + +### 前提条件 环境变量 `DASHSCOPE_API_KEY` 已配置（默认使用内置Key） -## 基本用法 +### 基本用法 ```bash python wan_image_edit.py <提示词> <输入图片> [输出路径] [尺寸] @@ -23,7 +199,7 @@ python wan_image_edit.py <提示词> <输入图片> [输出路径] [尺寸] - `输出路径`: 输出文件名（可选，默认 wan_output.png） - `尺寸`: 1K 或 2K（可选，默认 2K） -## 示例 +### 示例 ```bash # 白底产品图 @@ -32,50 +208,36 @@ python wan_image_edit.py "keep the product, pure white background, professional # 场景图 python wan_image_edit.py "place product on modern desk, cozy home office" "product.png" "scene.png" -# 高性能风格 -python wan_image_edit.py "cyberpunk gaming setup with RGB lights, benchmark scores" "product.png" "gaming.png" "2K" - # 文生图（无输入图片） python wan_image_edit.py "futuristic NAS server in data center" "" "t2i.png" - -# 直接在图上添加文字 -python wan_image_edit.py "keep product, add bold text: 千兆高速传输, professional tech background" "product.png" "with_text.png" ``` -## 可用尺寸 +### 万相2.7可用尺寸 | 尺寸 | 分辨率 | 适用场景 | |-----|-------|---------| | 1K | 1024x1024 | 快速预览、轮播图 | | 2K | 2048x2048 | 主图、海报（推荐）| -## 代码调用 +--- -```python -from wan_image_edit import wan_image_edit +## 引擎选择建议 -# 基础调用 -wan_image_edit( - prompt="keep the product, white background", - image_path="product.png", - output_path="output.png", - size="2K" -) +| 场景 | 推荐引擎 | 原因 | +|-----|---------|------| +| 电商产品主图 | 豆包万相 | 中文提示词支持好，风格丰富 | +| 场景图/氛围图 | 豆包万相 | 高质量渲染，支持多种风格 | +| 精细图片编辑 | 豆包万相(seededit) | 专用编辑模型，精确控制 | +| 多图融合 | 豆包万相 | 原生支持最多14图融合 | +| 批量生成 | 豆包万相 | 一次请求最多15张 | +| 快速产品抠图/换背景 | 万相2.7 | Python脚本调用便捷 | -# 批量生成多张 -styles = [ - ("white bg", "product.png", "white.png"), - ("cyberpunk", "product.png", "cyber.png"), - ("data center", "product.png", "datacenter.png"), -] -for prompt, img, out in styles: - wan_image_edit(prompt, img, out) -``` +--- -## 提示词技巧 +## 输出规范 -- **保持产品**: "keep the product", "retain the original product" -- **背景**: "white background", "modern office", "data center" -- **风格**: "cyberpunk", "minimalist", "professional" -- **氛围**: "dramatic lighting", "warm tones", "neon lights" -- **添加文字**: "add bold text: 千兆高速传输" \ No newline at end of file +- 保存图片到用户当前工作目录（或子目录） +- API返回的URL 24小时内有效 — 立即下载保存到本地 +- **不要回读图片** — 用markdown显示: `![image](/absolute/path/to/image.png)` +- 只使用**绝对路径** +- 不要在对话中重复路径 \ No newline at end of file diff --git a/.trae/skills/image-tools/references/doubao-api-reference.md b/.trae/skills/image-tools/references/doubao-api-reference.md new file mode 100644 index 0000000..f03f7d5 --- /dev/null +++ b/.trae/skills/image-tools/references/doubao-api-reference.md @@ -0,0 +1,76 @@ +# Volcengine Ark Image API Reference + +## Endpoint + +`POST https://ark.cn-beijing.volces.com/api/v3/images/generations` + +## Authentication + +``` +Authorization: Bearer ark-119a37ed-f123-42fc-aea6-b38d47d47fc0-f7ddf +``` + +## Response Format + +### Success Response (response_format: "url") + +```json +{ + "created": 1234567890, + "data": [ + { + "url": "https://...", + "revision": 0 + } + ] +} +``` + +### Success Response (response_format: "b64_json") + +```json +{ + "created": 1234567890, + "data": [ + { + "b64_json": "...", + "revision": 0 + } + ] +} +``` + +### Error Response + +```json +{ + "error": { + "code": "invalid_request_error", + "message": "..." + } +} +``` + +## Available Models + +| Model ID | Capabilities | Max Size | +|---|---|---| +| `doubao-seedream-5-0-260128` | Text-to-image, image-to-image, multi-image fusion, editing, batch | 2K | +| `doubao-seedream-4-5-t2i` | Text-to-image, image-to-image, multi-image fusion | 4K | +| `doubao-seedream-4-0-t2i` | Text-to-image, image-to-image, multi-image fusion | 4K | +| `doubao-seedream-5-0-lite-t2i` | Text-to-image, batch, web search | 3K | +| `doubao-seedream-3-0-t2i` | Text-to-image (with seed/guidance_scale) | 2K | +| `doubao-seededit-3-0-i2i` | Dedicated image editing (with seed/guidance_scale) | adaptive | + +## Image Input Formats + +- **URL**: Publicly accessible HTTP/HTTPS URL +- **Base64**: `data:image/;base64,` + - Format must be lowercase: `data:image/png;base64,...` (not `PNG`) + - Supported formats: png, jpeg, webp + +## Size Constraints + +- Pixel range: `[1280, 4096]` for both width and height +- Max aspect ratio: 3:1 (long edge to short edge) +- Custom size format: `"WIDTHxHEIGHT"` (e.g., `"2048x1024"`)