tongyi-image

name	tongyi-image
description	通过阿里云百炼 DashScope 生成 AI 图片 — 文生图、图像编辑、风格重绘、背景生成、画面扩展、涂鸦作画、电商套图。任务异步执行+轮询，成功后可自动下载到本地。
env_any	["DASHSCOPE_API_KEY"]

通义生图 / Tongyi Image

是什么 / What

输入一句中文/英文描述（可选参考图、风格、尺寸），输出一张或多张高清图片。 所有调用都是 DashScope 异步任务：先 POST 拿 task_id，再轮询 GET task_status， 就绪后下载图片 URL（24h 过期，自动落盘到 data_dir/images/）。

何时用 / When

• 用户描述了一个画面想法，想要参考图 / 海报 / 头图
• 用户已有一张图，想换风格、改局部、补背景、扩画面
• 用户在做电商，想一键给同一商品出多场景图
• 不要用于: 视频生成（用 seedance-video skill）；需要精确蒙版的局部修图（用 image-edit 插件）

工具 / Tools

• tongyi_image_create({prompt, model?, size?, negative_prompt?, n?})
• tongyi_image_status({task_id})
• tongyi_image_list({limit?})

模式 / Modes

mode	描述	主流模型
text2img	纯文本生图	wan27-pro, qwen-pro
img_edit	参考图改写（无蒙版）	wan27-edit
style_repaint	把一张人像换成预设风格	wanx-style-repaint
bg_generation	给商品/前景图生成新背景	wanx-background-generation
outpainting	画面外扩 / 改变长宽比	wanx-outpainting
sketch2img	涂鸦/线稿成图	wanx-sketch-to-image
ecommerce	电商套图（一组商品场景图）	wanx-ecommerce

流程 / Pipeline

prompt + (可选 ref image) → DashScope POST → task_id →
  poll loop（默认 10s）→ status==SUCCEEDED →
    extract image URLs → (可选 auto_download) → 落盘 + 广播 task_update

Quality Gates (G1–G3)

Gate	检查内容	通过条件
G1	DashScope API Key 已配置	await tm.get_config("dashscope_api_key") 非空
G2	upload 路径在插件 data_dir 内（防遍历）	add_upload_preview_route 已注册 + path.relative_to(base) OK
G3	task 异常用日志 + UI broadcast 兜底	_broadcast_update(task_id, "failed") + error_message 落库

Trust Hooks（你怎么知道我没乱花钱 / 偷数据）

信任点	怎么自查
钱花在哪 / Cost	DashScope API 唯一调用方；本插件不引入第三方计费
数据流向 / Data	上传图先存 data_dir/uploads/，仅作为 base64 发给百炼
出错怎么办 / Errors	全部异常落库 error_message，UI 通过 task_update 推送
远程依赖 / Network	仅 https://dashscope.aliyuncs.com/；无遥测

已知坑 / Known Pitfalls

• API Key 没填: 所有请求 502 → UI 提示去 Settings 配置
• DashScope content moderation: 敏感词命中会直接 fail，不可重试 — 改 prompt 重试
• 图片 URL 24h 过期: 必须开 auto_download=true（默认开）才能离线复用
• 长时间任务排队: 默认 poll 间隔 10s，繁忙时段可能等几分钟 — 不会卡 UI
• 大批量电商套图: 一次提交 6+ 场景会显著增加成本 — 先用 1 张试效果
• 路径遍历攻击: 已通过 SDK add_upload_preview_route 兜底（relative_to(base)）

安全升级 (Sprint 1) / Hardening Notes

• update_task SQL 列名走白名单，杜绝注入（见 tongyi_task_manager._UPDATABLE_COLUMNS）
• on_unload 改为 async，await _poll_task / _client.close() / _tm.close()，避免 Windows WinError 32
• 所有 fire-and-forget 后台任务改用 api.spawn_task(...)，host 在 unload 时统一 cancel + drain
• /storage/stats 走 SDK collect_storage_stats（asyncio.to_thread + max_files 上限），UI 不再卡顿
• POST /upload 响应新增 url 字段（build_preview_url），UI 端可渐进迁移到可访问 URL（见 issue #479）

storyboard 一键投喂 / Storyboard Bridge (Sprint 2)

storyboard 插件新增 GET /api/plugins/storyboard/tasks/{task_id}/export-tongyi.json， 把分镜直接转成本插件可消费的请求体数组：

# 拿到分镜 → 一键批量出图
curl -s localhost:8000/api/plugins/storyboard/tasks/<sb_id>/export-tongyi.json \
  | jq -c '.post_examples[]' \
  | while read -r row; do
      body=$(echo "$row" | jq -c '.body')
      curl -s -X POST localhost:8000/api/plugins/tongyi-image/tasks \
        -H 'content-type: application/json' -d "$body"
    done

prompt = visual + 构图 + 风格（省去音效/台词），size 默认 1024*1024， n 自动 clamp 到 1..4，body 字段名与 CreateTaskBody 完全一致 — 测试断言保护， 后续如重命名会立即报错。