butubb/MediaCrawler
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP
Deploy VitePress site to Pages / build (push) Canceled after 0s
Details
Deploy VitePress site to Pages / Deploy (push) Canceled after 0s
Details

Browse Source 
移植自 mac-agent-os 的 mediacrawler_adapter：不起子进程、不开页面，用浏览器里那份
登录态直接调抖音 Web 接口。产物键名照抄 store/douyin，所以 ingest 那条链路一个字不用改。

**目前能用的（真环境实测，非推断）**：

    profile/other : 200, 7075 字节  —— 博主主页指标（粉丝/获赞/作品数/昵称）
    aweme/detail  : 200, 45425 字节 —— 单条作品详情（含点赞/评论/收藏/分享）

**目前不能用的：作品列表 `aweme/post`。** 两个互相独立的原因：
  1. 这个接口被抖音单独升级成了真校验：不带 x-tt-argus 回 403「Uifid Not Found」，
     带上 dummy 值回 200 + **空 body**。也就是说「头在不在」骗得过，「真校验」过不了。
     同一套头打 profile/other 和 aweme/detail 都是通的 —— 抖音是挑着接口加保护的，
     挑中的恰好是「批量拉作品列表」这个最敏感的动作。
  2. 改走页面截获也不行：CDP 浏览器打开博主主页会落到「验证码中间页」（当天大量探测的
     代价，过几小时要重测）。

  所以现在的边界是：**已知作品的指标刷新能做，自动发现新作品做不了**。

**排查中控住变量后得到的两条事实**（都写进注释了）：
  · `Accept` / `Accept-Language` / `Referer` 才是主页接口能返回真数据的原因 —— 只有
    UA+client hints+Cookie 时是 200 但仅 121 字节的空壳，补上这三个头变 7074 字节。
    （我先前猜的 sec-ch-ua 不是关键。）
  · 因此 UA 与 client hints 必须**成套地取自同一个浏览器**，所以 BrowserIdentity 一次
    从 CDP 取齐 cookie + UA + hints，而不是各自写死。

「200 + 空 body 必须当场报错」也是刻意写死的：放过去它会在下游变成「这个博主没作品」，
把一次失败伪装成一条正常结果 —— 爬虫那条路正是这么栽的，还被翻译成「账号被封」。

测试 +11：cookie 解析、请求头成套性（含 uifid 缺失/回退）、产物键名与 store 对齐、
以及 _get 的三条失败路径（空 body / 403 带网关原话 / 正常返回）。
This commit is contained in:
butubb
2026-10-10 17:12:25 +08:00
parent 21ff01b894
commit 2112c1a870
1601 changed files with 367425 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mac-agent-os-main/05_tools/09_ave/PLANS/API_STRATEGY_REPORT.md
+179
View File
@@ -0,0 +1,179 @@
# AVE 视频工厂 AI 生成 API 战略报告
> **版本**: v1.0
> **创建**: 2026-05-15
> **范围**: 文生视频、图生视频、文生图、图生图、AI漫剧全品类
> **目标**: 为 AVE 视频工厂找到成本最低、可集成性最强的 AI 素材生成方案
---
## 一、核心结论
### 1.1 最佳推荐排序
| 排名 | 方案 | 成本(5s 1080p) | 适合场景 | 推荐理由 |
|:----:|:-----|:--------------:|:---------|:---------|
| 🥇 | **Kling 可灵 API** | **¥1.45** (≈$0.20) | 主力批量生产 | 性价比之王，质量分89.8，月送50次免费 |
| 🥈 | **即梦网页版会员** | **¥0.22~0.37** | 日常高频使用 | 成本最低，VIP 1080p，Peekaboo 自动化中 |
| 🥉 | **腾讯云混元(buddy-cloud)** | **¥1.80 (720p)** | 即时可用 | 已有集成，无需额外注册 |
| 4 | **通义万相 Wan2.6** | **¥5.00** (¥1/s) | 阿里系生态 | 90天免费50s，文生图¥0.2/张 |
| 5 | **Runway Gen-4.5** | **¥2.90** | 专业级稳定 | 支持4K，延迟最稳定 |
| 6 | **Dreamina CLI** | **¥0.37 (720p)** | 轻量调用 | 已安装，但VIP模型不支持 |
### 1.2 成本对比全景 (5秒视频，折合人民币)
```
Kling API(1.45) ||||||||
Buddy-cloud 720p(1.80) |||||||||
Runway(2.90) |||||||||||||||||
Sora 2(3.63) ||||||||||||||||||||
即梦API(4.00) ||||||||||||||||||||||
通义万相1080p(5.00) |||||||||||||||||||||||||
Sora 2 Pro(18.15) ||||||||||||||||||||||||||||||||||||||||||
即梦网页版会员(0.22-0.37) |||
```
---
## 二、AI 视频生成 API 详细对比
### 2.1 国际平台 (USD)
| 平台 | 模型 | 计费方式 | 5s/1080p成本 | 最大时长 | 最高分辨率 | 性价比评分 |
|:-----|:-----|:---------|:------------:|:--------:|:----------:|:---------:|
| **Kling 2.1** | 可灵 | 按条 | **$0.20** | 10s | 1080p | ⭐⭐⭐⭐⭐ |
| Runway Gen-4.5 | Gen-4.5 | Credit | $0.40 | 16s | 4K | ⭐⭐⭐⭐ |
| Sora 2 Standard | Sora 2 | 按秒 $0.10/s | $0.50 | 20s | 1080p | ⭐⭐⭐ |
| Sora 2 Pro | Sora 2 | 按秒 $0.50/s | $2.50 | 20s | 1080p | ⭐⭐ |
| Seedance 2.0 (即梦) | 即梦 | 分辨率×时长矩阵 | $0.55 | **30s** | **4K** | ⭐⭐⭐ |
**免费额度**: Kling 每月50次免费；Runway 125 Credits；Sora 无
### 2.2 国内平台 (RMB)
| 平台 | 文生视频 | 图生视频 | 720p价格 | 1080p价格 | API接入方式 |
|:-----|:--------:|:--------:|:--------:|:---------:|:-----------|
| **阿里云通义万相 Wan2.6** | ✅ | ✅ | **¥0.6/s** | **¥1.0/s** | 百炼平台 |
| **腾讯云混元 (buddy-cloud)** | ✅ | ✅ | **¥0.36/s** (¥1.8/5s) | **¥0.72/s** (¥3.6/5s) | ⭐ **WorkBuddy内置** |
| **即梦 Seedance API** | ✅ | ✅ | $0.35/5s (≈¥2.5) | $0.55/5s (≈¥4.0) | 火山引擎 |
| **Kling 可灵 API (国内)** | ✅ | ✅ | **$0.20/5s (≈¥1.45)** | 同左 | klingapi.com |
| **Dreamina CLI** | ✅ | ✅ | 5积分/次 (≈¥0.37) | ❌ (VIP锁) | 命令行 |
**免费额度**:
- 通义万相: 开通90天内，文生图50张+视频50秒
- 腾讯云混元: 50积分 (首次开通)
- Kling: 每月50次免费
- 即梦网页版: 每日送积分
### 2.3 文生图 API
| 平台 | 价格 | 质量 | 接入 |
|:-----|:----:|:----:|:----|
| **阿里云通义万相 Wan2.6** | **¥0.2/张** | ⭐⭐⭐⭐ | 百炼 API |
| **腾讯云混元 (buddy-cloud)** | 按积分 | ⭐⭐⭐⭐ | **WorkBuddy内置** |
| **Dreamina CLI** | 1积分/张 ≈ ¥0.07 | ⭐⭐⭐⭐⭐ | CLI命令 |
| **即梦网页版** | 0.25积分/张 ≈ ¥0.02 | ⭐⭐⭐⭐⭐ | Peekaboo自动化 |
| **Midjourney** | $10-60/月 | ⭐⭐⭐⭐⭐ | Discord/API |
| **Stable Diffusion** | 免费/自部署 | ⭐⭐⭐⭐ | 本地 |
---
## 三、AI 漫剧/动画工具
### 3.1 专业漫剧平台
| 工具 | 价格 | 特点 | API可用 | 集成难度 |
|:-----|:----:|:------|:-------:|:--------:|
| **Vidu** | ¥0.42/s | **AI漫剧行业标杆**，画面一致性好 | ❌ 网页端 | 中 |
| **OiiOii** | ¥0.37/s | 剧本→角色→分镜→成片全流程 | ❌ 网页端 | 中 |
| **Liblib (哩布哩布)** | **¥0.18/s** | **性价比最高**，集成多模型 | ⚠️ 有限 | 低 |
| **可灵 3.0 Omni** | ¥0.43/s | 音画同出，口型同步 | ✅ API | **低** |
| **PixVerse V6** | ¥0.48/s | 海外用户超千万 | ✅ API | 低 |
### 3.2 AVE 漫剧集成方案
```
文案 → LLM分镜 → 角色一致性控制 → Kling/通义万相逐帧生成 →
FFmpeg合成 → 配音(CosyVoice) → BGM → final.mp4
```
关键点：**角色一致性** 是 AI 漫剧的难点，可灵和通义万相支持图生视频，可以用同一张角色图作为参考。
---
## 四、战略架构建议
### 4.1 三层管线 (Tiered Pipeline)
```
用户文案
│
[01_director_parser] ← oMLX 本地解析
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Tier 1: 免费 Tier 2: 批量 Tier 3: 高品质
────────── ──────────── ─────────────
Kling 50次/月 Kling API $0.20 通义万相1080p
通义万相50s 即梦网页版会员 Runway 4K
Dreamina积分 buddy-cloud Sora 2
│ │ │
└───────────────┼───────────────┘
▼
[material_producer]
AI素材 → 下载 → 缓存
│
[composer] Ken Burns + 字幕
│
final.mp4
```
### 4.2 推荐接入优先级
| 阶段 | 动作 | 成本 | 工作量 |
|:-----|:-----|:----:|:------|
| **P0 立即** | 集成 Kling API (性价比最高，有免费额度) | ¥1.45/段 | 1天 |
| **P0 立即** | 完成即梦网页版 Peekaboo 自动化 | ¥0.22/段 | 进行中 |
| **P1 本周** | 接入通义万相 Wan2.6 API (免费50s先跑通) | ¥0.6/s | 半天 |
| **P2 本月** | 集成 AI漫剧管线 (Vidu/OiiOii 调研) | ¥0.37-0.42/s | 2-3天 |
| **P3 储备** | 通义万相图生视频 + 角色一致性方案 | ¥0.6/s | 1天 |
### 4.3 AVE 现有能力 vs 待接入
```
当前 AVE 已有:
✅ CosyVoice TTS (人声)
✅ Wan2.2-S2V (数字人)
✅ Pexels (免费素材)
✅ FFmpeg (合成)
✅ oMLX (文案解析)
✅ 火山引擎 OmniHuman (数字人备用)
下一步可接入:
🔲 Kling API (文生视频主力)
🔲 即梦网页版 (文生视频备用, VIP 1080p)
🔲 通义万相 Wan2.6 (文生图+文生视频, 阿里生态)
🔲 AI漫剧管线 (内容扩展)
```
---
## 五、总结
### 最低成本方案
如果是**日常生产口播视频素材**，按成本排序：
| 方案 | 一期12段素材成本 | 年费估算 |
|:-----|:---------------:|:--------:|
| ① 即梦网页版会员 ¥239/月 | **3.6元** | ¥2,868 |
| ② Kling API ($0.20/段) | **17.4元** (≈$2.4) | ¥6,960 (≈$960) |
| ③ 通义万相 720p (¥0.6/s) | 36元 | ¥13,140 |
| ④ 腾讯云混元 720p (¥1.8/段) | **21.6元** | ¥7,884 |
### 最终建议
1. **短期**: 即梦网页版 Peekaboo 自动化继续搞完，成本最低
2. **中期**: 接入 **Kling API** — 国际性价比之王，每月50次免费额度
3. **扩展**: 通义万相接入（文生图¥0.2/张，做封面和素材）
4. **漫剧**: 调研 Vidu/OiiOii，作为内容形式的扩展方向
mac-agent-os-main/05_tools/09_ave/PLANS/AVE_IMPLEMENTATION_PLAN.md
+550
View File
@@ -0,0 +1,550 @@
# AVE v2.0 落地实施计划
> AudioScore Video Engine — 智能体可调用的自动化视频编排引擎
>
> **版本**: v1.0 (规划)
> **创建**: 2026-05-04
> **负责人**: ghai / Claw
> **状态**: 📋 规划阶段
---
## 一、项目概览
### 1.1 这是什么
AVE v2.0 是一个以**双轨音频锚点**为时间轴，通过**导演脚本**精确控制视听元素的自动化视频编排引擎。它接收结构化YAML指令，输出最终视频文件。
### 1.2 核心能力
| 能力 | 说明 | 技术方案 |
|------|------|---------|
| 情绪化人声合成 | 一个音色演绎多种情绪 | 豆包语音 2.0 (火山引擎) |
| 背景音乐生成 | 氛围化配乐，风格可控 | ACE-Step 1.5 / MusicGen (云GPU) |
| 数字人出镜 | 静态图→口播视频 | Wan2.2-S2V (通义万相 API) |
| 素材搜索 | 根据语义搜索视频素材 | Pexels API (免费) |
| 导演脚本 | 文案→结构化YAML→视频 | 本地大模型解析 |
| 渲染合成 | 多轨合成最终视频 | Remotion + FFmpeg |
### 1.3 系统架构图
```
用户文案
│
[01_director_parser]
大模型解析 → director_script.yaml
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
[02_voice] [03_bgm] [05_material]
豆包语音2.0 ACE-Step Pexels + Wan2.2
│ │ │
└─────────────┼─────────────┘
│
[04_anchor_extractor]
双轨锚点对齐
│
[06_composer]
Remotion + FFmpeg
│
final.mp4
```
---
## 二、目录结构与文件清单
### 2.1 工具模块路径
参照 `05_tools/` 现有模块的 `TOOL.md + scripts/` 结构：
```
~/workbuddy-agent-os/agent-sync/
├── 05_tools/
│ └── 09_ave/ ← 工具模块根目录
│ ├── TOOL.md ← 工具说明文档 (必须)
│ ├── install.sh ← 一键安装脚本 (可选)
│ ├── requirements.txt.pip ← Python 依赖
│ ├── config.yaml ← API 密钥/默认参数配置模板
│ │
│ ├── scripts/ ← 核心脚本目录
│ │ ├── __init__.py
│ │ ├── main.py ← 统一 CLI 入口
│ │ │
│ │ ├── 01_director_parser/
│ │ │ ├── __init__.py
│ │ │ ├── parser.py ← 文案 → director_script.yaml
│ │ │ └── schemas.py ← YAML 结构校验
│ │ │
│ │ ├── 02_voice_synthesizer/
│ │ │ ├── __init__.py
│ │ │ ├── volcano.py ← 豆包语音 2.0 适配器
│ │ │ └── aliyun.py ← CosyVoice 备用适配器
│ │ │
│ │ ├── 03_bgm_generator/
│ │ │ ├── __init__.py
│ │ │ ├── ace_step.py ← ACE-Step 1.5 适配器
│ │ │ └── suno.py ← Suno API 备用适配器
│ │ │
│ │ ├── 04_anchor_extractor/
│ │ │ ├── __init__.py
│ │ │ └── extractor.py ← librosa 锚点提取
│ │ │
│ │ ├── 05_material_producer/
│ │ │ ├── __init__.py
│ │ │ ├── pexels.py ← Pexels 搜索
│ │ │ ├── wan2_2.py ← Wan2.2-S2V 适配器
│ │ │ └── fallback.py ← 本地素材回落
│ │ │
│ │ ├── 06_composer/
│ │ │ ├── __init__.py
│ │ │ ├── remotion.py ← Remotion 项目生成
│ │ │ └── ffmpeg.py ← FFmpeg 后处理
│ │ │
│ │ ├── 07_service_layer/
│ │ │ ├── __init__.py
│ │ │ ├── api.py ← FastAPI 服务
│ │ │ └── skill_bridge.py ← WorkBuddy 技能对接
│ │ │
│ │ └── lib/ ← 通用工具库
│ │ ├── __init__.py
│ │ ├── config.py ← 配置加载
│ │ ├── cache.py ← 素材/结果缓存
│ │ └── logger.py ← 日志
│ │
│ └── assets/ ← 模板/参考资源
│ ├── director_template.yaml ← 导演脚本模板
│ └── demo_scripts/ ← 测试脚本集
│
├── 02_skills/
│ └── ave/ ← WorkBuddy 技能
│ ├── SKILL.md ← 技能定义
│ └── reference/ ← 技能参考文档
│ └── director_schemas.md
│
└── agent-local/
└── tools/
└── ave/ ← 本机数据（不同步）
├── config/
│ └── local.yaml ← 本地 API 密钥等敏感配置
├── cache/
│ ├── materials/ ← 素材缓存
│ └── outputs/ ← 渲染缓存
└── templates/
└── remotion/ ← Remotion 项目模板
```
### 2.2 核心文件清单
| 编号 | 文件 | 功能 | 优先级 |
|------|------|------|--------|
| P0 | `09_ave/TOOL.md` | 工具说明文档 | ⭐ 必须 |
| P0 | `09_ave/scripts/main.py` | CLI 入口 | ⭐ 必须 |
| P0 | `09_ave/scripts/01_director_parser/parser.py` | 文案解析 | ⭐ 必须 |
| P0 | `09_ave/scripts/02_voice_synthesizer/volcano.py` | 豆包语音 | ⭐ 必须 |
| P0 | `09_ave/scripts/05_material_producer/pexels.py` | 素材搜索 | ⭐ 必须 |
| P0 | `09_ave/scripts/06_composer/ffmpeg.py` | 合成 | ⭐ 必须 |
| P1 | `09_ave/scripts/03_bgm_generator/ace_step.py` | 背景音乐 | 建议 |
| P1 | `09_ave/scripts/04_anchor_extractor/extractor.py` | 锚点提取 | 建议 |
| P2 | `09_ave/scripts/05_material_producer/wan2_2.py` | 数字人 | 可选 |
| P2 | `09_ave/scripts/07_service_layer/api.py` | FastAPI 服务 | 可选 |
| P2 | `02_skills/ave/SKILL.md` | WorkBuddy 技能 | 可选 |
---
## 三、实施阶段（分4阶段推进）
### 阶段 1：基础设施（1天）
**目标**：目录结构搭建 + API 注册 + 配置就绪
```
任务清单:
☐ 创建 09_ave/ 完整目录结构
☐ 创建 agent-local/tools/ave/config/ 目录
☐ 注册火山引擎豆包语音 2.0 → 获取 API Key + App ID + Access Token
☐ 注册阿里云百炼 → 获取 API Key
☐ 注册 Pexels → 获取 API Key
☐ 编写 config.yaml 模板
☐ 编写 local.yaml（本地敏感配置）
☐ 编写 install.sh 安装脚本
☐ 编写 TOOL.md 工具说明
☐ 提交到 Git: git add, commit, push
```
**产出**：
- 可 `git clone` 后在目标机器 `bash install.sh` 一键就绪
- agentos upgrade 能识别并检查 09_ave 模块
### 阶段 2：核心链路 MVP（2-3天）
**目标**：跑通 文案→人声→素材→合成 的可用闭环
**任务清单**：
**02_voice_synthesizer (半天)**
```
☐ 实现 volcano.py 基础 TTS 调用
☐ 测试: python main.py voice --text "测试" --output test.wav
☐ 上传音色样本 → 获取 speaker_id
☐ 实现情感指令参数: emotion, speed, pitch
☐ 实现 CosyVoice 备用适配器
```
**05_material_producer (半天)**
```
☐ 实现 pexels.py 搜索+下载
☐ 实现回退策略: search → fallback cache
☐ 测试: python main.py material --search "sunset beach"
```
**01_director_parser (半天)**
```
☐ 实现 schemas.py YAML 结构校验 (Pydantic)
☐ 实现 parser.py 文案 → YAML
☐ 编写 director_template.yaml
☐ 测试: python main.py parse --script demo.txt
```
**06_composer (半天)**
```
☐ 实现 ffmpeg.py 音视频合成
☐ 实现字幕叠加 (ass/srt 字幕)
☐ 测试: python main.py compose --voice voice.wav --material clips/
```
**MVP 集成测试**
```
☐ 用一个小笑话脚本跑通完整链路
☐ 产出第一个 final.mp4（纯人声+素材画面）
```
### 阶段 3：品质提升（1-2天）
**目标**：加入背景音乐 + 锚点对齐 → 多轨精准编排
**任务清单**：
**03_bgm_generator**
```
☐ 调研 ACE-Step 1.5 部署方案 (云端 GPU)
☐ 或实现 Suno API 备用适配器
☐ 实现 ace_step.py → bgm.wav
```
**04_anchor_extractor**
```
☐ 实现 extractor.py (librosa 节奏检测)
☐ 实现人声字级锚点: word_timestamps → anchors.json
☐ 实现 BGM 段落锚点: section_boundaries
```
**01_director_parser 升级**
```
☐ 支持完整的导演脚本模板 (bgm_section, camera, avatar 等字段)
```
**06_composer 升级**
```
☐ 双轨混音: voice.wav + bgm.wav → mixed_audio.wav
☐ 基于锚点对齐画面切换
☐ 支持分段渲染 (3分钟以上视频)
```
### 阶段 4：数字人 + 技能封装（1天）
**目标**：数字人出镜 + 作为 WorkBuddy 技能可调用
**任务清单**：
**05_material_producer 升级**
```
☐ 实现 wan2_2.py (通义万相 S2V)
☐ 实现 detect 图片合规检查
☐ 实现异步任务轮询
☐ 回落策略: detect失败 → 重试 → 跳过数字人
```
**07_service_layer**
```
☐ FastAPI 服务: POST /ave/generate
☐ 任务队列 + 进度轮询
☐ 错误处理与重试逻辑
```
**02_skills/ave/SKILL.md**
```
☐ 技能触发词: 视频、剪辑、生成视频
☐ 输入: 文案文本 + 风格标签
☐ 流程: 调用大模型 → 生成 YAML → 调用 AVE API
☐ 输出: 返回 final.mp4 本地路径
```
---
## 四、API 注册清单与成本
### 4.1 必须注册的服务
| 服务 | 用途 | 注册步骤 | 预计耗时 |
|------|------|---------|---------|
| **火山引擎** | 豆包语音 2.0 | 注册→实名→ARK模型服务→创建API Key | 30min |
| **阿里云百炼** | Wan2.2-S2V + CosyVoice | 注册→实名→开通服务→创建API Key | 20min |
| **Pexels** | 素材搜索 | 注册→API Dashboard→创建Application | 10min |
### 4.2 各服务凭证清单
```
agent-local/tools/ave/config/local.yaml：
# 火山引擎 (豆包语音 2.0)
volcano:
api_key: "sk-xxx" # ARK → API Key 管理
app_id: "xxx" # 语音控制台 → App ID
access_token: "xxx" # 语音控制台 → Access Token
speaker_id: "xxx" # 声音复刻 → 训练后获取
tts_model: "volcano_tts_2.0"
# 阿里云百炼
aliyun:
api_key: "sk-xxx" # 百炼 → API Key
wan_model: "wan2.2-s2v"
cosyvoice_model: "cosyvoice-v3.5-plus"
# Pexels
pexels:
api_key: "xxx" # Pexels API Dashboard
rate_limit: 200 # 请求/小时
```
### 4.3 月费预估 (日更一条3分钟视频)
| 模块 | 方案 | 月费 | 备注 |
|------|------|------|------|
| 人声合成 | 豆包语音 2.0 年付 | ~22元 | 首3月免费 |
| 数字人 | HeyGen Creator | ~211元 | 或用 Wan2.2 API 按量计费 |
| 背景音乐 | ACE-Step 云端GPU | ~2元 | 或 Suno API ~15-30元 |
| 素材搜索 | Pexels | 0元 | 免费 |
| 大模型调用 | DeepSeek / 通义千问 | ~1-10元 | 文案解析 |
| **合计** | | **~25-250元/月** | 取决于数字人方案 |
---
## 五、本地硬件需求
| 环节 | 部署位置 | 需求 | Mac 16G 可行性 |
|------|---------|------|---------------|
| 文案解析 | 云端 API | 无 | ✅ 直接调 |
| 人声合成 | 云端 API | 无 | ✅ 直接调 |
| 背景音乐 | 云端 GPU | 6GB+ 显存 | ❌ 需云 GPU |
| 数字人 | 云端 API | 无 | ✅ 直接调 |
| 素材搜索 | 云端 API | 无 | ✅ 直接调 |
| 锚点提取 | 本地 | CPU, librosa | ✅ |
| Remotion | 本地 | 16GB RAM | ✅ 3-5min 以内 |
| FFmpeg | 本地 | 无特殊要求 | ✅ 已装 |
> **结论**：Mac 16GB 内存足够处理 3 分钟内视频的本地环节。
> 仅背景音乐生成（ACE-Step）和 Remotion 渲染长视频需要云端或分段。
---
## 六、可能遇到的问题与应对
### 6.1 API 层问题
| 问题 | 概率 | 影响 | 应对方案 |
|------|------|------|---------|
| 豆包语音 API 认证失败 | 中 | 人声不可用 | 实现 CosyVoice 备选；local.yaml 三重凭证逐一校验 |
| Wan2.2-S2V 图片检测不通过 | 中 | 数字人无法生成 | 回落：跳过数字人片段，仅用素材画面+字幕 |
| Pexels 搜索无结果 | 高 | 素材缺失 | 3层回落：search → AI生成 → fallback_mood_videos |
| Pexels 速率限制 | 低 | 搜索被限 | 本地缓存层，已搜过的关键词不重复请求 |
| ACE-Step API 响应慢 | 中 | BGM 生成延迟 | 异步队列，不影响主流程；或改用 Suno API |
### 6.2 本地渲染问题
| 问题 | 概率 | 影响 | 应对方案 |
|------|------|------|---------|
| Remotion 内存不足 | 中 | 长视频渲染失败 | 分段渲染（3分钟/段）→ FFmpeg concat |
| FFmpeg 编码参数不合适 | 低 | 视频过大/质量差 | 预设多组编码参数，按场景切换 |
| 中间文件撑满磁盘 | 中 | 渲染中断 | 自动清理策略：渲染成功后删除 wav/clips |
| 中文字幕编码乱码 | 低 | 字幕显示异常 | 强制 UTF-8 + ASS 格式（非 SRT） |
### 6.3 编排逻辑问题
| 问题 | 概率 | 影响 | 应对方案 |
|------|------|------|---------|
| 语音与画面不同步 | 中 | 观感差 | 锚点容差机制：画面切换 ±0.2s |
| BGM 段落与文案不匹配 | 中 | 情绪割裂 | 导演脚本中明确 bgm_section 映射 |
| 多个素材时长与口播不匹配 | 高 | 画面空白/超长 | 自动拼接/裁剪素材到精确时长 |
| 大模型解析 YAML 格式错误 | 中 | 链路中断 | schemas.py 严格校验 + 自动修复 |
---
## 七、落地检查清单
### 7.1 基础设施
```
☐ 09_ave/ 目录创建完成
☐ TOOL.md 编写完成
☐ install.sh 编写完成
☐ agent-local/tools/ave/config/local.yaml 配置完成
☐ agentos upgrade 能识别 09_ave 模块
☐ git commit + push 到远程
```
### 7.2 MVP 链路
```
☐ 豆包语音 2.0 TTS 调用成功 → test.wav
☐ Pexels 搜索+下载成功 → material.mp4
☐ 文案→导演脚本 YAML 解析成功
☐ FFmpeg 音视频合成成功 → final.mp4
☐ 小笑话脚本跑通全链路
```
### 7.3 品质提升
```
☐ 背景音乐生成 (ACE-Step/Suno) → bgm.wav
☐ 双轨混音: voice + bgm
☐ 锚点提取 + 画面同步切换
☐ 分段渲染 + concat (长视频)
```
### 7.4 技能封装
```
☐ Wan2.2-S2V 数字人接入
☐ FastAPI 服务运行
☐ 02_skills/ave/SKILL.md 编写
☐ agentos sync 注册技能
☐ 技能调用测试: "帮我把这段文案做成视频"
```
---
## 八、技能定义草案
### 8.1 技能触发
**技能名**：`ave_video_director`
**触发词**：
- 视频、剪辑、生成视频、做视频
- 把这段话做成视频、AI 视频、自动剪辑
- director script、导演脚本
### 8.2 技能流程
```
用户输入文案
↓
01_director_parser: 大模型解析文案 → director_script.yaml
↓
02_voice_synthesizer: 逐段合成情绪化人声 → voice_segments/
↓
03_bgm_generator: 生成背景音乐 → bgm.wav (可选)
↓
04_anchor_extractor: 双轨锚点提取 → anchors.json
↓
05_material_producer: 并行搜索素材 → material_clips/
+ Wan2.2-S2V → avatar_clips/ (可选)
↓
06_composer: 编排渲染 + 编码 → final.mp4
↓
返回 final.mp4 路径给用户
```
### 8.3 用户输入示例
```bash
# 最简调用
python main.py generate --script "今天我们来聊聊..."
# 指定风格
python main.py generate --script demo.txt --style bedtime_story
# 高级：直接传导演脚本
python main.py compose --director-script script.yaml
```
---
## 九、首次启动步骤
```bash
# 1. 进入项目
cd ~/workbuddy-agent-os/agent-sync
# 2. 创建目录结构
mkdir -p 05_tools/09_ave/{scripts/{01_director_parser,02_voice_synthesizer,03_bgm_generator,04_anchor_extractor,05_material_producer/{pexels,wan2_2,fallback},06_composer,07_service_layer,lib},assets/demo_scripts}
mkdir -p agent-local/tools/ave/{config,cache/{materials,outputs},templates/remotion}
# 3. 配置 API 密钥 (参考 4.2 节)
# 编辑 agent-local/tools/ave/config/local.yaml
# 4. 安装 Python 依赖
pip install -r 05_tools/09_ave/requirements.txt.pip
# 5. 测试人声合成
python 05_tools/09_ave/scripts/main.py voice --text "你好，这是测试" --output test.wav
# 6. 跑通 MVP 闭环 (文案→人声→素材→合成)
python 05_tools/09_ave/scripts/main.py generate --script assets/demo_scripts/test_story.txt
# 7. 注册技能到 WorkBuddy
agentos sync
# 8. 提交到 Git
git add -A && git commit -m "feat: AVE v2.0 工具模块初始化" && git push
```
---
## 十、文件生成顺序（按依赖关系）
```
第1批 (并行，无依赖):
├── TOOL.md
├── config.yaml
├── requirements.txt.pip
├── lib/config.py
├── lib/cache.py
└── lib/logger.py
第2批 (无内部依赖):
├── 02_voice_synthesizer/volcano.py
├── 05_material_producer/pexels.py
└── 06_composer/ffmpeg.py
第3批 (依赖第2批):
├── 01_director_parser/parser.py
├── 01_director_parser/schemas.py
├── 02_voice_synthesizer/aliyun.py
└── 05_material_producer/fallback.py
第4批 (依赖第2+3批):
├── 03_bgm_generator/ace_step.py
├── 03_bgm_generator/suno.py
├── 04_anchor_extractor/extractor.py
└── 06_composer/remotion.py
第5批 (依赖前面全部):
├── main.py (CLI 入口)
├── 05_material_producer/wan2_2.py
├── 07_service_layer/api.py
└── 07_service_layer/skill_bridge.py
第6批 (最后):
├── 02_skills/ave/SKILL.md
├── install.sh
└── assets/director_template.yaml
```
---
**文档版本**: v1.0
**最后更新**: 2026-05-04
**下一步**: 开始阶段1 → 目录创建 + API 注册
mac-agent-os-main/05_tools/09_ave/PLANS/AVE_V2_ARCHITECTURE.md
+250
View File
@@ -0,0 +1,250 @@
# AVE v2.0 架构重构方案
> **版本**: v2.0 (草案)
> **创建**: 2026-05-15
> **核心理念**: 结果推导 — 从目标视频反推创作链路
> **知识基础**: AI视频提示词系统教科书（19章）+ 全网调研
---
## 一、核心差距分析
### 当前 AVE v1.x 的问题
| 维度 | 现状 | 目标 |
|:-----|:-----|:-----|
| **输入** | 仅支持 YAML 或 纯文本 | 支持小说/故事/RSS/链接等多种输入 |
| **分镜** | 直接 LLM 解析，无结构化分镜 | 四步工作流：场景拆分→镜头分配→风格定调→prompt生成 |
| **风格控制** | 无 | 统一的风格锚点 + 角色一致性 |
| **素材来源** | Pexels(单一) | Kling API / 百炼 / 即梦网页版 / Pexels / 数字人 多引擎 |
| **提示词** | 简单关键词搜索 | 五要素结构化提示词 + 正向/负向 + 权重控制 |
| **输出** | 1080p mp4 仅口播类型 | 支持宣传片/故事片/TVC/漫剧等多类型 |
---
## 二、五层架构设计
```
┌─────────────────────────────────────────────────────────┐
│ Layer 1: 输入层 (文案/小说/RSS/链接 → 结构化内容) │
├─────────────────────────────────────────────────────────┤
│ Layer 2: 分镜引擎 (LLM拆分场景→分配镜头→风格定调→生prompt) │
├─────────────────────────────────────────────────────────┤
│ Layer 3: 素材生产 (Kling/百炼/即梦/Pexels/数字人 多引擎) │
├─────────────────────────────────────────────────────────┤
│ Layer 4: 合成引擎 (TTS + KenBurns + BGM + 字幕 → mp4) │
├─────────────────────────────────────────────────────────┤
│ Layer 5: 输出层 (1080x1920.mp4 → 抖音/快手/视频号) │
└─────────────────────────────────────────────────────────┘
```
### Layer 1: 输入层
```
输入类型:
├─ YAML脚本 → 直接解析（当前已有）
├─ 纯文本文案 → LLM结构化（当前已有）
├─ 小说/故事 → 四步工作流：规范→分镜→场景表→完整脚本
├─ 网页链接/RSS → web_crawler采集 → 同上流程
└─ 已有视频 → 逆向解构（video-to-prompt）
```
### Layer 2: 分镜引擎（新增/重写）
替换当前的 `director_parser`，核心能力：
```
① LLM场景拆分
输入: 文案/故事
输出: 场景列表 (每个场景有时间/地点/氛围)
② 镜头分配
- 景别: 远景/全景/中景/特写/过肩
- 运镜: 推/拉/摇/移/跟/升降/环绕
- 时长: 3-15秒
③ 风格定调
- 风格锚点: "超写实电影感" / "水墨国风" / "扁平化3D"
- 色彩方案: 暖调/冷调/高饱和/低饱和
- 光照方案: 晨光/逆光/霓虹/戏剧光
④ Prompt生成（五要素）
= [风格] + [主体] + [环境] + [镜头运动] + [光线质感]
+ 负向词 + 权重控制
```
### Layer 3: 素材生产层（多引擎）
```
素材引擎路由:
├─ bailian_kling (主力) → ¥0.5-1/段, 45s, 已跑通
├─ kling_official → ¥1/段, 5min, 100积分
├─ jimeng_web (Peekaboo) → ¥0.3/段, 排队, 自动化中
├─ pexels_free → ¥0/段, 静态, 兜底
├─ wan2.2_digital_human → 数字人口播
└─ buddy_cloud → ¥1.8/段, 备用
```
### Layer 4: 合成引擎
```
人声合成: CosyVoice TTS + 字级时间戳
素材处理: Ken Burns (5种随机运镜)
背景音乐: 和弦垫音 / mlx-audiocraft / 即梦BGM
音量避让: duck_bgm (基于字级时间戳)
字幕: ASS 精确字幕
```
### Layer 5: 输出层
```
参数: 1080x1920, 30fps, h264, 8Mbps
格式: mp4
分发: 抖音 / 快手 / 视频号
```
---
## 三、提示词引擎设计（核心升级）
### 3.1 YAML 脚本格式升级
```yaml
meta:
project_id: "daoist_002"
style: "knowledge_lecture"
global_style_anchor: "水墨国风，工笔山水画质感" # 新增：全局风格
global_negative: "畸形、扭曲、面瘫、比例失调" # 新增：全局负向词
fps: 24 # 新增：帧率
voice:
provider: aliyun
emotion: 专业沉稳
bgm:
mood: calm
output:
resolution: 1080x1920
fps: 24
segments:
- id: 1
text: "上善若水，水善利万物而不争。——《道德经》"
duration_sec: 10
# 新增：镜头语言
camera: "镜头缓慢俯拍，从高空逐渐推进"
shot_type: "全景" # 远景/全景/中景/特写
# 新增：分镜描述（替代旧的 material.search）
material:
provider: bailian # 引擎选择
prompt_subject: "清澈溪水流过圆石，水滴晶莹"
prompt_environment: "云雾缭绕的深山幽谷"
prompt_lighting: "晨雾中的柔光"
subtitles: true
```
### 3.2 Prompt 组装逻辑
```python
def build_prompt(seg, global_style):
"""五要素+ 权重 + 负向词 组装"""
prompt = (
f"({global_style}:1.3), "
f"({seg['prompt_subject']}:1.5), "
f"({seg['prompt_environment']}:1.2), "
f"({seg['camera']}:1.1), "
f"({seg['prompt_lighting']}:1.0)"
)
negative = f"({global_negative}:1.5)"
return prompt, negative
```
### 3.3 四步分镜工作流
```
输入: "今天我要讲一个关于水的故事。上善若水..."
Step 1: LLM规范整理
→ [场景描述]深山溪谷 [人物动作]无 [对话]旁白
Step 2: 镜头规划
→ 需要 8 个镜头，分布: 全景(2) → 中景(3) → 特写(2) → 全景(1)
Step 3: 场景与角色表
→ 场景1: 深山溪谷，清晨，薄雾
→ 场景2: 水库大坝，午后，阳光强烈
Step 4: 生成完整分镜脚本
→ 镜号 | 景别 | 画面描述 | 旁白 | 场景 | 提示词
```
---
## 四、多内容类型支持
### 4.1 口播知识类（当前）
- 文案 → TTS → AI素材 → 合成
- 适用：道家金句、知识分享、观点输出
### 4.2 故事叙事类（新增）
- 小说/故事 → 四步分镜 → AI素材 → 合成
- 适用：民间故事、寓言、历史小故事
### 4.3 漫剧动画类（新增）
- 剧本 → 分镜 → 文生图(角色一致) → 图生视频 → 配音
- 适用：短剧、条漫转视频、AI漫剧
- 工具：Kling图生视频 + CosyVoice配音
### 4.4 宣传片类（新增）
- 产品介绍 → 分镜 → 风格化素材 → 合成
- 适用：品牌宣传、产品展示
---
## 五、实施路线图
| 阶段 | 内容 | 工作量 | 优先级 |
|:-----|:-----|:------|:-------|
| **P0 本周** | 分镜引擎: YAML升级 + prompt五要素组装 | 1天 | 🔴 |
| **P0 本周** | 接入百炼Kling API替换Pexels | 0.5天 | 🔴 |
| **P1 下周** | 四步分镜工作流(LLM驱动) + 场景/角色表 | 2天 | 🟡 |
| **P1 下周** | 即梦网页版Peekaboo自动化收尾 | 1天 | 🟡 |
| **P2 本月** | 故事输入 + 漫剧管线 | 3天 | 🟢 |
| **P2 本月** | 风格库 + 模板库建设 | 2天 | 🟢 |
| **P3 储备** | 宣传片类型 + 批量生产流水线 | 3天 | 🔵 |
---
## 六、知识体系关联
| AVE模块 | 关联教科书章节 | 知识点 |
|:--------|:--------------|:-------|
| director_parser | ch14 脚本转提示词 | 四步工作流 |
| material_producer | ch12 模型对比, ch13 工具工作流 | Kling/即梦/百炼接入 |
| composer | ch3 参数(ch4 分镜运镜), ch5 光影色彩 | 帧率/景别/光线设计 |
| bgm_generator | ch6 音频设计 | 音景/情绪音乐 |
| animate | ch7 微表情 | 动作拆解/表情控制 |
| strategy planner | ch1 核心逻辑, ch2 结果驱动 | 逆向推导方法论 |
| style library | ch8-11 多领域应用 | 电影/动漫/TVC/科幻风格 |
---
## 七、AVE 当前状态 vs 目标
```
当前 AVE:
输入 → 解析 → Pexels → TTS → 合成 → mp4
│ │ │ │ │
│ 仅YAML │ 无分镜 单一素材 │ CosyVoice 无BGM
目标 AVE v2.0:
输入 → 分镜引擎 → 多引擎素材 → TTS→BGM→合成 → mp4
│ │ │ │
│ 多类型 │ 四步分镜 │ Kling/即梦 │ 风格统一
│ 统一入口 │ 五要素prompt │ /Pexels/数字人 │ 全链路控制
```
> **核心理念总结**:
> 1. **结果推导** — 先想清楚最终画面，再反向拆解指令
> 2. **分镜先行** — 不做文字到视频的直接跳转，先做好分镜
> 3. **风格统一** — 全局风格锚点锁死一致性
> 4. **多引擎** — 根据成本/速度/质量动态选择素材来源
> 5. **持续迭代** — 每次只改5%进行AB测试
mac-agent-os-main/05_tools/09_ave/PLANS/AVE_V3_ARCHITECTURE.md
+351
View File
@@ -0,0 +1,351 @@
# AVE v3 全链路架构规划书
> 版本: v3.0-draft | 最后更新: 2026-05-15
> 基于全域调研（Kling API / HoloCine / BeatSync-Engine / LatentSync / Lights-Camera-Consistency）
---
## 一、现状总览
### 1.1 已实现能力 ✅
| 模块 | 功能 | 依赖 |
|:----|:----|:----:|
| **口播策略** | 文案→TTS→素材搜索→混音→字幕→合成 | CosyVoice + Pexels + FFmpeg |
| **卡点策略** | BGM→librosa节拍检测→素材→拍点切换→xfade | librosa + FFmpeg |
| **数字人策略** | 图片+音频→Wan2.2 OmniHuman 对口型/M1动作模仿 | 火山引擎 DreamActor |
| **Kling API 视频生成** | 文生视频/图生视频 (kling-v3) | 百炼 DashScope / Kling JWT |
| **剧本解析** | 文案→LLM分镜→YAML脚本 | LLM (模板/在线) |
| **锚点切换** | 静音检测驱动画面切换 | librosa |
| **BGM 避让** | 说话时压低BGM / 间隙恢复 | 字级时间戳驱动 |
| **字幕生成** | ASS字幕 (字级精确时间戳) | CosyVoice 时间戳 |
| **长视频分段** | >180s 自动分段 + concat | FFmpeg |
### 1.2 待增强能力 🔧
| 模块 | 现状 | 目标 |
|:----|:----|:-----|
| **变速卡点** | 仅固定速度 xfade 切换 | setpts + atempo 动态速度曲线 |
| **Kling LipSync** | 无集成 | 对接 fal.ai Kling LipSync API |
| **角色一致性** | 仅手动 prompt 工程 | 定妆照→参考图→批量生成的自动化管线 |
| **节拍检测** | 单层 beat_track | BeatSync-Engine 6阶段架构 (能量/结构/剪切策略) |
| **素材复用** | 无缓存系统 | 索引+缓存+标签体系 |
### 1.3 调研中能力 🔍
| 模块 | 来源 | 预计投入 |
|:----|:----|:--------:|
| **角色叙事策略** | HoloCine + Lights-Camera-Consistency | 2-3天 |
| **本地 Lip-Sync** | LatentSync v1.5 (字节跳动) | 0.5天部署 |
| **多场景批量生成** | Kling Image O1 多图融合 | 0.5天 |
| **数字资产索引** | 本地素材库 + 生成历史 | 1天 |
---
## 二、四策略管线详解
### 策略 A：口播（主路径，已成熟）
```
输入: 文案(.txt/.yaml)
流程:
文案 → [剧本解析] → YAML分镜脚本
→ [TTS: CosyVoice] → 带字级时间戳的人声 WAV
→ [素材搜索: Pexels] → 每段 2 个视频素材
→ [混音] → 人声 + BGM (可选避让)
→ [字幕: ASS] → 字级精确时间戳
→ [合成: FFmpeg] → 1080×1920 竖版视频
输出: final.mp4
```
**可直接执行的命令**: `python main.py video-factory --strategy 口播 --script script.yaml`
**增强方向**:
- 🔧 Kling LipSync 后处理: 合成后加一步 LipSync 让口型匹配
- 🧠 Kling AI 素材替代 Pexels: 图生视频生成更精准的场景素材
---
### 策略 B：卡点（已实现，需增强）
```
输入: BGM + 素材 (提供/Pexels搜索)
流程:
BGM → [节拍检测: librosa beat_track] → BPM + 拍点列表
→ [分组: N拍/组] → 每组时长 = N × (60/BPM)
→ [素材分配] → 循环取素材, 精确裁剪到组时长
→ [拼接: xfade] → 过渡拼接 (≤8组)
输出: beat_sync.mp4
```
**可直接执行的命令**: `python main.py video-factory --strategy 卡点 --bgm bgm.wav --search 风景`
**待增强**:
| 功能 | 来源 | 实现方式 |
|:----|:----|:--------|
| **变速卡点 (speed ramp)** | FFmpeg setpts | `setpts=(1/v)*PTS` + `atempo=v` 滤波器链 |
| **能量波切密度** | BeatSync-Engine | 高能段落更密集剪切, 低能段落保持 |
| **歌曲结构检测** | BeatSync-Engine | Intro→Verse→Chorus→Bridge→Outro 分区 |
| **视觉智能选素材** | BeatSync-Engine Qwen3-VL | 动作/美感/质量评分, 语义标签匹配 |
---
### 策略 C：数字人（已实现，分模式）
```
输入: 角色头像 + 文案/参考视频
流程 (对口型):
头像 + 文案 → [TTS: CosyVoice] → 音频
→ [Wan2.2 OmniHuman] → 带口型的数字人视频
输出: /tmp/ave_digital_human.mp4
流程 (动作模仿):
头像 + 参考视频 → [火山引擎 DreamActor M1] → 动作模仿视频
```
**可直接执行的命令**: `python main.py video-factory --strategy 数字人 --image photo.jpg --text "文案"`
**增强方向**:
- 🔧 Kling LipSync: 将 OmniHuman 换成 Kling LipSync (成本可控, 质量更高)
- 🔧 LatentSync v1.5 本地部署: 零成本, 中文优化
- 🧠 Wan2.2-S2V-14B: 远期替换, 音频→视频一步到位
---
### 策略 D：角色叙事（新策略，调研中）
```
输入: 定妆照 + 剧本(.yaml) → 多场景故事
流程:
[定妆照生成] → 角色 sheet / 参考图
→ [场景分解] → 剧本 → N个场景 + 每个场景的 Prompt
→ [批量生成] → Kling 图生视频 (每场景固定seed + 角色描述块)
→ [Temporal Bridge] → 上场景末帧 → 下场景首帧条件
→ [卡点合成] → BGM + 节拍 + 变速过渡
→ [LipSync] → 语音驱动口型
输出: story_final.mp4
```
**这个策略目前不存在**，需要从零构建。它吸收外部项目的核心思路：
| 来源 | 吸收点 | 实现方式 |
|:----|:-------|:--------|
| **HoloCine** (CVPR 2026) | 全局场景一致性, 稀疏注意力 | 用 Kling 的固定seed + 参考图模拟 |
| **Lights-Camera-Consistency** | Asset-First, Temporal Bridge, JSON蓝图 | 设计 AVE 剧本 YAML 扩展格式 |
| **Kling 3.0 参考图** | 单参考图锚定全片 | 定妆照→参考图→每场景生成 |
| **Grid Method** | 2x3 多视角 Character Sheet | 先生成定妆照网格, 再逐一入场景 |
---
## 三、数字资产管理体系
### 3.1 资产分类
| 资产类型 | 来源 | 存储位置 | 复用方式 |
|:---------|:----|:---------|:--------|
| **角色定妆照** | AI生成/用户提供 | `assets/characters/` | Kling 参考图 / IP-Adapter |
| **角色 LoRA** | CharForge 训练 | `assets/lora/` | ComfyUI / SD 生态 |
| **生成视频片段** | Kling API | `cache/generations/` | 剪辑拼接 / 素材库 |
| **Pexels 素材** | 网络搜索 | `cache/pexels/` | 各策略通用 |
| **BGM 文件** | Pixabay/生成 | `assets/bgm/` | 卡点 / 口播策略 |
| **剧本 YAML** | 用户编写/LLM生成 | `scripts/` | 版本管理 / 批量生产 |
| **历史输出** | 各策略成品 | `output/` | 回放 / 二次剪辑 |
| **LipSync 缓存** | LatentSync | `cache/lipsync/` | 重复使用 |
### 3.2 资产流转图（跨策略复用）
```
定妆照 ────→ 口播 (片头数字人)
│
├──────→ 数字人 (恒等保持)
│
└──────→ 角色叙事 (场景批量生成)
│
├──────→ 卡点 (混剪素材)
│
└──────→ 口播 (最终合成)
生成片段 ───→ 口播 (Pexels 素材替代)
│
├──────→ 卡点 (素材复用)
│
└──────→ 素材缓存 → 下一次复用
BGM ─────→ 口播 / 卡点 / 角色叙事 (通用)
```
### 3.3 资产索引建议
当前没有素材索引系统。建议新增 `scripts/asset_manager/` 模块：
```python
# asset_manager/index.py — 素材索引
class AssetIndex:
def index_pexels_cache(self, cache_dir): ...
def index_generations(self, gen_dir): ...
def search(self, tags: list[str], type: str): ...
def get_character_ref(self, char_id: str): ...
def get_lipsync_cache(self, audio_hash: str): ...
```
---
## 四、外部项目集成点矩阵
| 外部项目 | 类型 | 集成方式 | 优先级 | 投入 |
|:---------|:----|:---------|:-----:|:----:|
| **BeatSync-Engine** | 开源 | 6阶段架构 → 升级 AVE beat_sync.py | P1 | 0.5天 |
| **Kling LipSync (fal.ai)** | API | `scripts/composer/lipsync.py` 新增 | **P0** | 0.5天 |
| **LatentSync v1.5** | 开源 | `scripts/latentsync/` 本地推理 | P2 | 0.5天 |
| **HoloCine** | 论文 | 角色叙事策略的核心理论框架 | P2 | 2天 |
| **Lights-Camera-Consistency** | 论文 | JSON蓝图+Temporal Bridge 设计模式 | P2 | 1天 |
| **CharForge / IC-LoRA** | 开源 | LoRA 训练管线 | P3 | 1天 |
| **Grid Method (Midjourney社区)** | 方法论 | 定妆照生成 prompt 模板 | P0 | 0.2天 |
| **Wan2.2-S2V-14B** | 开源 | 远期替换数字人引擎 | P3 | 待定 |
| **MoneyPrinterTurbo** | 开源 | 参考其全自动化架构设计 | P3 | 0.3天 |
| **ComfyUI-vidflows** | 开源 | ComfyUI 内的多镜头叙事参考 | P3 | 0.3天 |
---
## 五、开发路线图（按优先级）
### Sprint 1 (P0, ~1天)
| 序号 | 任务 | 产出文件 | 来源 |
|:---:|:----|:---------|:-----|
| 1 | **定妆照生成** — 2x3 Grid Method Prompt 模板 + 自动化脚本 | `scripts/character_sheet.py` | Grid Method |
| 2 | **Kling LipSync 集成** — 新增 lipsync.py 模块 + CLI 子命令 | `scripts/composer/lipsync.py` | fal.ai |
| 3 | **角色描述块锁定** — Scene YAML 扩展 `character_ref` 字段 | `scripts/director_parser/schemas.py` | Lights-Camera |
### Sprint 2 (P1, ~1天)
| 序号 | 任务 | 产出文件 | 来源 |
|:---:|:----|:---------|:-----|
| 4 | **变速卡点引擎** — setpts + atempo 动态速度曲线 | `scripts/composer/speed_ramp.py` | BeatSync-Engine |
| 5 | **节拍检测升级** — 能量曲线+歌曲结构+剪切策略 (6阶段) | 改写 `scripts/composer/beat_sync.py` | BeatSync-Engine |
| 6 | **卡点+口播融合管线** — 口播场景中插入变速卡点过渡 | `scripts/composer/hybrid.py` | 新设计 |
### Sprint 3 (P2, ~2天)
| 序号 | 任务 | 产出文件 | 来源 |
|:---:|:----|:---------|:-----|
| 7 | **角色叙事策略** — 定妆照→场景批量生成→Temporal Bridge | `scripts/story_director/` | HoloCine + LCC |
| 8 | **本地 LatentSync 部署** — Docker / venv 部署 + AVE 集成 | `scripts/latentsync/` | 字节跳动 |
| 9 | **素材资产管理器** — 索引 + 缓存 + 标签 + 搜索 | `scripts/asset_manager/` | 新设计 |
### Sprint 4 (P3, 可选)
| 序号 | 任务 | 来源 |
|:---:|:----|:-----|
| 10 | LoRA 训练管线 (CharForge) | CharForge |
| 11 | Wan2.2-S2V-14B 本地部署 | Wan-AI |
| 12 | ComfyUI 工作流导出支持 | ComfyUI-vidflows |
---
## 六、关键决策记录
### 6.1 Kling LipSync vs. 本地 LatentSync
| 维度 | Kling LipSync (fal.ai) | LatentSync v1.5 (本地) |
|:----|:---------------------:|:---------------------:|
| 成本 | $0.014/5s (¥0.10/镜头) | 免费 |
| 质量 | ⭐⭐⭐⭐ 商业级 | ⭐⭐⭐⭐⭐ 中文优化 |
| 部署 | 零部署 (API调用) | 需 8GB VRAM + Docker |
| 延迟 | ~12分钟/次 | ~数秒~数十秒 |
| 适合 | **短期快速集成** | 中期大批量场景 |
**结论**：先上 Kling LipSync（P0，半天完成集成），LatentSync 作为 P2 储备。
### 6.2 角色叙事 vs. 增强现有策略
**不新建策略**，而是在现有策略上叠加 3 个增强层：
1. **定妆照层** — 所有策略共享（P0）
2. **角色锁定层** — 场景 YAML 加 character_ref 字段（P0）
3. **LipSync 层** — 合成后后处理（P0）
角色叙事策略本质上是"口播 + 定妆照 + 批量场景 + 卡点的融合产物"，不是独立的全新管线。
### 6.3 素材策略：Pexels vs. Kling AI vs. 即梦VIP
| 策略 | 成本 | 质量匹配度 | 可用性 |
|:----|:----:|:---------:|:------:|
| **Pexels** (当前) | 免费 (需API Key) | ⭐⭐ (通用素材, 不精确) | ✅ 稳定 |
| **Kling AI 图生视频** | ¥1/5s | ⭐⭐⭐⭐ (精准匹配) | ✅ AVE已集成 |
| **即梦VIP (网页版)** | ¥0.22-0.37/段 | ⭐⭐⭐⭐⭐ | 🚧 需Peekaboo |
| **即梦API** | ¥1-3/段 | ⭐⭐⭐⭐⭐ | 🚧 高级会员 |
**结论**：维持 Pexels 为默认素材源（免费），Kling AI 素材为按需增强（高精度场景），即梦为长期优化方向。
---
## 七、自纠偏：架构辩论
### 辩论 1：要不要做统一的"剧本→多场景→角色叙事"管线？
**正方**：这是用户需要的最终形态——输入一个故事，输出一个完整的角色化视频
**反方**：这会是一个很重的投入（2-3天），且依赖多个未成熟的外部模型
**裁决**：先不做统一管线。改为在现有 3 个策略上加"角色一致性增强层"和"LipSync 层"，角色叙事是"口播+定妆照+卡点"的组合产物。等 P0/P1 完成后，自然就知道统一的管线应该长什么样。
### 辩论 2：Kling LipSync API 还是本地模型？
**正方**：API 零部署、零维护、商业级质量、价格合理
**反方**：12分钟推理时间太长、依赖服务商、文本模式仅120字
**裁决**：API 先上（P0），本地模型作为中期增强（P2）。API 的 12 分钟可以通过并行提交缓冲。
### 辩论 3：变速卡点值不值得单独做一个模块？
**正方**：这是用户明确提到的核心需求，也是和竞品差异化的关键
**反方**：FFmpeg setpts/atempo 实现简单，不需要单独模块
**裁决**：值。但不是单独做"speed_ramp.py"，而是把变速作为 beat_sync 管线的一个可选滤波器链。BeatSync-Engine 的能量波切密度策略才是真正的核心创新——变速只是具体实现手段。
---
## 八、项目文件结构建议
```
scripts/
├── main.py # CLI 入口
├── video_factory.py # 工厂路由 (已有, 扩展)
├── character_sheet.py # 🆕 定妆照生成 (Grid Method)
├── asset_manager/ # 🆕 资产管理
│ ├── index.py # 素材索引
│ ├── cache.py # 缓存管理
│ └── tags.py # 标签系统
├── composer/
│ ├── beat_sync.py # 🔧 节拍检测升级 (6阶段)
│ ├── speed_ramp.py # 🆕 变速滤波器链
│ ├── lipsync.py # 🆕 Kling LipSync 集成
│ ├── ffmpeg.py # (已有)
│ └── hybrid.py # 🆕 口播+卡点融合
├── story_director/ # 🆕 角色叙事 (P2)
│ ├── scene_planner.py # 场景分解
│ ├── temporal_bridge.py # Temporal Bridge
│ └── batch_generator.py # 批量 Kling 生成
├── director_parser/
│ ├── parser.py # 🔧 扩展 character_ref
│ └── schemas.py # 🔧 YAML schema 扩展
├── material_producer/
│ ├── kling/kling.py # 🔧 增加 seed 参数
│ └── pexels/search.py # (已有)
├── voice_synthesizer/ # (已有)
└── lib/
└── config.py # (已有)
```
---
## 九、下一步行动
**立即做 (P0)**:
1. 定妆照 Grid Method Prompt 模板
2. Kling LipSync 集成 (lipsync.py + CLI)
3. YAML Schema 扩展 (character_ref 字段)
**明天做 (P1)**:
4. 变速卡点引擎
5. 节拍检测升级
**本周做 (P2)**:
6. 角色叙事管线初版
7. 素材资产管理器
mac-agent-os-main/05_tools/09_ave/PLANS/BGM_LIBRARY.md
+197
View File
@@ -0,0 +1,197 @@
# AVE BGM 素材库 v1.0
> 版本: 1.0 | 更新: 2026-05-13
> 用途: 人工选曲参考 + AI 生成参考 (mlx-audiocraft prompt 模板)
> 路径索引: 按情绪/场景/节奏三级分类
---
## 一、分类体系
### 按情绪 (Mood)
| 情绪 | 标签 | BPM 范围 | 适用场景 |
|:-----|:-----|:--------:|:---------|
| 激昂 | epic, triumphant, powerful | 100-130 | 科技突破、企业里程碑、颁奖 |
| 大气 | cinematic, majestic, grand | 70-90 | 新闻联播、国家成就、纪录片 |
| 紧张 | suspenseful, intense, urgent | 120-150 | 科技竞争、局势分析、倒计时 |
| 温馨 | warm, gentle, cozy | 60-80 | 励志金句、生活记录、情感故事 |
| 励志 | inspiring, uplifting, motivational | 80-110 | 金句合集、个人成长、正能量 |
| 轻松 | happy, cheerful, light | 90-120 | Vlog、日常分享、旅游记录 |
| 科技感 | futuristic, electronic, tech | 110-130 | 芯片、AI、数码产品、演示 |
| 悬疑 | mysterious, dark, ambient | 50-70 | 深度分析、悬疑故事、揭秘 |
| 悲伤 | sad, emotional, melancholic | 55-75 | 感人故事、离别、怀旧 |
### 按场景 (Scene)
| 场景 | 首选情绪 | 备选 | 典型时长 |
|:-----|:--------:|:----:|:--------:|
| 科技新闻/芯片突破 | 激昂 | 科技感、紧张 | 15-45s |
| 励志金句/正能量 | 励志 | 温馨、轻松 | 30-60s |
| 品牌宣传/企业视频 | 大气 | 激昂、科技感 | 30-90s |
| 故事讲述/叙事 | 温馨 | 悬疑、悲伤 | 60-180s |
| 卡点视频/节奏混剪 | 激昂 | 轻松、励志 | 15-30s |
| 片头/片尾 | 大气 | 激昂、励志 | 3-8s |
| 科普/知识分享 | 轻松 | 温馨、科技感 | 30-120s |
---
## 二、推荐曲库
### 🏆 激昂 · Epic (科技新闻/芯片突破)
| 曲名 | BPM | 时长 | 版权 | 获取 | AI Prompt |
|:-----|:---:|:----:|:----:|:-----|:----------|
| **Heroes Today** | 120 | 2:30 | CC0 | YouTube Audio Library | `epic orchestral, brass and strings, powerful drums, triumphant, building tension, 120 BPM, no vocals` |
| **The Rising** | 115 | 3:00 | CC0 | Free Music Archive | `cinematic orchestral, rising strings, heroic brass, driving percussion, 115 BPM, no vocals` |
| **Epic Cinematic** | 110 | 2:45 | CC0 | Pixabay Music | `epic cinematic, orchestral hits, powerful crescendo, 110 BPM, no vocals` |
| **Beyond the Stars** | 105 | 3:30 | CC0 | YouTube Audio Library | `uplifting cinematic, building strings, triumphant brass, space ambient, 105 BPM, no vocals` |
### 🏆 大气 · Cinematic (品牌/新闻/纪录片)
| 曲名 | BPM | 时长 | 版权 | 获取 | AI Prompt |
|:-----|:---:|:----:|:----:|:-----|:----------|
| **Inspire** | 85 | 3:15 | CC0 | YouTube Audio Library | `cinematic ambient, gradual build, orchestral swells, inspiring, 85 BPM, no vocals` |
| **Echoes of Truth** | 75 | 4:00 | CC0 | Free Music Archive | `cinematic ambient, serious tone, orchestra and choir, majestic, 75 BPM, no vocals` |
| **Last Dawn** | 80 | 2:50 | CC0 | Pixabay Music | `cinematic slow build, atmospheric pads, emotional strings, 80 BPM, no vocals` |
| **Documentary Background** | 90 | 3:00 | CC0 | Pixabay Music | `documentary style, soft piano, ambient strings, professional, 90 BPM, no vocals` |
### 🏆 励志 · Inspiring (金句/正能量/成长)
| 曲名 | BPM | 时长 | 版权 | 获取 | AI Prompt |
|:-----|:---:|:----:|:----:|:-----|:----------|
| **Uplifting Piano** | 95 | 2:30 | CC0 | Pixabay Music | `uplifting piano, soft strings, warm and emotional, inspirational, 95 BPM, no vocals` |
| **Never Give Up** | 100 | 3:00 | CC0 | YouTube Audio Library | `motivational rock, driving beat, uplifting melody, 100 BPM, no vocals` |
| **Warm Hope** | 85 | 2:40 | CC0 | Pixabay Music | `warm acoustic guitar, soft piano, hopeful, gentle rise, 85 BPM, no vocals` |
| **Morning Motivation** | 105 | 2:20 | CC0 | YouTube Audio Library | `upbeat motivational, light percussion, cheerful piano, 105 BPM, no vocals` |
### 🏆 科技感 · Tech (数码/AI/产品演示)
| 曲名 | BPM | 时长 | 版权 | 获取 | AI Prompt |
|:-----|:---:|:----:|:----:|:-----|:----------|
| **Digital Horizon** | 120 | 3:00 | CC0 | Pixabay Music | `electronic futuristic, synth pads, glitch beats, tech, 120 BPM, no vocals` |
| **Neon Lights** | 125 | 2:30 | CC0 | YouTube Audio Library | `electronic ambient, pulsing synth, modern tech feel, 125 BPM, no vocals` |
| **Innovation** | 110 | 2:45 | CC0 | Free Music Archive | `corporate tech, clean synth, modern electronic, professional, 110 BPM, no vocals` |
### 🏆 温馨/轻松 · Warm (生活/Vlog/故事)
| 曲名 | BPM | 时长 | 版权 | 获取 | AI Prompt |
|:-----|:---:|:----:|:----:|:-----|:----------|
| **Gentle Breeze** | 70 | 3:00 | CC0 | Pixabay Music | `soft ambient, gentle piano, nature sounds, relaxing, 70 BPM, no vocals` |
| **Sunny Day** | 95 | 2:15 | CC0 | YouTube Audio Library | `happy ukulele, cheerful melody, light percussion, 95 BPM, no vocals` |
| **Cozy Morning** | 80 | 2:30 | CC0 | Pixabay Music | `warm acoustic, soft guitar, cozy atmosphere, 80 BPM, no vocals` |
---
## 三、AI 生成参考 (mlx-audiocraft Prompt 模板)
以下 prompt 与上述曲库风格对应, 可用于 `--use-mlx` 模式生成类似风格的 BGM:
```bash
# 激昂 (对标 Heroes Today)
python main.py bgm --mood epic --duration 60 --use-mlx
# → prompt: epic orchestral, brass and strings, powerful drums, 120 BPM
# 大气 (对标 Inspire)
python main.py bgm --mood inspiring --duration 60 --use-mlx
# → prompt: uplifting cinematic, building strings, triumphant, 85 BPM
# 励志
python main.py bgm --mood happy --duration 60 --use-mlx
# → prompt: bright ukulele, cheerful melody, acoustic guitar, 90 BPM
# 科技感 (使用 custom prompt)
HF_ENDPOINT=https://hf-mirror.com python main.py bgm --mood normal --duration 60 --use-mlx
# → 用自定义 prompt 覆盖: electronic futuristic, synth pads, 120 BPM
```
### Prompt 优化技巧
| 效果 | 关键词 |
|:-----|:-------|
| 更激昂 | `epic, triumphant, powerful crescendo, building tension` |
| 更柔和 | `soft, gentle, warm, relaxing, smooth` |
| 更快节奏 | `driving beat, fast tempo, energetic` |
| 更有电影感 | `cinematic, orchestral, dramatic swells` |
| 更科技感 | `electronic, synth, futuristic, digital` |
| 更真实乐器 | `acoustic, piano, strings, live instruments` |
| 不要打击乐 | `no percussion, no drums` |
| 纯背景 | `ambient, background, subtle, pad` |
---
## 四、版权合规指南
| 来源 | 商用 | 需署名 | 费用 | 安全等级 |
|:-----|:----:|:------:|:----:|:--------:|
| **Pixabay Music** | ✅ 可 | ❌ 不强制 | 免费 | 🟢 安全 |
| **YouTube Audio Library** | ✅ 可 | ⚠️ 部分需 | 免费 | 🟢 大部分安全 |
| **Free Music Archive (CC0)** | ✅ 可 | ❌ 不强制 | 免费 | 🟢 安全 |
| **Free Music Archive (CC BY)** | ✅ 可 | ⚠️ **必须** | 免费 | 🟡 需标注 |
| **爱给网** | ✅ 可 | ❌ | ¥19-99/首 | 🟢 付费安全 |
| **曲多多** | ✅ 可 | ❌ | ¥10-30/首 | 🟢 付费安全 |
| **耳聆网** | ⚠️ 视具体 | ⚠️ 视具体 | 免费/付费 | 🟡 需逐首确认 |
| **mlx-audiocraft AI 生成** | ⚠️ 见下 | ❌ | 免费 | 🟡 需确认 |
### mlx-audiocraft 商用说明
- 模型权重: CC-BY-NC 4.0 (Meta 许可, 非商业)
- 生成结果: 法律灰色地带, 建议非商用途
- 替代: 如果用 Suno API 付费生成则无此顾虑
---
## 五、使用方式
### 人工选曲
```bash
# 查看此文档 → 按情绪/场景定位 → 按链接下载 → 放入对应目录
python bgm_generator/bgm_download.py list
```
### AI 生成 (替代选曲)
```bash
# 直接生成对应情绪的 BGM (如激昂类型)
HF_ENDPOINT=https://hf-mirror.com python main.py bgm --mood epic --duration 60 --use-mlx
# 效果不满意可以加自定义 prompt
python -c "
from bgm_generator.suno import generate_bgm
generate_bgm(
mood='custom',
duration=60,
output='/tmp/custom_bgm.wav',
use_mlx=True,
)
# 内部会使用自定义 mood 的 prompt
"
```
### 与视频工厂集成
```bash
# 口播 + BGM (选 AI 生成或已有曲目)
python main.py video-factory --strategy 口播 --script script.yaml --bgm /path/to/bgm.wav --duck
# 卡点 + BGM (自动节拍检测)
python main.py video-factory --strategy 卡点 --bgm /path/to/bgm.wav --search "nature"
```
---
## 六、扩展曲库
如需扩充曲库, 推荐以下免费渠道:
| 渠道 | 数量 | 质量 | 获取方式 |
|:-----|:----:|:----:|:---------|
| **Pixabay Music** | 5万+ | ⭐⭐⭐⭐ | `search --mood happy` 打开浏览器下载 |
| **YouTube Audio Library** | 2万+ | ⭐⭐⭐⭐⭐ | 需科学上网 |
| **Free Music Archive** | 10万+ | ⭐⭐⭐⭐ | 需筛选 CC0 标签 |
| **耳聆网** | 3万+ | ⭐⭐⭐ | 含音效+音乐 |
| **爱给网** | 5万+ | ⭐⭐⭐⭐ | 付费商用 ¥19起 |
```bash
# 快速添加新曲目:
# 1. 下载 MP3 到 bgm_library/{mood}/ 目录
# 2. 运行 scan 入库
python bgm_generator/bgm_download.py scan
```
mac-agent-os-main/05_tools/09_ave/PLANS/DASHBOARD_DESIGN.md
+237
View File
@@ -0,0 +1,237 @@
# AVE Dashboard — 生产监控面板方案设计
> 版本: v1.0-draft | 2026-05-15
> 状态: 概念设计
---
## 一、需求还原
你的诉求：
> "在一个页面里，能全方位看到生产线的进度和进展，追溯历史、查询资产（BGM、素材、定妆照、生成片段等），看到一条视频产线的全流程回溯，能复用、能修正、能定位问题，还能跟踪成本和付费历史。"
**一句话**：一个 AVE 的"生产管理后台"，把 CLI 的黑盒操作变成可视化的透明产线。
---
## 二、价值评估
### 2.1 解决了什么核心问题
| 问题 | 现状 | Dashboard 解决 |
|:----|:----|:--------------|
| **产线不可视** | CLI 跑完才知道结果 | 实时看进度、每步状态 |
| **无法追溯** | 不知道哪次用了哪个 BGM/素材 | 每条 production 关联所有输入输出 |
| **无法复用** | 想重跑类似配置要手动记参数 | 一键 re-run / clone |
| **费用失控** | 跑完才知道花了多少钱 | 实时累计 + 单步成本分解 |
| **故障定位慢** | 出错了要翻终端日志 | 红点 + 错误详情 + 重试按钮 |
| **素材管理散** | 文件散落在 cache、output、tmp 里 | 统一索引 + 标签 + 搜索 |
### 2.2 投入产出分析
| 维度 | 评估 |
|:----|:-----|
| **工程量** | 中等（~1.5天：0.5天数据层 + 0.5天后端 + 0.5天前端） |
| **长期收益** | 极高——每次生产都自动记录，解决了"不可追溯、不可复用"的根本问题 |
| **风险** | 低——数据层是增量添加，不影响现有 CLI 运行 |
| **是否阻塞 P0** | 否——可以和 P0 平行开发 |
**结论：应该做，但不是立即做。建议在 P0/P1 核心功能完成后，作为 P2 的基石模块启动。**
---
## 三、架构设计
### 3.1 整体架构
```
现有AVE CLI 新 Dashboard
────────── ──────────
main.py ave_dashboard/
├── video-factory ├── app.py (FastAPI 后端)
├── beat-sync ├── templates/
├── digital-human │ └── dashboard.html (前端页面)
└── ... └── static/
│ └── app.js
│ 自动写DB
▼
┌─────────────────────────┐
│ SQLite: data/ave.db │ ◄──── FastAPI 读取 + API
└─────────────────────────┘
```
### 3.2 数据模型（SQLite）
```sql
-- 生产记录（每次运行一条）
CREATE TABLE productions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
strategy TEXT NOT NULL, -- 'oral' | 'beat-sync' | 'digital-human' | 'story'
status TEXT DEFAULT 'running', -- 'running' | 'completed' | 'failed'
script_path TEXT,
script_name TEXT,
output_path TEXT,
duration_sec REAL,
total_cost REAL DEFAULT 0.0,
config_json TEXT, -- 完整的 CLI 参数 JSON
error_message TEXT,
created_at TEXT DEFAULT (datetime('now')),
completed_at TEXT
);
-- 生产步骤（每个 production 的每一步）
CREATE TABLE production_steps (
id INTEGER PRIMARY KEY AUTOINCREMENT,
production_id INTEGER REFERENCES productions(id),
step_name TEXT NOT NULL, -- 'parse_script' | 'tts' | 'search_material' | ...
status TEXT DEFAULT 'pending', -- 'pending' | 'running' | 'completed' | 'failed'
started_at TEXT,
ended_at TEXT,
duration_sec REAL,
cost REAL DEFAULT 0.0,
detail TEXT, -- 步骤详情（如素材数、字数等）
error_message TEXT
);
-- 资产注册表（所有可复用的数字资产）
CREATE TABLE assets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
asset_type TEXT NOT NULL, -- 'character_sheet' | 'bgm' | 'generated_clip' | 'script' | 'lora' | 'pexels_cache'
name TEXT,
file_path TEXT,
file_size INTEGER,
hash TEXT, -- 文件哈希，用于去重
source TEXT, -- 'pexels' | 'kling' | 'user_upload' | 'generated'
meta_json TEXT, -- 元数据（BPM, mood, segment_count 等）
production_id INTEGER, -- 从哪次 production 产生的
created_at TEXT DEFAULT (datetime('now'))
);
-- 资产标签
CREATE TABLE asset_tags (
asset_id INTEGER REFERENCES assets(id),
tag TEXT NOT NULL,
PRIMARY KEY (asset_id, tag)
);
-- 资产-生产关联（一个 production 用了哪些资产）
CREATE TABLE production_assets (
production_id INTEGER REFERENCES productions(id),
asset_id INTEGER REFERENCES assets(id),
role TEXT, -- 'input' | 'output' | 'intermediate'
PRIMARY KEY (production_id, asset_id)
);
```
### 3.3 集成方式（对现有 CLI 的改动）
**改动极小**——只需要在 `main.py` 和 `video_factory.py` 的每个关键节点加一行：
```python
from lib.dashboard import log_production, log_step, log_asset
# 在 production 开始时
prod_id = log_production(strategy="口播", config=args)
# 在每步结束时
log_step(prod_id, step_name="tts", status="completed", cost=0.30, detail="85 字符")
# 在生成资产时
log_asset(prod_id, type="generated_clip", path="/tmp/clip.mp4", tags=["hermit", "kling"])
```
现有代码量 3000+ 行，新增约 **50 行埋点** 即可。不需要改现有逻辑。
### 3.4 Dashboard 功能清单
| 板块 | 功能 |
|:----|:-----|
| **总览卡片** | 总产量、本月产量、累计费用、资产总数 |
| **生产列表** | 按时间倒叙、按策略/状态筛选、搜索 |
| **生产详情** | 每步状态+耗时+费用、输入输出资产列表、输出视频预览 |
| **资产浏览器** | 按类型/标签筛选、搜索、预览、查看被哪些 production 使用 |
| **重复利用** | re-run（同配置）、clone as new（修改配置再跑） |
| **费用分析** | 按策略/按时间/按单步的费用分解图 |
| **失败追踪** | 失败 production 列表、错误详情、重试按钮 |
---
## 四、与现有规划的关系
### 4.1 优先级定位
```
P0 (Sprint 1) ─── 定妆照 + Kling LipSync + Schema 扩展
│
P1 (Sprint 2) ─── 变速卡点 + 节拍升级
│
P2 (Sprint 3) ─── 角色叙事 + LatentSync + 资产管理
│ ↑
└── Dashboard ───────┘ ← 建议和 Sprint 3 一起做
```
**理由**：
- P0 和 P1 是核心功能增强，应该优先
- Dashboard 的**数据层**可以和 P0 并行搭（半天）
- Dashboard 的**前端**等到 Sprint 3 再做，那时资产管理和角色叙事也需要界面，一次性写完整
### 4.2 依赖关系
| 依赖 | 说明 | 是否阻塞 |
|:----|:-----|:--------:|
| P0 完成 | Dashboard 不依赖任何 P0 功能 | ❌ 不阻塞 |
| 资产索引 | Dashboard 的资产浏览器依赖 asset_manager 模块 | ⚠️ 建议 asset_manager 先搭 |
| CLI 埋点 | 需要在 main.py 加 ~50 行 log 调用 | ✅ 半天可完成 |
### 4.3 分步交付
| 阶段 | 内容 | 交付物 | 时间 |
|:----|:-----|:------|:----:|
| **Phase 1** (和P0平行) | DB schema + 埋点 + 后端 API | `data/ave.db`, `lib/dashboard.py`, `app.py` | 0.5天 |
| **Phase 2** (P2开始时) | 前端页面 V1: 生产列表+详情+费用 | `dashboard.html` | 0.5天 |
| **Phase 3** (资产管理器完成) | 资产浏览器 + 搜索 + 复用 | 前端更新 | 0.5天 |
---
## 五、我自问自答的几个问题
### 这会不会变成一个沉重的 Web 项目？
**不会。** 设计原则是"轻量 + 可摘除"：
- 后端用 FastAPI（Python 自带，AVE 不需要新依赖）
- 前端用单 HTML 页面（Vue.js CDN 或原生 JS，不构建）
- 数据用 SQLite（零运维）
- 所有新增代码放在 `scripts/lib/dashboard.py` 一个文件
- 如果以后不需要，删掉这个文件 + 前端目录即可
### CLI 用户会不会受影响？
**不会。** Dashboard 是增量添加。所有埋点都是 `try/except` 包起来的——如果 DB 写失败，CLI 继续运行，不报错。
### 值不值得在开发核心功能之前做？
**不值得先做。** 但值得在核心功能开发的同时**搭好数据层**。数据层（DB schema + 埋点）只需要半天，埋完后 CLI 自动积累数据。前端可以在任何时候再写——数据已经在那里了。
---
## 六、建议方案
> **做。但分步做。**
| 时机 | 做什么 | 原因 |
|:----|:------|:-----|
| **现在** (和定妆照+P0平行) | 搭 DB schema + CLI 埋点 | 半天工作量, 数据开始积累 |
| **P1 完成后** (也就是1-2天内) | 写后端 API + 前端 V1 | 那时已经有几十条 production 数据了, 面板直接有内容 |
| **资产管理器完成后** | 前端 V2 加上资产浏览器 | 资产管理器的索引+Dashboard 的展示天然互补 |
**要不要**这个功能？——**要**。
**什么时候做？**——建议从明天开始搭数据层（0.5天），前端等有数据了再写。这样既不影响 P0/P1 的开发节奏，又能在 1-2 天内看到 Dashboard 的效果。
如果确认要做，我可以：
1. 先创 SQLite schema 文件
2. 在 `main.py` 和 `video_factory.py` 加埋点
3. 搭好 FastAPI 后端骨架
等你决定 P0 从哪步开始后，Dashboard 数据层可以同步启动。
mac-agent-os-main/05_tools/09_ave/PLANS/DASHBOARD_MULTI_AGENT.md
+408
View File
@@ -0,0 +1,408 @@
# Dashboard 数据层 · 多智能体协同设计
> 版本: v1.0 | 2026-05-15
> 定位: AgentOS 多智能体系统 · 共享观测层
---
## 一、定位：不是 AVE 的面板，是 AgentOS 的观测层
Dashboard 不是 AVE 的附属工具。它应该是一套**跨智能体的共享数据服务**，任何 Agent（Claw、AVE、Matrix、Trae 等）都可以通过统一接口写入和查询。
### 现存 Agent 一览
| Agent | 目录 | 适合 Dashboard 跟踪什么 |
|:------|:-----|:------------------------|
| **09_ave** | `05_tools/09_ave/` | 视频生产任务、素材生成、API 调用 |
| **07_matrix** | `05_tools/07_matrix/` | 抖音养号任务、蓝�运行、账号切换 |
| **claw assistant** | `~/.workbuddy/` | 各种自动化任务、CLI 执行的历史 |
| **02_browser / 05_crawl** | `05_tools/` | 爬虫任务、页面采集记录 |
---
## 二、存储位置
根据 AgentOS 的目录结构约定：
| 类别 | 路径 | 说明 |
|:----|:-----|:------|
| **代码（可同步）** | `~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/` | 多机共享，坚果云同步 |
| **数据（本地）** | `~/workbuddy-agent-os/agent-local/runtime/dashboard/` | 本地 SQLite + 缓存，不同步 |
| **客户端库** | `~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/client.py` | Agent 导入用，写数据入口 |
| **后端服务** | `~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/server.py` | FastAPI 应用 |
| **前端页面** | `~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/templates/` | HTML 单页应用 |
**为什么数据放 `agent-local` 而不是 `agent-sync`？**
- SQLite 不适合坚果云同步（并发写会导致 DB 损坏）
- 每台机器的生产数据天然不同，不应该同步
- `agent-local/runtime/` 已经是 AgentOS 为"运行时数据"预设的位置
---
## 三、多智能体数据模型
### 3.1 agents — 智能体注册表
```sql
CREATE TABLE agents (
id TEXT PRIMARY KEY, -- 'ave', 'matrix', 'claw', 'trae'
name TEXT NOT NULL, -- 'audio score video engine'
type TEXT DEFAULT 'tool', -- 'tool' | 'skill' | 'pipeline' | 'assistant'
version TEXT, -- 当前版本号
status TEXT DEFAULT 'active',
last_seen_at TEXT, -- 最后心跳时间
meta_json TEXT -- 扩展元数据
);
```
预注册的 Agent：
| id | name | type |
|:---|:-----|:-----|
| `ave` | AudioScore Video Engine | tool |
| `matrix` | Matrix Account Manager | tool |
| `claw` | Claw AI Assistant | assistant |
| `memory` | Memory Manager | skill |
### 3.2 productions — 生产任务（跨 agent 通用）
这是核心表。**不限于视频生产**——任何 agent 的"一次任务执行"都是一条 production。
```sql
CREATE TABLE productions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
agent_id TEXT NOT NULL REFERENCES agents(id),
pipeline TEXT NOT NULL, -- 'ave:oral' | 'ave:beat-sync' | 'matrix:browse' | 'claw:research'
status TEXT DEFAULT 'running', -- 'running' | 'completed' | 'failed' | 'cancelled'
title TEXT, -- 人类可读名称
input_summary TEXT, -- JSON: 输入概览
output_summary TEXT, -- JSON: 输出概览
config_json TEXT, -- JSON: 完整参数快照
duration_sec REAL,
total_cost REAL DEFAULT 0.0,
currency TEXT DEFAULT 'CNY',
error_message TEXT,
tags TEXT, -- 逗号分隔，跨 agent 搜索用
created_at TEXT DEFAULT (datetime('now')),
completed_at TEXT
);
CREATE INDEX idx_productions_agent ON productions(agent_id);
CREATE INDEX idx_productions_status ON productions(status);
CREATE INDEX idx_productions_created ON productions(created_at);
```
### 3.3 production_steps — 步骤级跟踪
```sql
CREATE TABLE production_steps (
id INTEGER PRIMARY KEY AUTOINCREMENT,
production_id INTEGER REFERENCES productions(id) ON DELETE CASCADE,
agent_id TEXT NOT NULL,
step_name TEXT NOT NULL, -- 'parse_script' | 'tts' | 'kling_generate' | ...
step_type TEXT DEFAULT 'process', -- 'process' | 'api_call' | 'human_review' | 'decision' | 'wait'
status TEXT DEFAULT 'pending',
input_ref TEXT, -- 输入引用（文件路径 / URL）
output_ref TEXT, -- 输出引用
started_at TEXT,
ended_at TEXT,
duration_sec REAL,
cost REAL DEFAULT 0.0,
detail TEXT, -- 步骤详情 JSON
error_message TEXT,
metadata_json TEXT -- 扩展字段
);
CREATE INDEX idx_steps_production ON production_steps(production_id);
```
### 3.4 assets — 跨 agent 共享资产
所有 agent 生成的、可复用的数字资产统一注册在这里。**关键设计**：资产一旦注册，就属于全局资产池，任何 agent 都可以引用。
```sql
CREATE TABLE assets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
asset_type TEXT NOT NULL, -- 'character_sheet' | 'bgm' | 'generated_clip' | 'script' | 'lora' | 'screenshot' | 'dataset'
name TEXT,
description TEXT,
file_path TEXT, -- 本地绝对路径
file_size INTEGER,
file_hash TEXT, -- SHA256，用于去重
source_agent TEXT REFERENCES agents(id),
source TEXT, -- 'generated' | 'imported' | 'downloaded' | 'user_provided' | 'pexels'
license TEXT, -- 版权信息
meta_json TEXT, -- JSON: 资产元数据
tags TEXT, -- 逗号分隔
created_at TEXT DEFAULT (datetime('now')),
UNIQUE(file_hash)
);
CREATE INDEX idx_assets_type ON assets(asset_type);
CREATE INDEX idx_assets_source ON assets(source_agent);
```
### 3.5 production_assets — 资产使用记录
```sql
CREATE TABLE production_assets (
production_id INTEGER REFERENCES productions(id) ON DELETE CASCADE,
asset_id INTEGER REFERENCES assets(id) ON DELETE CASCADE,
role TEXT DEFAULT 'input', -- 'input' | 'output' | 'intermediate' | 'reference'
PRIMARY KEY (production_id, asset_id)
);
```
### 3.6 agent_events — 智能体间事件总线
这是**跨智能体通信**的关键设计。一个 agent 完成某项任务后，可以通过事件通知其他 agent。
```sql
CREATE TABLE agent_events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
source_agent TEXT REFERENCES agents(id),
target_agent TEXT, -- null = broadcast 给所有 agent
event_type TEXT NOT NULL, -- 'production.completed' | 'asset.created' | 'pipeline.ready' | 'error.occurred'
severity TEXT DEFAULT 'info', -- 'info' | 'warning' | 'error' | 'critical'
title TEXT,
payload_json TEXT, -- 事件负载 JSON
status TEXT DEFAULT 'pending', -- 'pending' | 'read' | 'acknowledged'
created_at TEXT DEFAULT (datetime('now')),
read_at TEXT
);
CREATE INDEX idx_events_target ON agent_events(target_agent);
CREATE INDEX idx_events_status ON agent_events(status);
CREATE INDEX idx_events_created ON agent_events(created_at);
```
### 3.7 ER 关系
```
agents ──1:N── productions ──1:N── production_steps
│ │
│ └── M:N ── assets (via production_assets)
│
└──1:N── agent_events (source)
└──?:1── agent_events (target)
```
---
## 四、客户端库设计
每个 Agent 通过 `client.py` 写入，不需要直接操作 SQLite。这是**唯一**的写入口。
```python
# ~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/client.py
"""
Dashboard Client — 供所有 Agent 调用
用法:
from dashboard_client import DashboardClient
db = DashboardClient() # 自动连接 agent-local/runtime/dashboard/ave.db
# 注册自己
db.register_agent("ave", "AudioScore Video Engine", "tool")
# 开始一个 production
prod_id = db.start_production(
agent_id="ave",
pipeline="ave:oral",
title="知识讲座视频 #047",
config={"script": "lecture.yaml", "style": "knowledge_lecture"}
)
# 记录步骤
db.log_step(prod_id, "tts", "completed", cost=0.30, detail={"chars": 85})
db.log_step(prod_id, "render", "completed", cost=0.0)
# 注册资产
asset_id = db.register_asset(
asset_type="generated_clip",
name="clip_hermit_01.mp4",
file_path="/tmp/kling_hermit.mp4",
source_agent="ave",
tags=["kling", "hermit", "cinematic"]
)
# 关联资产到 production
db.link_asset(prod_id, asset_id, role="output")
# 完成 production
db.complete_production(prod_id, status="completed", total_cost=1.20)
# 发送事件通知
db.send_event("ave", "claw", "production.completed",
title="视频 #047 生成完成", payload={"prod_id": prod_id})
```
### 核心 API
| 方法 | 功能 | 被调用频率 |
|:-----|:-----|:----------|
| `register_agent(id, name, type)` | 注册/更新 agent | 安装时一次 |
| `start_production(...)` | 开始任务 | 每次 CLI 执行 |
| `log_step(...)` | 记录步骤 | 每个步骤 |
| `update_step(...)` | 更新步骤状态 | 异步步骤 |
| `complete_production(...)` | 完成任务 | 每次完成/失败 |
| `register_asset(...)` | 注册资产 | 每个新文件 |
| `link_asset(prod, asset, role)` | 关联资产 | 每次资产使用 |
| `send_event(source, target, type, ...)` | 发送事件 | 按需 |
---
## 五、后端 API 设计
FastAPI 服务，运行在 `http://localhost:9132`。
### 核心端点
```
GET /api/status # 服务健康检查
GET /api/summary # 总览指标（总数、本月、总成本、资产数）
GET /api/productions # 生产列表（支持 filter: ?agent=&status=&pipeline=&tags=）
GET /api/productions/{id} # 生产详情 + 步骤列表
GET /api/productions/{id}/assets # 生产关联的资产
GET /api/assets # 资产列表（支持 filter: ?type=&agent=&tags=&q=）
GET /api/assets/{id} # 资产详情 + 使用记录
GET /api/assets/{id}/productions # 该资产被哪些 production 用过
GET /api/agents # agent 列表
GET /api/agents/{id}/productions # 某个 agent 的所有 production
GET /api/events # 事件列表
GET /api/events?target={agent_id} # 发给某个 agent 的事件
GET /api/costs # 费用汇总（按 agent/策略/时间分组）
```
### 查询示例
```
# 查看 AVE 最近失败的 production
GET /api/productions?agent=ave&status=failed
# 搜索资产
GET /api/assets?q=定妆照&type=character_sheet
# 查看 matrix 本周的全部任务
GET /api/productions?agent=matrix&from=2026-05-08&to=2026-05-15
```
---
## 六、集成方式
### 6.1 AVE 集成（Sprint 1 要做）
在 `main.py` 的每个关键节点加 ~50 行调用。改动量极小：
```python
# 在 video_factory.py 的入口
from dashboard_client import DashboardClient
db = DashboardClient()
# run_oral() 开始
prod_id = db.start_production("ave", "ave:oral", title, config=args)
# TTS 步骤完成
db.log_step(prod_id, "tts", "completed", cost=0.30)
# 素材搜索完成
db.log_step(prod_id, "search_material", "completed", detail={"count": 6})
# 合成完成
db.complete_production(prod_id, status="completed", total_cost=tracker.total)
```
### 6.2 Matrix 集成（Sprint 3 可选）
```python
# 在 task_engine.py 的入口
prod_id = db.start_production("matrix", "matrix:browse", "抖音浏览 #102")
db.log_step(prod_id, "switch_account", "completed")
db.log_step(prod_id, "open_douyin", "completed")
db.log_step(prod_id, "browse_videos", "completed", detail={"count": 15})
db.complete_production(prod_id, status="completed")
```
### 6.3 Claw Assistant 集成（Sprint 3 可选）
通过 WorkBuddy 的 CLI 埋点，每次执行自动化任务自动记录。
---
## 七、数据生命周期
| 阶段 | 操作 | 位置 |
|:-----|:-----|:------|
| **创建** | `client.py` 写入 | `agent-local/runtime/dashboard/ave.db` |
| **读取** | HTTP API → 前端 Dashboard | FastAPI + HTML |
| **备份** | 随 agent-local 整体备份策略 | 暂不单独处理 |
| **清理** | >90 天的 production 自动归档 (可配置) | 归档到 `agent-local/runtime/dashboard/archive/` |
| **跨机迁移** | 不同步。每台机器独立数据 | `agent-local` 不同步的设计 |
---
## 八、文件结构
```
agent-sync/05_tools/10_dashboard/
├── __init__.py
├── client.py # Agent 客户端库（唯一写入口）
├── models.py # SQLAlchemy ORM 或 raw SQL schema
├── server.py # FastAPI 应用
├── templates/
│ ├── index.html # 总览页
│ ├── productions.html # 生产列表
│ ├── detail.html # 生产详情
│ └── assets.html # 资产浏览器
├── static/
│ └── app.js # 前端交互逻辑
└── README.md # 使用说明
agent-local/runtime/dashboard/
├── ave.db # SQLite 主数据库
├── cache/ # 文件缓存
└── archive/ # 历史归档
```
---
## 九、为什么这样设计
### 9.1 为什么用 SQLite 而不是其他 DB？
| 数据库 | 适用性 | |
|:-------|:-------|:-|
| SQLite | ✅ 单机多进程读、零运维、AgentOS 已有使用 | **选这个** |
| PostgreSQL | ❌ 太重，单机不需要 |
| JSON 文件 | ❌ 不支持并发写、不支持查询 |
| LevelDB/RocksDB | ❌ 没 SQL 查询，不支持关联 |
### 9.2 为什么用 HTTP API 而不是直接写 SQLite？
| 方式 | 问题 |
|:-----|:-----|
| 直接写 SQLite | 每个 agent 都要 import sqlite3 + 写 SQL，产生代码耦合 |
| 通过 API | agent 只需 import client.py + 调方法，后端封装所有 DB 逻辑 |
### 9.3 为什么 events 表放在这里而不是单独的消息队列？
轻量。当前多智能体在同一台机器上，SQLite 轮询足够。如果以后需要跨机器，可以从 events 表迁移到真正的消息队列（如 Redis pub/sub）。
---
## 十、开发量估算
| 模块 | 估计 | 说明 |
|:-----|:----:|:------|
| `models.py` (schema) | 0.2h | SQL 建表语句 |
| `client.py` (核心 6 个方法) | 1h | ~150 行 Python |
| `server.py` (API 端点) | 1h | ~200 行 FastAPI |
| AVE 埋点接入 | 0.5h | main.py + video_factory.py 加 ~50 行 |
| **合计** | **~2.7h** | 一个下午可完成 |
mac-agent-os-main/05_tools/09_ave/PLANS/JIMENG_AUTOMATION_PLAN.md
+209
View File
@@ -0,0 +1,209 @@
# 即梦(Dreamina) 网页版自动化方案
> **版本**: v0.1 (规划阶段)
> **创建**: 2026-05-14
> **状态**: ⏸️ 暂停（操作路径记录中，生成任务卡在排队）
> **下次目标**: 完成下载步骤的记录，编写 jimeng_ops.py
---
## 一、项目背景
### 1.1 目标
为 AVE 视频工厂提供高质量的 AI 生成视频素材，替代 Pexels 免费素材。
每期口播视频需要 12 段素材，每段 5-10 秒竖屏视频。
### 1.2 为什么选即梦网页版
| 方案 | 每段5秒成本 | 一期12段 | 备注 |
|:-----|:----------:|:--------:|:-----|
| Pexels 免费素材 | 0元 | 0元 | 画面静态，观感差 |
| 腾讯云混元 API | 1.8-3.6元 | 21.6-43.2元 | 后付费，贵 |
| **即梦网页版会员** | **0.22-0.37元** | **2.6-4.4元** | **VIP 可用 1080p，便宜** |
| 即梦 CLI | 同会员积分 | 同左 | **VIP 模型 CLI 不支持，720p 限制** |
**结论**：即梦网页版会员(¥79-649/月)性价比最高，但需通过 Peekaboo 自动化操作网页。
### 1.3 备选方案对比
| 方案 | 结果 | 原因 |
|:-----|:----:|:-----|
| Dreamina CLI 直接调用 | ❌ 放弃 | CLI 免费版锁 720p，VIP 模型不支持 |
| Buddy-cloud.py (腾讯云) | ✅ 可用 | 1080p 可用，但成本是即梦网页版的 5-10x |
| CloakBrowser Playwright 自动化 | 🔧 备用 | 需处理反爬/登录态，不如 Peekaboo 直接 |
| Peekaboo GUI 自动化 | ✅ **主方案** | 基于视觉识别，即梦不管怎么改UI都能用 |
---
## 二、当前进度
### 2.1 已完成
- [x] Dreamina CLI 安装到 `~/.local/bin/dreamina`
- [x] CLI OAuth 登录成功（积分余额: 80）
- [x] 验证 CLI 命令集（`text2video`, `text2image`, `user_credit` 等）
- [x] 确认 CLI VIP 模型不可用（网页端会员 ≠ CLI 会员）
- [x] Peekaboo 截图测试成功（可捕获 Chromium 窗口）
- [x] 即梦首页页面结构记录完成
- [x] 文生视频操作路径第 1-5 步记录完成
### 2.2 待完成
- [ ] **步骤 ⑥：下载视频** — 生成完成后下载按钮在哪？如何触发下载？
- [ ] 编写 `jimeng_ops.py`（Peekaboo 原子操作脚本）
- [ ] 编写 blueprint 蓝图（批量生成多段素材）
- [ ] 集成到 AVE pipeline（生成 → 下载到 cache → Ken Burns → 合成）
- [ ] 处理异常情况（积分不足、模型降级、生成失败）
---
## 三、即梦首页页面结构
### 3.1 侧边栏（左）
| 图标按钮 | 文字 | 功能 |
|:--------|:----|:-----|
| 💡 | 灵感 | 默认首页，直接输入 prompt |
| ⚡ | 生成 | 各类生成任务入口 |
| 📦 | 资产 | 历史作品 |
| 🎨 | 画布 | 编辑/合成 |
| ❓ | OCTO | 未知功能 |
底部：开通会员 | 积分(80) | 头像(登录后显示) | 通知🔔 | CLI 介绍
### 3.2 主输入区（中）
大输入框（类智能体对话框），包含：
| 元素 | 位置 | 说明 |
|:-----|:----|:-----|
| + 添加文件 | 输入框左上角 | 图生图/图生视频等 |
| 智能体模式(Agent) | 输入框下方左 | 默认模式，自动判断输出类型 |
| 自动/生成偏好 | 模式按钮旁 | 可设图片/视频、比例、模型版本 |
| [使用技能] | 模式按钮区 | 剧情短片、电商套图、海报设计等 |
| [@] | 模式按钮区 | 指定主体/人物 |
| 🎤 麦克风 | 输入框右下角 | 语音输入 |
| ↑ 发送箭头 | 输入框右下角 | 灰色→变亮（输入内容后） |
### 3.3 模式切换弹窗
点"智能体模式"可切换：
| 模式 | 用途 |
|:-----|:-----|
| 图片生成 | 文生图 |
| 视频生成 | 文生视频（本方案目标模式） |
| 数字人 | 数字人出镜 |
| 配音 | 语音合成 |
| 动作模仿 | 动作驱动 |
### 3.4 自动/生成偏好设置
| 设置项 | 可选值 |
|:-------|:-------|
| 输出类型 | 图片 / 视频 |
| 比例 | 21:9 / 16:9 / 9:16(竖屏) / 等 |
| 模型版本 | 图片4.0 / 3.0 / 等 |
---
## 四、完整操作路径（已记录 5/7 步）
```
① 首页（灵感Tab，Agent模式）
状态: 输入框空，发送按钮灰色
操作: 输入 prompt
↓
② 输入 prompt 后
状态: 发送按钮由灰变亮，其他无变化
操作: 按回车 或 点发送箭头
↓
③ 进入对话模式
状态: AI 开始分析 prompt
↓
④ ⚠️ 模型不可用降级（每次都会触发）
状态: 弹出积分确认框
├─ "消耗 X 积分，确认继续生成"
├─ ⭐ "本次对话不再确认"（鼠标悬浮出现小按钮，可勾选）
└─ 点确认 → 扣积分
↓
⑤ 生成排队
状态: 输入框右上方出现生成状态条
内容区: "排队中" → "生成中"
结果区: 图片占位框 + "以上内容由AI生成本次消耗X积分"
+ [重新生成] 按钮 + [引用作品] 按钮（双引号）
↓
⑥ 生成完成
状态: ?（待下次记录）
下载方式: ?（待下次记录）
↓
⑦ 保存到 AVE cache
⏳ 待实现
```
### 4.1 关键交互细节
- **积分确认**: 每次生成都会弹出，可勾选"本次对话不再确认"
- **模型降级**: Agent 模式自动选 VIP 模型 → VIP 不可用 → 降级普通模型 → 重新确认积分
- **排队等待**: 生成任务进入队列，排队时间不定（上次卡住未完成）
- **发送方式**: 回车键 或 点发送箭头
---
## 五、技术方案
### 5.1 核心工具
- **Peekaboo v3.1.2**：macOS GUI 自动化（视觉识别 + 点击 + 输入）
- **CloakBrowser**：备用浏览器（需持久化 profile 保持登录态）
- **AVE pipeline**：接收生成素材 → Ken Burns → 合成
### 5.2 原子操作设计（待实现）
```python
# jimeng_ops.py 初步设计
def input_prompt(text): # 输入 prompt
def click_send(): # 点发送
def confirm_credit(): # 确认积分消耗
def disable_credit_confirm(): # 勾选"不再确认"
def wait_generation(): # 轮询检测生成完成
def click_download(): # 点下载
def save_to_ave_cache(): # 保存到 AVE cache
```
### 5.3 Peekaboo 命令映射
| 操作 | Peekaboo 命令 | 锚点策略 |
|:-----|:-------------|:---------|
| 输入 prompt | `peekaboo type "..."` | 当前焦点（先点输入框） |
| 点发送 | `peekaboo click "↑"` 或回车 | OCR 识别箭头图标或键盘发送 |
| 确认积分 | `peekaboo click "确认继续"` | OCR 识别按钮文字 |
| 勾选不再确认 | `peekaboo click "不再确认"` | OCR 识别悬浮按钮文字 |
| 等生成完成 | 轮询 `peekaboo image` 检测下载按钮 | 截图 OCR |
| 下载 | `peekaboo click "下载"` | OCR 识别按钮文字 |
---
## 六、相关文件
| 文件 | 路径 |
|:-----|:-----|
| 本计划文档 | `05_tools/09_ave/PLANS/JIMENG_AUTOMATION_PLAN.md` |
| AVE 实施计划 | `05_tools/09_ave/PLANS/AVE_IMPLEMENTATION_PLAN.md` |
| AVE 策略体系 | `05_tools/09_ave/PLANS/STRATEGY.md` |
| Dreamina CLI | `~/.local/bin/dreamina` |
| Dreamina CLI 说明 | `~/.dreamina_cli/dreamina/SKILL.md` |
| AVE 主脚本 | `05_tools/09_ave/scripts/main.py` |
| 视频合成 | `05_tools/09_ave/scripts/composer/ffmpeg.py` |
| 测试道家 YAML | `05_tools/09_ave/scripts/daoist_quotes.yaml` |
---
## 七、下次启动检查清单
- [ ] 确认 CloakBrowser/Chromium 是否还在运行
- [ ] 确认即梦网页登录态是否过期
- [ ] 确认 Dreamina CLI 登录态（`dreamina user_credit`）
- [ ] 继续步骤 ⑥：生成完成后探索下载方式
- [ ] 完整走通一次后开始写 `jimeng_ops.py`
mac-agent-os-main/05_tools/09_ave/PLANS/SPORTS_CHARACTER_PLANNING_v1.md
+196
View File
@@ -0,0 +1,196 @@
# 体育角色一致性图片生成方案 v1
> 版本: 1.0 | 日期: 2026-05-18
> 用途: ghai 审核 → 确认后再执行
---
## 一、背景
前次会话完成 AudioLine→AVE Phase 1 四路集成（T169-T172）后，转向**体育主题角色一致性图片生成**。此前 AVE 的角色管线以漫剧/日常场景为主，缺少体育/运动场景的专项能力。
---
## 二、问题定义
| 维度 | 说明 |
|:----|:-----|
| 目标 | 生成带角色一致性的体育/运动主题图片，男女角色各一 |
| 渠道 | Kling 文生图 + Kling I2I 变体（现有 AVE 基础设施） |
| 场景 | 跑步、篮球、足球、健身等多运动姿态 |
| 核心挑战 | 高动态姿态下保持面部/体型/服装一致性 |
| 输出形式 | 定妆照 + 多姿态参考图 → 可用于 AVE 视频生成 |
---
## 三、三层工作流策略（全网调研结论）
AI 角色一致性主流方案分为三个层级，底层性价比最高：
| 层级 | 方法 | 一致性 | 成本 | 学习曲线 | 推荐场景 |
|:----|:-----|:------|:----|:--------|:--------|
| **轻量层** | 单图引用 + 提示词纪律 | 60-70% | 低 | 低 | 快速试错/概念探索 |
| **受控层** | Grid Method + I2I 变体 | 75-85% | 中 | 中 | **体育角色首选 ← 我们在这里** |
| **训练层** | LoRA 微调 | 90-96% | 高 | 高 | 长期 IP / 商业级项目 |
**体育角色推荐路径**：先走受控层（我们已有 character_sheet.py 的 Grid Method + Kling I2I），待角色确认为长期资产后再升级 LoRA。
---
## 四、现有 AVE 基础设施可用性
| 模块 | 当前能力 | 体育场景适配 |
|:----|:---------|:------------|
| `character_sheet.py` | 2x3 Grid Method + Kling 文生图 + I2I 变体 | **核心引擎，直接可用** |
| `character_registry` | 角色注册/切换/参考图管理 | **支持扩展**，需增加运动服/装备字段 |
| `character_locker` | 全片 Prompt 注入角色描述块 | **无需改动** |
| `character_adapter` | 中文→英文映射 + Kling 格式 | **无需改动** |
| `prompts/character_sheet_prompts.md` | 标准角色描述块模板 | **需新增体育专用模板** |
---
## 五、体育角色提示词模板
基于全网调研的"身份锚点 + 可换场景"原则设计：
### 5.1 角色描述块规范 (Identity Anchor)
所有体育角色描述块遵循固定结构，**全片不变**：
```
[姓名]，[性别] [年龄]，[身高] [体型]，
[发型][发色]，[面部特征]，[肤色]，
[运动装备描述]，
[标志性特征/纹身/饰品]。
```
### 5.2 男性角色：锋哥 (Feng) — 街头篮球
**角色描述块**（固定锚点，全片复用）：
```
锋哥，中国男性 26岁，身高183cm 精壮偏瘦体型，
黑色寸头修剪整齐，单眼皮眼神锐利，小麦色健康皮肤，
身穿宽松白色无袖篮球背心配黑色运动短裤，
左小臂有一条简约的黑色几何纹身，右手腕戴着红色运动腕带。
```
**运动场景 Prompt 示例**:
| 场景 | Prompt |
|:----|:-------|
| 运球突破 | `锋哥，中国男性26岁，...（完整描述块）... 在室外水泥篮球场上运球突破，身体低伏重心压低，左手运球右手护球，篮球在手掌和地面之间弹跳，动态抓拍，下午的暖色斜阳，背景是老旧的城市居民楼，体育摄影风格，高速快门凝固动作瞬间` |
| 急停跳投 | `锋哥，...（同一描述块）... 在烈日下的街头篮球场急停跳投，身体腾空后仰，右手托球左手辅助，短裤因动作飘起，双腿打开呈剪刀腿式，汗水在空气中飞溅，广角镜头从低角度拍摄，强烈的阳光穿过篮筐形成光晕` |
| 防守姿态 | `锋哥，...（同一描述块）... 在篮球场上弯腰防守，双脚打开与肩同宽，双臂张开，眼神紧盯对手，额头上布满汗水，嘴巴微张喘气，全身肌肉紧绷，中景拍摄，下午暖色调光线，背景有模糊的球场铁丝网` |
### 5.3 女性角色：小雨 (Xiaoyu) — 户外运动
**角色描述块**（固定锚点，全片复用）：
```
小雨，中国女性 24岁，身高168cm 匀称健美的运动体型，
乌黑长发扎成高马尾露出额头，鹅蛋脸型五官精致，白皙肤色透着健康红润，
身穿浅蓝色速干运动背心配黑色紧身瑜伽裤，
脖子上挂着一副白色运动耳机，手上戴着运动手套。
```
**运动场景 Prompt 示例**:
| 场景 | Prompt |
|:----|:-------|
| 户外跑步 | `小雨，中国女性24岁，...（完整描述块）... 在清晨的滨海步道上跑步，身体前倾摆臂有力，高马尾在身后甩动，阳光从海面反射到脸上形成温暖的侧光，背景是大海和远处的城市天际线，运动摄影风格，中景跟拍视角` |
| 力量训练 | `小雨，...（同一描述块）... 在户外健身区的单杠区做引体向上，双手抓杠身体悬空，核心收紧双腿微屈，背部和手臂肌肉线条明显，额头渗出汗珠，阳光透过树叶打在脸上形成斑驳光影，低角度仰拍展现力量感` |
| 拉伸放松 | `小雨，...（同一描述块）... 在公园草地上做跑后拉伸，单腿站立另一条腿向后弯曲用手握住脚踝，身体微微前倾保持平衡，表情放松面带微笑，夕阳的金色光线从侧面打过来勾勒出身体轮廓，温暖柔和的色彩` |
---
## 六、角色一致性图库方案
### 6.1 方案架构
基于现有 Grid Method 改造：
```
第一阶段：定妆照（2x3 → 3x3 升级）
┌─────────────┬─────────────┬─────────────┐
│ 全身正面 │ 全身侧面 │ 全身 3/4 │
│ （标准站姿） │ （侧身） │ （斜45度） │
├─────────────┼─────────────┼─────────────┤
│ 面部中性 │ 面部微笑 │ 面部发力 │
│ （标准表情） │ （亲和） │ （运动表情） │
├─────────────┼─────────────┼─────────────┤
│ 运动姿态 A │ 运动姿态 B │ 运动姿态 C │
│ （如运球） │ （如投篮） │ （如防守） │
└─────────────┴─────────────┴─────────────┘
第二阶段：Kling I2I 变体生成
各单格 → 3 变体 → 总计 18+ 参考图
第三阶段：注册到 CharacterRegistry
定妆照 + 裁剪图 → 注册 → character_locker 全片注入
```
### 6.2 生成流程
```
1. 用 character_sheet.py（改造后）生成 3x3 网格定妆照
├── Kling 文生图 (kling-v1, 3:2 比例)
├── 裁剪 9 张单格（extract_cells 升级版）
└── 存入角色库
2. 对"运动姿态"和"面部-运动表情"格执行 Kling I2I 变体
├── 每个 source → 3 变体
└── 增加场景多样性（室内/室外/不同光线）
3. 注册到 CharacterRegistry
├── 网格图 → reference_images.grid
├── 面部中性 → reference_images.portrait
├── 表情 → reference_images.expressions
└── 运动姿态 → reference_images.sport_poses （新字段）
```
### 6.3 所需改动
| 改动点 | 文件 | 工作量 | 说明 |
|:------|:----|:------|:-----|
| Grid Method 升级 3x3 | `character_sheet.py` | 中 | 裁剪行列数、CELL_NAMES、GRID_PROMPT 模板 |
| 新增体育 prompt 模板 | `prompts/character_sheet_prompts.md` | 小 | 追加 3x3 模板 + 运动场景示例 |
| Registry 新字段 | `character_registry/registry.yaml` | 小 | 角色 schema 增加 sport_poses 字段 |
| 多姿态变体批量生成 | `character_sheet.py` | 中 | 对多个 cell 批量跑 I2I |
---
## 七、执行计划（审核后）
| 步骤 | 内容 | 预估耗时 |
|:----|:-----|:--------|
| 1 | 方案审核（你就是这里） | — |
| 2 | 升级 character_sheet.py：3x3 网格 + 体育模板 | ~30min |
| 3 | 生成男性角色（锋哥）定妆照 | ~5min（API 调用） |
| 4 | 生成女性角色（小雨）定妆照 | ~5min |
| 5 | Kling I2I 运动姿态变体批量生成 | ~10min × N |
| 6 | 注册到 CharacterRegistry | ~2min |
| 7 | 验证 Prompt 注入效果 | ~5min |
---
## 八、风险与备选
| 风险 | 概率 | 缓解方案 |
|:----|:----|:--------|
| Kling 文生图 3x3 网格排版不准 | 中 | 备选：先出 2x3 再手动补运动姿态格 |
| I2I 变体人脸偏离 | 中 | 重复调用强制 seed / 人工筛选最佳变体 |
| 运动姿态下服装细节丢失 | 低 | 描述块中强调颜色/logo/纹理细节 |
| API 调用费用 | 低 | 每张定妆照 ~¥0.3，总成本可控 <¥10 |
---
## 九、后续升级方向
- **LoRA 微调**：角色确认为长期 IP 后，用 15-20 张参考图训练 LoRA，一致性可提升至 90%+
- **Kling Image O1**：利用 Kling 的 Image O1 模式做更精细的角色控制（待评估）
- **即梦文生图备选**：Peekaboo 自动化方案可降低成本，质量略低
---
**请审核以上方案，确认后进入执行阶段。**
mac-agent-os-main/05_tools/09_ave/PLANS/STRATEGY.md
+92
View File
@@ -0,0 +1,92 @@
# AVE 视频工厂 — 策略体系 v1.0
> 最后更新: 2026-05-09 | 版本: v1.0
## 概述
将视频生产按策略分类, 每种策略有独立的输入/处理/输出管线。
生成时只需选择策略 + 提供内容素材, 系统自动路由到对应管线。
---
## 策略一览
### ① 口播策略 (当前可用 ✅)
| 项目 | 内容 |
|:-----|------|
| **输入** | 文案脚本 (YAML/TXT) |
| **核心流程** | 文案→CosyVoice TTS→Pexels素材搜索→mlx-audiocraft BGM→BGM避让→锚点画面切换→精确字幕→(可选)数字人片头片尾 |
| **CLI** | `python main.py generate --script xxx.yaml --bgm xxx.wav --duck --anchor-transitions` |
| **适用场景** | 知识分享、励志金句、故事讲述、教程讲解 |
| **输出** | 40-60s 竖屏视频, 1080p |
| **依赖** | 阿里云百炼(CosyVoice), Pexels, 火山引擎(OmniHuman 可选) |
### ② 卡点策略 (待开发 🔧)
| 项目 | 内容 |
|:-----|------|
| **输入** | BGM + 图片/视频素材列表 |
| **核心流程** | BGM→librosa节拍检测→按4拍/8拍分组→素材分配→拍点切换→xfade过渡→文字叠加 |
| **CLI** | `python main.py beat-sync --bgm xxx.wav --images img1.jpg img2.jpg` |
| **适用场景** | 卡点视频、节奏混剪、照片 Slideshow |
| **关键能力** | librosa beat_track 检测拍点; FFmpeg xfade ≤8段过渡 |
| **已知限制** | xfade 链 >10段 FFmpeg 崩溃, 需分组 ≤8段 |
### ③ 数字人策略 (部分可用 🔧)
| 子策略 | 能力 | API | 状态 |
|:-------|:-----|:----|:----:|
| **OmniHuman** | 头像图片 + 音频 → 对口型视频 | 火山引擎 CV API | ✅ 可用 |
| **DreamActor M1** | 照片 + 参考视频 → 动作模仿 | 火山引擎/即梦 API | 🔧 待接入 |
| **动作模仿流程** | 找参考视频 → 上传照片 → 提交 DreamActor → 下载结果 | — | 🔧 |
### ④ 模板策略 (调研中 🔍)
| 项目 | 内容 |
|:-----|------|
| **目标** | 程序化生成剪映草稿, 利用剪映模板/渲染能力 |
| **候选工具** | • pyJianYingDraft (Python 生成剪映草稿)<br>• cutcli (剪映草稿 CLI)<br>• CapCutAPI (完整剪映编程接口) |
| **思路** | AVE 生成草稿文件 → 剪映打开/CLI渲染 → 得到最终视频 |
| **优势** | 可复用剪映的丰富模板和特效 |
| **风险** | 剪映版本更新可能导致草稿格式变更 |
---
## 实施路线
```
P1: 卡点策略 (beat-sync) ✅ 已完成
├─ BGM 节拍检测器 (librosa)
├─ 拍点→素材调度器
├─ xfade 拍点过渡
└─ CLI 子命令
P2: DreamActor M1 接入 ✅ 已完成
├─ 参考视频上传 (Gitee中转仓库)
├─ 动作模仿 API 封装
├─ 结果下载 + 缓存
└─ 集成到数字人策略
P3: 视频工厂 CLI ⏳ 待开始
├─ 策略路由: video-factory --strategy 口播/卡点/数字人/模板
├─ 统一输入接口
└─ 进度报告
P4: 剪映模板集成 🔍 调研中
├─ pyJianYingDraft 调研
├─ 草稿生成器
├─ CLI 渲染
└─ 模板市场
```
## API 依赖汇总
| 服务 | 用途 | 费用 | 状态 |
|:-----|:-----|:----|:----:|
| 阿里云百炼 CosyVoice | TTS 人声合成 | 按量 | ✅ |
| Pexels | 视频素材搜索 | 免费(200次/h) | ✅ |
| 火山引擎 CV/即梦 | OmniHuman 数字人 | 按量 | ✅ |
| 火山引擎 即梦 | DreamActor M1 动作模仿 | 按量 | 🔧 |
| mlx-audiocraft | 本地 AI BGM 生成 | 免费 | ✅ |
| 剪映 (本地) | 模板渲染 | 免费 | 🔍 |
mac-agent-os-main/05_tools/09_ave/PLANS/TASK_TRACKER.md
+225
View File
@@ -0,0 +1,225 @@
# AVE 项目落地任务清单 · 跟踪看板
> 版本: v3.2-tracker | 最后更新: 2026-05-16
> 状态: ⬜ 待办 · 🔄 进行中 · ✅ 已完成 · 🚧 阻塞
---
## 使用方式
```diff
+ 每完成一项，把 ⬜ 改成 ✅
+ 每开始一项，把 ⬜ 改成 🔄
+ 遇到阻塞，把 ⬜ 改成 🚧 并在备注写原因
```
---
## Sprint 0 — 已完成的基建（不需要再做）
| # | 任务 | 状态 | 产出 |
|:-:|:----|:----:|:-----|
| 0.1 | Kling API 图生视频集成 | ✅ | `material_producer/kling/kling.py` |
| 0.2 | TTS (CosyVoice + 字级时间戳) | ✅ | `voice_synthesizer/aliyun.py` |
| 0.3 | Pexels 素材搜索 | ✅ | `material_producer/pexels/search.py` |
| 0.4 | BGM 混音 + 避让 | ✅ | `composer/ffmpeg.py` |
| 0.5 | ASS 字级字幕生成 | ✅ | `composer/ffmpeg.py` |
| 0.6 | 长视频自动分段 + concat | ✅ | `composer/ffmpeg.py` |
| 0.7 | 剧本解析 (LLM/模板) | ✅ | `director_parser/parser.py` |
| 0.8 | 口播策略 (video-factory) | ✅ | `video_factory.py` |
| 0.9 | 数字人策略 (Wan2.2 + DreamActor) | ✅ | `material_producer/wan2_2/` |
| 0.10 | 节拍检测 + xfade 卡点 | ✅ | `composer/beat_sync.py` |
| 0.11 | 成本跟踪器 | ✅ | `lib/cost_tracker.py` |
| 0.12 | 全域调研（角色一致性 + LipSync + 外部项目） | ✅ | 入库知识库 + `PLANS/AVE_V3_ARCHITECTURE.md` |
| 0.13 | AVE v3 全链路架构规划 | ✅ | `PLANS/AVE_V3_ARCHITECTURE.md` |
| 0.14 | Dashboard 生产监控面板方案设计 | ✅ | `PLANS/DASHBOARD_DESIGN.md` |
---
## Sprint 1 — P0 (核心增强，~1天)
### 1.1 角色一致性：定妆照 Grid Method
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 1.1.1 | 编写 Grid Method Prompt 模板（2x3多视角 + 多表情） | ✅ | `prompts/character_sheet_prompts.md` |
| 1.1.2 | 创建 `scripts/character_sheet.py`（定妆照自动生成模块） | ✅ | `scripts/character_sheet.py` |
| 1.1.3 | CLI 子命令 `python main.py character-sheet --desc "..." --output sheet.png` | ✅ | `main.py` 扩展 |
| 1.1.4 | YAML Schema 扩展：剧本增加 `character_ref` 字段 | ✅ | `director_parser/schemas.py` |
| 1.1.5 | 角色描述块锁定：全片自动注入固定角色描述 | ✅ | `composer/character_locker.py` |
**依赖**: 无（独立模块）
**验收标准**: 跑一个命令输出 2x3 网格定妆照 + 一个剧本能用 `character_ref` 引用角色
---
### 1.2 唇形同步：Kling LipSync 集成
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 1.2.1 | 创建 `scripts/composer/lipsync.py`（Kling LipSync API 封装） | ✅ | `scripts/composer/lipsync.py` |
| 1.2.2 | CLI 子命令 `python main.py lipsync --video clip.mp4 --audio voice.wav` | ✅ | `main.py` 扩展 |
| 1.2.3 | 口播策略后处理钩子：合成后自动跑 LipSync | ✅ | `video_factory.py` 扩展 |
| 1.2.4 | 成本跟踪对接 | ✅ | `lib/cost_tracker.py` 扩展 |
**依赖**: 需要 fal.ai API Key（$0.014/5s）
**验收标准**: 跑一个口播 production，输出视频带口型匹配
---
### 1.3 Dashboard 数据层（和 1.1/1.2 平行）
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 1.3.1 | SQLite schema 定义（6 表） | ✅ | `data/ave.db` (自动创建) |
| 1.3.2 | 创建 `scripts/lib/dashboard.py`（埋点封装） | ✅ | `scripts/lib/dashboard.py` |
| 1.3.3 | main.py 埋点：每次 production 自动写 DB（~50行） | ✅ | `main.py` + `video_factory.py` 扩展 |
| 1.3.4 | cost_tracker 埋点：自动记录费用 | ✅ | `lib/cost_tracker.py` 扩展 |
| 1.3.5 | FastAPI 后端骨架 + DB 读取 API | ✅ | `scripts/dashboard/app.py` |
**依赖**: 无（纯增量，和 P0 功能平行）
**验收标准**: 跑一条 production 后，SQLite 里有对应的 production + steps + cost 记录
---
## Sprint 2 — P1 (体验增强，~1天)
### 2.1 变速卡点引擎
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 2.1.1 | 创建 `scripts/composer/speed_ramp.py`（setpts + atempo 滤波器链） | ✅ | `scripts/composer/speed_ramp.py` |
| 2.1.2 | 支持缓变速度曲线（0.7→1.0→1.3） | ✅ | `speed_ramp.py` |
| 2.1.3 | CLI 子命令 `python main.py speed-ramp --input clip.mp4 --curve 0.5,1.0,1.5` | ✅ | `main.py` 扩展 |
| 2.1.4 | 卡点策略集成：高能段落自动变速 | ✅ | `video_factory.py` + `beat_sync.py` 扩展 |
**依赖**: 无
**验收标准**: ✅ 输入一段视频 + 速度曲线，输出变速后的视频（音频同步）
---
### 2.2 节拍检测升级（BeatSync-Engine 架构）
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 2.2.1 | 能量曲线 + 频谱特征提取（RMS/Flux） | ✅ | `composer/beat_sync.py` 增强 |
| 2.2.2 | 歌曲结构检测（Intro→Verse→Chorus→Bridge→Outro） | ✅ | `composer/beat_sync.py` 增强 |
| 2.2.3 | 能量波切密度（高能→加速，低能→减速） | ✅ | `composer/beat_sync.py` 增强 + `speed_ramp.py` |
| 2.2.4 | Frame-locked 时间线（消除 xfade 漂移） | ✅ | `composer/beat_sync.py` 增强 |
**依赖**: 无
**验收标准**: ✅ 对比升级前后的节拍匹配精确度
---
### 2.3 口播+卡点融合管线
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 2.3.1 | 创建 `scripts/composer/hybrid.py`（口播场景间插入变速卡点过渡） | ✅ | `scripts/composer/hybrid.py` |
| 2.3.2 | 过渡段自动匹配 BGM 节拍 | ✅ | `hybrid.py` |
| 2.3.3 | CLI 子命令 / video-factory 扩展 | ✅ | `main.py` + `video_factory.py` 扩展 |
**依赖**: 2.1.1 + 2.2.1
**验收标准**: ✅ 一个口播视频在高潮段落自动插入变速卡点过渡
---
## Sprint 3 — P2 (系统完善，~2天)
### 3.1 角色叙事策略
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 3.1.1 | 场景分解模块（剧本→N个场景 + 每场景Prompt） | ✅ | `scripts/story_director/scene_planner.py` |
| 3.1.2 | Temporal Bridge（上场景末帧→下场景首帧条件） | ✅ | `scripts/story_director/temporal_bridge.py` |
| 3.1.3 | 批量 Kling 生成（固定 seed + 角色描述块） | ✅ | `scripts/story_director/batch_generator.py` |
| 3.1.4 | story 策略 CLI + video-factory 入口 | ✅ | `main.py` + `video_factory.py` 扩展 |
| 3.1.5 | HoloCine 全局一致性策略参考实现 | ✅ | `scripts/story_director/HOLOCINE_REFERENCE.md` |
**依赖**: 1.1.1, 1.1.2, 1.1.3
**验收标准**: 输入一个多场景剧本 + 定妆照，输出一个带角色一致性的多场景视频
---
### 3.2 本地 Lip-Sync（LatentSync v1.5）
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 3.2.1 | 本地部署 LatentSync（Docker 或 venv） | ⬜ | `scripts/latentsync/` |
| 3.2.2 | AVE 集成接口（与 lipsync.py 统一接口） | ⬜ | `composer/lipsync.py` 扩展 |
| 3.2.3 | 自动切换：API 不可用时降级到本地 | ⬜ | `composer/lipsync.py` 扩展 |
**依赖**: 无，但需要 8GB VRAM
**验收标准**: 在本地 GPU 上跑通 LipSync
---
### 3.3 素材资产管理器
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 3.3.1 | 创建 `scripts/asset_manager/index.py`（素材索引） | ✅ | `scripts/asset_manager/index.py` |
| 3.3.2 | 缓存管理（Pexels/Kling 生成片段自动入索引） | ✅ | `scripts/asset_manager/cache.py` |
| 3.3.3 | 标签系统 + 搜索 | ✅ | `scripts/asset_manager/tags.py` |
**依赖**: 1.3.2（Dashboard 数据层）
**验收标准**: ✅ 搜索关键词能找到对应的历史素材（83 个素材已入库，21 个标签）
---
### 3.4 Dashboard 前端页面
| # | 子任务 | 状态 | 产出文件 |
|:-:|:-------|:----:|:---------|
| 3.4.1 | 生产列表页（筛/搜/排序） | ✅ | `dashboard/static/index.html` |
| 3.4.2 | 生产详情页（每步状态 + 资产 + 费用） | ✅ | `dashboard/static/index.html` (弹窗视图) |
| 3.4.3 | 资产浏览器（类型/标签筛选 + 搜索） | ✅ | `dashboard/static/index.html` |
| 3.4.4 | 费用分析（按策略 + 汇总） | ✅ | `dashboard/static/index.html` + `/api/costs/breakdown` |
| 3.4.5 | **系统级迁移**：Dashboard 从 AVE 迁至 `05_tools/10_dashboard/` | ✅ | 2026-05-16 插件框架落地 |
**依赖**: 1.3.5（后端 API）✅ 已完成
**验收标准**: ✅ 打开浏览器能看到所有 production 和数据
**⚠️ 架构变更**: Dashboard 已从 AVE 解耦为系统级模块
- 新路径: `05_tools/10_dashboard/` (插件式数据源架构)
- AVE 是第一个数据源插件 (`plugins/ave.py`)
- 兼容: `main.py dashboard` 命令自动重定向
---
## Sprint 4 — P3 (可选增强)
| # | 任务 | 状态 | 备注 |
|:-:|:----|:----:|:-----|
| 4.1 | LoRA 训练管线（CharForge / IC-LoRA） | ⬜ | 极高一致性需求时启用 |
| 4.2 | Wan2.2-S2V-14B 本地部署 | ⬜ | 需要 24-40GB VRAM，消费级显卡暂不支持 |
| 4.3 | ComfyUI 工作流导出支持 | ⬜ | 从 AVE 导出到 ComfyUI 编辑 |
| 4.4 | 即梦 VIP 自动化接入（Peekaboo） | ⬜ | 复用 Matrix 养号框架 |
| 4.5 | 多音色 TTS 库管理 | ⬜ | 管理多个 CosyVoice 音色 + 配音切换 |
---
## 快速参考：分策略状态总览
| 策略 | 当前状态 | Sprint 1 后 | Sprint 2 后 | Sprint 3 后 |
|:----|:--------:|:----------:|:----------:|:----------:|
| **口播** | ✅ 可用 | ✅ + 定妆照 + LipSync | ✅ + 变速过渡 | ✅ + 资产索引 + Dashboard |
| **卡点** | ✅ 可用 | ✅🔧 | ✅ 节拍升级 + 变速 + 帧锁定 | ✅ |
| **数字人** | ✅ 可用 | ✅ + LipSync 增强 | ✅ | ✅ |
| **口播+卡点** | ✅ 新增 | — | ✅ 融合管线 | ✅ |
| **角色叙事** | ❌ 不存在 | ❌ | ❌ | ✅ 初版可用 |
| **Dashboard** | ✅ 可用 | ✅ 数据层 + 前端 | ✅ 中文界面 | ✅ |
---
## 进度标记说明
```diff
+ ✅ 已完成 — 无需再关注
+ 🔄 进行中 — 正在开发
+ ⬜ 待办 — 计划内但未开始
+ 🚧 阻塞 — 等待前置条件
```
> 建议把这个文件放在 AVE 项目根目录，每次完成一项就更新状态。
> 或者你告诉我完成了哪项，我来帮你更新。
mac-agent-os-main/05_tools/09_ave/TOOL.md
+260
View File
@@ -0,0 +1,260 @@
# TOOL.md — AVE v3.0 (AudioScore Video Engine)
> **工具版本**: v3.0
> **接入日期**: 2026-05-04
> **最后更新**: 2026-05-09
> **维护者**: ghai
> **路径方案**: local.yaml + local_paths.py（无软链接，多机安全）
> **Python**: ~/.workbuddy/binaries/python/versions/3.13.12/
> **FFmpeg**: /opt/homebrew/bin/ffmpeg (v7.1.1)
---
## 一句话说明
通过**导演脚本**（YAML）驱动，自动完成文案→人声合成→素材搜索→背景音乐→渲染合成的全流程视频编排引擎。BGM 采用三阶路由：真实音乐库 → AI 生成 (mlx-audiocraft) → FFmpeg 和弦垫音。
---
## 依赖的 API 服务
| 服务 | 用途 | 费用 | 配置位置 |
|------|------|------|---------|
| 阿里云百炼 (CosyVoice) | 人声合成 | 按量付费 | agent-local/tools/ave/config/local.yaml |
| Pexels | 素材搜索 (视频) | 免费 (200次/小时) | 同上 |
| HuggingFace / hf-mirror | AI 模型下载 | 免费 | 环境变量 HF_ENDPOINT |
---
## 快速开始
```bash
cd 05_tools/09_ave/scripts/
# 人声合成
python main.py voice --text "测试文字" --output test.wav
# 素材搜索 (中文自动翻译英文)
python main.py material --search "日出云海" --count 3
# 背景音乐 (三阶路由自动选择)
python main.py bgm --mood calm --duration 60 # Tier 3: 和弦垫音
# AI BGM (需 pip install mlx-audiocraft, 首次下载模型)
HF_ENDPOINT=https://hf-mirror.com python main.py bgm --mood funny --duration 60 --use-mlx
# 全链路生成
python main.py generate --script director_script.yaml --output final.mp4 --clips-per-segment 2
# 全链路生成 + BGM
python main.py generate --script director_script.yaml --output final.mp4 --clips-per-segment 2 --bgm /path/to/bgm.wav
# 全链路生成 + BGM 避让 (说话音低→间隙恢复)
python main.py generate --script director_script.yaml --output final.mp4 --clips-per-segment 2 --bgm /path/to/bgm.wav --duck
# 全链路生成 + 锚点画面切换
python main.py generate --script director_script.yaml --output final.mp4 --clips-per-segment 2 --anchor-transitions
# 全链路生成 + BGM避让 + 锚点切换
python main.py generate --script director_script.yaml --output final.mp4 --clips-per-segment 2 --bgm /path/to/bgm.wav --duck --anchor-transitions
# 字幕 (默认开启, 基于 CosyVoice 字级时间戳精准对齐)
python main.py generate --script director_script.yaml --no-subtitles # 关闭字幕
# 数字人片尾
python main.py digital-human --image avatar.jpg --text "关注我，一起聆听世界，我们下期再见"
# 情绪参数测试
python main.py emotion-test --text "测试文本"
```
---
## 架构
```
YAML 导演脚本 ──→ main.py generate
│
┌────────────┼──────────────┐
▼ ▼ ▼
voice_synthesizer │ material_producer
CosyVoice TTS │ Pexels 搜索+缓存
│ │ │
└────────────┼──────────────┘
▼
bgm_generator (三阶路由)
┌───────┬───────┬──────────┐
▼ ▼ ▼ ▼
bgm_lib mlx- chord_pad composer/
(未启用) audiocra ft (备用) ffmpeg.py
ft (主) │
▼
final.mp4
```
## BGM 三阶路由 (v3.0)
| mood | prompt | BPM |
```
请求 BGM (mood, duration)
│
├─→ Tier 1: 音乐库 (有文件?) ─→ 载入 + 循环截取
│
├─→ Tier 2: mlx-audiocraft (--use-mlx) ─→ AI 生成 + 循环
│
└─→ Tier 3: chord_pad (默认) ─→ FFmpeg 和弦氛围音
```
### Tier 2: mlx-audiocraft
- 模型: `facebook/musicgen-small` (300M 参数)
- 安装: `pip install mlx-audiocraft`
- 首次: 下载 ~300MB 模型权重 (需 huggingface 或 hf-mirror.com)
- 速度: M1 上 10s 音乐 ~46s 生成
- Prompt 控制风格/乐器/BPM/节奏
- 国内用户需设置 `HF_ENDPOINT=https://hf-mirror.com`
- 代码中已自动检测并设置镜像
### Tier 3: chord_pad (离线保障)
- 文件: `scripts/bgm_generator/chord_pad.py`
- 原理: FFmpeg aevalsrc 生成多层 detuned 正弦波和弦
- 效果: 低通滤波 + 混响，产生温暖垫音
- 10种情绪预设: calm/soothing/happy/excited/sad/mystery/angry/professional/normal/funny/inspiring
- 速度: 即时生成
### 情绪→Prompt 映射
| mood | prompt | BPM |
|------|--------|:---:|
| calm | soft ambient piano, gentle pad, nature sounds, no percussion, no vocals | 60 |
| soothing | warm ambient drone, slow strings, peaceful atmosphere, no vocals | 50 |
| happy | bright ukulele, cheerful melody, acoustic guitar, no vocals | 90 |
| excited | upbeat electronic, driving beat, synth pads, no vocals | 120 |
| sad | melancholic piano, slow strings, emotional, no vocals | 55 |
| mystery | dark ambient, deep synth pad, suspenseful, no vocals | 60 |
| angry | intense orchestral, heavy drums, dramatic, no vocals | 110 |
| professional | corporate soft jazz, clean piano, polished, no vocals | 75 |
| funny | playful xylophone, quirky light music, cartoon style, no vocals | 100 |
| inspiring | uplifting cinematic, building strings, triumphant, no vocals | 85 |
| normal | soft background music, gentle, ambient, no vocals | 70 |
---
## 文件清单
```
05_tools/09_ave/
├── TOOL.md ← 本文件
├── director_script.yaml ← 演示脚本 (会打太极的猫)
├── requirements.txt.pip ← Python 依赖
├── scripts/
│ ├── main.py ← CLI 入口 (v1.1)
│ ├── anchor_extractor/ ← librosa 音频锚点
│ ├── bgm_generator/ ← BGM 三阶路由
│ │ ├── suno.py ← Tier 1-2-3 路由 + mlx-audiocraft
│ │ ├── chord_pad.py ← Tier 3 FFmpeg 和弦垫音
│ │ └── bgm_download.py ← BGM 库管理 (搁置)
│ ├── composer/
│ │ └── ffmpeg.py ← FFmpeg 合成/混音/字幕 (v1.1)
│ ├── director_parser/ ← 文案→YAML (oMLX + 降级)
│ ├── lib/ ← 通用库 (config/logger)
│ ├── material_producer/
│ │ └── pexels/
│ │ └── search.py ← Pexels 搜索 (v1.1, 中文翻译)
│ ├── service_layer/ ← API 服务层
│ └── voice_synthesizer/
│ ├── aliyun.py ← CosyVoice TTS
│ └── volcano.py ← 豆包语音 TTS (备用)
├── PLANS/ ← 规划文档
├── assets/ ← 资源
└── install.sh ← 安装
```
---
## 已知问题 & 修复记录
### 已修复
| 问题 | 修复 | 版本 |
|------|------|:----:|
| 视频时长 > 音频时长 (135s vs 53s) | composer/ffmpeg.py `compose_video`: 无条件加 `-shortest` | v1.1 |
| BGM 纯正弦波像杂音 | BGM v2: 和弦进行+低通+混响 | v2.0 |
| BGM 音量过低 (0.06) | suno.py: 移除生成时 volume 衰减; main.py: `bgm_volume=0.35` | v3.0 |
| Python UnboundLocalError | 移除函数内 `import os` / `from lib.config import load_config` | v1.1 |
| FFmpeg amix 语法错误 | 输入标签 `[0:a][1:a]` 直接拼接不用逗号 | v2.0 |
| 手动下载 BGM 效率低 | 改为 mlx-audiocraft AI 生成 (Tier 2 主方案) | v3.0 |
| **字幕不精确 (脚本时长 vs 实际人声)** | **aliyun.py `synthesize_with_timestamps()`: CosyVoice 字级时间戳对齐** | **v2.3** |
| **Callback 数据未收集** | **加 `wait_done()` 等待异步回调完成** | **v2.3** |
| **BGM 像杂音** | **V2 和弦垫音 (低通+混响) + mlx-audiocraft AI BGM** | v3.0 |
### 保留特性
- `--subtitles` 标志 (默认开启): 基于 CosyVoice 字级时间戳自动计算每段精确起止时间
- 时间戳回退: 字数不匹配时自动回落比例估算
- 字幕样式: 字号 = height × 4.4% (竖屏1080p→84px), 位置 = 底部上方20%, 描边3px
- `--duck` BGM 避让: 基于字级时间戳, 说话时 BGM=0.15, 间隙时 BGM=0.50, 300ms 过渡
- `--anchor-transitions` 锚点画面切换: librosa 检测静音段, 在切换点切换素材
- `--beat-sync` (v3.0): BGM 节拍检测 → 拍点切换素材 → xfade 过渡
- 费用追踪: `lib/cost_tracker.py` 每次 API 调用自动记录费用
## 文件中转仓库
即梦/火山引擎 API 需要图片/视频/音频的公网 HTTP URL。
```
仓库: [email protected]:babycalf/ghvideo.git
直链: https://gitee.com/babycalf/ghvideo/raw/master/{filename}
用途: 存储 API 调用所需的临时媒体文件
本地: agent-local/tools/ave/ghvideo/
上传: python lib/ghvideo_upload.py 文件1 文件2
```
## 策略体系 (v3.0)
视频工厂按 4 种策略组织, 生产时选择策略 + 提供内容即可:
```
请求: {策略, 内容素材}
│
├─→ 口播策略 ✅ (当前)
│ 文案 → TTS → Pexels素材 → BGM避让 → 锚点切换 → 精确字幕 → 数字人片头片尾
│ 适用: 知识分享、励志金句、故事讲述
│
├─→ 卡点策略 🔧 (待开发)
│ BGM → 节拍检测 → 素材/图片 → 拍点切换 → xfade过渡 → 文字叠加
│ 适用: 卡点视频、节奏混剪
│
├─→ 数字人策略 🔧 (待开发)
│ DreamActor M1: 照片 + 参考视频 → 动作模仿视频
│ OmniHuman: 头像 + 音频 → 对口型数字人
│ 适用: 数字人出镜、动作模仿
│
└─→ 模板策略 🔍 (调研中)
pyJianYingDraft/CapCutAPI → 程序化生成剪映草稿 → 渲染导出
适用: 批量生产、模板复用
```
### 各策略依赖
| 策略 | 核心依赖 | API | 状态 |
|:-----|:---------|:----|:----:|
| 口播 | CosyVoice + Pexels + mlx-audiocraft | 阿里云 + Pexels | ✅ 可用 |
| 卡点 | librosa + FFmpeg xfade | 无 | ✅ P1 完成 |
| 数字人 | OmniHuman / DreamActor M1 | 火山引擎 | ✅ OmniHuman + DreamActor 均已可用 |
| 模板 | pyJianYingDraft / CapCutAPI | 无(本地剪映) | 🔍 调研中 |
### 实施优先级
| 阶段 | 内容 | 状态 |
|:----|:-----|:----:|
| P1 | beat-sync 卡点模式 | ✅ 完成 |
| P2 | DreamActor M1 动作模仿接入 | ✅ 完成 |
| P3 | 视频工厂 CLI (策略路由) | ✅ 完成 |
| P4 | 剪映模板集成 | 🔍 调研中 |
### 待优化
- 生成速度: mlx-audiocraft 在 M1 上 10s 需 ~46s (~4.7x)
- 视频分段渲染: 3分钟以上自动分段 (composer 已有代码，未充分测试)
- 字幕叠加: ASS 字幕 (composer 已有代码，generate 未启用)
- 锚点提取: librosa 模块 (目前未集成到全链路)
mac-agent-os-main/05_tools/09_ave/assets/demo_scripts/cat_tai_chi.txt
+22
View File
@@ -0,0 +1,22 @@
# AVE 演示脚本：一个小笑话
# 用于验证 MVP 链路 (文案→人声→素材→合成)
标题: "一只会打太极的猫"
今天我要讲一个真实的故事。
我家养了一只橘猫，名字叫"大橘"。
大橘有个奇怪的爱好——每天早上六点，它会准时蹲在阳台的瑜伽垫上，开始打太极。
你没听错，打太极。
一开始我以为它在伸懒腰，后来发现不对劲。它的动作实在太标准了——野马分鬃、白鹤亮翅、搂膝拗步，一套下来行云流水。
更离谱的是，如果你在它练功的时候打扰它，它会瞪你一眼，然后换个地方继续打。
后来我调了监控才发现，它是在偷看我奶奶晨练，看了一年，学会了。
现在大橘在我们小区已经出名了，每天早上都有人专门来看它打太极。
所以下次有人说"猫不如狗聪明"，你就告诉他：有一种猫，比你还会养生。
mac-agent-os-main/05_tools/09_ave/config.yaml
+77
View File
@@ -0,0 +1,77 @@
# AVE v2.0 配置文件模板
# 复制到 agent-local/tools/ave/config/local.yaml 并填入真实值
# === 火山引擎 (豆包语音 2.0) ===
volcano:
api_key: "sk-xxx" # ARK → API Key 管理
app_id: "xxx" # 语音控制台 → App ID
access_token: "xxx" # 语音控制台 → Access Token
speaker_id: "xxx" # 声音复刻 → 训练后获取
tts_model: "volcano_tts_2.0"
# === 阿里云百炼 ===
aliyun:
api_key: "sk-xxx" # 百炼 → API Key
wan_model: "wan2.2-s2v"
# TTS 模型（实测可用的只有 4 个）：
# cosyvoice-v3-flash ← 推荐（支持 88 个音色，含全部 _v3 后缀音色）
# cosyvoice-v3-plus （只支持 longanyang / longanhuan 两个音色）
# cosyvoice-v2 / cosyvoice-v1
# ⚠️ 音色必须与模型匹配，否则报 InvalidParameter(418)；音色目录见
# 09_ave/config/cosyvoice_voices.yaml
cosyvoice_model: "cosyvoice-v3-flash"
# === Pexels ===
pexels:
api_key: "xxx" # Pexels API Dashboard
rate_limit: 200 # 请求/小时
# === 大模型 (文案解析) ===
llm:
provider: "openai" # openai | deepseek | volc
api_key: "sk-xxx"
base_url: "https://api.deepseek.com" # 或 openai/volc 地址
model: "deepseek-chat" # 或 gpt-4o / doubao-pro
# === 输出设置 ===
output:
resolution: "1080x1920" # 竖屏
fps: 30
codec: "h264"
bitrate: "8M"
# === 缓存 ===
cache:
enabled: true
max_size_gb: 10
ttl_days: 7
# === 人物置换 (person_swap, 阿里云百炼 Wan2.2-Animate-Mix 视频换人) ===
# 用途: 原视频(人物A动作+场景) + 参考图(人物B形象) → 输出「B 保留动作与场景」的新视频
# 官方模型: wan2.2-animate-mix (2026-10-02 实测校准: 接口 image2video/video-synthesis,
# 字段 input.image_url / input.video_url / parameters.mode)
person_swap:
model: "wan2.2-animate-mix" # 官方模型 id (换人; 另有 wan2.2-animate-move 图生动作)
mode: "std" # 档位: std(¥0.6/秒) | pro(增强版 ¥0.9/秒)
price_per_sec: 0.6 # 单价 元/秒 (std 官方价; pro 改 0.9)
max_duration: 10 # 单条源视频最长秒数(超长自动截取; 按模型支持范围调整)
image_max_side: 2048 # 参考图长边上限
monthly_budget: 300.0 # 月度费用护栏(元), 超预算拒绝新任务
max_retries: 2 # 生成失败自动重试次数(损耗系数 ~1.4 由预算兜底)
timeout_sec: 900 # 单次生成轮询上限(秒)
# ── 可灵 AI（Kling）──
# 用途: 定妆照/角色图 文生图、图生图（character_sheet.py provider=kling）
# 鉴权两种方式二选一（api_key 优先）:
# api_key : Bearer 方式（新版/第三方发放 key，格式 api-key-kling-xxx）
# access_key + secret_key : 官方 AK/SK（JWT HS256 签名）
# ⚠️ 真实密钥放 agent-local/tools/ave/config/local.yaml（不同步、不进 git），此处仅占位
# 接口: POST {base_url}/v1/images/generations（异步任务）→ GET .../{task_id} 查询
kling:
api_key: "" # Bearer key（优先）
access_key: "" # 官方 AK（回退 JWT 方式）
secret_key: "" # 官方 SK（回退 JWT 方式）
base_url: "https://api-beijing.klingai.com"
default_model: "kling-v1" # 文生图模型
poll_interval: 5 # 任务轮询间隔(秒)
timeout_sec: 300 # 单任务轮询上限(秒)
mac-agent-os-main/05_tools/09_ave/config/capabilities.yaml
+1601
View File
File diff suppressed because it is too large Load Diff
mac-agent-os-main/05_tools/09_ave/config/cosyvoice_voices.yaml
+115
View File
@@ -0,0 +1,115 @@
# CosyVoice 官方音色目录（音色库「从官方挑选」用）
# =====================================================================
# 来源：https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
# 抓取：2026-10-02 · 模型：cosyvoice-v3.5-plus（配置 aliyun.cosyvoice_model）
# 用法：音色库页面点「＋ 从官方挑选」→ 选一个 → 自动建音色资产（填 provider_voice_id）
#
# 注意：每个模型仅支持一组特定音色，不可跨模型混用；文本语言须在该音色支持范围内。
# =====================================================================
provider: aliyun-cosyvoice
model: cosyvoice-v3-flash
source: https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
# ⚠️ 音色必须与模型匹配（实测 2026-10-02）：
# cosyvoice-v3-flash 支持 88 个音色（含全部 _v3 后缀）← 用这个
# cosyvoice-v3-plus 仅支持 longanyang / longanhuan
# 不匹配会报 InvalidParameter(418)
# 角色分配建议（供 UI 提示）
pools:
male_lead: [longanyang, longanlang_v3, longyichen_v3, longze_v3]
male_mature: [longtian_v3, longsanshu_v3, longhao_v3, longanzhi_v3]
female_lead: [longxiaochun_v3, longhua_v3, longxing_v3, longanwen_v3]
female_charm: [longqiang_v3, longyue_v3, longanyan_v3]
extra_male: [longze_v3, longzhe_v3, longanlang_v3]
extra_female: [longxing_v3, longmiao_v3, longanqin_v3]
narrator: [longxiu_v3, longshuo_v3, longyue_v3]
groups:
- id: male
name: 男声
voices:
- {name: 龙安洋, voice_id: longanyang, trait: 阳光大男孩, age: "20~30", tags: [年轻男主]}
- {name: 龙安朗, voice_id: longanlang_v3, trait: 清爽利落男, age: "20~25"}
- {name: 龙逸尘, voice_id: longyichen_v3, trait: 洒脱活力男, age: "20~30"}
- {name: 龙泽, voice_id: longze_v3, trait: 温暖元气男, age: "25~30"}
- {name: 龙哲, voice_id: longzhe_v3, trait: 呆板大暖男, age: "25~30"}
- {name: 龙安昀, voice_id: longanyun_v3, trait: 居家暖男, age: "30~35"}
- {name: 龙天, voice_id: longtian_v3, trait: 磁性理智男, age: "30~35", tags: [成熟男主]}
- {name: 龙浩, voice_id: longhao_v3, trait: 多情忧郁男, age: "30~35"}
- {name: 龙寒, voice_id: longhan_v3, trait: 温暖痴情男, age: "30~35"}
- {name: 龙安智, voice_id: longanzhi_v3, trait: 睿智轻熟男, age: "25~35"}
- {name: 龙三叔, voice_id: longsanshu_v3, trait: 沉稳质感男, age: "25~45", tags: [中年]}
- {name: 龙硕, voice_id: longshuo_v3, trait: 博才干练男, age: "25~30"}
- {name: 龙修, voice_id: longxiu_v3, trait: 博才说书男, age: "25~35", tags: [旁白]}
- {name: 龙机器, voice_id: longjiqi_v3, trait: 呆萌机器人, age: "20~30", tags: [特殊]}
- {name: 龙猴哥, voice_id: longhouge_v3, trait: 经典猴哥, age: "20~25", tags: [特殊]}
- id: female
name: 女声
voices:
- {name: 龙小淳, voice_id: longxiaochun_v3, trait: 知性积极女, age: "25~30", tags: [女主角, 通用]}
- {name: 龙小夏, voice_id: longxiaoxia_v3, trait: 沉稳权威女, age: "25~30"}
- {name: 龙华, voice_id: longhua_v3, trait: 元气甜美女, age: "20~25", tags: [年轻女主]}
- {name: 龙星, voice_id: longxing_v3, trait: 温婉邻家女, age: "20~25"}
- {name: 龙安亲, voice_id: longanqin_v3, trait: 亲和活泼女, age: "20~25"}
- {name: 龙菲菲, voice_id: longfeifei_v3, trait: 甜美娇气女, age: "20~25"}
- {name: 龙安欢, voice_id: longanhuan_v3, trait: 欢脱元气女, age: "20~30"}
- {name: 龙安灵, voice_id: longanling_v3, trait: 思维灵动女, age: "20~30"}
- {name: 龙婉, voice_id: longwan_v3, trait: 细腻柔声女, age: "20~30"}
- {name: 龙婉君, voice_id: longwanjun_v3, trait: 细腻柔声女, age: "20~30"}
- {name: 龙安柔, voice_id: longanrou_v3, trait: 温柔闺蜜女, age: "20~35"}
- {name: 龙应沐, voice_id: longyingmu_v3, trait: 优雅知性女, age: "25~30"}
- {name: 龙应聆, voice_id: longyingling_v3, trait: 温和共情女, age: "25~30"}
- {name: 龙应桃, voice_id: longyingtao_v3, trait: 温柔淡定女, age: "25~30"}
- {name: 龙应静, voice_id: longyingjing_v3, trait: 低调冷静女, age: "25~35"}
- {name: 龙安温, voice_id: longanwen_v3, trait: 优雅知性女, age: "25~35"}
- {name: 龙安雅, voice_id: longanya_v3, trait: 高雅气质女, age: "25~35"}
- {name: 龙安莉, voice_id: longanli_v3, trait: 利落从容女, age: "25~35"}
- {name: 龙妙, voice_id: longmiao_v3, trait: 抑扬顿挫女, age: "25~30"}
- {name: 龙颜, voice_id: longyan_v3, trait: 温暖春风女, age: "30~35"}
- {name: 龙悦, voice_id: longyue_v3, trait: 温暖磁性女, age: "30~35", tags: [旁白]}
- {name: 龙嫱, voice_id: longqiang_v3, trait: 浪漫风情女, age: "30~35", tags: [御姐, 魅惑]}
- {name: 龙媛, voice_id: longyuan_v3, trait: 温暖治愈女, age: "35~40"}
- {name: 龙安燃, voice_id: longanran_v3, trait: 活泼质感女, age: "30~40"}
- {name: 龙安宣, voice_id: longanxuan_v3, trait: 经典直播女, age: "30~40"}
- {name: 龙安台, voice_id: longantai_v3, trait: 嗲甜台湾女, age: "20~25"}
- {name: 龙应笑, voice_id: longyingxiao_v3, trait: 清甜推销女, age: "20~25"}
- id: child
name: 童声
voices:
- {name: 龙呼呼, voice_id: longhuhu_v3, trait: 天真烂漫女童, age: "6~10"}
- {name: 龙泡泡, voice_id: longpaopao_v3, trait: 飞天泡泡音, age: "6~15"}
- {name: 龙杰力豆, voice_id: longjielidou_v3, trait: 阳光顽皮男, age: "10"}
- {name: 龙仙, voice_id: longxian_v3, trait: 豪放可爱女, age: "12"}
- {name: 龙铃, voice_id: longling_v3, trait: 稚气呆板女, age: "10"}
- {name: 龙闪闪, voice_id: longshanshan_v3, trait: 戏剧化童声, age: "6~15"}
- {name: 龙牛牛, voice_id: longniuniu_v3, trait: 阳光男童声, age: "6~15"}
- id: dialect
name: 方言
voices:
- {name: 龙嘉欣, voice_id: longjiaxin_v3, trait: 优雅粤语女, age: "30~35", lang: 粤语}
- {name: 龙嘉怡, voice_id: longjiayi_v3, trait: 知性粤语女, age: "25~30", lang: 粤语}
- {name: 龙安粤, voice_id: longanyue_v3, trait: 欢脱粤语男, age: "25~35", lang: 粤语}
- {name: 龙老铁, voice_id: longlaotie_v3, trait: 东北直率男, age: "25~30", lang: 东北话}
- {name: 龙陕哥, voice_id: longshange_v3, trait: 原味陕北男, age: "25~35", lang: 陕西话}
- {name: 龙安闽, voice_id: longanmin_v3, trait: 清纯萝莉女, age: "18~25", lang: 闽南话}
- id: foreign
name: 外语（出海）
voices:
- {name: loongriko, voice_id: loongriko_v3, trait: 二次元霓虹女, age: "18~25", lang: 日语}
- {name: loongtomoka, voice_id: loongtomoka_v3, trait: 日语女, age: "30~35", lang: 日语}
- {name: loongtomoya, voice_id: loongtomoya_v3, trait: 日语男, age: "30~35", lang: 日语}
- {name: Jihun, voice_id: loongjihun_v3, trait: 韩语男, age: "25~30", lang: 韩语}
- {name: loongkyong, voice_id: loongkyong_v3, trait: 韩语女, age: "25~30", lang: 韩语}
- {name: loongabby, voice_id: loongabby_v3, trait: 美式英文女, age: "30~35", lang: 英语}
- {name: loongandy, voice_id: loongandy_v3, trait: 美式英文男, age: "30~35", lang: 英语}
- {name: loongindah, voice_id: loongindah_v3, trait: 印尼女, age: "22~27", lang: 印尼语}
# 火山引擎备用音色（voice_type 格式，供 reference）
volcano_default:
- {name: 火山-通用女声, voice_type: BV001_V2, trait: 通用女声}
- {name: 火山-通用男声, voice_type: BV002_streaming, trait: 通用男声}
mac-agent-os-main/05_tools/09_ave/config/creative_matrix.yaml
+199
View File
@@ -0,0 +1,199 @@
# 创意矩阵配置（GapEngine）— 负面/正向/道具场景 + 生成参数
# =====================================================================
# 来源：GapEngine 设计（2026-10-02 讨论）原文内容，整理为可编辑配置。
#
# 用法：创意工坊的 ②负面矩阵 / ③正向矩阵 / ④道具场景 三个标签页读写本文件；
# ⑤生成&筛选 依据 negative 硬过滤、positive 加权、generation 控制条数。
# 维护：可直接编辑；也可以把不同模式另存为 presets 下的一套（如"肛肠科反差模式"）。
# =====================================================================
version: '1.0'
updated: '2026-10-02'
# ── 生成参数 ──────────────────────────────────────────────
generation:
candidates_per_round: 30 # 每轮候选条数（默认 30，AI 按规则推荐一轮）
max_params_per_layer: 2 # 每层最多选中的参数数（原文约束；0 = 不限制）
min_params_total: 2 # 少于该数量无法计算缺口（原文 app.py 校验）
# ── 负面矩阵（勾选排除）────────────────────────────────────
# hard = 🔴 平台硬违禁：默认锁死，不参与创意（locked: true 表示不可放开）
# soft = 🟡 观众反感：默认全部排除，允许放开某一项来制造反差（relaxed: true 表示已放开）
negative:
hard:
- id: politics
name: 政治敏感
detail: 国家象征标志不规范使用、歪曲解读政策、不当关联政治事件营销
locked: true
- id: porn
name: 色情低俗
detail: 淫秽色情内容、性暗示、擦边球文案
locked: true
- id: violence
name: 暴力恐怖
detail: 血腥暴力、恐怖主义、教唆犯罪
locked: true
- id: gambling_drug
name: 赌博毒品
detail: 赌博、毒品、违禁药物
locked: true
- id: superstition
name: 迷信荒诞
detail: 封建迷信、荒诞不经的内容
locked: true
- id: false_claim
name: 虚假宣传
detail: 弄虚作假、夸大功效、绝对化用语（"最""第一""国家级"等）
locked: true
- id: medical_violation
name: 医疗违规
detail: 医疗功效词、未标注"演绎"的诊疗场景、以医生身份带货
locked: true
soft:
- id: anxiety
name: 贩卖焦虑
detail: 容貌焦虑、年龄焦虑、职场内卷焦虑
relaxed: false
hint: 泰国广告的反差恰恰建立在"先制造焦虑，再反转消解"上——放开此项可做此类反差
- id: division
name: 制造对立
detail: 地域对立、性别对立、身份对立
relaxed: false
hint: 放开此项可做"对立→和解"的反转
- id: emotional_coercion
name: 情绪勒索
detail: '"不转不是中国人" "你忍心看着…" 等强制情感绑架'
relaxed: false
hint: 放开可做"反套路"嘲讽
- id: misery
name: 过度卖惨
detail: 医疗卖惨、贫穷卖惨、残障卖惨
relaxed: false
hint: 医疗题材放开此项，可做"惨到好笑"的反差
- id: petty_bourgeois
name: 小资情结
detail: 刻意精致、脱离现实的生活展示
relaxed: false
hint: 放开可做"精致破产"的反差
- id: caustic
name: 尖酸刻薄
detail: 以嘲讽弱者为乐、居高临下的幽默
relaxed: false
hint: 放开可做"刻薄者反被刻薄"的反转
- id: cunning_honest
name: 老实人精明
detail: 表面老实实则算计的叙事模式
relaxed: false
hint: 放开可做"精明者失算"的反转
- id: preachy
name: 油腻说教
detail: 居高临下的人生道理、爹味说教
relaxed: false
hint: 放开可做"说教者出丑"的反转
- id: exaggeration
name: 极端夸张
detail: 脱离物理常识的夸张表现
relaxed: false
hint: 泰国广告核心手法之一——放开此项才能做极限夸张，但需控制尺度
# ── 正向矩阵（勾选引入，命中时给缺口分加成）─────────────────
positive:
- id: warm_twist
name: 温情反转
detail: 先制造误解或冲突，结尾转向温暖
bonus: 10
- id: self_mockery
name: 幽默自嘲
detail: 角色嘲笑自己的处境，而非嘲笑他人
bonus: 8
- id: ordinary_hero
name: 平凡英雄
detail: 普通人做出不平凡的小事
bonus: 8
- id: anti_cliche
name: 反套路认知
detail: 颠覆观众对某类人的刻板印象
bonus: 12
- id: warm_stranger
name: 温暖陌生人
detail: 陌生人之间的善意互动
bonus: 8
- id: reconciliation
name: 和解与释然
detail: 冲突最终走向理解而非对抗
bonus: 10
# ── 道具变量库（勾选可用；AI 推荐 + 手动增选）────────────────
props:
- id: childlike
name: 童趣道具
examples: [卡通玩偶, 棒棒糖, 气球]
contrast: 严肃场景 × 童趣道具 = 荒诞温情
- id: tech
name: 科技道具
examples: [手机, 智能手表, 耳机]
contrast: 日常场景 × 科技介入 = 现代荒诞
- id: wealth
name: 财富符号
examples: [股票软件, 豪车钥匙, 名表]
contrast: 平凡角色 × 财富符号 = 身份反差
- id: medical
name: 医疗道具
examples: [病历本, 输液架, 病号服]
contrast: 常规道具 × 非常规使用 = 叙事转折
- id: daily
name: 日常小物
examples: [咖啡杯, 雨伞, 钥匙]
contrast: 日常物件 × 特殊时刻 = 情感锚点
- id: symbol
name: 象征物（隐喻用）
examples: [地震, 潮水, 风暴, 种子, 齿轮, 流水线, 监控, 牢笼, 笼中鸟, 茧, 飞蛾, 镜子, 雨伞, 闹钟, 门]
contrast: 抽象主题 × 具体物象 = 观众自己完成的那次替代
# ── 场景变量库 ─────────────────────────────────────────────
scenes:
- id: space
name: 空间反差
examples: [病房vs豪宅, 诊室vs演唱会]
contrast: 空间错位制造荒诞
- id: time
name: 时间反差
examples: [白天vs深夜, 术前vs术后]
contrast: 时间跳跃制造悬念
- id: weather
name: 天气反差
examples: [晴天vs暴雨, 室内vs室外]
contrast: 环境变化推动情绪转折
- id: social
name: 社交反差
examples: [独处vs人群, 熟人vs陌生人]
contrast: 社交密度变化制造戏剧张力
# ── 预设矩阵配置（多套可切换）──────────────────────────────
# 使用某套 preset 时，soft 项的 relaxed / positive 勾选 / props / scenes 按此覆盖。
presets:
- id: conservative
name: 保守模式（默认）
soft_relaxed: []
positive: [warm_twist, self_mockery]
props: []
scenes: []
- id: contrast
name: 反差模式
soft_relaxed: [exaggeration, anxiety]
positive: [warm_twist, anti_cliche]
props: [childlike, medical]
scenes: [space, time]
# ── 与六层参数的联动规则（供生成器参考）────────────────────
linkage:
- when: {layer: narrative, param: conflict_type, value: 认知反转}
recommend: {props: [childlike], note: 用童趣道具作为反转触发器}
- when: {layer: visual, param: shot_size, value: 特写}
recommend: {props: [daily], note: 用道具特写作为转场锚点}
- when: {layer: rhetoric, param: expression_mode, value: 暗喻}
recommend: {props: [symbol], note: 从象征物里挑一个作喻体，被比喻的事始终不出现}
- when: {layer: rhetoric, param: vehicle_source, value: 自然现象}
recommend: {props: [symbol], note: 自然类喻体：地震 / 潮水 / 风暴 / 干旱}
- when: {layer: rhetoric, param: mapping, value: 整体寓言}
recommend: {props: [symbol], note: 全片围绕一个喻体展开，不得中途切回写实}
mac-agent-os-main/05_tools/09_ave/config/feasibility_rules.yaml
+372
View File
@@ -0,0 +1,372 @@
# 可行性规则库 — 技术优选层的规则源（v1.0 / 2026-10-02）
# =====================================================================
# 用途：
# 导演产出分镜后，capability_matcher 用本规则库做「技术需求 → 能力匹配 → 缺口报告」。
# 规则分三级：blocking（必须解决）/ warning（风险提示）/ info（建议）。
#
# 维护：
# 能力建设完成后改对应 capability_needs[].status（missing → ready），
# 技术方案检测到版本变化会自动标记「可升级」，无需改分镜。
# =====================================================================
version: '1.1'
updated: '2026-10-02'
# ── 引擎时长档位对照（规则 duration_over_single_limit 的判定依据）──────
# 本项目默认引擎=可灵；接入其他引擎时按此表调整上限
engine_duration_limits:
kling: {single_max: 10, slots: [5, 10], note: 可灵 kling-v3 档位 5s/10s}
wan: {single_max: 10, slots: [5, 10], note: 通义万相}
seedance_2_5: {single_max: 30, slots: [4, 30], note: '官方：单条 4–30s，无 1080p；超长模式 30–180s；延长累计 ≤60s'}
seedance_2_0: {single_max: 15, slots: [4, 15], note: '官方：单条 4–15s，可 1080p/4K（15s 时）'}
# ── 能力需求映射（缺口清单的来源）──────────────────────────────
# status: missing（能力目录中无对应实现）/ planned（已登记未实现）/ ready（可用）
capability_needs:
frame_chain:
name: 首尾帧衔接
capability_id: frame_chain
status: partial
note: 长镜头接续 / 无缝延续 / 跨生成单元拼接。
可行路径：可灵/万相首尾帧(kf2v) 或 分段生成+取尾帧作下一段参考。当前能力目录无此项。
expression_consistency:
name: 表情微管理
capability_id: null
status: missing
note: 跨镜表情延续（眼神/嘴部/眉宇一致）。当前仅有 expression_detail 字段靠提示词描述，
无独立能力；精细控制需接 ComfyUI 或专用表情迁移模型。
vfx_apply:
name: 视频特效
capability_id: vfx_apply
status: planned
note: 可灵 camera_control 已部分可用（环绕/子弹时间/慢动作/焦点锁定）；更多特效待接入。
character_3d:
name: 3D 角色
capability_id: character_3d
status: planned
note: 混元3D，未接入。
comfyui_workflow:
name: ComfyUI 工作流
capability_id: comfyui_workflow
status: planned
note: RunningHub / ComfyDeploy，未接入。
lipsync:
name: 对口型
capability_id: lipsync
status: partial
note: 代码就绪（fal.ai Kling Lipsync），缺 fal.api_key；火山 OmniHuman 可用。
person_swap:
name: 人物置换
capability_id: person_swap
status: partial
note: 百炼 wan2.2-animate-mix 已校准（std/pro），待真实样片验证。
character_card_seven_dim:
name: 七维角色卡 + 三格出图
capability_id: character_lock
status: partial
note: '现有角色锁定（固定描述块+seed+参考图）已具备雏形；Seedance 方法论要求更严：
七维公式[年龄/种族+肤色质感+面部细节(≥3-4点)+眼神+发型+服装+体型/气质]、
三格出图(一张图三格=同一次噪声=同一个人；格2去头让全图唯一脸源=格1大特写)、
皮肤强制后缀"保留真实的微细毛孔与肌肤纹理"。待纳入角色生成器。'
voice_lock:
name: 声线锁
capability_id: voice_lock
status: ready
note: 'TTS 已可按角色固定音色；方法论要求更严：声线锁逐字复用、连近义词都不换、
外观变体(湿身/带伤/换装)不换锁；群演不逐人建档(人群是一个资产，超15人塌缩)。'
long_video_extend:
name: 超长/视频延长
capability_id: frame_chain
status: missing
note: 底片 ≤30s，单次延长 4–30s，累计 ≤60s（Seedance 2.5 特例通道）。依赖首尾帧衔接能力。
# ── 规则清单 ────────────────────────────────────────────────────
rules:
# ═══ 时长 / 接续 ═══
- id: duration_over_single_limit
name: 单镜时长超生成上限
level: blocking
nature: yellow
trigger: {type: shot_duration_over, value: 10}
problem: 单次视频生成上限 10 秒（可灵/万相档位 5s/10s）
action: 切成两条并在接缝声明接续（chain_from_prev），或压缩到 10 秒内
need: frame_chain
- id: duration_over_5s_complex
name: 超 5 秒且动作幅度大
level: warning
nature: yellow
trigger: {type: duration_and_motion, duration_over: 5, motion_in: [medium, large]}
problem: 长时长 + 大幅动作，角色变形/闪烁风险高
action: 优先 5 秒档；必要时拆分动作节拍，或改用 10 秒档并接受重试损耗
need: null
- id: text_exceeds_duration
name: 台词超出时长容量
level: warning
nature: yellow
trigger: {type: text_fit, chars_per_sec: 4.5}
problem: 台词字数按语速估算需要更长时间，会被截断或语速过快
action: 加长该镜时长（≤10s）或切分台词到下一镜
need: null
# ═══ 一致性需求（缺口驱动）═══
- id: need_frame_chain
name: 要求承接上一镜尾帧（长镜接续）
level: blocking
nature: yellow
trigger: {type: tech_flag, field: chain_from_prev, value: true}
problem: 当前无「首尾帧衔接」能力，无法保证无缝接续
action: 建设该能力（首尾帧 kf2v / 分段+尾帧参考），或改成硬切分镜
need: frame_chain
- id: need_expression_consistency
name: 要求跨镜表情一致
level: blocking
nature: yellow
trigger: {type: tech_continuity, field: expression, values: [must, prefer]}
problem: 无「表情微管理」能力，跨镜表情延续不可控
action: 建设表情一致性能力（ComfyUI/表情迁移），或降级为"不要求"
need: expression_consistency
- id: need_character_consistency
name: 要求跨镜角色一致
level: info
nature: yellow
trigger: {type: tech_continuity, field: character, values: [must, prefer]}
problem: ""
action: 使用「角色锁定」能力（固定描述块 + seed + 参考图绑定）
need: null # 已有能力，满足
- id: need_location_consistency
name: 要求跨镜场景一致
level: info
nature: yellow
trigger: {type: tech_continuity, field: location, values: [must, prefer]}
problem: ""
action: 使用场地资产 + 首帧参考（部分依赖 frame_chain 才能完全无缝）
need: null
# ═══ 特效 / 运镜 / 特殊需求 ═══
- id: need_vfx
name: 需要视频特效
level: warning
nature: yellow
trigger: {type: shot_or_need, shot_type: vfx, need_keywords: [特效, 子弹时间, 环绕, 慢动作, 焦点锁定, 变速]}
problem: vfx_apply 能力为 planned，仅可灵 camera_control 部分可用
action: 用可灵运镜参数承载（环绕/子弹时间/慢动作/焦点锁定），其余待能力建设
need: vfx_apply
- id: camera_complex
name: 复杂运镜调度
level: warning
nature: yellow
trigger: {type: tech_flag, field: camera_difficulty, value: complex}
problem: 复杂调度（环绕/跟拍/多段运镜合一）单次生成成功率低
action: 拆成多个简单运镜的条，或接受重试损耗
need: null
- id: need_hand_closeup
name: 手部特写/精细手部动作
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [手部特写, 手部动作, 拿取细节, 手指]}
problem: 手部是最易变形区域，特写下更明显
action: 降低手部占比或改为中近景；必要时接受局部重绘
need: null
- id: need_on_screen_text
name: 画面内文字/LOGO
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [画面文字, 字幕特效, LOGO, 招牌, 书籍文字]}
problem: 视频模型对画面内文字渲染不稳定（易乱码）
action: 文字改为后期叠加（字幕能力），画面内避免依赖文字
need: null
- id: need_multi_person
name: 多人同框互动
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [多人, 双人互动, 对话双方, 群像]}
problem: 多人一致性/交互稳定性差
action: 减少同框人数或用正反打（单人对镜）替代同框
need: null
# ═══ 合规红线 ═══
- id: real_person_authorization
name: 真人肖像未授权
level: blocking
nature: red
trigger: {type: manual_check}
problem: 使用真人肖像（含真人参考图/人物置换）必须有书面授权
action: 在授权登记中登记后放行；未授权不得生成
need: null
- id: platform_restricted
name: 平台禁限内容
level: blocking
nature: red
trigger: {type: manual_check}
problem: 暴力/色情/政治敏感等平台禁限内容会被拒绝或封号
action: 停下报告用户，不自行改写规避
need: null
# ══════════════════════════════════════════════════════════════
# v1.1 追加 — 来自 Seedance 方法论卡片（hongxian / moxinglei / leiqu）
#
# nature 三色分性质（对应 Seedance 审核体系）：
# red = 绝对红线（法律/平台硬禁）→ 命中即 blocking，不许生成
# yellow = 平台误杀规避（工程约束，不是法律红线）→ 只标「建议改 + 通过率风险」，不判 FAIL
# blue = 投放侧合规（内容能生成，卡的是上线手续）→ 只标「前置事项 + 责任方=user」
# ══════════════════════════════════════════════════════════════
# ── 模型雷 · B 动态预演 ──
- id: mine_identity_drift_seam
name: 条缝/镜缝身份漂移（变脸）
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [换装, 湿身, 淋雨, 受伤, 带伤, 血迹, 变装]}
problem: 外观状态变化处若未声明接缝状态，跨条/跨镜会变脸漂移
action: 在接缝声明**结束状态五字段**（位置 / 朝向 / 持物 / 动作动势 / 情绪），下一条按此承接
need: null
- id: mine_conflicting_actions
name: 一镜叠加互斥动作
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [一边, 同时又, 同时进行, 并同时]}
problem: 一条内并行多个互斥动作 → 模型取平均，动作糊成一片
action: 拆成两条（条一个目的），或只保留承重动作
need: null
- id: mine_abstract_emotion
name: 情绪单词化（漫画化/死面）
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [悲伤, 愤怒, 开心, 绝望, 恐惧, 震惊, 兴奋]}
problem: 只写情绪形容词 → 模型输出夸张漫画化表情或死面
action: 改写成**可见行为 + 微表情**（眼神/嘴部/眉宇 + 具体动作）
need: null
- id: mine_crowd_collapse
name: 群像人数超稳定区（塌缩）
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [人群, 群像, 人群涌动, 众多, 上百, 几十人, 十多人]}
problem: 主体稳定区 1–5 人；群像写实数或超 15 人会塌缩/相似脸
action: 人群作**一个资产**不逐人建档；只写身体质量与局部，不写人数
need: null
- id: mine_precise_lipsync
name: 精确口型与长台词
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [口型, 对口型, 说话特写, 长篇独白]}
problem: 口型三前提：短句 / 正脸 / 中景；单句超 20 词未拆则口型必崩
action: 拆短句，改正脸中景，或后期对口型（lipsync 能力）
need: lipsync
- id: mine_open_motion
name: 开放运动无终点
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [走去, 跑向远方, 走出画面, 渐行渐远, 无限延伸]}
problem: 开放式运动缺终点锚 → 模型卡死或抽搐
action: 给运动一个**可见终点/落点**，或明确写出结束状态
need: null
# ── 可行性雷 · 11 卡要点 ──
- id: feas_precise_quantity
name: 精确数量承重
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [三只手, 五个人, 恰好, 正好, 数量精确, 一共, 整齐排列]}
problem: 精确数量是模型弱项，数量承重易错
action: 降低数量承重（改"几个"），或降档/标注放行
need: null
- id: feas_sustained_contact
name: 持续精确接触点
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [抵住, 贴着, 接触点, 手指按, 刀抵, 针尖, 精确触碰]}
problem: 持续精确接触（刀抵喉/针尖等）易穿模错位
action: 用**解剖位正向描述 + 对比双写**（"刀锋贴在颈侧皮肤上"），或降档为不接触
need: null
- id: feas_special_physics
name: 特殊物理（硬机械/液体火烟粒子）
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [爆炸, 火焰, 烟雾, 水流, 液体, 机械结构, 齿轮, 碎片]}
problem: 特殊物理模拟不稳定（硬机械穿模、流体/粒子失控）
action: 缩短其出现时长、减少精细交互，或改用后期特效叠加（vfx）
need: vfx_apply
- id: feas_large_group_scale
name: 大规模群体场面（卡01）
level: warning
nature: yellow
trigger: {type: need_keywords, keywords: [大军, 战场, 广场人群, 集会, 阅兵, 无数人]}
problem: 稳定区 1–5 主体；大规模群体必然塌缩
action: 用**局部特写 + 数量暗示**（旗帜/脚步/背影）替代全景实数
need: null
# ── 红线 · 三色体系 ──
- id: red_copyright_ip
name: 版权 IP（🔴 绝对红线）
level: blocking
nature: red
trigger: {type: need_keywords, keywords: [动漫角色, 影视角色, 游戏角色, 明星, IP形象, 知名卡通, 品牌logo, 商标]}
problem: 使用受版权保护的 IP/角色/品牌形象 → 侵权（判例：投喂《斗破苍穹》角色形象被判赔 5 万）
action: 停止；改为原创形象或取得授权
need: null
- id: red_false_info
name: 虚假信息 / 伪证类（🔴 绝对红线）
level: blocking
nature: red
trigger: {type: need_keywords, keywords: [去水印, 去角标, 去AI标识, 消除标识, 伪街拍, 伪监控, 伪新闻, 伪造现场]}
problem: 伪造真实性/去除 AI 标识属虚假信息红线
action: 停止；不得用于伪造真实场景或消除 AI 标识
need: null
- id: red_real_person
name: 真人肖像（🔴 绝对红线）
level: blocking
nature: red
trigger: {type: manual_check}
problem: 使用真人肖像（含真人参考图 / 人物置换 / 明星脸）须书面授权
action: 在授权登记中登记后放行；未授权不得生成（责任方=user）
need: null
- id: yellow_platform_false_kill
name: 平台误杀规避（🟡 工程约束）
level: warning
nature: yellow
trigger: {type: manual_check}
problem: 密集血腥特写 / 敏感历史题材 / 动漫风低拦截阈值 等易被平台误杀
action: 标注「建议改 + 通过率风险」；**不判 FAIL、不置 blocking**（除非同时踩某条 🔴）
need: null
- id: blue_delivery_compliance
name: 投放侧合规（🔵 前置手续）
level: info
nature: blue
trigger: {type: manual_check}
problem: 内容可生成，卡的是上线手续（网络剧片发行许可/备案/分级）
action: 标注「投放前置事项 + 责任方=user」；**不判 FAIL、不置 blocking**
need: null
- id: green_protect
name: 绿档保护（不许以「可实现性」砍）
level: info
nature: yellow
trigger: {type: need_keywords, keywords: [长场, 长镜头调度, 夜戏, 逆光, 剪影, 情绪重头戏, 正反打]}
problem: 这些是本方法论的**绿档**内容，不得以技术可实现性为由删除
action: 优先保内容；技术手段不足时按「改写 → 降档 → 标注放行 → 待决」处理，而不是砍内容
need: null
# ── 处置四类说明（供前端提示） ──
# 处置顺序：改写（首选）→ 降档（保画面类型压复杂度）→ 标注放行 → 待决（用户拍板）
# 原则：能改写就不降档，能降档就不删。
mac-agent-os-main/05_tools/09_ave/config/image_models.yaml
+126
View File
@@ -0,0 +1,126 @@
# 图像生成模型注册表 —— 关键帧工作台「引擎」下拉的数据源
#
# 用途：让用户知道「换这个模型能得到什么」，并据此过滤可用的生成方式。
#
# supports 取值（= 生成方式 / 底层能力）：
# multi 多图融合（角色图 + 场景图 → 一张）
# single 图生图（单参考图）
# text2img 文生图（无参考图）
# edit 改造已有图（指令编辑 / 结构保持重绘）
#
# key_field 指定用哪个凭证（对应 agent-local/tools/ave/config/local.yaml 的节）
#
# ⚠️ 价格与限制来自官方文档，可能随平台调整；标注「待验证」的未实测。
version: 1
updated: "2026-10-04"
models:
# ─────────── 百炼 / 千问AI平台（同一 key，已实测可用）───────────
- id: wan2.7-image-pro
name: 万相 2.7 Image Pro
vendor: 百炼（千问AI平台）
price: "¥0.2/张"
verified: true
note: 旗舰图像模型。最多 9 张输入图，顺序模式一次可出 12 张；多图融合（角色+场景）效果最好。
supports: [multi, single, text2img]
limits:
max_input_images: 9
size_range: "宽高 512–2048；总像素 1280²–1440²"
n_max: 4
key_field: aliyun
- id: qwen-image-3.0-pro
name: 千问图像 3.0 Pro
vendor: 百炼（千问AI平台）
price: "¥0.2/张"
verified: false
note: 强在文字渲染与复杂版面（10 像素小字、12 国语言），也支持文生图；画面文字多时选它。
supports: [multi, single, text2img]
limits:
max_input_images: 3
size_range: "宽高各 512–2048；不指定时模型自动推荐"
n_max: 6
key_field: aliyun
- id: qwen-image-edit-max
name: 千问图像编辑 Max
vendor: 百炼（千问AI平台）
price: "¥0.2/张"
verified: false
note: 编辑专用。增强工业设计、几何推理与【人物一致性】——改图时人物不易走形，比 plus 更稳。
supports: [edit, single, multi]
limits:
max_input_images: 3
size_range: "宽高各 512–2048"
n_max: 6
key_field: aliyun
- id: qwen-image-edit-plus
name: 千问图像编辑 Plus
vendor: 百炼（千问AI平台）
price: "¥0.2/张"
verified: true
note: 默认编辑引擎。结构保持重绘，支持多图输出与自定义分辨率。
supports: [edit, single, multi]
limits:
max_input_images: 3
size_range: "宽高各 512–2048；默认约 1024×1024（贴近原图比例）"
n_max: 6
key_field: aliyun
- id: qwen-image-edit
name: 千问图像编辑（基础）
vendor: 百炼（千问AI平台）
price: "¥0.2/张"
verified: false
note: 最轻量。单图编辑 + 多图融合；但只能用默认分辨率，且一次只出 1 张。
supports: [edit, single, multi]
limits:
max_input_images: 3
size_range: "仅默认分辨率（不可指定）"
n_max: 1
key_field: aliyun
# ─────────── 可灵（需 kling key；本期先登记，调用接线待做）───────────
- id: kling-v3
name: 可灵 Image 3.0
vendor: 可灵（Kling）
price: "¥0.2/张"
verified: true
note: 本机角色定妆照已在用。人物质感好；与短剧镜头语言同一个生态，风格更容易延续。
supports: [single, text2img]
limits:
max_input_images: 1
size_range: "由接口 aspect_ratio 控制（9:16 / 16:9 / 1:1 等）"
n_max: 4
key_field: kling
status: 待接线
- id: kling-multi-image2image
name: 可灵 多图参考生图
vendor: 可灵（Kling）
price: "¥0.4/张"
verified: false
note: 官方多图参考。主体图 1–4 张 + 场景图 + 风格图【分开传、互不污染】——融合逻辑比通用模型更干净。
supports: [multi, single]
limits:
max_input_images: 4
size_range: "由接口控制"
n_max: 4
key_field: kling
status: 待接线
# ─────────── 即梦 / 火山方舟（需先在火山控制台开通模型）───────────
- id: seedream-3.0
name: 即梦 Seedream 3.0
vendor: 即梦（火山方舟）
price: "按火山计费"
verified: false
note: 中文语义与海报感强；需先在火山控制台开通该模型，否则报权限错误。
supports: [single, text2img]
limits:
max_input_images: 1
size_range: "以火山接口为准"
n_max: 4
key_field: volcano
status: 待开通
mac-agent-os-main/05_tools/09_ave/config/param_library.yaml
+786
View File
@@ -0,0 +1,786 @@
# 六层参数库（GapEngine）— 创意缺口计算的基础资产
# =====================================================================
# 来源：GapEngine 设计（2026-10-02 讨论）原文全量导入，零删改。
# 用途：创意工坊中挑参数 → 计算"缺口分"（选中值 intensity 的方差）→ 生成画面联想卡。
#
# 字段：
# intensity 预期强度 0~1 —— 观众看到该选择时的"不寻常程度"
# （低=符合预期/常规，高=出乎预期/有张力）
# cue 画面联想描述 —— 拼成"画面联想卡"的一段话，用于触发导演脑补
#
# 维护：可直接编辑本文件（数值/描述/新增值均可），下次生成立刻生效。
# =====================================================================
layers:
- id: narrative
name: 叙事层
params:
- id: info_release
name: 信息释放节奏
values:
- value: 结果前置
intensity: 0.9
cue: "画面直接从结局开始，观众第一眼看到的是结果，不是原因"
- value: 线性递进
intensity: 0.2
cue: "画面按时间顺序推进，从开始到结束，不跳跃"
- value: 倒叙悬念
intensity: 0.7
cue: "画面从中间或结尾切入，再回到起点，制造'为什么'的追问"
- value: 碎片拼图
intensity: 0.85
cue: "画面跳跃在不同时间点之间，观众需要自己拼出完整故事"
- id: conflict_type
name: 冲突类型
values:
- value: 人与环境
intensity: 0.5
cue: "角色在和外部环境对抗，比如病房、走廊、时间"
- value: 人与人
intensity: 0.6
cue: "角色在和另一个人对峙或互动，有对话张力"
- value: 人与自我
intensity: 0.7
cue: "角色在和自己较劲，内心矛盾通过微表情和停顿外化"
- value: 认知反转
intensity: 0.9
cue: "观众以为的真相被推翻，画面信息前后矛盾"
- id: reversal_density
name: 反转密度
values:
- value: 零次
intensity: 0.1
cue: "全片没有反转，情绪平稳推进"
- value: 一次结尾
intensity: 0.6
cue: "结尾处有一个反转，前面积累的情绪在最后释放"
- value: 两次递进
intensity: 0.8
cue: "中间一次小反转，结尾一次大反转，情绪两次起伏"
- value: 高频反转
intensity: 1.0
cue: "每隔几秒就有一次认知颠覆，观众来不及建立预期就被打破"
- id: perspective
name: 视角
values:
- value: 第一人称自述
intensity: 0.3
cue: "镜头就是角色的眼睛，观众通过角色视角看世界"
- value: 第三人称旁观
intensity: 0.2
cue: "镜头在角色外部观察，像纪录片摄制组跟拍"
- value: 上帝视角
intensity: 0.5
cue: "镜头可以出现在任何位置，不受物理限制"
- value: 不可靠叙述者
intensity: 0.9
cue: "画面呈现的内容和角色说的不一致，观众需要自己判断真相"
- id: emotional_end
name: 情感终点
values:
- value: 释然
intensity: 0.3
cue: "结尾情绪是放下、轻松、呼出一口气"
- value: 共鸣
intensity: 0.4
cue: "结尾让观众觉得'我也是这样'，产生认同感"
- value: 爽感
intensity: 0.7
cue: "结尾是压抑后的爆发，观众获得替代性满足"
- value: 困惑
intensity: 0.8
cue: "结尾不给答案，观众带着疑问离开"
- value: 温馨
intensity: 0.2
cue: "结尾是柔和、温暖、让人微笑的情绪"
- id: info_gap
name: 信息缺口
values:
- value: 无缺口
intensity: 0.1
cue: "所有信息都在画面里，观众不需要猜"
- value: 小缺口
intensity: 0.4
cue: "有一个小疑问，观众想知道答案但不会焦虑"
- value: 大缺口
intensity: 0.8
cue: "核心信息被隐藏，观众必须看下去才能理解"
- value: 多重缺口
intensity: 1.0
cue: "多个悬念叠加，每个镜头都在制造新的未知"
# ── 第七层：表达层（本项目扩展 2026-10-03，原对话六层之外新增）──
# 用途：用"不直接说"的方式表达主题——隐喻 / 象征 / 反讽 / 留白。
# 说明：直述是默认（低强度）；一旦用了隐喻类手法，缺口分自然升高。
- id: rhetoric
name: 表达层
params:
- id: expression_mode
name: 表达方式
values:
- value: 直述
intensity: 0.1
cue: "画面直接把要说的事讲出来，不绕弯，观众一眼懂"
- value: 明喻
intensity: 0.5
cue: "画面明确把两件事摆在一起（像…一样），观众当下就能看出这个类比"
- value: 暗喻
intensity: 0.85
cue: "画面只呈现喻体本身（如地震、潮水），被比喻的事始终不出现，观众自己完成那次替代"
- value: 象征
intensity: 0.9
cue: "一个物象在片中被反复带出（笼中鸟、镜子），逐渐脱离实物含义，成为某种处境的固定符号"
- value: 反讽
intensity: 0.7
cue: "画面呈现的和话里说的相反，观众听得出那层言外之意"
- value: 留白
intensity: 0.8
cue: "最关键的信息始终没给，画面停在动作之前或之后，让观众被迫自己补完"
- id: vehicle_source
name: 喻体来源
values:
- value: 自然现象
intensity: 0.85
cue: "地震、潮水、风暴、干旱——用自然的剧烈或枯竭，对应人的处境与情绪"
- value: 机械人造
intensity: 0.8
cue: "齿轮、流水线、监控、牢笼——用工业与规训的秩序，对应被安排的处境"
- value: 动物
intensity: 0.7
cue: "笼中鸟、困兽、茧、飞蛾——用它们的姿态与命运，对应人的状态"
- value: 身体感官
intensity: 0.75
cue: "呼吸、脉搏、疼痛、麻木——用生理反应外化内在的情绪强度"
- value: 日常物件
intensity: 0.6
cue: "镜子、雨伞、闹钟、行李、门——用日常物件的非常规使用承载含义"
- id: mapping
name: 映射关系
values:
- value: 整体寓言
intensity: 0.95
cue: "整条片子从头到尾就是同一个比喻，没有一个镜头是写实的"
- value: 一物多义
intensity: 0.85
cue: "同一个喻体在不同观众那里读出不同所指，不做唯一解释"
- value: 一对一
intensity: 0.4
cue: "喻体与所指严格对应，A 就是 B，观众能准确还原"
- value: 局部点缀
intensity: 0.3
cue: "只在某几个镜头里出现一个带含义的物象，其余部分写实推进"
- id: reveal_timing
name: 揭示时机
values:
- value: 全程不点破
intensity: 0.9
cue: "从头到尾不解释这层含义，相信观众能自己悟到"
- value: 中途暗示
intensity: 0.6
cue: "中段给一个信号让观众意识到'这里还有另一层意思'，之后照旧不点破"
- value: 结尾点破
intensity: 0.5
cue: "结尾用一个回扣的镜头，让前面所有暗喻一次性被观众读懂"
- id: visual
name: 视觉造型层
params:
- id: shot_size
name: 景别
values:
- value: 大远景
intensity: 0.3
cue: "人物在画面中很小，环境占主导"
- value: 全景
intensity: 0.2
cue: "人物全身可见，和环境关系清晰"
- value: 中景
intensity: 0.2
cue: "人物腰部以上，日常对话的常规景别"
- value: 近景
intensity: 0.5
cue: "人物胸部以上，表情开始变得重要"
- value: 特写
intensity: 0.7
cue: "面部占据画面大部分，每一个微表情都被放大"
- value: 大特写
intensity: 0.9
cue: "只有眼睛、嘴唇或某个局部，极其强烈的聚焦"
- id: angle
name: 角度
values:
- value: 平视
intensity: 0.1
cue: "摄影机和眼睛齐平，最中性的视角"
- value: 俯拍
intensity: 0.7
cue: "摄影机从高处向下看，人物显得渺小或被压迫"
- value: 仰拍
intensity: 0.7
cue: "摄影机从低处向上看，人物显得高大或有威胁感"
- value: 荷兰角
intensity: 0.9
cue: "画面倾斜，地平线不水平，制造不安和失衡"
- value: 鸟瞰
intensity: 0.8
cue: "垂直向下看，像地图视角，人物变成几何图形"
- value: 虫视
intensity: 0.9
cue: "从地面向上看，极低角度，世界变得陌生"
- id: depth
name: 景深
values:
- value: 深景深
intensity: 0.2
cue: "前景背景全部清晰，观众可以自由选择看哪里"
- value: 浅景深
intensity: 0.6
cue: "只有主体清晰，背景虚化，强制观众聚焦"
- value: 微距极浅
intensity: 0.9
cue: "只有几毫米的清晰范围，像透过放大镜看世界"
- id: focal_length
name: 焦距感
values:
- value: 广角畸变
intensity: 0.7
cue: "边缘拉伸，空间被夸大，有轻微的鱼眼效果"
- value: 标准
intensity: 0.1
cue: "接近人眼自然视角，无明显畸变"
- value: 长焦压缩
intensity: 0.6
cue: "前后景被压扁，空间变得扁平，有偷窥感"
- value: 鱼眼
intensity: 1.0
cue: "极端球形畸变，世界完全变形"
- id: composition
name: 构图
values:
- value: 居中对称
intensity: 0.3
cue: "主体在正中间，左右对称，稳定但可能呆板"
- value: 三分法
intensity: 0.1
cue: "主体在三分之一交点，常规舒适构图"
- value: 对角线
intensity: 0.6
cue: "主体沿对角线排列，画面有动感和方向感"
- value: 框架式
intensity: 0.7
cue: "主体被门框、窗框等包围，有被困或窥视感"
- value: 不平衡
intensity: 0.8
cue: "主体严重偏一侧，画面失衡，制造紧张"
- id: aspect_ratio
name: 画面比例
values:
- value: "16:9"
intensity: 0.1
cue: "标准横屏，常规视频比例"
- value: "9:16"
intensity: 0.3
cue: "竖屏，手机原生比例，有亲密感"
- value: "4:3"
intensity: 0.5
cue: "复古电视比例，有年代感"
- value: "1:1"
intensity: 0.6
cue: "正方形，社交媒体感，中性但非常规"
- value: "2.35:1"
intensity: 0.7
cue: "宽银幕，电影感强烈，有史诗感"
- id: motion
name: 运动层
params:
- id: camera_move
name: 相机运动
values:
- value: 固定
intensity: 0.1
cue: "摄影机完全不动，画面像一张会呼吸的照片"
- value: 推
intensity: 0.5
cue: "摄影机缓慢靠近主体，注意力逐渐收紧"
- value: 拉
intensity: 0.5
cue: "摄影机缓慢远离主体，揭示更多环境"
- value: 摇
intensity: 0.4
cue: "摄影机在原地左右转动，像转头看"
- value: 移
intensity: 0.5
cue: "摄影机平行移动，画面像画卷展开"
- value: 跟
intensity: 0.6
cue: "摄影机跟随主体移动，观众有同行感"
- value: 升降
intensity: 0.7
cue: "摄影机垂直上下移动，视角高度变化"
- value: 环绕
intensity: 0.8
cue: "摄影机绕着主体转圈，主体成为中心"
- value: 手持晃动
intensity: 0.8
cue: "画面持续轻微抖动，像有人举着手机在拍"
- id: motion_speed
name: 运动速度
values:
- value: 静止
intensity: 0.1
cue: "没有任何运动，时间像被冻结"
- value: 缓慢
intensity: 0.3
cue: "运动极慢，几乎察觉不到，但画面在呼吸"
- value: 正常
intensity: 0.2
cue: "自然速度，和日常体验一致"
- value: 快速
intensity: 0.7
cue: "运动很快，有紧迫感或慌乱感"
- value: 变速
intensity: 0.9
cue: "速度在镜头内变化，比如从快到慢，制造时间异常感"
- id: motion_direction
name: 运动方向
values:
- value: 水平
intensity: 0.2
cue: "左右移动，常规方向"
- value: 垂直
intensity: 0.4
cue: "上下移动，有升起或坠落感"
- value: 斜向
intensity: 0.5
cue: "对角线移动，有动感和不稳定感"
- value: 旋转
intensity: 0.8
cue: "画面旋转，世界倾斜，制造眩晕"
- value: 无方向
intensity: 0.7
cue: "手持随机晃动，没有明确方向，有真实感但不安"
- id: stability
name: 镜头稳定性
values:
- value: 三脚架
intensity: 0.1
cue: "完全稳定，像专业摄影机架在支架上"
- value: 稳定器
intensity: 0.2
cue: "平滑移动，没有抖动，有专业感"
- value: 手持轻微
intensity: 0.5
cue: "有轻微呼吸感抖动，像真人手持拍摄"
- value: 手持剧烈
intensity: 0.8
cue: "明显晃动，像在走路或跑步中拍摄"
- value: 呼吸感模拟
intensity: 0.4
cue: "画面有规律的轻微起伏，像摄影师的呼吸"
- id: focus_behavior
name: 焦点行为
values:
- value: 全程清晰
intensity: 0.1
cue: "所有内容都在焦点内，观众自由观看"
- value: 缓慢拉焦
intensity: 0.5
cue: "焦点从一个对象缓慢转移到另一个，引导注意力"
- value: 快速变焦
intensity: 0.7
cue: "焦点快速切换，有紧张感或强调感"
- value: 焦点呼吸
intensity: 0.6
cue: "焦点轻微前后移动，像眼睛在调整，有生命感"
- id: frame_rate_feel
name: 帧率感
values:
- value: 24fps电影感
intensity: 0.4
cue: "有轻微的运动模糊，电影质感"
- value: 30fps手机感
intensity: 0.2
cue: "日常视频感，和手机拍摄一致"
- value: 60fps流畅
intensity: 0.5
cue: "极其流畅，有运动相机或游戏感"
- value: 升格慢动作
intensity: 0.8
cue: "时间被拉长，动作变慢，有强调和仪式感"
- value: 抽帧卡顿
intensity: 0.9
cue: "画面不流畅，像定格动画或故障，有风格化感"
- id: lighting
name: 光影与色彩层
params:
- id: light_direction
name: 光线方向
values:
- value: 正面光
intensity: 0.1
cue: "光线从摄影机方向照来，面部无阴影，平淡"
- value: 侧面光
intensity: 0.5
cue: "光线从一侧照来，面部一半亮一半暗，有立体感"
- value: 逆光
intensity: 0.7
cue: "光线从背后照来，主体变成剪影，有神秘感"
- value: 顶光
intensity: 0.7
cue: "光线从头顶照下，眼窝和下巴有阴影，有压迫感"
- value: 底光
intensity: 0.9
cue: "光线从下方照来，面部阴影反转，有恐怖或诡异感"
- value: 混合光
intensity: 0.6
cue: "多个方向的光源，色温和强度不同，有复杂感"
- id: light_quality
name: 光线质感
values:
- value: 柔光
intensity: 0.2
cue: "光线柔和，阴影边缘模糊，有温和感"
- value: 硬光
intensity: 0.7
cue: "光线强烈，阴影边缘锐利，有戏剧性"
- value: 混合
intensity: 0.5
cue: "柔光和硬光混合，有层次感"
- value: 无方向环境光
intensity: 0.3
cue: "光线来自四面八方，没有明确方向，像阴天"
- id: color_temperature
name: 色温
values:
- value: 暖
intensity: 0.3
cue: "画面偏黄橙色，有温暖、怀旧或温馨感"
- value: 中性
intensity: 0.1
cue: "画面色温正常，无明显偏色"
- value: 冷
intensity: 0.6
cue: "画面偏蓝青色，有冷静、疏离或科技感"
- value: 混合色温
intensity: 0.8
cue: "画面中同时存在暖光和冷光，有冲突感"
- id: saturation
name: 饱和度
values:
- value: 低饱和
intensity: 0.6
cue: "颜色灰暗，像褪色照片，有纪实或抑郁感"
- value: 正常
intensity: 0.1
cue: "颜色自然，和日常视觉一致"
- value: 高饱和
intensity: 0.7
cue: "颜色鲜艳，有广告或梦幻感"
- value: 局部高饱和
intensity: 0.8
cue: "大部分画面灰暗，只有某个颜色突出，有强调感"
- id: contrast
name: 对比度
values:
- value: 低对比
intensity: 0.4
cue: "画面平淡，明暗差异小，有朦胧感"
- value: 正常
intensity: 0.1
cue: "明暗关系自然"
- value: 高对比
intensity: 0.7
cue: "明暗差异强烈，有硬朗或戏剧感"
- value: 剪影
intensity: 0.9
cue: "主体全黑，只有轮廓，背景明亮"
- id: color_scheme
name: 色彩方案
values:
- value: 单色
intensity: 0.4
cue: "画面只有一个色系，有统一感和风格化"
- value: 互补色
intensity: 0.6
cue: "使用色轮上相对的两种颜色，有视觉张力"
- value: 邻近色
intensity: 0.2
cue: "使用色轮上相邻的颜色，和谐舒适"
- value: 冲突色
intensity: 0.9
cue: "使用红绿、橙蓝等强烈冲突的颜色，有不安或荒诞感"
- id: performance
name: 表演层
params:
- id: facial_expression
name: 面部表情
values:
- value: 中性
intensity: 0.1
cue: "面部肌肉完全放松，没有情绪波动"
- value: 微表情
intensity: 0.5
cue: "极其细微的表情变化，只有眼角或嘴角的轻微移动"
- value: 克制的情绪
intensity: 0.6
cue: "有情绪但被压制，面部有紧张感但不释放"
- value: 夸张表情
intensity: 0.9
cue: "表情幅度极大，像喜剧或默片表演"
- value: 面具式表情
intensity: 0.8
cue: "面部像戴了面具，表情固定不变，有诡异感"
- id: eye_behavior
name: 眼神
values:
- value: 直视镜头
intensity: 0.5
cue: "角色看着镜头，像在和观众对视"
- value: 看向画外
intensity: 0.3
cue: "角色看向画面外，有叙事空间感"
- value: 眼神游离
intensity: 0.7
cue: "眼神不确定地移动，有不安或心虚感"
- value: 眼神锁定
intensity: 0.6
cue: "眼神死死盯住某个对象，有强烈意图"
- value: 闭眼
intensity: 0.8
cue: "眼睛闭上，有内省、逃避或享受感"
- id: body_movement
name: 肢体动作
values:
- value: 静止
intensity: 0.1
cue: "身体完全不动，只有呼吸"
- value: 微动作
intensity: 0.4
cue: "手指、呼吸等细微动作，有生命感"
- value: 日常动作
intensity: 0.2
cue: "走路、坐下、拿东西等自然动作"
- value: 刻意动作
intensity: 0.6
cue: "动作有明确意图，比如刻意整理衣服、刻意转身"
- value: 夸张肢体
intensity: 0.9
cue: "动作幅度极大，有表演性或喜剧感"
- id: posture
name: 姿态
values:
- value: 放松
intensity: 0.2
cue: "肩膀下沉，身体自然，无紧张感"
- value: 紧张
intensity: 0.7
cue: "肩膀耸起，身体僵硬，有防御感"
- value: 开放
intensity: 0.3
cue: "身体面向对方，手臂不交叉，有接纳感"
- value: 防御
intensity: 0.6
cue: "手臂交叉或身体后缩，有拒绝感"
- value: 不对称
intensity: 0.5
cue: "身体歪斜或重心偏移，有随意或不安感"
- id: spatial_distance
name: 空间距离
values:
- value: 亲密
intensity: 0.8
cue: "距离小于45厘米，有亲密或侵入感"
- value: 社交
intensity: 0.3
cue: "距离1-3米，日常交流距离"
- value: 公共
intensity: 0.5
cue: "距离大于3米，有距离感或正式感"
- value: 极远
intensity: 0.7
cue: "距离极远，人物很小，有孤独感"
- id: performance_style
name: 表演风格
values:
- value: 自然主义
intensity: 0.2
cue: "表演像真实生活，没有痕迹"
- value: 风格化
intensity: 0.6
cue: "表演有明确风格，比如夸张、冷峻、诗意"
- value: 布莱希特间离
intensity: 0.9
cue: "表演刻意让观众意识到'这是表演'，打破沉浸"
- value: 默片式
intensity: 0.8
cue: "表演夸张，依赖肢体和表情，像无声电影"
- value: 超现实
intensity: 1.0
cue: "表演逻辑不符合现实，有梦境或荒诞感"
- id: sound
name: 声音层
params:
- id: speech_rate
name: 人声语速
values:
- value: 极慢
intensity: 0.7
cue: "每个字之间都有明显停顿，有沉重或犹豫感"
- value: 慢
intensity: 0.4
cue: "语速缓慢，有平静或疲惫感"
- value: 正常
intensity: 0.1
cue: "日常语速"
- value: 快
intensity: 0.6
cue: "语速较快，有兴奋或焦虑感"
- value: 极快
intensity: 0.9
cue: "语速极快，像在赶时间或情绪失控"
- id: speech_volume
name: 人声音量
values:
- value: 耳语
intensity: 0.8
cue: "极低音量，像在耳边说话，有亲密或秘密感"
- value: 轻声
intensity: 0.5
cue: "低音量，有温柔或虚弱感"
- value: 正常
intensity: 0.1
cue: "日常音量"
- value: 大声
intensity: 0.6
cue: "音量提高，有强调或愤怒感"
- value: 喊叫
intensity: 0.9
cue: "极大声，有失控或爆发感"
- id: speech_emotion
name: 人声情绪
values:
- value: 平静
intensity: 0.1
cue: "声音没有情绪波动，像在陈述事实"
- value: 克制
intensity: 0.5
cue: "有情绪但被压制，声音有轻微颤抖或停顿"
- value: 波动
intensity: 0.6
cue: "情绪有起伏，声音时高时低"
- value: 爆发
intensity: 0.9
cue: "情绪完全释放，声音有冲击力"
- value: 冷漠
intensity: 0.7
cue: "声音没有任何温度，有疏离或机械感"
- id: bgm_presence
name: BGM存在感
values:
- value: 无BGM
intensity: 0.6
cue: "没有任何背景音乐，只有环境音或沉默"
- value: 极低环境音
intensity: 0.4
cue: "只有极低的环境音铺底，几乎察觉不到"
- value: 低音量垫底
intensity: 0.2
cue: "有BGM但音量很低，不抢人声"
- value: 正常配乐
intensity: 0.3
cue: "BGM和人声平衡，有情绪引导作用"
- value: 主导性配乐
intensity: 0.8
cue: "BGM是主角，人声被音乐包裹，有MV感"
- id: bgm_emotion_match
name: BGM情绪匹配
values:
- value: 匹配画面情绪
intensity: 0.1
cue: "音乐和画面情绪一致，观众感受被强化"
- value: 不匹配
intensity: 0.8
cue: "音乐和画面情绪相反，比如悲伤画面配欢快音乐，制造反差"
- value: 完全无关
intensity: 1.0
cue: "音乐和画面毫无关系，有荒诞或间离感"
- id: sfx_density
name: 音效密度
values:
- value: 无音效
intensity: 0.5
cue: "没有任何额外音效，只有原始声音"
- value: 关键音效
intensity: 0.4
cue: "只在关键动作或转折处有音效强调"
- value: 环境音铺底
intensity: 0.3
cue: "有持续的环境音，比如风声、走廊声，有空间感"
- value: 密集音效
intensity: 0.8
cue: "大量音效叠加，每个动作都有声音，有设计感"
- id: silence_usage
name: 沉默使用
values:
- value: 无沉默
intensity: 0.2
cue: "全片有持续的声音，没有安静时刻"
- value: 短暂停顿
intensity: 0.5
cue: "在关键处有短暂停顿，有强调作用"
- value: 长沉默
intensity: 0.8
cue: "有大段沉默，只有画面在动，有压迫或内省感"
- value: 全片沉默
intensity: 1.0
cue: "没有任何人声和音乐，只有环境音或完全安静"
- id: sound_space
name: 声音空间感
values:
- value: 干声
intensity: 0.3
cue: "声音没有混响，像在录音棚，有亲近感"
- value: 小空间
intensity: 0.2
cue: "声音有轻微混响，像在小房间"
- value: 大空间
intensity: 0.5
cue: "声音有明显混响，像在礼堂或空旷处"
- value: 异常空间
intensity: 0.9
cue: "声音有水下、金属、隧道等异常混响，有超现实感"
mac-agent-os-main/05_tools/09_ave/config/portrait_presets.yaml
+88
View File
@@ -0,0 +1,88 @@
# 短剧角色参考图套装 — 预设角色包（6 套）
# =====================================================================
# 用途：角色生成器「📸 生成套装（5 视角）」时可直接选用，免去每次重填
# 来源：用户提供的短剧角色卡规范（2026-10-04）
#
# 每套 = 人物基础描述 + 背景 + 光线 + 各视角神态（可选覆盖）
# 套装流程：① 主定妆（正面半身·文生图）→ ② 其余 4 视角以其为参考图（图生图）
# 通用负面词见 character_generator/portrait_set.py 的 PORTRAIT_NEGATIVE_ZH
# =====================================================================
presets:
- id: patient_girl
name: 破碎感病号女主
age: 24
desc: "24 岁年轻中国女生，黑茶色中长发，面色苍白，淡花掉的妆容，浅蓝条纹病号服，皮肤偏白，五官清秀"
bg: "浅灰纯色背景"
light: "柔和冷调棚柔光"
expressions:
front_half: "眉头微敛，强忍疼痛的神态"
side_45: "眉头微敛，隐忍神情"
profile: "安静垂眸"
face_closeup: "眼尾泛红，强忍痛苦眼神"
shoulder_look: "神情脆弱"
- id: gentle_heroine
name: 小白花温柔女主
age: 22
desc: "22 岁年轻中国女生，鹅蛋脸，黑长直中分长发，淡伪素颜裸妆，米白色宽松针织衫，气质温顺"
bg: "浅灰色纯色背景"
light: "棚拍柔光"
expressions:
front_half: "眼神温顺略带怯懦"
side_45: "眼神柔和"
profile: "安静温婉"
face_closeup: "眼神温顺"
shoulder_look: "眼神柔和"
- id: cold_ceo
name: 高冷女总裁
age: 27
desc: "27 岁年轻中国女性，利落高马尾，冷调淡妆，哑光红棕唇，黑色修身西装套装，眼神冷静锐利"
bg: "深灰纯色背景"
light: "单侧柔和轮廓光"
expressions:
front_half: "眼神冷静锐利"
side_45: "神情冷静"
profile: "气质干练"
face_closeup: "眼神锐利冷静"
shoulder_look: "气场强大"
- id: scheming_villainess
name: 白切黑心机女配
age: 25
desc: "25 岁年轻中国女性，低盘黑长发，精致伪素颜，豆沙唇色，米杏色收腰连衣裙，珍珠耳坠"
bg: "浅灰纯色背景"
light: "柔和影棚光"
expressions:
front_half: "浅淡微笑，眼底藏算计"
side_45: "浅笑"
profile: "神情平静"
face_closeup: "浅微笑，眼神暗藏心机"
shoulder_look: "淡淡笑容"
- id: sweet_heiress
name: 甜妹富家千金
age: 21
desc: "21 岁年轻中国女生，蓬松黑色大波浪卷发，元气淡妆，水光蜜桃唇，浅粉色小香风短外套，碎钻耳钉"
bg: "纯白色背景"
light: "明亮柔和棚光"
expressions:
front_half: "笑容清甜"
side_45: "浅浅微笑"
profile: "神情甜美"
face_closeup: "笑容甜美"
shoulder_look: "灵动微笑"
- id: cool_rebel
name: 酷飒拽姐
age: 23
desc: "23 岁年轻中国女生，黑色高马尾带碎刘海，轻欧美小烟熏妆，暗红色唇，黑色短款皮衣，银色圆环耳饰"
bg: "纯黑背景"
light: "硬侧轮廓光"
expressions:
front_half: "眼神桀骜"
side_45: "眼神冷飒"
profile: "神情冷淡"
face_closeup: "眼神桀骜"
shoulder_look: "冷感眼神"
mac-agent-os-main/05_tools/09_ave/config/scene_presets.yaml
+49
View File
@@ -0,0 +1,49 @@
# 场景预设（短剧常用场景的成套提示词）
# =====================================================================
# 用途：在「🏠 场景生成器」里一键载入，或直接生成 5 机位套装。
#
# 结构：
# presets.<id>.name 显示名
# presets.<id>.slots 各机位槽位的提示词（槽位名 = 场景资产的槽位）
# wide=主图(T2I) · 其余以主图作参考图生成(I2I)
# presets.<id>.negative 负面提示词（统一规避翻车）
#
# ⚠️ 注意：提示词里的「8K / 高清 / 电影级」等词会被系统自动剔除
# （研究结论：这些词让模型往"无瑕"理解 → 过度磨皮 → 塑料感）
# 所以预设里保留原样，生成时由 realism_boost 过滤。
# =====================================================================
presets:
hospital_ward_proctology:
name: 肛肠科单人病房（短剧标准病房）
note: 来源：用户 2026-10-04 提供的提示词合集（5 机位）
slots:
wide: |
完整单人肛肠病房全景，墙面浅淡蓝白色，医用白色病床，床头有呼叫铃、吸氧装置，
床边可折叠陪护椅，墙角医用垃圾桶，小型床头柜放一次性水杯，墙面贴健康宣教海报
（文字模糊不清晰），浅灰色防滑地板，窗户带百叶帘，柔和阳光从窗户照进来，
空房间，没有病人，没有伤口，电影广角镜头，平视角度，写实摄影，短剧场景参考图，
柔和冷白色医疗灯光，高清细节，8K，景深，氛围安静
front: |
肛肠病房病床中景机位，平视角度，白色医用病床，床头靠着枕头，床头柜在病床右侧，
上面放纸巾盒与保温杯，旁边折叠陪护椅，墙面浅蓝色，窗户半拉百叶帘，柔和自然光，
空病房，干净整洁，现代医院装修，浅灰色防滑地面，镜头聚焦病床区域，写实摄影，
短剧场景参考图，柔和医疗顶灯，8K 高清，浅景深，安静医疗氛围，无人物，无隐私画面
detail: |
肛肠病房床头近景，略微侧拍角度，病床床头面板，红色呼叫按钮，电源插座，
床头小置物台，床头柜一角，柔和侧光，浅蓝白色墙面，干净医疗环境，局部场景，
写实摄影，短剧分镜参考，细节清晰，浅景深，虚化背景，空病房，没有病人，
不展示任何私密医疗操作
back: |
站在肛肠病房门外向内拍摄，病房门半开，门框视野，向内看到单人病房全貌，
白色病床，床头柜，百叶窗，走廊柔和顶灯，室内自然光，浅蓝墙面，现代医院，
写实摄影，短剧开场镜头，广角，轻微暗角，氛围感，空房间，干净整洁，8K 高清，无人物
side: |
斜侧 45° 机位拍摄肛肠单人病房，病床在画面左侧，陪护椅放在病床侧边，床头柜居中，
百叶窗在画面后方，阳光透过百叶形成光影条纹，浅蓝白色墙面，防滑地板，安静病房，
写实摄影，短剧对话场景参考，柔和室内灯光，景深，空病房，干净简约
negative: |
畸形，丑陋，伤口，人体隐私部位，裸露，血腥，恐怖，夸张，卡通，手绘，动漫，
文字清晰可读，水印，模糊，低分辨率，多人，病人躺在床上，医疗器械特写，
不雅画面，医疗操作，伤口敷料特写
mac-agent-os-main/05_tools/09_ave/config/video_models.yaml
+74
View File
@@ -0,0 +1,74 @@
# 视频生成模型注册表 —— 「关键帧 → 视频」工作台「引擎」下拉的数据源
#
# supports 取值：
# i2v 图生视频（首帧 = 关键帧）
# kf2v 首尾帧生视频（首帧 + 尾帧）
# r2v 多图参考生视频
# t2v 文生视频
#
# key_field 对应 agent-local/tools/ave/config/local.yaml 的节
#
# ⚠️ 价格来自公开资料/实测记录，可能随平台调整；标注「待验证」的未实测。
version: 1
updated: "2026-10-04"
models:
# ─────────── 可灵（已通路，kling_video.py 现用）───────────
- id: kling-v3
name: 可灵 3.0（质量优先）
vendor: 可灵（Kling）
price: "¥0.6/秒（720P）· ¥0.8/秒（1080P）"
verified: true
note: 当前出片在用。人物质感与运动流畅度最好；支持尾帧衔接（image_tail）与运镜控制。
supports: [i2v, kf2v, t2v]
limits:
duration_options: [5, 10]
tail_frame: true
camera_control: true
key_field: kling
channel: kling # 走 kling_video.py
- id: kling-v2-5-turbo
name: 可灵 2.5 Turbo（省钱优选）
vendor: 可灵（Kling）
price: "¥0.3/秒（720P）· ¥0.5/秒（1080P）"
verified: false
note: 价格是 3.0 的一半，质量略降。适合大量测试镜头。
supports: [i2v, t2v]
limits:
duration_options: [5, 10]
tail_frame: false
camera_control: false
key_field: kling
channel: kling
# ─────────── 百炼（新通道，本期接入）───────────
- id: wan2.2-kf2v-flash
name: 万相 2.2 首尾帧 Flash（最省）
vendor: 百炼（千问AI平台）
price: "¥0.1/秒（480P）"
verified: false
note: 首尾帧专用，价格最低（可灵的 1/6）。必须同时给首帧+尾帧，模型在两帧之间插值 —— 跨镜衔接就靠它。
requires: tail_frame # 前端据此提示「必须选尾帧」
supports: [kf2v, i2v]
limits:
duration_options: [5]
tail_frame: true
camera_control: false
key_field: aliyun
channel: dashscope
- id: wan2.6-r2v-flash
name: 万相 2.6 参考生视频 Flash
vendor: 百炼（千问AI平台）
price: "¥0.3/秒（720P）"
verified: false
note: 多图参考生视频（角色图 + 场景图 + 首帧可同时给）。适合既要保角色又要保环境的镜头。
supports: [r2v, i2v]
limits:
duration_options: [5, 10]
tail_frame: false
max_reference_images: 5
key_field: aliyun
channel: dashscope
status: 待接线
mac-agent-os-main/05_tools/09_ave/docs/api/README.md
+81
View File
@@ -0,0 +1,81 @@
# 📚 API 文档中心
> 本目录把各平台**官方 API 文档抓到本地**，供看板「📚 API 文档中心」页浏览，
> 与 `config/capabilities.yaml` 的能力条目**互相跳转** —— 不用每次现抓。
---
## 目录结构
```
docs/api/
├── README.md ← 本文件
├── index.json ← 自动生成的索引（页面清单 + 原文 URL + 本地文件 + sha256）
└── raw/
├── qwen/ ← 千问AI平台（阿里 DashScope）官方文档（.md）
└── kling/ ← 可灵 AI 官方文档
```
## 怎么更新
```bash
cd 05_tools/09_ave
# 增量更新（已存在的跳过）
~/.workbuddy/binaries/python/envs/agent-os/bin/python3 scripts/tools/fetch_api_docs.py
# 全量重抓
... fetch_api_docs.py --force
# 只看会抓哪些（不下载）
... fetch_api_docs.py --list
# 只抓某个平台
... fetch_api_docs.py --source qwen
... fetch_api_docs.py --source kling
```
脚本位置：`scripts/tools/fetch_api_docs.py`
## 怎么加新平台
编辑脚本里的 `SOURCES` 列表，加一项即可：
```python
{
"id": "volcano", # 目录名
"name": "火山引擎（即梦 / Seedream）",
"kind": "llms-txt", # 或 "explicit"
"index": "https://.../llms.txt", # llms-txt 模式：索引地址
"base": "https://.../", # 相对链接的 base
"include_paths": ["image", "video"], # 只抓这些路径
"exclude_paths": ["text-generation"], # 排除这些
}
```
`kind="explicit"` 时改为 `"pages": [("slug", "标题"), ...]` 显式登记。
## 各平台文档入口（原始地址，便于人工核对）
| 平台 | 文档入口 | 抓取方式 |
|:--|:--|:--|
| 千问AI平台（阿里） | https://platform.qianwenai.com/docs/ | `llms.txt` 自动发现 |
| 可灵 AI | https://app.klingai.com/cn/dev/document-api/ | 显式登记（单页应用） |
| 火山引擎（待加） | — | — |
> 💡 千问AI平台提供 `llms.txt`（专给 AI 读的索引）与 `llms-full.txt`（全量），
> 是目前最好抓的源。其它平台若也有类似索引，优先用它。
## 与能力清单的关联
`config/capabilities.yaml` 里每个能力可加一个字段指向本文档：
```yaml
- id: text_to_image
...
docs:
- qwen: api-reference/image-generation/wan27-image-gen-edit/create-task
- kling: imageGeneration
```
看板「⚙️ 能力配置」页据此显示「📖 查看官方文档 →」链接，跳到本文档中心对应页。
mac-agent-os-main/05_tools/09_ave/docs/api/index.json
+1708
View File
File diff suppressed because it is too large Load Diff
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-ai-tryon-create-task.md
+391
View File
@@ -0,0 +1,391 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI试衣 — 创建任务
> 提交AI试衣任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: AI试衣 API
version: 1.0.0
description: AI试衣模型支持使用服饰平拍图片以及人物正面全身照，生成逼真的试衣效果图。提供两个模型：aitryon（基础版，生成更快）和 aitryon-plus（Plus版，在图像清晰度、布料纹理和 Logo 还原方面表现更出色，但生成耗时更长）。两个模型的接口参数完全一致，仅 model 字段不同。
servers:
- url: https://maas.qianwenaiapi.com/api/v1
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createAiTryonTask
summary: 创建试衣任务
description: 发送 POST 请求创建AI虚拟试衣任务。因该模型调用耗时较长，故采用异步调用的方式创建任务。任务创建后，系统会立即返回一个 task_id，需使用此 task_id 在24小时内查询任务结果。
security:
- BearerAuth: []
parameters:
- name: Content-Type
in: header
required: true
description: 请求类型，固定值为 application/json。
schema:
type: string
default: application/json
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
- name: X-DashScope-Async
in: header
required: true
description: 固定值为 enable，表示使用异步调用方式。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AiTryonRequest"
responses:
"200":
description: 任务提交成功。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 参数缺失或格式错误
value:
code: InvalidParameter
message: The request is missing required parameters or in a wrong format, please check the parameters that you send.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidURL:
summary: 图片URL无效
value:
code: InvalidURL
message: "The request URL is invalid, please check the request URL is available and the request image format is one of the following types: JPEG, JPG, PNG, BMP, and WEBP."
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidPerson:
summary: 模特图不合规
value:
code: InvalidPerson
message: The input image has no human body or multi human bodies. Please upload other image with single person.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidGarment:
summary: 缺少服饰图片
value:
code: InvalidGarment
message: Missing clothing image.Please input at least one top garment or bottom garment image.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidInputLength:
summary: 图片尺寸或文件大小不符合要求
value:
code: InvalidInputLength
message: The image resolution is invalid, please make sure that the largest length of image is smaller than 4096, and the smallest length of image is larger than 150. and the size of image ranges from 5KB to 5MB.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"429":
description: 请求频率超过限制。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: Throttling
message: Requests throttling triggered.
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx
x-codeSamples:
- lang: curl
label: 试穿上装
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: 试穿上装（保留原下装）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg",
"bottom_garment_url": "图片分割API输出的图像URL"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: 试穿下装
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: 试穿下装（保留原上衣）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "图片分割API输出的图像URL",
"bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: 试穿上下装
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg",
"bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: 试穿连衣裙/连体服
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/odngby/dress.jpg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
- lang: curl
label: Plus版-试穿上装
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon-plus",
"input": {
"person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
"top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg"
},
"parameters": {
"resolution": -1,
"restore_face": true
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
AiTryonRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 指明需要调用的模型。`aitryon`（基础版）生成更快；`aitryon-plus`（Plus版）在清晰度和纹理还原方面更出色，但耗时更长。
enum:
- aitryon
- aitryon-plus
default: aitryon
input:
type: object
required:
- person_image_url
description: 输入参数。
properties:
person_image_url:
type: string
format: uri
description: 模特人物图片的公网URL。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。需保持图片中有且仅有一个完整的人。仅支持HTTP/HTTPS链接，不支持本地路径。
top_garment_url:
type: string
format: uri
description: 上装/连衣裙服饰图的公网URL。需上传服饰平拍图，保持服饰是单一主体且完整，背景干净，四周不宜留白过多。对于连衣裙/连体衣，请将图片URL填入此字段，并将 bottom_garment_url 留空。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。仅支持HTTP/HTTPS链接，不支持本地路径。
bottom_garment_url:
type: string
format: uri
description: 下装服饰图的公网URL。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。需上传服饰平拍图，保持服饰是单一主体且完整，背景干净，四周不宜留白过多。仅支持HTTP/HTTPS链接，不支持本地路径。
parameters:
type: object
description: 可选参数。
properties:
resolution:
type: integer
description: 输出图片的分辨率。-1（默认值）：与原图尺寸保持一致；1024：表示 576x1024 分辨率；1280：表示 720x1280 分辨率。若后续还需调用AI试衣-图片精修API，此值必须设为 -1。
enum:
- -1
- 1024
- 1280
default: -1
restore_face:
type: boolean
description: 是否还原模特图中的人脸。true（默认值）：保留原图人脸；false：随机生成一张新的人脸。若后续还需调用AI试衣-图片精修API，此值必须设为 true。
default: true
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 异步任务的唯一ID。
task_status:
type: string
description: 任务提交后的状态。
enum:
- PENDING
request_id:
type: string
description: 本次请求的唯一ID。
TaskStatusResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 查询的任务ID。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
- CANCELED
image_url:
type: string
format: uri
description: 生成的试衣效果图地址。image_url有效期为24小时，请及时下载。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。任务失败时返回此参数。
message:
type: string
description: 错误详情。任务失败时返回此参数。
usage:
type: object
properties:
image_count:
type: integer
description: 本次请求生成的图片张数。
request_id:
type: string
description: 本次请求的唯一ID。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求ID。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-ai-tryon-query-result.md
+251
View File
@@ -0,0 +1,251 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI试衣 — 查询结果
> 查询AI试衣任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: AI试衣 API
version: 1.0.0
description: AI试衣模型支持使用服饰平拍图片以及人物正面全身照，生成逼真的试衣效果图。提供两个模型：aitryon（基础版，生成更快）和 aitryon-plus（Plus版，在图像清晰度、布料纹理和 Logo 还原方面表现更出色，但生成耗时更长）。两个模型的接口参数完全一致，仅 model 字段不同。
servers:
- url: https://maas.qianwenaiapi.com/api/v1
paths:
/tasks/{task_id}:
get:
operationId: getAiTryonTaskResult
summary: 查询任务结果
description: 使用创建任务时获取的 task_id，发送 GET 请求查询任务状态和结果。AI试衣任务耗时较长（约90秒），建议采用轮询机制，并设置合理的查询间隔（如3-5秒）来获取结果。任务成功后返回的 image_url 有效期为24小时，请及时下载并保存图片。
security:
- BearerAuth: []
parameters:
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
- name: task_id
in: path
required: true
description: 需要查询任务的ID，即创建任务时返回的 task_id。
schema:
type: string
responses:
"200":
description: 任务状态和结果。
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 98d46cd0-1f90-9231-9a6c-xxxxxx
output:
task_id: 15991992-1487-40d4-ae66-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-06-30 14:37:53.838
scheduled_time: 2025-06-30 14:37:53.858
end_time: 2025-06-30 14:38:11.472
image_url: http://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/tryon.jpg?Expires=xxx
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: 6bf4693b-c6d0-933a-b7b7-xxxxxx
output:
task_id: e32bd911-5a3d-4687-bf53-xxxxxx
task_status: FAILED
code: InvalidParameter
message: The request is missing required parameters xxxxx
RUNNING:
summary: 任务处理中
value:
request_id: a1b2c3d4-5678-90ab-cdef-xxxxxxxxxxxx
output:
task_id: 15991992-1487-40d4-ae66-xxxxxx
task_status: RUNNING
submit_time: 2025-06-30 14:37:53.838
scheduled_time: 2025-06-30 14:37:53.858
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: The request is missing required parameters or in a wrong format
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx
"401":
description: 认证失败。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx
"429":
description: 请求频率超过限制。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: Throttling
message: Requests throttling triggered.
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
AiTryonRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 指明需要调用的模型。`aitryon`（基础版）生成更快；`aitryon-plus`（Plus版）在清晰度和纹理还原方面更出色，但耗时更长。
enum:
- aitryon
- aitryon-plus
default: aitryon
input:
type: object
required:
- person_image_url
description: 输入参数。
properties:
person_image_url:
type: string
format: uri
description: 模特人物图片的公网URL。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。需保持图片中有且仅有一个完整的人。仅支持HTTP/HTTPS链接，不支持本地路径。
top_garment_url:
type: string
format: uri
description: 上装/连衣裙服饰图的公网URL。需上传服饰平拍图，保持服饰是单一主体且完整，背景干净，四周不宜留白过多。对于连衣裙/连体衣，请将图片URL填入此字段，并将 bottom_garment_url 留空。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。仅支持HTTP/HTTPS链接，不支持本地路径。
bottom_garment_url:
type: string
format: uri
description: 下装服饰图的公网URL。5KB≤图像文件≤5M，150≤图像边长≤4096，格式支持jpg/png/jpeg/bmp/heic。需上传服饰平拍图，保持服饰是单一主体且完整，背景干净，四周不宜留白过多。仅支持HTTP/HTTPS链接，不支持本地路径。
parameters:
type: object
description: 可选参数。
properties:
resolution:
type: integer
description: 输出图片的分辨率。-1（默认值）：与原图尺寸保持一致；1024：表示 576x1024 分辨率；1280：表示 720x1280 分辨率。若后续还需调用AI试衣-图片精修API，此值必须设为 -1。
enum:
- -1
- 1024
- 1280
default: -1
restore_face:
type: boolean
description: 是否还原模特图中的人脸。true（默认值）：保留原图人脸；false：随机生成一张新的人脸。若后续还需调用AI试衣-图片精修API，此值必须设为 true。
default: true
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 异步任务的唯一ID。
task_status:
type: string
description: 任务提交后的状态。
enum:
- PENDING
request_id:
type: string
description: 本次请求的唯一ID。
TaskStatusResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 查询的任务ID。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
- CANCELED
image_url:
type: string
format: uri
description: 生成的试衣效果图地址。image_url有效期为24小时，请及时下载。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。任务失败时返回此参数。
message:
type: string
description: 错误详情。任务失败时返回此参数。
usage:
type: object
properties:
image_count:
type: integer
description: 本次请求生成的图片张数。
request_id:
type: string
description: 本次请求的唯一ID。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求ID。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-aitryon-parsing.md
+209
View File
@@ -0,0 +1,209 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI试衣-图片分割
> 从模特图或 AI 试衣图中分割出服装区域，支持上装、下装、连衣裙等类型
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
AI 试衣-图片分割是一个辅助模型，支持从模特图或 AI 试衣图中分割出服装区域，如上装、下装、连衣裙或连体衣。此模型为可选模型，与 AI 试衣模型配合使用，可实现**局部试衣**、**获取指定服饰坐标**等特定效果。
## OpenAPI
````yaml post /services/vision/image-process/process
openapi: 3.1.0
info:
title: AI试衣-图片分割 API
version: 1.0.0
description: 从模特图或AI试衣图中分割出服装区域，支持上装、下装、连衣裙等类型。
servers:
- url: https://maas.qianwenaiapi.com/api/v1
security:
- BearerAuth: []
paths:
/services/vision/image-process/process:
post:
summary: Segment garments
operationId: segmentGarments
description: 从模特图或 AI 试衣图中分割出服装区域，返回分割图片 URL 和边界框坐标。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AitryonParsingRequest"
responses:
"200":
description: 请求成功
content:
application/json:
schema:
$ref: "#/components/schemas/AitryonParsingResponse"
examples:
SuccessWithClothes:
summary: 成功响应（存在对应类型服饰）
value:
output:
bbox:
- - 331
- 239
- 641
- 637
parsing_img_url:
- http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/example_parsing_img.png?Expires=xxxx
crop_img_url:
- http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/example_crop_img.jpg?Expires=xxxx
usage:
image_count: 1
request_id: b68147d6-e7d0-920f-b889-xxxxxx
SuccessWithoutClothes:
summary: 成功响应（不存在对应类型服饰）
value:
output:
bbox:
- null
parsing_img_url:
- null
crop_img_url:
- null
usage:
image_count: 1
request_id: c56f62df-724e-9c19-96bd-308627cf5262
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
request_id: 1d075a37-3768-9bc9-b781-xxxx
code: InvalidParameter.ClothesType
message: The request parameter is invalid, please check the request parameter.
"401":
description: 认证失败
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"429":
description: 请求频率超限
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: Throttling
message: Requests throttling triggered.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/vision/image-process/process' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "aitryon-parsing-v1",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250630/bakbqz/aitryon_parse_model.png"
},
"parameters": {
"clothes_type": ["upper"]
}
}'
components:
schemas:
AitryonParsingRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- aitryon-parsing-v1
description: 模型名称，固定为 `aitryon-parsing-v1`。
input:
type: object
required:
- image_url
properties:
image_url:
type: string
description: 待分割的模特图公网 URL。要求：图像文件 5KB～5MB；图像边长 150～4096 px；支持格式 jpg、png、jpeg、bmp、heic；图片中有且仅有一个完整的人；仅支持 HTTP/HTTPS 链接。
parameters:
type: object
properties:
clothes_type:
type: array
items:
type: string
enum:
- upper
- lower
- dress
default:
- upper
description: 指定需要分割的服饰类型。默认为 `["upper"]`（上装）。列表的长度和顺序决定了输出结果中 URL 列表的长度和顺序。可选值：`["upper"]` 分割上装；`["lower"]` 分割下装；`["dress"]` 分割连衣裙或连体衣或全身穿搭；`["upper", "lower"]` 同时分割上装和下装。
AitryonParsingResponse:
type: object
properties:
request_id:
type: string
description: 本次请求的唯一 ID。
output:
type: object
properties:
parsing_img_url:
type: array
items:
type: string
nullable: true
description: 分割区域的可视化图片 URL 列表（RGBA PNG 格式）。长度和顺序与入参 `clothes_type` 一致。如果未检测到对应服饰，则该位置为 null。URL 有效期为 24 小时，请及时下载保存。
crop_img_url:
type: array
items:
type: string
nullable: true
description: 分割出的服饰图片 URL 列表（RGB 格式）。长度和顺序与入参 `clothes_type` 一致。如果未找到对应服饰，则该位置为 null。URL 有效期为 24 小时，请及时下载保存。
bbox:
type: array
items:
type: array
items:
type: integer
nullable: true
description: 分割区域在原图中的坐标列表。按照入参 `clothes_type` 中指定的顺序排列。每个 bbox 为 `[x1, y1, x2, y2]`，以输入原图左上角为坐标原点，分别代表左上角和右下角坐标。如果未检测到对应服饰，则该位置为 null。
usage:
type: object
properties:
image_count:
type: integer
description: 本次请求处理的图片张数。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-aitryon-refiner-create-task.md
+260
View File
@@ -0,0 +1,260 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI试衣精修 — 创建任务
> 提交AI试衣-图片精修任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis/
openapi: 3.1.0
info:
title: Try-on Refiner API
version: 1.0.0
description: AI试衣-图片精修是一个后处理模型，可增强AI试衣生成图片的真实感与清晰度。
servers:
- url: https://maas.qianwenaiapi.com/api/v1
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis/:
post:
summary: Create task
operationId: createAitryonRefinerTask
description: 提交AI试衣-图片精修任务。该模型可增强AI试衣生成图片的真实感与清晰度。
parameters:
- name: X-DashScope-Async
in: header
required: true
schema:
type: string
enum:
- enable
description: 必须设置为 `enable` 以使用异步模式。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AitryonRefinerRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 缺少必传参数或格式错误
value:
code: InvalidParameter
message: The request is missing required parameters xxxxx
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidURL:
summary: 图片URL无法访问
value:
code: InvalidURL
message: The image URL is not accessible.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidPerson:
summary: 未检测到人体或检测到多个人体
value:
code: InvalidPerson
message: No human body detected or multiple human bodies detected.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
InvalidInputLength:
summary: 图片分辨率不合规
value:
code: InvalidInputLength
message: Image resolution is invalid.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"429":
description: 请求频率超限
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: Throttling
message: Requests throttling triggered.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "aitryon-refiner",
"input": {
"top_garment_url": "https://dashscope-swap.oss-cn-beijing.aliyuncs.com/aa-test/sample-top.jpg",
"bottom_garment_url": "https://dashscope-swap.oss-cn-beijing.aliyuncs.com/aa-test/sample-bottom.jpg",
"person_image_url": "https://dashscope-swap.oss-cn-beijing.aliyuncs.com/aa-test/sample-person.png",
"coarse_image_url": "https://dashscope-swap.oss-cn-beijing.aliyuncs.com/aa-test/result.png"
},
"parameters": {
"gender": "woman"
}
}'
components:
schemas:
AitryonRefinerRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- aitryon-refiner
description: 模型名称，固定为 `aitryon-refiner`。
input:
type: object
required:
- top_garment_url
- person_image_url
- coarse_image_url
properties:
top_garment_url:
type: string
description: 上半身服装图片URL。图片大小范围5KB~5MB，图片分辨率范围150px~4096px（宽和高均需满足），支持格式：jpg、png、jpeg、bmp、heic。
bottom_garment_url:
type: string
description: 下半身服装图片URL。图片大小范围5KB~5MB，图片分辨率范围150px~4096px（宽和高均需满足），支持格式：jpg、png、jpeg、bmp、heic。
person_image_url:
type: string
description: 模特人台图片URL。图片中有且仅有一个完整人物。
coarse_image_url:
type: string
description: AI试衣的结果图片URL。调用AI试衣接口时，需要设置 `resolution=-1` 和 `restore_face=true`。
parameters:
type: object
required:
- gender
properties:
gender:
type: string
enum:
- woman
- man
description: 性别。可选值为 `woman` 或 `man`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID，用于后续查询任务结果。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
description: 任务状态。提交成功后通常为 `PENDING`。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
- CANCELED
description: 任务状态。
image_url:
type: string
description: 图片精修结果图片URL。24小时内有效。仅在任务成功时返回。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。仅在任务完成时返回。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误信息。仅在任务失败时返回。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-aitryon-refiner-query-result.md
+215
View File
@@ -0,0 +1,215 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI试衣精修 — 查询结果
> 查询AI试衣-图片精修任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Try-on Refiner API
version: 1.0.0
description: AI试衣-图片精修是一个后处理模型，可增强AI试衣生成图片的真实感与清晰度。
servers:
- url: https://maas.qianwenaiapi.com/api/v1
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
summary: Query task result
operationId: getAitryonRefinerTaskResult
description: 查询AI试衣-图片精修任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
schema:
type: string
description: 任务ID，从创建任务的响应中获取。
responses:
"200":
description: 查询成功
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功完成
value:
request_id: 98d46cd0-1f90-9231-9a6c-xxxxxx
output:
task_id: 15991992-1487-40d4-ae66-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-06-30 14:37:53.838
scheduled_time: 2025-06-30 14:37:53.858
end_time: 2025-06-30 14:38:11.472
image_url: https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/tryon.jpg?Expires=xxx
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: 6bf4693b-c6d0-933a-b7b7-xxxxxx
output:
task_id: e32bd911-5a3d-4687-bf53-xxxxxx
task_status: FAILED
code: InvalidParameter
message: The request is missing required parameters xxxxx
RUNNING:
summary: 任务运行中
value:
request_id: 98d46cd0-1f90-9231-9a6c-xxxxxx
output:
task_id: 15991992-1487-40d4-ae66-xxxxxx
task_status: RUNNING
submit_time: 2025-06-30 14:37:53.838
scheduled_time: 2025-06-30 14:37:53.858
x-codeSamples:
- lang: curl
label: cURL — Query task result
source: |-
# Replace {task_id} with the actual task ID from the submit response
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
schemas:
AitryonRefinerRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- aitryon-refiner
description: 模型名称，固定为 `aitryon-refiner`。
input:
type: object
required:
- top_garment_url
- person_image_url
- coarse_image_url
properties:
top_garment_url:
type: string
description: 上半身服装图片URL。图片大小范围5KB~5MB，图片分辨率范围150px~4096px（宽和高均需满足），支持格式：jpg、png、jpeg、bmp、heic。
bottom_garment_url:
type: string
description: 下半身服装图片URL。图片大小范围5KB~5MB，图片分辨率范围150px~4096px（宽和高均需满足），支持格式：jpg、png、jpeg、bmp、heic。
person_image_url:
type: string
description: 模特人台图片URL。图片中有且仅有一个完整人物。
coarse_image_url:
type: string
description: AI试衣的结果图片URL。调用AI试衣接口时，需要设置 `resolution=-1` 和 `restore_face=true`。
parameters:
type: object
required:
- gender
properties:
gender:
type: string
enum:
- woman
- man
description: 性别。可选值为 `woman` 或 `man`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID，用于后续查询任务结果。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
description: 任务状态。提交成功后通常为 `PENDING`。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
- CANCELED
description: 任务状态。
image_url:
type: string
description: 图片精修结果图片URL。24小时内有效。仅在任务成功时返回。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。仅在任务完成时返回。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误信息。仅在任务失败时返回。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-background-generation-create-task.md
+496
View File
@@ -0,0 +1,496 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像背景生成 — 创建任务
> 提交图像背景生成异步任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## 模型概览
**模型简介**
| 模型名 | 模型简介 |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| wanx-background-generation-v2 | Wan-图像背景生成模型，为主体商品生成背景图，适用于电商和海报场景。支持多种背景生成方法：文本引导、图像引导、文本与图像结合引导，以及文本、图像与边缘引导元素的综合应用。 |
## 边缘引导元素生成方法
边缘引导元素生成方法因其能够有效保留图像中的边缘和结构信息，在图像背景生成任务中常用于生成前景或背景元素图像。
**步骤1**：PS 抠图，导出带透明背景的 4 通道格式图像。
**步骤2**：生成边缘引导元素图像。
针对步骤2，提供两种方案，任选一种即可。
**方案一：ModelScope 在线生成**
访问 ModelScope [背景图 edge 元素生成](https://modelscope.cn/studios/lllcho/bg_edge_elements)，直接上传第一步抠图后的图像点击运行即可获得符合要求的元素图像。
**方案二：使用代码本地生成**
安装依赖包：
```bash
pip install controlnet-aux==0.0.7
```
运行以下 Python 脚本生成边缘引导元素：
```python
import numpy as np
from PIL import Image
from controlnet_aux.processor import Processor
hed_processor = Processor('softedge_hed')
def make_elements(name):
img=Image.open(name)
img=np.array(img)
img[:,:,:-1]=img[:,:,:-1]*(img[:,:,-1:]>127)
img=Image.fromarray(img,mode='RGBA')
r,g,b,a=img.split()
img=Image.merge(mode='RGB',bands=[r,g,b])
edge = hed_processor(img, to_pil=True).resize(img.size).convert('RGB')
edge.putalpha(a)
edge=np.array(edge)
edge[:,:,:-1]=edge[:,:,:-1]*(edge[:,:,-1:]>50)
edge=Image.fromarray(edge,mode='RGBA')
edge.save('result.png')
# 使用方法：将步骤1导出的前景图路径传入
make_elements('foreground.png')
```
## 错误码
大模型服务通用状态码请查阅[错误信息](/api-reference/preparation/error-messages)。
## 常见问题
### wanx-background-generation-v3 模型不存在
**报错场景**：如果将 `model` 参数设置为 `wanx-background-generation-v3`，发送请求后报错显示模型不存在。
```json
{
"code": "InvalidParameter",
"message": "Model not exist.",
"request_id": "539f3cf9-9b9c-9a0f-988f-1829c7eb502f"
}
```
**原因及解决方案**：目前图像背景生成只有 `wanx-background-generation-v2` 这一个模型。如果需要切换 V3 模型，请设置 `parameters.model_version` 为 `v3`，才能成功调用 v3 模型。
### 使用示例图片报错提示需要提供 RGBA 模式的图片
**报错场景**：将文档的示例图片下载到本地后重新上传，使用新链接请求时报错图像格式是 RGB 而非 RGBA。
```json
{
"request_id": "8f7d6829-281a-9270-944b-xxxxxx",
"output": {
"task_id": "72a2d266-6822-4165-a6e4-xxxxxx",
"task_status": "FAILED",
"submit_time": "2024-11-07 09:51:19.xxx",
"scheduled_time": "2024-11-07 09:51:19.xxx",
"end_time": "2024-11-07 09:51:20.xxx",
"code": "BadRequest.UnsupportedFileFormat",
"message": "Base image require RGBA format, but is RGB, modes concept see https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-modes"
},
"usage": {
"image_count": 0
}
}
```
**主要原因**：主体图像、前景元素图像或背景元素图像不是 RGBA 图像。图片从示例链接下载后再上传的过程中可能改变原始格式，例如：下载时使用不支持透明度的格式（如 .jpg、.jpeg）、上传至存储服务器时不支持 RGBA 格式，或图像编辑工具未保留透明度。
**解决方案**：确保图像保存为支持 RGBA 透明通道的格式（如 .png），并在整个上传流程中保留透明度信息。
## OpenAPI
````yaml post /services/aigc/background-generation/generation/
openapi: 3.1.0
info:
title: 图像背景生成 API
description: 本文介绍Wan-背景生成模型的输入输出参数。Wan-图像背景生成模型为主体商品生成背景图，适用于电商和海报场景。支持多种背景生成方法：文本引导、图像引导、文本与图像结合引导，以及文本、图像与边缘引导元素的综合应用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 中国内地（北京）
security:
- BearerAuth: []
paths:
/services/aigc/background-generation/generation/:
post:
operationId: createBackgroundGenerationTask
summary: 创建任务获取任务ID
description: 提交异步背景生成任务。API 会立即返回 task_id，需轮询 GET /tasks/{task_id} 获取结果。图像模型处理时间较长，HTTP 调用仅支持异步获取模型结果。
parameters:
- name: Content-Type
in: header
required: true
description: 请求内容类型，必须设置为 application/json。
schema:
type: string
enum:
- application/json
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置参数。HTTP 请求只支持异步，必须设置为 enable。缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
- name: X-DashScope-WorkSpace
in: header
required: false
description: 千问AI平台业务空间 ID。示例值：llm-xxxx。主账号 API-Key 可不填；RAM 子账号 API-Key 必填。
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BackgroundGenerationRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
examples:
success:
summary: 任务已接受
value:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidApiKey:
summary: 无效的 API Key
value:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxx
DataInspection:
summary: 数据审核超时
value:
code: InvalidParameter.DataInspection
message: Download the media resource timed out during the data inspection process.
request_id: a4d78a5f-655f-9639-8437-xxxxxx
"401":
description: 认证失败 — API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"429":
description: 请求频率超出限制
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/background-generation/generation/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-background-generation-v2",
"input": {
"base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
"ref_image_url": "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg",
"ref_prompt": "山脉和晚霞",
"reference_edge": {
"foreground_edge": [
"https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png",
"http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/2c36cc4b7da027279e87311dac48fc2d5d784b1e72c0e-x4f1wC_fw658webp.png"
],
"background_edge": [
"http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/0718a9741e07c52ca5506e75c4f2b99e22fff68a4c7d3-P9WGLr_fw658webp.png"
],
"foreground_edge_prompt": [
"粉色桃花",
"可爱小狗"
],
"background_edge_prompt": [
"树叶"
]
}
},
"parameters": {
"n": 4,
"ref_prompt_weight": 0.5,
"model_version": "v3"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
BackgroundGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。当前仅支持填写 wanx-background-generation-v2。通过 parameters.model_version 参数切换 v2/v3 版本，请勿将 model 设置为 wanx-background-generation-v3。
enum:
- wanx-background-generation-v2
example: wanx-background-generation-v2
input:
type: object
required:
- base_image_url
description: 输入图像的基本信息。ref_image_url 和 ref_prompt 至少需要填写一个。
properties:
base_image_url:
type: string
format: uri
description: 主体图像 URL。主体图像必须为带透明背景的 RGBA 四通道 PNG 图像，输出图像的分辨率与该图像保持一致。图像长边不超过 2048 像素。
example: https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png
ref_image_url:
type: string
format: uri
description: 引导图像 URL。用于引导背景风格。与 ref_prompt 至少需要填写一个。支持 jpg、png、webp 等常见格式。引导图像可以是 RGB 图像或带透明背景的 RGBA 图像。
example: http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg
ref_prompt:
type: string
description: 引导文本提示词，支持中英双语。与 ref_image_url 至少需要填写一个。英文最多支持 150 个单词，中文约 100-120 个中文字符，超过部分会被自动忽略。示例：山脉和晚霞。
example: 山脉和晚霞
neg_ref_prompt:
type: string
description: 负向提示词，描述画面不希望出现的内容。一般不填，使用模型内置的默认值。英文最多支持 150 个单词，中文约 100-120 个中文字字符。示例：低质量的，模糊的，错误的。
reference_edge:
type: object
description: 边缘引导元素图像，包括前景元素图像列表和背景元素图像列表。
properties:
foreground_edge:
type: array
items:
type: string
format: uri
description: 前景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像，分辨率和主体图像相同。所有前景元素生成的图层在主体前面，可以对主体形成遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。
foreground_edge_prompt:
type: array
items:
type: string
description: 前景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 foreground_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。
background_edge:
type: array
items:
type: string
format: uri
description: 背景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像。生成图层在主体的后面，如果重叠会被主体遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。
background_edge_prompt:
type: array
items:
type: string
description: 背景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 background_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。
title:
type: string
deprecated: true
description: 已废弃，建议使用图配文。图像上添加文字主标题，算法自动确定文字的大小和位置，限制 1-8 个字符。
minLength: 1
maxLength: 8
sub_title:
type: string
deprecated: true
description: 已废弃，建议使用图配文。图像上添加文字副标题，算法自动确定文字的大小和位置，限制 1-10 个字符。仅当 title 不为空时生效。
minLength: 1
maxLength: 10
parameters:
type: object
description: 图像处理参数。
properties:
n:
type: integer
description: 图片生成的数量，支持 1-4 张，默认值 1。
minimum: 1
maximum: 4
default: 1
example: 4
model_version:
type: string
description: 模型版本。v2：旧版模型，速度快（默认值）。v3：新版模型，速度稍慢但效果更好，推荐切换到 v3。
enum:
- v2
- v3
default: v2
example: v3
noise_level:
type: integer
description: 当 ref_image_url 不为空时生效。该参数在图像引导的过程中添加随机变化，数值越大生成背景与引导图像的相关性越低。默认值 300，取值范围 [0, 999]。
minimum: 0
maximum: 999
default: 300
ref_prompt_weight:
type: number
description: 仅当 ref_image_url 和 ref_prompt 同时输入时生效，表示引导文本 prompt 的权重。取值范围 [0, 1]，默认值 0.5。数值越大表示引导文本对生成背景的影响程度越大。
minimum: 0
maximum: 1
default: 0.5
example: 0.5
scene_type:
type: string
deprecated: true
description: 已废弃，不建议使用。使用场景：GENERAL（通用场景，默认值）、ROOM（室内家居场景）、COSMETIC（美妆场景，也适用于大部分小商品摆放场景）。
enum:
- GENERAL
- ROOM
- COSMETIC
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。用于查询任务状态及结果，查询有效期 24 小时。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态轮询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: ded2407a-ec61-4a7d-adc0-xxxxxxxxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
example: 86ecf553-d340-4e21-xxxxxxxxx
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:25:26.436
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:25:26.471
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:26:06.390
results:
type: array
description: 返回结果图像。仅在 task_status 为 SUCCEEDED 时返回。图像分辨率与输入图像（base_image_url）保持一致。
items:
type: object
properties:
url:
type: string
format: uri
description: 生成图像的 URL。有效期 24 小时，请及时下载保存。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
code:
type: string
description: 错误码。仅在 task_status 为 FAILED 时返回。
example: InvalidParameter.FileDownload
message:
type: string
description: 错误详情。仅在 task_status 为 FAILED 时返回。
example: download for input_image error
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
example: 4
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
example: 4
FAILED:
type: integer
description: 任务状态为失败的任务数。
example: 0
usage:
type: object
description: 输出信息统计。计费公式：费用 = 图片数量 × 单价。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。
example: 4
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: fb53c4ec-1c12-4fc4-a580-xxxxxx
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
example: InvalidApiKey
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
example: Invalid API-key provided.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-background-generation-query-result.md
+354
View File
@@ -0,0 +1,354 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像背景生成 — 查询结果
> 查询图像背景生成任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 图像背景生成 API
description: 本文介绍Wan-背景生成模型的输入输出参数。Wan-图像背景生成模型为主体商品生成背景图，适用于电商和海报场景。支持多种背景生成方法：文本引导、图像引导、文本与图像结合引导，以及文本、图像与边缘引导元素的综合应用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 中国内地（北京）
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getBackgroundGenerationTaskStatus
summary: 根据任务ID查询结果
description: 轮询背景生成任务的状态及结果。持续轮询直到 task_status 变为 SUCCEEDED 或 FAILED。任务数据（如任务状态、图像 URL 等）仅保留 24 小时，超时后会被自动清除，请及时保存生成的图像。
parameters:
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
- name: task_id
in: path
required: true
description: 创建任务接口返回的任务 ID。
schema:
type: string
example: 86ecf553-d340-4e21-xxxxxxxxx
responses:
"200":
description: 成功获取任务状态
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: ded2407a-ec61-4a7d-adc0-xxxxxxxxxxxx
output:
task_id: 86ecf553-d340-4e21-xxxxxxxxx
task_status: SUCCEEDED
submit_time: 2025-12-23 10:25:26.436
scheduled_time: 2025-12-23 10:25:26.471
end_time: 2025-12-23 10:26:06.390
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
task_metrics:
TOTAL: 4
SUCCEEDED: 4
FAILED: 0
usage:
image_count: 4
FAILED:
summary: 任务执行失败
value:
request_id: dccfdf23-b38e-97a6-a07b-f35118c1ada6
output:
task_id: 4cbabbdf-2c1f-43f4-b983-c2cc47f4c115
task_status: FAILED
submit_time: 2024-05-16 14:15:14.103
scheduled_time: 2024-05-16 14:15:14.154
end_time: 2024-05-16 14:15:14.694
code: InvalidParameter.FileDownload
message: download for input_image error
RUNNING:
summary: 任务执行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-xxxxxxxxxxxx
output:
task_id: 13b1848b-5493-4c0e-xxxxxxxxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL — 查询任务结果
source: |-
# 将 {task_id} 替换为创建任务接口返回的真实 task_id
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
BackgroundGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。当前仅支持填写 wanx-background-generation-v2。通过 parameters.model_version 参数切换 v2/v3 版本，请勿将 model 设置为 wanx-background-generation-v3。
enum:
- wanx-background-generation-v2
example: wanx-background-generation-v2
input:
type: object
required:
- base_image_url
description: 输入图像的基本信息。ref_image_url 和 ref_prompt 至少需要填写一个。
properties:
base_image_url:
type: string
format: uri
description: 主体图像 URL。主体图像必须为带透明背景的 RGBA 四通道 PNG 图像，输出图像的分辨率与该图像保持一致。图像长边不超过 2048 像素。
example: https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png
ref_image_url:
type: string
format: uri
description: 引导图像 URL。用于引导背景风格。与 ref_prompt 至少需要填写一个。支持 jpg、png、webp 等常见格式。引导图像可以是 RGB 图像或带透明背景的 RGBA 图像。
example: http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg
ref_prompt:
type: string
description: 引导文本提示词，支持中英双语。与 ref_image_url 至少需要填写一个。英文最多支持 150 个单词，中文约 100-120 个中文字符，超过部分会被自动忽略。示例：山脉和晚霞。
example: 山脉和晚霞
neg_ref_prompt:
type: string
description: 负向提示词，描述画面不希望出现的内容。一般不填，使用模型内置的默认值。英文最多支持 150 个单词，中文约 100-120 个中文字字符。示例：低质量的，模糊的，错误的。
reference_edge:
type: object
description: 边缘引导元素图像，包括前景元素图像列表和背景元素图像列表。
properties:
foreground_edge:
type: array
items:
type: string
format: uri
description: 前景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像，分辨率和主体图像相同。所有前景元素生成的图层在主体前面，可以对主体形成遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。
foreground_edge_prompt:
type: array
items:
type: string
description: 前景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 foreground_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。
background_edge:
type: array
items:
type: string
format: uri
description: 背景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像。生成图层在主体的后面，如果重叠会被主体遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。
background_edge_prompt:
type: array
items:
type: string
description: 背景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 background_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。
title:
type: string
deprecated: true
description: 已废弃，建议使用图配文。图像上添加文字主标题，算法自动确定文字的大小和位置，限制 1-8 个字符。
minLength: 1
maxLength: 8
sub_title:
type: string
deprecated: true
description: 已废弃，建议使用图配文。图像上添加文字副标题，算法自动确定文字的大小和位置，限制 1-10 个字符。仅当 title 不为空时生效。
minLength: 1
maxLength: 10
parameters:
type: object
description: 图像处理参数。
properties:
n:
type: integer
description: 图片生成的数量，支持 1-4 张，默认值 1。
minimum: 1
maximum: 4
default: 1
example: 4
model_version:
type: string
description: 模型版本。v2：旧版模型，速度快（默认值）。v3：新版模型，速度稍慢但效果更好，推荐切换到 v3。
enum:
- v2
- v3
default: v2
example: v3
noise_level:
type: integer
description: 当 ref_image_url 不为空时生效。该参数在图像引导的过程中添加随机变化，数值越大生成背景与引导图像的相关性越低。默认值 300，取值范围 [0, 999]。
minimum: 0
maximum: 999
default: 300
ref_prompt_weight:
type: number
description: 仅当 ref_image_url 和 ref_prompt 同时输入时生效，表示引导文本 prompt 的权重。取值范围 [0, 1]，默认值 0.5。数值越大表示引导文本对生成背景的影响程度越大。
minimum: 0
maximum: 1
default: 0.5
example: 0.5
scene_type:
type: string
deprecated: true
description: 已废弃，不建议使用。使用场景：GENERAL（通用场景，默认值）、ROOM（室内家居场景）、COSMETIC（美妆场景，也适用于大部分小商品摆放场景）。
enum:
- GENERAL
- ROOM
- COSMETIC
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。用于查询任务状态及结果，查询有效期 24 小时。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态轮询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: ded2407a-ec61-4a7d-adc0-xxxxxxxxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
example: 86ecf553-d340-4e21-xxxxxxxxx
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:25:26.436
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:25:26.471
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2025-12-23 10:26:06.390
results:
type: array
description: 返回结果图像。仅在 task_status 为 SUCCEEDED 时返回。图像分辨率与输入图像（base_image_url）保持一致。
items:
type: object
properties:
url:
type: string
format: uri
description: 生成图像的 URL。有效期 24 小时，请及时下载保存。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
code:
type: string
description: 错误码。仅在 task_status 为 FAILED 时返回。
example: InvalidParameter.FileDownload
message:
type: string
description: 错误详情。仅在 task_status 为 FAILED 时返回。
example: download for input_image error
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
example: 4
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
example: 4
FAILED:
type: integer
description: 任务状态为失败的任务数。
example: 0
usage:
type: object
description: 输出信息统计。计费公式：费用 = 图片数量 × 单价。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。
example: 4
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: fb53c4ec-1c12-4fc4-a580-xxxxxx
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
example: InvalidApiKey
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
example: Invalid API-key provided.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-creative-poster-create-task.md
+337
View File
@@ -0,0 +1,337 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创意海报 — 创建任务
> 创意海报异步生成
<Warning>
wanx-poster-generation-v1 模型当前仅提供**免费体验**，免费额度用完后不可调用且不支持付费。
</Warning>
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## 生成模式
| 模式 | 说明 |
| ---------- | ------------------------------------------------------- |
| `generate` | 默认模式，生成海报 |
| `sr` | 超分辨率模式，需要传入 `auxiliary_parameters`（由 `generate` 模式返回） |
| `hrf` | 高分辨率修复模式，需要传入 `auxiliary_parameters`（由 `generate` 模式返回） |
## 海报风格
支持以下 18 种风格（通过 `lora_name` 参数指定）：
2D插画1、2D插画2、浩瀚星云、浓郁色彩、光线粒子、透明玻璃、剪纸工艺、折纸工艺、中国水墨、中国刺绣、真实场景、2D卡通、儿童水彩、赛博背景、浅蓝抽象、深蓝抽象、抽象点线、童话油画
## OpenAPI
````yaml post /services/aigc/text2image/image-synthesis
openapi: 3.1.0
info:
title: Creative Poster Generation API
version: 1.0.0
description: 创意海报生成 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/text2image/image-synthesis:
post:
summary: 生成海报
operationId: createCreativePosterTask
parameters:
- name: X-DashScope-Async
in: header
required: true
schema:
type: string
enum:
- enable
description: 启用异步模式。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreativePosterRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 生成海报（generate 模式）
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data-raw '{
"model":"wanx-poster-generation-v1",
"input": {
"title":"春节快乐",
"sub_title":"家庭团聚，共享天伦之乐",
"body_text":"春节是中国最重要的传统节日之一，它象征着新的开始和希望",
"prompt_text_zh":"灯笼，小猫，梅花",
"wh_ratios":"竖版",
"lora_name":"童话油画",
"lora_weight":0.8,
"ctrl_ratio":0.7,
"ctrl_step":0.7,
"generate_mode":"generate",
"generate_num":1
},
"parameters":{}
}'
- lang: curl
label: 生成海报（hrf 模式）
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data-raw '{
"model":"wanx-poster-generation-v1",
"input": {
"title":"春节快乐",
"sub_title":"家庭团聚，共享天伦之乐",
"body_text":"春节是中国最重要的传统节日之一，它象征着新的开始和希望",
"prompt_text_zh":"灯笼，小猫，梅花",
"wh_ratios":"竖版",
"lora_name":"童话油画",
"lora_weight":0.8,
"ctrl_ratio":0.7,
"ctrl_step":0.7,
"generate_mode":"hrf",
"auxiliary_parameters": "WMq4SC4......",
"generate_num":1
},
"parameters":{}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
CreativePosterRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- wanx-poster-generation-v1
description: 模型名称。
input:
type: object
required:
- generate_mode
- title
description: 输入参数。
properties:
generate_mode:
type: string
enum:
- generate
- sr
- hrf
description: 生成模式。`generate`：默认生成模式；`sr`：超分辨率模式，需要传入 `auxiliary_parameters`（由 generate 模式返回）；`hrf`：高分辨率修复模式，需要传入 `auxiliary_parameters`（由 generate 模式返回）。
title:
type: string
maxLength: 30
description: 海报主标题，最多 30 个字符。
sub_title:
type: string
maxLength: 30
description: 海报副标题，最多 30 个字符。
body_text:
type: string
maxLength: 50
description: 海报正文内容，最多 50 个字符。
prompt_text_zh:
type: string
description: 中文关键词，用于描述海报背景。
prompt_text_en:
type: string
description: 英文关键词，用于描述海报背景。
wh_ratios:
type: string
enum:
- 横版
- 竖版
description: 海报版式。`横版`：横版海报；`竖版`：竖版海报。
lora_name:
type: string
enum:
- 2D插画1
- 2D插画2
- 浩瀚星云
- 浓郁色彩
- 光线粒子
- 透明玻璃
- 剪纸工艺
- 折纸工艺
- 中国水墨
- 中国刺绣
- 真实场景
- 2D卡通
- 儿童水彩
- 赛博背景
- 浅蓝抽象
- 深蓝抽象
- 抽象点线
- 童话油画
description: 海报风格。
lora_weight:
type: number
minimum: 0
maximum: 1
default: 0.8
description: 风格权重，取值范围 0~1，默认 0.8。
ctrl_ratio:
type: number
minimum: 0
maximum: 1
default: 0.7
description: 控制比例，取值范围 0~1，默认 0.7。
ctrl_step:
type: number
minimum: 0
maximum: 1
default: 0.7
description: 控制步长，取值范围 0~1，默认 0.7。
generate_num:
type: integer
minimum: 1
maximum: 4
description: 生成图片数量，取值范围 1~4。
auxiliary_parameters:
type: string
description: 辅助参数，在 `sr` 或 `hrf` 模式下必传。该值由 `generate` 模式的任务结果返回。
creative_title_layout:
type: boolean
default: false
description: 是否使用创意标题排版，默认 false。
parameters:
type: object
description: 模型参数，传空对象 `{}`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUSPENDED
- SUCCEEDED
- FAILED
description: 任务状态。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
render_urls:
type: array
items:
type: string
description: 渲染后的海报图片 URL 列表。
auxiliary_parameters:
type: array
items:
type: string
description: 辅助参数列表，用于 `sr` 或 `hrf` 模式的二次生成。
bg_urls:
type: array
items:
type: string
description: 背景图片 URL 列表。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-creative-poster-query-result.md
+348
View File
@@ -0,0 +1,348 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创意海报 — 查询结果
> 查询创意海报生成任务状态
查询任务状态并获取生成的海报图片。
## 轮询策略
1. 通过[生成海报](/api-reference/image-generation/creative-poster/create-task)接口提交任务，获取 `task_id`。
2. 每 **5 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，从响应中获取海报图片。
## 响应字段说明
任务成功后，响应中包含以下字段：
| 字段 | 说明 |
| ---------------------- | ------------------------------ |
| `render_urls` | 渲染后的海报图片 URL 列表 |
| `bg_urls` | 背景图片 URL 列表 |
| `auxiliary_parameters` | 辅助参数列表，用于 `sr` 或 `hrf` 模式的二次生成 |
## 注意事项
- **URL 有效期**：生成的图片 URL 有效期为 **24 小时**，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED`、`FAILED` 或 `SUSPENDED`。
- **任务 ID 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## 错误码
| HTTP 状态码 | 错误码 | 错误信息 | 含义 |
| -------- | ---------------- | ---------------------- | ----------- |
| 400 | InvalidParameter | check input data style | 输入参数不满足入参要求 |
| 500 | InternalError | inference error | 算法内部错误 |
## 常见问题
**Q：创意海报生成需要多长时间？**
A：生成时间一般为 20\~60 秒，受排队情况影响可能有所延迟。建议以 5 秒为间隔轮询查询接口，避免频繁请求。
**Q：`render_urls` 和 `bg_urls` 有什么区别？**
A：`render_urls` 是包含文字排版的完整海报图片；`bg_urls` 是不含文字的背景图片，可用于后续二次编辑。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Creative Poster Generation API
version: 1.0.0
description: 创意海报生成 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
summary: 查询海报生成结果
operationId: getCreativePosterTaskResult
parameters:
- name: task_id
in: path
required: true
schema:
type: string
description: 任务 ID，由[生成海报](/api-reference/image-generation/creative-poster/create-task)接口返回。
responses:
"200":
description: 任务状态查询结果
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
task_id: d76ec1e8-ea27-4038-8913-235c88ef0f70
task_status: SUCCEEDED
submit_time: 2024-05-16 13:50:01.247
scheduled_time: 2024-05-16 13:50:01.354
end_time: 2024-05-16 13:50:27.795
render_urls:
- http://vision-poster.oss-cn-shanghai.aliyuncs.com/xxxxxx
auxiliary_parameters:
- xxxxxx
bg_urls:
- http://vision-poster.oss-cn-shanghai.aliyuncs.com/xxxxxx
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: dccfdf23-b38e-97a6-a07b-f35118c1ada6
output:
task_id: 4cbabbdf-2c1f-43f4-b983-c2cc47f4c115
task_status: FAILED
submit_time: 2024-05-16 14:15:14.103
scheduled_time: 2024-05-16 14:15:14.154
end_time: 2024-05-16 14:15:14.694
code: InvalidParameter
message: check input data style
RUNNING:
summary: 任务运行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
PENDING:
summary: 任务排队中
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: d76ec1e8-ea27-4038-8913-xxxxxxxxxxxx
task_status: PENDING
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
curl --location --request GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
CreativePosterRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- wanx-poster-generation-v1
description: 模型名称。
input:
type: object
required:
- generate_mode
- title
description: 输入参数。
properties:
generate_mode:
type: string
enum:
- generate
- sr
- hrf
description: 生成模式。`generate`：默认生成模式；`sr`：超分辨率模式，需要传入 `auxiliary_parameters`（由 generate 模式返回）；`hrf`：高分辨率修复模式，需要传入 `auxiliary_parameters`（由 generate 模式返回）。
title:
type: string
maxLength: 30
description: 海报主标题，最多 30 个字符。
sub_title:
type: string
maxLength: 30
description: 海报副标题，最多 30 个字符。
body_text:
type: string
maxLength: 50
description: 海报正文内容，最多 50 个字符。
prompt_text_zh:
type: string
description: 中文关键词，用于描述海报背景。
prompt_text_en:
type: string
description: 英文关键词，用于描述海报背景。
wh_ratios:
type: string
enum:
- 横版
- 竖版
description: 海报版式。`横版`：横版海报；`竖版`：竖版海报。
lora_name:
type: string
enum:
- 2D插画1
- 2D插画2
- 浩瀚星云
- 浓郁色彩
- 光线粒子
- 透明玻璃
- 剪纸工艺
- 折纸工艺
- 中国水墨
- 中国刺绣
- 真实场景
- 2D卡通
- 儿童水彩
- 赛博背景
- 浅蓝抽象
- 深蓝抽象
- 抽象点线
- 童话油画
description: 海报风格。
lora_weight:
type: number
minimum: 0
maximum: 1
default: 0.8
description: 风格权重，取值范围 0~1，默认 0.8。
ctrl_ratio:
type: number
minimum: 0
maximum: 1
default: 0.7
description: 控制比例，取值范围 0~1，默认 0.7。
ctrl_step:
type: number
minimum: 0
maximum: 1
default: 0.7
description: 控制步长，取值范围 0~1，默认 0.7。
generate_num:
type: integer
minimum: 1
maximum: 4
description: 生成图片数量，取值范围 1~4。
auxiliary_parameters:
type: string
description: 辅助参数，在 `sr` 或 `hrf` 模式下必传。该值由 `generate` 模式的任务结果返回。
creative_title_layout:
type: boolean
default: false
description: 是否使用创意标题排版，默认 false。
parameters:
type: object
description: 模型参数，传空对象 `{}`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUSPENDED
- SUCCEEDED
- FAILED
description: 任务状态。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
render_urls:
type: array
items:
type: string
description: 渲染后的海报图片 URL 列表。
auxiliary_parameters:
type: array
items:
type: string
description: 辅助参数列表，用于 `sr` 或 `hrf` 模式的二次生成。
bg_urls:
type: array
items:
type: string
description: 背景图片 URL 列表。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-facechain-finetune-create-task.md
+408
View File
@@ -0,0 +1,408 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物形象训练 — 创建任务
> 提交 FaceChain 人物形象训练任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /fine-tunes
openapi: 3.1.0
info:
title: FaceChain 人物形象训练 API
description: 提交 FaceChain 人物形象训练任务，使用 1-10 张人像图片训练专属人像模型。训练完成后，使用 `finetuned_output` 中的模型名称调用人物写真生成 API 生成写真。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/fine-tunes:
post:
operationId: createFaceChainFinetuneTask
summary: 提交训练任务
description: |-
提交 FaceChain 人物形象训练任务。上传 1-10 张人像图片后，API 立即返回 `job_id`，训练在后台异步执行。通过 `GET /fine-tunes/{job_id}` 轮询训练状态。
- QPS 限制：2 次/秒
- 并发任务数限制：每个账号同时只能有 1 个训练任务在运行
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/FaceChainFinetuneRequest"
responses:
"200":
description: 训练任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/FaceChainFinetuneResponse"
examples:
success:
summary: 任务已接受（PENDING）
value:
request_id: b6c9e77d-02a1-4a70-b127-xxxxxx
output:
job_id: ft-202509020951-f8bf
job_name: ft-202509020951-f8bf
status: PENDING
finetuned_output: facechain-finetune-ft-202509020951-f8bf
model: facechain-finetune
base_model: facechain-finetune
training_file_ids:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
validation_file_ids: []
hyper_parameters: {}
training_type: sft
create_time: 2025-09-02 09:51:02
workspace_id: llm-dmt509ikxxxxxx
user_identity: 12402258xxxxxx
modifier: 124022586xxxxxx
creator: 1240225868xxxxxx
group: facechain
model_name: ft-202509020951-f8bf
max_output_cnt: 1
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
MissingTrainingFiles:
summary: 缺少训练文件
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: Missing training files.
UnsupportedOperation:
summary: 不支持的操作
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: UnsupportedOperation
message: The fine-tune job can not be deleted because it is succeeded,failed or canceled
"401":
description: 认证失败，API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"404":
description: 资源不存在
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
NotFound:
summary: 任务不存在
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: NotFound
message: job {job_id} not found.
"409":
description: 冲突
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
Conflict:
summary: 模型实例已存在
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: Conflict
message: Model instance xxxxx already exists, please specify a suffix
"429":
description: 请求频率超限
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
Throttling:
summary: 运行中任务数超限
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: Throttling
message: Too many fine-tune job in running, please retry later
"500":
description: 服务器内部错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InternalError:
summary: 服务器内部错误
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InternalError
message: Internal server error!
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "facechain-finetune",
"training_file_ids": [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"
]
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
FaceChainFinetuneRequest:
type: object
required:
- model
- training_file_ids
properties:
model:
type: string
description: 模型名称，固定值 `facechain-finetune`。
enum:
- facechain-finetune
example: facechain-finetune
training_file_ids:
type: array
description: |-
训练图片 URL 或文件 ID 列表。提供 1-10 张人像图片。
- 支持公开可访问的图片 URL（例如 `https://dashscope.oss-cn-beijing.aliyuncs.com/...`）
- 或通过文件管理 API 上传后获取的 file_id
- 建议使用清晰的正脸照片以获得最佳训练效果
items:
type: string
minItems: 1
maxItems: 10
example:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
FaceChainFinetuneResponse:
type: object
description: 提交训练任务的响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于追踪和排查问题。
example: b6c9e77d-02a1-4a70-b127-xxxxxx
output:
type: object
description: 训练任务输出信息。
properties:
job_id:
type: string
description: 训练任务 ID。通过 `GET /fine-tunes/{job_id}` 查询任务状态。
example: ft-202509020951-f8bf
job_name:
type: string
description: 训练任务名称，与 `job_id` 相同。
example: ft-202509020951-f8bf
status:
type: string
description: 训练任务当前状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: PENDING
finetuned_output:
type: string
description: 微调后的模型名称。训练成功后，将此值作为 `model` 参数传入人物写真生成 API。
example: facechain-finetune-ft-202509020951-f8bf
model:
type: string
description: 训练使用的模型。
example: facechain-finetune
base_model:
type: string
description: 基础模型名称。
example: facechain-finetune
training_file_ids:
type: array
description: 训练图片 URL 或文件 ID 列表。
items:
type: string
validation_file_ids:
type: array
description: 验证文件 ID 列表（FaceChain 训练为空）。
items:
type: string
hyper_parameters:
type: object
description: 训练使用的超参数（FaceChain 训练为空）。
training_type:
type: string
description: 训练类型。
example: sft
create_time:
type: string
description: 任务创建时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。
example: 2025-09-02 09:51:02
workspace_id:
type: string
description: 工作空间 ID。
example: llm-dmt509ikxxxxxx
user_identity:
type: string
description: 用户标识。
example: 12402258xxxxxx
modifier:
type: string
description: 最后修改者标识。
example: 124022586xxxxxx
creator:
type: string
description: 创建者标识。
example: 1240225868xxxxxx
group:
type: string
description: 模型组。
example: facechain
model_name:
type: string
description: 模型名称标识符。
example: ft-202509020951-f8bf
max_output_cnt:
type: integer
description: 最大输出模型数量。
example: 1
FaceChainFinetuneStatusResponse:
type: object
description: 查询训练任务状态的响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于追踪和排查问题。
example: fcfb99e6-7ae5-48b2-acca-xxxxxx
output:
type: object
description: 训练任务输出信息。
properties:
job_id:
type: string
description: 训练任务 ID。
example: ft-202509020951-f8bf
job_name:
type: string
description: 训练任务名称。
example: ft-202509020951-f8bf
status:
type: string
description: 训练任务当前状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
finetuned_output:
type: string
description: 微调后的模型名称。训练成功后，将此值作为 `model` 参数传入人物写真生成 API。
example: facechain-finetune-ft-202509020951-f8bf
model:
type: string
description: 训练使用的模型。
example: facechain-finetune
base_model:
type: string
description: 基础模型名称。
example: facechain-finetune
training_file_ids:
type: array
description: 训练图片 URL 或文件 ID 列表。
items:
type: string
validation_file_ids:
type: array
description: 验证文件 ID 列表。
items:
type: string
hyper_parameters:
type: object
description: 训练使用的超参数。
training_type:
type: string
description: 训练类型。
example: sft
create_time:
type: string
description: 任务创建时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。
example: 2025-09-02 09:51:02
workspace_id:
type: string
description: 工作空间 ID。
example: llm-dmt509ikxxxxxxx
user_identity:
type: string
description: 用户标识。
example: 1240225868xxxxxx
modifier:
type: string
description: 最后修改者标识。
example: 1240225868xxxxxx
creator:
type: string
description: 创建者标识。
example: 1240225868xxxxxx
end_time:
type: string
description: 任务结束时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。仅在 `status` 为 `SUCCEEDED` 或 `FAILED` 时返回。
example: 2025-09-02 09:56:04
group:
type: string
description: 模型组。
example: facechain
usage:
type: integer
description: 训练次数（用于计费）。仅在 `status` 为 `SUCCEEDED` 时返回。
example: 1
model_name:
type: string
description: 模型名称标识符。
example: ft-202509020951-f8bf
max_output_cnt:
type: integer
description: 最大输出模型数量。
example: 1
output_cnt:
type: integer
description: 已生成的模型数量。仅在训练完成后返回。
example: 1
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识符。
example: a4d78a5f-655f-9639-8437-xxxxxx
code:
type: string
description: 错误码。可选值包括：`InvalidParameter`、`UnsupportedOperation`、`NotFound`、`Conflict`、`Throttling`、`InternalError`。
example: InvalidParameter
message:
type: string
description: 错误详情描述。
example: Missing training files.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-facechain-finetune-query-result.md
+392
View File
@@ -0,0 +1,392 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物形象训练 — 查询结果
> 查询 FaceChain 人物形象训练任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /fine-tunes/{job_id}
openapi: 3.1.0
info:
title: FaceChain 人物形象训练 API
description: 提交 FaceChain 人物形象训练任务，使用 1-10 张人像图片训练专属人像模型。训练完成后，使用 `finetuned_output` 中的模型名称调用人物写真生成 API 生成写真。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/fine-tunes/{job_id}:
get:
operationId: getFaceChainFinetuneStatus
summary: 查询训练结果
description: |-
查询 FaceChain 人物形象训练任务的状态和结果。持续轮询直到 `status` 变为 `SUCCEEDED` 或 `FAILED`。
训练成功后，将 `finetuned_output` 的值作为模型名称，传入人物写真生成 API 调用生成写真。
parameters:
- name: job_id
in: path
required: true
description: 训练任务 ID，由 `POST /fine-tunes` 接口返回。
schema:
type: string
example: ft-202509020951-f8bf
responses:
"200":
description: 成功获取任务状态
content:
application/json:
schema:
$ref: "#/components/schemas/FaceChainFinetuneStatusResponse"
examples:
SUCCEEDED:
summary: 训练成功
value:
request_id: fcfb99e6-7ae5-48b2-acca-xxxxxx
output:
job_id: ft-202509020951-f8bf
job_name: ft-202509020951-f8bf
status: SUCCEEDED
finetuned_output: facechain-finetune-ft-202509020951-f8bf
model: facechain-finetune
base_model: facechain-finetune
training_file_ids:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
validation_file_ids: []
hyper_parameters: {}
training_type: sft
create_time: 2025-09-02 09:51:02
workspace_id: llm-dmt509ikxxxxxxx
user_identity: 1240225868xxxxxx
modifier: 1240225868xxxxxx
creator: 1240225868xxxxxx
end_time: 2025-09-02 09:56:04
group: facechain
usage: 1
model_name: ft-202509020951-f8bf
max_output_cnt: 1
output_cnt: 1
FAILED:
summary: 训练失败
value:
request_id: fcfb99e6-7ae5-48b2-acca-xxxxxx
output:
job_id: ft-202509020951-f8bf
job_name: ft-202509020951-f8bf
status: FAILED
finetuned_output: facechain-finetune-ft-202509020951-f8bf
model: facechain-finetune
base_model: facechain-finetune
training_file_ids:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
validation_file_ids: []
hyper_parameters: {}
training_type: sft
create_time: 2025-09-02 09:51:02
workspace_id: llm-dmt509ikxxxxxxx
user_identity: 1240225868xxxxxx
modifier: 1240225868xxxxxx
creator: 1240225868xxxxxx
end_time: 2025-09-02 09:56:04
group: facechain
model_name: ft-202509020951-f8bf
max_output_cnt: 1
RUNNING:
summary: 训练中
value:
request_id: fcfb99e6-7ae5-48b2-acca-xxxxxx
output:
job_id: ft-202509020951-f8bf
job_name: ft-202509020951-f8bf
status: RUNNING
finetuned_output: facechain-finetune-ft-202509020951-f8bf
model: facechain-finetune
base_model: facechain-finetune
training_file_ids:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
validation_file_ids: []
hyper_parameters: {}
training_type: sft
create_time: 2025-09-02 09:51:02
workspace_id: llm-dmt509ikxxxxxxx
user_identity: 1240225868xxxxxx
modifier: 1240225868xxxxxx
creator: 1240225868xxxxxx
group: facechain
model_name: ft-202509020951-f8bf
max_output_cnt: 1
"404":
description: 任务不存在
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
NotFound:
summary: 任务不存在
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: NotFound
message: job {job_id} not found.
x-codeSamples:
- lang: curl
label: cURL
source: |-
# 将 {job_id} 替换为提交任务时返回的实际 job_id
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/fine-tunes/{job_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
FaceChainFinetuneRequest:
type: object
required:
- model
- training_file_ids
properties:
model:
type: string
description: 模型名称，固定值 `facechain-finetune`。
enum:
- facechain-finetune
example: facechain-finetune
training_file_ids:
type: array
description: |-
训练图片 URL 或文件 ID 列表。提供 1-10 张人像图片。
- 支持公开可访问的图片 URL（例如 `https://dashscope.oss-cn-beijing.aliyuncs.com/...`）
- 或通过文件管理 API 上传后获取的 file_id
- 建议使用清晰的正脸照片以获得最佳训练效果
items:
type: string
minItems: 1
maxItems: 10
example:
- https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg
FaceChainFinetuneResponse:
type: object
description: 提交训练任务的响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于追踪和排查问题。
example: b6c9e77d-02a1-4a70-b127-xxxxxx
output:
type: object
description: 训练任务输出信息。
properties:
job_id:
type: string
description: 训练任务 ID。通过 `GET /fine-tunes/{job_id}` 查询任务状态。
example: ft-202509020951-f8bf
job_name:
type: string
description: 训练任务名称，与 `job_id` 相同。
example: ft-202509020951-f8bf
status:
type: string
description: 训练任务当前状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: PENDING
finetuned_output:
type: string
description: 微调后的模型名称。训练成功后，将此值作为 `model` 参数传入人物写真生成 API。
example: facechain-finetune-ft-202509020951-f8bf
model:
type: string
description: 训练使用的模型。
example: facechain-finetune
base_model:
type: string
description: 基础模型名称。
example: facechain-finetune
training_file_ids:
type: array
description: 训练图片 URL 或文件 ID 列表。
items:
type: string
validation_file_ids:
type: array
description: 验证文件 ID 列表（FaceChain 训练为空）。
items:
type: string
hyper_parameters:
type: object
description: 训练使用的超参数（FaceChain 训练为空）。
training_type:
type: string
description: 训练类型。
example: sft
create_time:
type: string
description: 任务创建时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。
example: 2025-09-02 09:51:02
workspace_id:
type: string
description: 工作空间 ID。
example: llm-dmt509ikxxxxxx
user_identity:
type: string
description: 用户标识。
example: 12402258xxxxxx
modifier:
type: string
description: 最后修改者标识。
example: 124022586xxxxxx
creator:
type: string
description: 创建者标识。
example: 1240225868xxxxxx
group:
type: string
description: 模型组。
example: facechain
model_name:
type: string
description: 模型名称标识符。
example: ft-202509020951-f8bf
max_output_cnt:
type: integer
description: 最大输出模型数量。
example: 1
FaceChainFinetuneStatusResponse:
type: object
description: 查询训练任务状态的响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于追踪和排查问题。
example: fcfb99e6-7ae5-48b2-acca-xxxxxx
output:
type: object
description: 训练任务输出信息。
properties:
job_id:
type: string
description: 训练任务 ID。
example: ft-202509020951-f8bf
job_name:
type: string
description: 训练任务名称。
example: ft-202509020951-f8bf
status:
type: string
description: 训练任务当前状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
finetuned_output:
type: string
description: 微调后的模型名称。训练成功后，将此值作为 `model` 参数传入人物写真生成 API。
example: facechain-finetune-ft-202509020951-f8bf
model:
type: string
description: 训练使用的模型。
example: facechain-finetune
base_model:
type: string
description: 基础模型名称。
example: facechain-finetune
training_file_ids:
type: array
description: 训练图片 URL 或文件 ID 列表。
items:
type: string
validation_file_ids:
type: array
description: 验证文件 ID 列表。
items:
type: string
hyper_parameters:
type: object
description: 训练使用的超参数。
training_type:
type: string
description: 训练类型。
example: sft
create_time:
type: string
description: 任务创建时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。
example: 2025-09-02 09:51:02
workspace_id:
type: string
description: 工作空间 ID。
example: llm-dmt509ikxxxxxxx
user_identity:
type: string
description: 用户标识。
example: 1240225868xxxxxx
modifier:
type: string
description: 最后修改者标识。
example: 1240225868xxxxxx
creator:
type: string
description: 创建者标识。
example: 1240225868xxxxxx
end_time:
type: string
description: 任务结束时间，东八区。格式：`YYYY-MM-DD HH:mm:ss`。仅在 `status` 为 `SUCCEEDED` 或 `FAILED` 时返回。
example: 2025-09-02 09:56:04
group:
type: string
description: 模型组。
example: facechain
usage:
type: integer
description: 训练次数（用于计费）。仅在 `status` 为 `SUCCEEDED` 时返回。
example: 1
model_name:
type: string
description: 模型名称标识符。
example: ft-202509020951-f8bf
max_output_cnt:
type: integer
description: 最大输出模型数量。
example: 1
output_cnt:
type: integer
description: 已生成的模型数量。仅在训练完成后返回。
example: 1
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识符。
example: a4d78a5f-655f-9639-8437-xxxxxx
code:
type: string
description: 错误码。可选值包括：`InvalidParameter`、`UnsupportedOperation`、`NotFound`、`Conflict`、`Throttling`、`InternalError`。
example: InvalidParameter
message:
type: string
description: 错误详情描述。
example: Missing training files.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-facechain-generation-create-task.md
+452
View File
@@ -0,0 +1,452 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物写真生成 — 创建任务
> 提交FaceChain人物写真生成任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /services/aigc/album/gen_potrait
openapi: 3.1.0
info:
title: 人物写真生成 FaceChain API
description: 基于 FaceChain 模型生成人物写真。支持两种模式：人物形象训练 LoRA 模式（需先完成人物形象训练）和人物形象免训练 TrainFree 模式（推荐，无需训练，一键极速生成）。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/services/aigc/album/gen_potrait:
post:
operationId: createFaceChainGenerationTask
summary: 提交人物写真生成任务
description: |-
提交一个异步的人物写真生成任务。支持基于 LoRA 的预设风格写真、自定义模板写真，以及免训练（TrainFree）自定义模板写真。接口会立即返回 `task_id`，需通过 `GET /tasks/{task_id}` 轮询获取任务状态和结果。
**输入限制**：
- 人物单人照：JPEG/JPG/PNG 格式，不超过 3MB，分辨率 256×256 ~ 2048×2048，人脸占比不低于 128×128，清晰正脸（角度不超过 15 度），1~5 张
- 自定义模板：JPEG/JPG/PNG 格式，不超过 5MB，分辨率 512×512 ~ 1680×1260，单人清晰风格模板图
- URL 地址中不能包含中文字符
**接口限制**：单账户（含主账号与 RAM 子账号）任务下发 QPS 为 2，并发任务数量限制为 1。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 固定设置为 `enable`，表示使用异步方式提交任务。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/FaceChainGenerationRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
examples:
success:
summary: 任务已接受
value:
request_id: 0b6a411a-56e6-9028-84eb-6852183248d8
output:
task_id: 7eb1032e-09a1-4df5-96ed-14091859ad57
task_status: PENDING
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 参数无效
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InvalidParameter
message: The request is missing required parameters or the parameters are out of the specified range, please check the parameters that you send
InvalidURL:
summary: URL 无效
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InvalidURL
message: The request URL is invalid, make sure the url is correct and is an image
InvalidImageResolution:
summary: 图像分辨率无效
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InvalidImageResolution
message: The input image resolution is too large or small
InvalidParameterDataInspection:
summary: 数据安全审查无法访问资源
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InvalidParameter.DataInspection
message: Don't have authorization to access the media resource during the data inspection process.
BadRequestEmptyModel:
summary: 缺少必选参数 model
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: BadRequest.EmptyModel
message: Required parameter "model" missing from request.
"401":
description: 认证失败 — API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidApiKey:
summary: API Key 无效
value:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
"403":
description: 资源访问被拒绝
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
ResourceAccessDenied:
summary: 资源无访问权限
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: Resource.AccessDenied
message: Resource {resource_id} access denied.
"500":
description: 内部服务错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InternalErrorAlgo:
summary: 算法内部错误
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InternalError.Algo
message: An internal error occurs during computation, please try this model later
InternalErrorInference:
summary: 推理错误
value:
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code: InternalError.Algo
message: "Inference error: Inference error"
x-codeSamples:
- lang: curl
label: 预设风格（LoRA 模式）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/album/gen_potrait' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "facechain-generation",
"parameters": {
"style": "f_idcard_female",
"size": "768*1024",
"n": 4
},
"resources": [
{
"resource_id": "women_model",
"resource_type": "facelora"
}
]
}'
- lang: curl
label: 自定义模板（LoRA 模式）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/album/gen_potrait' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "facechain-generation",
"parameters": {
"style": "portrait_url_template",
"n": 1
},
"input": {
"template_url": "https://example.com/template.jpg"
},
"resources": [
{
"resource_id": "women_model",
"resource_type": "facelora"
}
]
}'
- lang: curl
label: 免训练模式（TrainFree）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/album/gen_potrait' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
"model": "facechain-generation",
"parameters": {
"style": "train_free_portrait_url_template",
"n": 1
},
"input": {
"template_url": "https://example.com/template.jpg",
"user_urls": ["https://example.com/face.jpg"]
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
FaceChainGenerationRequest:
type: object
required:
- model
properties:
model:
type: string
description: 模型名称。此处固定为 `facechain-generation`。
enum:
- facechain-generation
example: facechain-generation
resources:
type: array
description: 人物形象 LoRA 资源列表。使用预设风格或自定义模板模式（非免训练模式）时为必填，从人物形象训练 API 获取。使用免训练模式（TrainFree）时无需填写，填写也会被忽略。
items:
type: object
properties:
resource_id:
type: string
description: 模型定制得到的 LoRA 数据 ID，从人物形象训练任务的成功结果中获取。
example: women_model
resource_type:
type: string
description: 资源类型。固定为 `facelora`。
enum:
- facelora
example: facelora
parameters:
type: object
description: 生成参数。
properties:
style:
type: string
description: |-
输出图像的预设风格或自定义模板模式。
**预设风格**（需要 LoRA 资源）：
- `f_idcard_male` — 证件照男
- `f_business_male` — 商务写真男
- `f_idcard_female` — 证件照女
- `f_business_female` — 商务写真女
- `m_springflower_female` — 春日花园
- `f_summersport_female` — 夏日运动
- `f_autumnleaf_female` — 秋日印象
- `m_winterchinese_female` — 冬日国风
- `f_hongkongvintage_female` — 港风复古
- `f_lightportray_female` — 轻写真
**自定义模板模式**：
- `portrait_url_template` — 自定义模板 + LoRA（需传入 `input.template_url` 和 LoRA 资源）
- `train_free_portrait_url_template` — 自定义模板免训练（需传入 `input.template_url` 和 `input.user_urls`，无需 LoRA 资源）
example: f_idcard_female
size:
type: string
description: 生成图像的分辨率。目前支持 `768*1024`。使用自定义模板模式或免训练模式时不需要该参数。
example: 768*1024
n:
type: integer
description: 生成图片数量。取值范围 `1~5`，默认值为 `4`。
minimum: 1
maximum: 5
default: 4
example: 4
skin_retouch:
type: boolean
description: 免训练写真生成时是否对输入用户图进行自动美颜处理。默认为 `true`（自动美颜），可设置为 `false`（不美颜，用户可自行前后处理）。
default: true
input:
type: object
description: 自定义模板模式下的输入数据。
properties:
template_url:
type: string
format: uri
description: |-
用户自定义模板的 URL 链接。当 `parameters.style` 为 `portrait_url_template` 或 `train_free_portrait_url_template` 时为必填。
- **格式**：JPEG、JPG、PNG
- **大小**：不超过 5MB
- **分辨率**：512×512 ~ 1680×1260 像素
- **要求**：单人、清晰且高质量的风格模板图，人脸无遮挡和模糊。URL 中不能包含中文字符。
example: https://example.com/template.jpg
user_urls:
type: array
description: |-
一组包含用户正脸单人照的 URL 链接。当 `parameters.style` 为 `train_free_portrait_url_template` 时为必填。至少 1 张，最多 5 张，需通过人物图像检测 API（facechain-facedetect）验证通过。
- **格式**：JPEG、JPG、PNG
- **大小**：每张不超过 3MB
- **分辨率**：256×256 ~ 2048×2048 像素
- **人脸**：占比不低于 128×128 像素
- **要求**：清晰正脸单人照，人脸角度不超过 15 度。URL 中不能包含中文字符。
items:
type: string
format: uri
minItems: 1
maxItems: 5
example:
- https://example.com/face.jpg
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交接口的响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: 0b6a411a-56e6-9028-84eb-6852183248d8
output:
type: object
properties:
task_id:
type: string
description: 提交异步任务的作业 ID。实际作业结果需要通过异步任务查询接口获取。
example: 7eb1032e-09a1-4df5-96ed-14091859ad57
task_status:
type: string
description: 提交异步任务后的作业状态，初始状态通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
TaskStatusResponse:
type: object
description: 查询任务状态接口的响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。
example: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status:
type: string
description: |-
被查询作业的作业状态。
- `PENDING` — 排队中
- `RUNNING` — 处理中
- `SUCCEEDED` — 成功
- `FAILED` — 失败
- `UNKNOWN` — 作业不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:22.629
scheduled_time:
type: string
description: 任务开始执行的时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:22.655
end_time:
type: string
description: 任务完成时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:50.540
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
type: object
properties:
url:
type: string
format: uri
description: 生成图像的 URL。有效期 24 小时，请及时下载。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image1.jpg
result_url:
type: string
format: uri
description: 包含模型生成结果的 URL，可在 24 小时内随时下载。输出图像分辨率为 768×1024。仅当 `task_status` 为 `SUCCEEDED` 时返回。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
example: InvalidImageResolution
message:
type: string
description: 错误详细信息。仅当 `task_status` 为 `FAILED` 时返回。
example: The input image resolution is too large or small
task_metrics:
type: object
description: 任务完成指标。
properties:
TOTAL:
type: integer
description: 子任务总数。
example: 4
SUCCEEDED:
type: integer
description: 成功的子任务数。
example: 4
FAILED:
type: integer
description: 失败的子任务数。
example: 0
usage:
type: object
description: 本次请求的计量信息。
properties:
image_count:
type: integer
description: 本次请求生成图像的数量。
example: 4
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code:
type: string
description: 错误码。可能值包括 `InvalidParameter`（参数无效）、`InvalidURL`（URL 无效）、`InvalidImageResolution`（图像分辨率无效）、`InvalidParameter.DataInspection`（数据安全审查无法访问资源）、`BadRequest.EmptyModel`（缺少必选参数 model）、`Resource.AccessDenied`（资源无访问权限）、`InvalidApiKey`（API Key 无效）、`InternalError.Algo`（算法内部错误）。
example: InvalidParameter
message:
type: string
description: 错误详情。
example: The request is missing required parameters or the parameters are out of the specified range, please check the parameters that you send
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-facechain-generation-facechain-face-det.md
+231
View File
@@ -0,0 +1,231 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# FaceChain — 图像检测
> 检测图像中是否包含符合要求的人脸
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
FaceChain 人物图像检测用于判断输入图像是否包含符合要求的人脸，通常在人物写真生成前作为图像筛选步骤使用。
**限制**：每个账号 QPS 上限为 5。
## OpenAPI
````yaml post /services/vision/facedetection/detect
openapi: 3.1.0
info:
title: FaceChain Face Detection API
description: 人物图像检测 API。检测输入图像中是否包含人脸，用于人物写真生成前的图像筛选。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: Beijing
security:
- BearerAuth: []
paths:
/services/vision/facedetection/detect:
post:
operationId: detectFace
summary: 检测人脸
description: 检测输入图像中是否包含符合要求的人脸。支持批量输入多张图像，返回每张图像的检测结果。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/FaceDetectionRequest"
responses:
"200":
description: 检测成功
content:
application/json:
schema:
$ref: "#/components/schemas/FaceDetectionResponse"
examples:
success:
summary: 检测成功
value:
output:
is_face:
- true
- false
- true
failed_reason:
- ""
- no face detected
- ""
usage: {}
request_id: 549e0573-f630-9c17-8df2-08f605b4a646
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 参数缺失或无效
value:
code: InvalidParameter
message: Required parameter(s) missing or invalid, please check the request parameters.
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
"401":
description: 认证失败 — API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidApiKey:
summary: API Key 无效
value:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
"429":
description: 超出速率限制（QPS 上限为 5）
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"500":
description: 服务端内部错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InternalErrorAlgo:
summary: 算法执行异常
value:
code: InternalError.Algo
message: 服务内部算法执行异常。常见原因为输入的图片 URL 包含非 ASCII 字符（如中文），请对 URL 进行编码处理后重试。
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/vision/facedetection/detect' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "facechain-facedetect",
"input": {
"images": [
"https://example.com/image1.png",
"https://example.com/image2.jpg",
"https://example.com/image3.png"
]
},
"parameters": {}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
FaceDetectionRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称，固定为 `facechain-facedetect`。
enum:
- facechain-facedetect
example: facechain-facedetect
input:
type: object
required:
- images
description: 输入图像参数。
properties:
images:
type: array
items:
type: string
format: uri
description: |-
待检测图像的公网可访问 URL 列表。
**图像要求**：
- **格式**：JPEG、PNG、JPG、WEBP
- **分辨率**：宽和高必须在 256 到 4096 像素之间
- **文件大小**：不超过 5 MB
> **重要**
>
> 图片 URL 中如果包含非 ASCII 字符（如中文文件名），需要先进行 URL 编码（percent-encoding），否则可能导致 `InternalError.Algo` 错误。例如，在 Python 中使用 `urllib.parse.quote()`，在 JavaScript 中使用 `encodeURI()` 对 URL 进行编码。
**选图建议**（用于人物写真生成）：
- 每张图像仅包含 1 张人脸
- 五官清晰可见、正面照
- 人脸区域大于 128x128 像素
- 避免佩戴墨镜或面部遮挡
- 避免浓妆
example:
- https://example.com/image1.png
- https://example.com/image2.jpg
parameters:
type: object
description: 生成参数。当前无可用参数，传空对象 `{}` 即可。
properties: {}
FaceDetectionResponse:
type: object
description: 人脸检测响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于链路追踪和问题排查。
example: 549e0573-f630-9c17-8df2-08f605b4a646
output:
type: object
description: 检测结果。
properties:
is_face:
type: array
items:
type: boolean
description: 每张输入图像的人脸检测结果。`true` 表示检测到符合要求的人脸，`false` 表示未检测到。数组顺序与输入图像顺序一致。
example:
- true
- false
- true
failed_reason:
type: array
items:
type: string
description: 每张输入图像的检测失败原因。检测通过时为空字符串 `""`，未通过时返回具体原因（如 `"no face detected"`）。数组顺序与输入图像顺序一致。
example:
- ""
- no face detected
- ""
usage:
type: object
description: 使用量统计。当前为空对象。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识符。
example: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code:
type: string
description: 错误码。
example: InvalidParameter
message:
type: string
description: 错误描述信息。
example: Required parameter(s) missing or invalid, please check the request parameters.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-facechain-generation-query-result.md
+343
View File
@@ -0,0 +1,343 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物写真生成 — 查询结果
> 查询FaceChain人物写真生成任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 人物写真生成 FaceChain API
description: 基于 FaceChain 模型生成人物写真。支持两种模式：人物形象训练 LoRA 模式（需先完成人物形象训练）和人物形象免训练 TrainFree 模式（推荐，无需训练，一键极速生成）。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getFaceChainGenerationTaskStatus
summary: 查询人物写真生成任务状态
description: 轮询人物写真生成任务的状态和结果。持续轮询直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。结果图像的 URL 有效期为 24 小时，请及时下载或转存。
parameters:
- name: task_id
in: path
required: true
description: 提交人物写真生成任务时返回的任务 ID。
schema:
type: string
example: 86ecf553-d340-4e21-af6e-a0c6a421c010
responses:
"200":
description: 获取任务状态成功
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 0b6a411a-56e6-9028-84eb-6852183248d8
output:
task_id: 7eb1032e-09a1-4df5-96ed-14091859ad57
task_status: SUCCEEDED
submit_time: 2025-08-15 10:20:22.629
scheduled_time: 2025-08-15 10:20:22.655
end_time: 2025-08-15 10:20:50.540
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image1.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image2.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image3.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image4.jpg
task_metrics:
TOTAL: 4
SUCCEEDED: 4
FAILED: 0
usage:
image_count: 4
FAILED:
summary: 任务失败
value:
request_id: f24149fe-4722-9763-xxxxxx
output:
task_id: 9d62befa-0139-4e4d-xxxxxx
task_status: FAILED
submit_time: 2025-08-15 10:20:22.629
scheduled_time: 2025-08-15 10:20:22.655
end_time: 2025-08-15 10:20:50.540
code: InvalidImageResolution
message: The input image resolution is too large or small
usage:
image_count: 0
RUNNING:
summary: 任务处理中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 查询任务状态
source: |-
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header 'Authorization: Bearer $DASHSCOPE_API_KEY'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
FaceChainGenerationRequest:
type: object
required:
- model
properties:
model:
type: string
description: 模型名称。此处固定为 `facechain-generation`。
enum:
- facechain-generation
example: facechain-generation
resources:
type: array
description: 人物形象 LoRA 资源列表。使用预设风格或自定义模板模式（非免训练模式）时为必填，从人物形象训练 API 获取。使用免训练模式（TrainFree）时无需填写，填写也会被忽略。
items:
type: object
properties:
resource_id:
type: string
description: 模型定制得到的 LoRA 数据 ID，从人物形象训练任务的成功结果中获取。
example: women_model
resource_type:
type: string
description: 资源类型。固定为 `facelora`。
enum:
- facelora
example: facelora
parameters:
type: object
description: 生成参数。
properties:
style:
type: string
description: |-
输出图像的预设风格或自定义模板模式。
**预设风格**（需要 LoRA 资源）：
- `f_idcard_male` — 证件照男
- `f_business_male` — 商务写真男
- `f_idcard_female` — 证件照女
- `f_business_female` — 商务写真女
- `m_springflower_female` — 春日花园
- `f_summersport_female` — 夏日运动
- `f_autumnleaf_female` — 秋日印象
- `m_winterchinese_female` — 冬日国风
- `f_hongkongvintage_female` — 港风复古
- `f_lightportray_female` — 轻写真
**自定义模板模式**：
- `portrait_url_template` — 自定义模板 + LoRA（需传入 `input.template_url` 和 LoRA 资源）
- `train_free_portrait_url_template` — 自定义模板免训练（需传入 `input.template_url` 和 `input.user_urls`，无需 LoRA 资源）
example: f_idcard_female
size:
type: string
description: 生成图像的分辨率。目前支持 `768*1024`。使用自定义模板模式或免训练模式时不需要该参数。
example: 768*1024
n:
type: integer
description: 生成图片数量。取值范围 `1~5`，默认值为 `4`。
minimum: 1
maximum: 5
default: 4
example: 4
skin_retouch:
type: boolean
description: 免训练写真生成时是否对输入用户图进行自动美颜处理。默认为 `true`（自动美颜），可设置为 `false`（不美颜，用户可自行前后处理）。
default: true
input:
type: object
description: 自定义模板模式下的输入数据。
properties:
template_url:
type: string
format: uri
description: |-
用户自定义模板的 URL 链接。当 `parameters.style` 为 `portrait_url_template` 或 `train_free_portrait_url_template` 时为必填。
- **格式**：JPEG、JPG、PNG
- **大小**：不超过 5MB
- **分辨率**：512×512 ~ 1680×1260 像素
- **要求**：单人、清晰且高质量的风格模板图，人脸无遮挡和模糊。URL 中不能包含中文字符。
example: https://example.com/template.jpg
user_urls:
type: array
description: |-
一组包含用户正脸单人照的 URL 链接。当 `parameters.style` 为 `train_free_portrait_url_template` 时为必填。至少 1 张，最多 5 张，需通过人物图像检测 API（facechain-facedetect）验证通过。
- **格式**：JPEG、JPG、PNG
- **大小**：每张不超过 3MB
- **分辨率**：256×256 ~ 2048×2048 像素
- **人脸**：占比不低于 128×128 像素
- **要求**：清晰正脸单人照，人脸角度不超过 15 度。URL 中不能包含中文字符。
items:
type: string
format: uri
minItems: 1
maxItems: 5
example:
- https://example.com/face.jpg
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交接口的响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: 0b6a411a-56e6-9028-84eb-6852183248d8
output:
type: object
properties:
task_id:
type: string
description: 提交异步任务的作业 ID。实际作业结果需要通过异步任务查询接口获取。
example: 7eb1032e-09a1-4df5-96ed-14091859ad57
task_status:
type: string
description: 提交异步任务后的作业状态，初始状态通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
TaskStatusResponse:
type: object
description: 查询任务状态接口的响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。
example: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status:
type: string
description: |-
被查询作业的作业状态。
- `PENDING` — 排队中
- `RUNNING` — 处理中
- `SUCCEEDED` — 成功
- `FAILED` — 失败
- `UNKNOWN` — 作业不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:22.629
scheduled_time:
type: string
description: 任务开始执行的时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:22.655
end_time:
type: string
description: 任务完成时间（UTC+8），格式为 `YYYY-MM-DD HH:mm:ss.SSS`。
example: 2025-08-15 10:20:50.540
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
type: object
properties:
url:
type: string
format: uri
description: 生成图像的 URL。有效期 24 小时，请及时下载。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/image1.jpg
result_url:
type: string
format: uri
description: 包含模型生成结果的 URL，可在 24 小时内随时下载。输出图像分辨率为 768×1024。仅当 `task_status` 为 `SUCCEEDED` 时返回。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
example: InvalidImageResolution
message:
type: string
description: 错误详细信息。仅当 `task_status` 为 `FAILED` 时返回。
example: The input image resolution is too large or small
task_metrics:
type: object
description: 任务完成指标。
properties:
TOTAL:
type: integer
description: 子任务总数。
example: 4
SUCCEEDED:
type: integer
description: 成功的子任务数。
example: 4
FAILED:
type: integer
description: 失败的子任务数。
example: 0
usage:
type: object
description: 本次请求的计量信息。
properties:
image_count:
type: integer
description: 本次请求生成图像的数量。
example: 4
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code:
type: string
description: 错误码。可能值包括 `InvalidParameter`（参数无效）、`InvalidURL`（URL 无效）、`InvalidImageResolution`（图像分辨率无效）、`InvalidParameter.DataInspection`（数据安全审查无法访问资源）、`BadRequest.EmptyModel`（缺少必选参数 model）、`Resource.AccessDenied`（资源无访问权限）、`InvalidApiKey`（API Key 无效）、`InternalError.Algo`（算法内部错误）。
example: InvalidParameter
message:
type: string
description: 错误详情。
example: The request is missing required parameters or the parameters are out of the specified range, please check the parameters that you send
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-image-erase-completion-create-task.md
+235
View File
@@ -0,0 +1,235 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像擦除补全 — 创建任务
> 异步提交图像擦除补全任务
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: 图像擦除补全 API
description: 图像擦除补全（image-erase-completion）API，可根据mask区域对原图进行擦除补全。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API (Beijing)
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createImageEraseCompletion
summary: 创建擦除补全任务
description: 提交一个异步图像擦除补全任务。需要设置 `X-DashScope-Async` header 为 `enable`。
parameters:
- name: X-DashScope-Async
in: header
required: true
schema:
type: string
enum:
- enable
default: enable
description: 必须设置为 `enable`，表示使用异步方式提交任务。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ImageEraseCompletionRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 53950fb7-281a-4e60-b543-xxxxxxxxxxxx
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
code: InvalidParameter
message: The model is not supported.
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
"401":
description: 认证失败
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-codeSamples:
- lang: curl
label: curl
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "image-erase-completion",
"input": {
"image_url": "http://xxx/input.png",
"mask_url": "http://xxx/mask.png",
"foreground_url": "http://xxx/foreground.png"
},
"parameters":{
"dilate_flag":true
}
}'
security:
- BearerAuth: []
components:
schemas:
ImageEraseCompletionRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- image-erase-completion
description: 模型名称，固定值为 `image-erase-completion`。
input:
$ref: "#/components/schemas/ImageEraseCompletionInput"
parameters:
$ref: "#/components/schemas/ImageEraseCompletionParameters"
ImageEraseCompletionInput:
type: object
required:
- image_url
- mask_url
properties:
image_url:
type: string
description: 待擦除处理的输入图片的URL链接。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
mask_url:
type: string
description: 蒙版图片的URL链接。蒙版区域为白色，保留区域为黑色。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
foreground_url:
type: string
description: 前景图片的URL链接。指定前景，可避免擦除结果改变前景。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
ImageEraseCompletionParameters:
type: object
properties:
fast_mode:
type: boolean
default: false
description: 是否使用快速模式，开启后可加快推理速度。默认值为false。
dilate_flag:
type: boolean
default: true
description: 是否使用mask扩展功能。开启后，将对mask进行自动扩展来增强擦除效果。默认值为true。
add_watermark:
type: boolean
default: true
description: 是否添加水印。默认值为true。添加的水印不影响图像质量。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID，用于后续查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态，提交成功时为 PENDING。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUSPENDED
- SUCCEEDED
- FAILED
description: 任务状态。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
output_image_url:
type: string
description: 擦除补全后的结果图片URL。仅在任务成功时返回。URL有效期为24小时。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功的任务数。
FAILED:
type: integer
description: 失败的任务数。
description: 任务的执行指标。
code:
type: string
description: 错误码，仅在任务失败时返回。
message:
type: string
description: 错误信息，仅在任务失败时返回。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
description: 计量信息。仅在任务成功时返回。
ErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-image-erase-completion-query-result.md
+226
View File
@@ -0,0 +1,226 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像擦除补全 — 查询结果
> 根据任务ID查询异步擦除补全任务的状态和结果
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 图像擦除补全 API
description: 图像擦除补全（image-erase-completion）API，可根据mask区域对原图进行擦除补全。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API (Beijing)
paths:
/tasks/{task_id}:
get:
operationId: getImageEraseCompletionTaskStatus
summary: 查询擦除补全任务结果
description: 根据任务ID查询异步擦除补全任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
schema:
type: string
description: 任务ID，从创建任务接口的返回结果中获取。
responses:
"200":
description: 任务查询成功
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
task_id: 53950fb7-281a-4e60-b543-xxxxxxxxxxxx
task_status: SUCCEEDED
submit_time: 2024-05-16 13:50:01.247
scheduled_time: 2024-05-16 13:50:01.354
end_time: 2024-05-16 13:50:27.795
output_image_url: http://xxx/result.png
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: 4246a1de-2aab-9b49-ba87-e0d12e221a06
output:
task_id: 53950fb7-281a-4e60-b543-xxxxxxxxxxxx
task_status: FAILED
submit_time: 2024-03-22 12:07:07.183
scheduled_time: 2024-03-22 12:07:07.253
end_time: 2024-03-22 12:07:07.604
code: InternalError.Algo
message: video generation error
RUNNING:
summary: 任务运行中
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: 53950fb7-281a-4e60-b543-xxxxxxxxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://maas.qianwenaiapi.com/api/v1/tasks/53950fb7-281a-4e60-b543-xxxxxxxxxxxx
security:
- BearerAuth: []
components:
schemas:
ImageEraseCompletionRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- image-erase-completion
description: 模型名称，固定值为 `image-erase-completion`。
input:
$ref: "#/components/schemas/ImageEraseCompletionInput"
parameters:
$ref: "#/components/schemas/ImageEraseCompletionParameters"
ImageEraseCompletionInput:
type: object
required:
- image_url
- mask_url
properties:
image_url:
type: string
description: 待擦除处理的输入图片的URL链接。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
mask_url:
type: string
description: 蒙版图片的URL链接。蒙版区域为白色，保留区域为黑色。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
foreground_url:
type: string
description: 前景图片的URL链接。指定前景，可避免擦除结果改变前景。图片格式支持JPEG、PNG、JPG、BMP、WEBP，图片分辨率在512×512~4096×4096之间，文件大小不超过10MB。
ImageEraseCompletionParameters:
type: object
properties:
fast_mode:
type: boolean
default: false
description: 是否使用快速模式，开启后可加快推理速度。默认值为false。
dilate_flag:
type: boolean
default: true
description: 是否使用mask扩展功能。开启后，将对mask进行自动扩展来增强擦除效果。默认值为true。
add_watermark:
type: boolean
default: true
description: 是否添加水印。默认值为true。添加的水印不影响图像质量。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID，用于后续查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态，提交成功时为 PENDING。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUSPENDED
- SUCCEEDED
- FAILED
description: 任务状态。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
output_image_url:
type: string
description: 擦除补全后的结果图片URL。仅在任务成功时返回。URL有效期为24小时。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功的任务数。
FAILED:
type: integer
description: 失败的任务数。
description: 任务的执行指标。
code:
type: string
description: 错误码，仅在任务失败时返回。
message:
type: string
description: 错误信息，仅在任务失败时返回。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
description: 计量信息。仅在任务成功时返回。
ErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-image-out-painting-create-task.md
+435
View File
@@ -0,0 +1,435 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像画面扩展 — 创建任务
> 创建图像画面扩展异步任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
支持旋转图像、等比例扩图、指定方向扩图、指定宽高比扩图。
## 扩图模式与优先级
参数存在优先级关系：当同时设置多个扩图模式的参数时，仅高优先级的参数生效。旋转参数 `angle` 不受优先级影响，可与任意扩图模式叠加使用。
| 功能 | 参数 | 说明 |
| ------- | --------------------------------------------------------- | ----------------------- |
| 旋转 | `angle` | 先旋转，后扩展。可与下方任意扩图模式同时使用。 |
| 扩图优先级 1 | `output_ratio` | 按宽高比扩展画面。 |
| 扩图优先级 2 | `x_scale`、`y_scale` | 按比例扩展画面。 |
| 扩图优先级 3 | `left_offset`、`right_offset`、`top_offset`、`bottom_offset` | 在指定方向添加像素扩展画面。 |
## 参数设置建议
- **仅按宽高比扩图**：设置 `output_ratio` 为非空值（如 `"4:3"`）。
- **仅按比例扩图**：设置 `x_scale` 和 `y_scale`，至少一个大于 1.0。
- **仅在指定方向添加像素扩图**：设置 `left_offset`、`right_offset`、`top_offset`、`bottom_offset`，至少一个大于 0。
- **仅旋转图像**：设置 `angle` 为 \[1, 359] 之间的值。建议避免设置为 90、180、270 度。
- **先旋转再扩图**：设置 `angle` 的同时，搭配上述任一扩图模式的参数。
## 参数组合示例
<Accordion title="查看组合示例">
| 参数设置 | 生效参数 | 说明 |
| ------------------------------------------------------------------ | ------------------------ | ------------------------------- |
| `output_ratio="4:3"`, `x_scale=2.0` | `output_ratio` | `output_ratio` 优先级高于 `x_scale`。 |
| `x_scale=2.0`, `left_offset=100` | `x_scale` | `x_scale` 优先级高于 `left_offset`。 |
| `angle=90`, `x_scale=2.0` | `angle` + `x_scale` | 旋转与扩图叠加，两者均生效。 |
| `angle=90`, `output_ratio="4:3"`, `x_scale=2.0`, `left_offset=100` | `angle` + `output_ratio` | 旋转与最高优先级扩图模式生效。 |
</Accordion>
## 错误码
| HTTP 状态码 | 错误码 | 错误信息 | 说明 |
| -------- | ------------------------------- | ----------------------------------------------------------------- | ---------------------- |
| 400 | InvalidParameter.JsonPhrase | input json error | 输入 JSON 格式错误。 |
| 400 | InvalidParameter.FileDownload | oss download error | 输入图像下载失败，请检查 URL 是否有效。 |
| 400 | InvalidParameter.ImageFormat | read image error | 读取图像失败，请检查图像格式。 |
| 400 | InvalidParameter.ImageContent | The image content does not comply with green network verification | 图像内容不合规。 |
| 400 | InvalidParameter | the parameters must conform to the specification: xxx | 输入参数值超出范围。 |
| 400 | InvalidParameter.DataInspection | The image size is not supported for the data inspection. | 输出图像尺寸超限（大于 10 MB）。 |
| 500 | InternalError.Algo | algorithm process error | 算法处理错误。 |
| 500 | InternalError.FileUpload | oss upload error | 文件上传失败。 |
## FAQ
<Accordion title="创建任务接口响应成功，但没有返回图像 URL？">
创建任务接口只返回 `task_id` 和 `task_status`。请使用[查询扩图结果](/api-reference/image-generation/image-out-painting/query-result)接口，通过 `task_id` 轮询获取生成结果。
</Accordion>
<Accordion title="设置 output_ratio 后，为什么模型没有根据 x_scale 或 y_scale 自动计算另一个方向的比例？">
三种扩图方式（宽高比、比例缩放、方向偏移）是互斥的，存在优先级关系。`output_ratio` 优先级最高，设置后 `x_scale`/`y_scale` 和 `*_offset` 参数不生效。如需按比例扩图，请不要设置 `output_ratio`。
</Accordion>
## OpenAPI
````yaml post /services/aigc/image2image/out-painting
openapi: 3.1.0
info:
title: Image Out-Painting API
description: 图像画面扩展 API。支持旋转图像、等比例扩图、指定方向扩图、指定宽高比扩图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/image2image/out-painting:
post:
operationId: createImageOutPainting
summary: 创建扩图任务
description: 创建图像画面扩展任务。支持旋转图像、等比例扩图、指定方向扩图、指定宽高比扩图。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 开启异步处理，必须设为 `enable`。HTTP 调用仅支持异步方式，不设置此 Header 会返回错误。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ImageOutPaintingRequest"
responses:
"200":
description: 任务提交成功。使用返回的 `task_id` 轮询任务结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数错误。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: Invalid request parameters.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败，API Key 无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxx
x-codeSamples:
- lang: curl
label: 旋转图像
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/out-painting' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
"model": "image-out-painting",
"input": {
"image_url": "http://xxx/image.jpg"
},
"parameters": {
"angle": 45,
"x_scale": 1.5,
"y_scale": 1.5
}
}'
- lang: curl
label: 等比例扩图
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/out-painting' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
"model": "image-out-painting",
"input": {
"image_url": "http://xxx/image.jpg"
},
"parameters": {
"x_scale": 2,
"y_scale": 2,
"best_quality": false,
"limit_image_size": true
}
}'
- lang: curl
label: 指定方向扩图
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/out-painting' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
"model": "image-out-painting",
"input": {
"image_url": "http://xxx/image.jpg"
},
"parameters": {
"left_offset": 200,
"right_offset": 100,
"best_quality": false,
"limit_image_size": true
}
}'
- lang: curl
label: 指定宽高比扩图
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/out-painting' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
"model": "image-out-painting",
"input": {
"image_url": "http://xxx/image.jpg"
},
"parameters": {
"angle": 0,
"output_ratio": "4:3",
"best_quality": false,
"limit_image_size": true
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ImageOutPaintingRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
description: 模型名称。
enum:
- image-out-painting
example: image-out-painting
input:
$ref: "#/components/schemas/OutPaintingInput"
parameters:
$ref: "#/components/schemas/OutPaintingParameters"
OutPaintingInput:
type: object
required:
- image_url
description: 输入数据。
properties:
image_url:
type: string
description: |-
待扩展图像的 URL。
**图片限制：**
- 支持格式：JPG、JPEG、PNG、HEIF、WEBP
- 单边像素范围：512 ~ 4096
- 文件大小：≤ 10 MB
example: http://xxx/image.jpg
OutPaintingParameters:
type: object
description: 扩图参数。支持四种扩图模式：旋转、宽高比、等比例缩放、指定方向偏移。存在优先级：`angle`（旋转） → `output_ratio`（宽高比） → `x_scale`/`y_scale`（等比例） → `*_offset`（方向偏移）。
properties:
angle:
type: integer
description: |-
旋转角度，逆时针方向旋转。取值范围：0 ~ 359。默认值：0。
旋转后系统自动扩展画面以填充因旋转产生的空白区域。建议避免设置为 90、180、270 度。
default: 0
minimum: 0
maximum: 359
example: 45
output_ratio:
type: string
description: |-
输出图像的宽高比。设置后，系统按照指定比例扩展画面。
可选值：`""`（不使用）、`"1:1"`、`"3:4"`、`"4:3"`、`"9:16"`、`"16:9"`。默认值：`""`。
default: ""
enum:
- ""
- 1:1
- 3:4
- 4:3
- 9:16
- 16:9
example: 4:3
x_scale:
type: number
description: 水平方向缩放倍数。取值范围：1.0 ~ 3.0。默认值：1.0。
default: 1
minimum: 1
maximum: 3
example: 2
y_scale:
type: number
description: 垂直方向缩放倍数。取值范围：1.0 ~ 3.0。默认值：1.0。
default: 1
minimum: 1
maximum: 3
example: 2
top_offset:
type: integer
description: |-
向上扩展的像素数。默认值：0。
约束：`top_offset + bottom_offset` 必须小于原图高度的 3 倍。
default: 0
example: 0
bottom_offset:
type: integer
description: |-
向下扩展的像素数。默认值：0。
约束：`top_offset + bottom_offset` 必须小于原图高度的 3 倍。
default: 0
example: 0
left_offset:
type: integer
description: |-
向左扩展的像素数。默认值：0。
约束：`left_offset + right_offset` 必须小于原图宽度的 3 倍。
default: 0
example: 200
right_offset:
type: integer
description: |-
向右扩展的像素数。默认值：0。
约束：`left_offset + right_offset` 必须小于原图宽度的 3 倍。
default: 0
example: 100
best_quality:
type: boolean
description: 是否开启高质量模式。开启后生成质量更高，但耗时更长。默认值：`false`。
default: false
example: false
limit_image_size:
type: boolean
description: 是否限制输出图像的尺寸。开启后，当输出图像尺寸超过原图尺寸时，系统会等比缩放到原图大小。默认值：`true`。
default: true
example: true
add_watermark:
type: boolean
description: 是否在图像右下角添加水印。默认值：`true`。
default: true
example: true
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，有效期为 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识，用于排查问题。
OutPaintingTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识，用于排查问题。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，有效期为 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
output_image_url:
type: string
description: 生成的图片 URL。有效期为 24 小时，请及时下载保存。仅在任务成功时返回。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功数。
FAILED:
type: integer
description: 失败数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误详情。仅在任务失败时返回。
usage:
type: object
description: 用量统计，仅统计成功的结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误详情。
request_id:
type: string
description: 请求唯一标识，用于排查问题。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-image-out-painting-query-result.md
+332
View File
@@ -0,0 +1,332 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 图像画面扩展 — 查询结果
> 查询图像画面扩展任务状态
查询任务状态和结果。
## 轮询策略
1. 通过[创建扩图任务](/api-reference/image-generation/image-out-painting/create-task)接口提交请求，获取 `task_id`。
2. 每 **10 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`output_image_url` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Image Out-Painting API
description: 图像画面扩展 API。支持旋转图像、等比例扩图、指定方向扩图、指定宽高比扩图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getImageOutPaintingTaskStatus
summary: 查询扩图结果
description: 查询图像画面扩展任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 创建扩图任务时返回的任务 ID。
schema:
type: string
responses:
"200":
description: 任务状态查询成功。
content:
application/json:
schema:
$ref: "#/components/schemas/OutPaintingTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
task_id: d76ec1e8-ea27-4038-8913-235c88ef0f70
task_status: SUCCEEDED
submit_time: 2024-05-16 13:50:01.247
scheduled_time: 2024-05-16 13:50:01.354
end_time: 2024-05-16 13:50:27.795
output_image_url: https://xxxx/xxxx
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: dccfdf23-b38e-97a6-a07b-f35118c1ada6
output:
task_id: 4cbabbdf-2c1f-43f4-b983-c2cc47f4c115
task_status: FAILED
submit_time: 2024-05-16 14:15:14.103
scheduled_time: 2024-05-16 14:15:14.154
end_time: 2024-05-16 14:15:14.694
code: InvalidParameter.FileDownload
message: download for input_image error
RUNNING:
summary: 任务运行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: d76ec1e8-ea27-4038-8913-235c88ef0f70
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
"400":
description: 请求参数错误。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
# 将 {task_id} 替换为创建任务时返回的实际任务 ID
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ImageOutPaintingRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
description: 模型名称。
enum:
- image-out-painting
example: image-out-painting
input:
$ref: "#/components/schemas/OutPaintingInput"
parameters:
$ref: "#/components/schemas/OutPaintingParameters"
OutPaintingInput:
type: object
required:
- image_url
description: 输入数据。
properties:
image_url:
type: string
description: |-
待扩展图像的 URL。
**图片限制：**
- 支持格式：JPG、JPEG、PNG、HEIF、WEBP
- 单边像素范围：512 ~ 4096
- 文件大小：≤ 10 MB
example: http://xxx/image.jpg
OutPaintingParameters:
type: object
description: 扩图参数。支持四种扩图模式：旋转、宽高比、等比例缩放、指定方向偏移。存在优先级：`angle`（旋转） → `output_ratio`（宽高比） → `x_scale`/`y_scale`（等比例） → `*_offset`（方向偏移）。
properties:
angle:
type: integer
description: |-
旋转角度，逆时针方向旋转。取值范围：0 ~ 359。默认值：0。
旋转后系统自动扩展画面以填充因旋转产生的空白区域。建议避免设置为 90、180、270 度。
default: 0
minimum: 0
maximum: 359
example: 45
output_ratio:
type: string
description: |-
输出图像的宽高比。设置后，系统按照指定比例扩展画面。
可选值：`""`（不使用）、`"1:1"`、`"3:4"`、`"4:3"`、`"9:16"`、`"16:9"`。默认值：`""`。
default: ""
enum:
- ""
- 1:1
- 3:4
- 4:3
- 9:16
- 16:9
example: 4:3
x_scale:
type: number
description: 水平方向缩放倍数。取值范围：1.0 ~ 3.0。默认值：1.0。
default: 1
minimum: 1
maximum: 3
example: 2
y_scale:
type: number
description: 垂直方向缩放倍数。取值范围：1.0 ~ 3.0。默认值：1.0。
default: 1
minimum: 1
maximum: 3
example: 2
top_offset:
type: integer
description: |-
向上扩展的像素数。默认值：0。
约束：`top_offset + bottom_offset` 必须小于原图高度的 3 倍。
default: 0
example: 0
bottom_offset:
type: integer
description: |-
向下扩展的像素数。默认值：0。
约束：`top_offset + bottom_offset` 必须小于原图高度的 3 倍。
default: 0
example: 0
left_offset:
type: integer
description: |-
向左扩展的像素数。默认值：0。
约束：`left_offset + right_offset` 必须小于原图宽度的 3 倍。
default: 0
example: 200
right_offset:
type: integer
description: |-
向右扩展的像素数。默认值：0。
约束：`left_offset + right_offset` 必须小于原图宽度的 3 倍。
default: 0
example: 100
best_quality:
type: boolean
description: 是否开启高质量模式。开启后生成质量更高，但耗时更长。默认值：`false`。
default: false
example: false
limit_image_size:
type: boolean
description: 是否限制输出图像的尺寸。开启后，当输出图像尺寸超过原图尺寸时，系统会等比缩放到原图大小。默认值：`true`。
default: true
example: true
add_watermark:
type: boolean
description: 是否在图像右下角添加水印。默认值：`true`。
default: true
example: true
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，有效期为 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识，用于排查问题。
OutPaintingTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识，用于排查问题。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，有效期为 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间。UTC+8 时区，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
output_image_url:
type: string
description: 生成的图片 URL。有效期为 24 小时，请及时下载保存。仅在任务成功时返回。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功数。
FAILED:
type: integer
description: 失败数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误详情。仅在任务失败时返回。
usage:
type: object
description: 用量统计，仅统计成功的结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误详情。
request_id:
type: string
description: 请求唯一标识，用于排查问题。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-kling-image-generation-create-task.md
+349
View File
@@ -0,0 +1,349 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建图像生成任务
> 提交可灵图像生成任务（文生图或参考图生图），获取 task_id 用于后续查询。
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.0.0
info:
title: 可灵图像生成 API
description: 可灵图像生成模型支持文生图、参考图生图两种任务。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
paths:
/services/aigc/image-generation/generation:
post:
summary: 创建图像生成任务
description: 提交可灵图像生成任务。图像生成任务有一定耗时（通常为1-2分钟），API采用异步调用。提交后请保存 task_id，用于查询任务状态与结果。
operationId: createKlingImageGenerationTask
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置参数。HTTP请求只支持异步，必须设置为 `enable`。缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/KlingImageGenerationRequest"
responses:
"200":
description: 任务创建成功
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTaskResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
4XX:
description: 创建任务失败
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
security:
- BearerAuth: []
x-codeSamples:
- lang: curl
label: 文生图
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling/kling-v3-image-generation",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵"
}
]
}
]
},
"parameters": {
"n": 2,
"aspect_ratio": "1:1",
"resolution": "1k"
}
}'
- lang: curl
label: 图生图（组图模式）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling/kling-v3-omni-image-generation",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "参考图1的风格和图2的背景，生成番茄炒蛋"
},
{
"image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
}
]
}
]
},
"parameters": {
"n": 4,
"result_type": "series",
"aspect_ratio": "1:1",
"resolution": "1k"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
KlingImageGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- kling/kling-v3-image-generation
- kling/kling-v3-omni-image-generation
input:
type: object
required:
- messages
description: 输入参数对象。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，因此数组内有且只有一个对象，该对象包含 `role` 和 `content` 两个属性。
items:
type: object
properties:
role:
type: string
description: 消息的角色。此参数必须设置为 `user`。
enum:
- user
content:
type: array
description: 消息内容，包含文本提示词（text）和可选的参考图像（image，支持多张）。
items:
type: object
properties:
text:
type: string
description: 正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过2500个字符，每个汉字、字母、数字或符号计为一个字符，超过将返回错误。注意：仅支持传入一个text，不传或传入多个将报错。示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。
image:
type: string
description: 参考图像的URL。支持 HTTP 或 HTTPS 协议。示例值：https://xxx/xxx.png。图像限制：格式为JPEG、JPG、PNG（不支持透明通道）；宽和高的范围为[300, 8000]像素；宽高比在1:2.5 ~ 2.5:1之间；文件大小不超过10MB；参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
element_list:
type: array
description: 主体列表，用于指定需要保持的主体。参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
items:
type: object
properties:
element_id:
type: integer
description: 传 element_list 时必填，表示主体ID。请在可灵-主体ID列表获取主体ID。参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
parameters:
type: object
description: 控制图像生成，比如图像张数、宽高比等。
properties:
n:
type: integer
description: |-
生成的图像张数。
- kling/kling-v3-image-generation：取值范围为1～9，默认值为1。
- kling/kling-v3-omni-image-generation：当且仅当 `result_type=single` 时生效，取值范围为1～9，默认值为1。
result_type:
type: string
description: |-
生成图像的类型。仅支持模型 kling/kling-v3-omni-image-generation。
- `single`（默认值）：单图。批量生成时仅风格相似，无分镜关联。
- `series`：组图。生成具有叙事/视觉连续性的分镜系列图像。
enum:
- single
- series
series_amount:
type: integer
description: 组图模式下的输出张数。仅支持模型 kling/kling-v3-omni-image-generation。取值范围为2～9，默认值为4。当且仅当 `result_type=series` 时生效。
aspect_ratio:
type: string
description: 输出图像的宽高比。示例值：16:9。
enum:
- 16:9
- 9:16
- 1:1
default: 16:9
resolution:
type: string
description: |-
输出图像分辨率。
- kling/kling-v3-image-generation：可选值为 `1k`、`2k`，默认值为 `1k`。
- kling/kling-v3-omni-image-generation：可选值为 `1k`、`2k`、`4k`，默认值为 `1k`。
示例值：1k。
enum:
- 1k
- 2k
- 4k
watermark:
type: boolean
description: |-
是否同时生成含水印的图像。水印位于图像右下角，文案固定为"可灵AI"。
- `false`（默认值）：不生成含水印的图像。
- `true`：同时生成含水印的图像。
示例值：false。
default: false
CreateTaskResponse:
type: object
properties:
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
QueryTaskResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
finished:
type: boolean
description: 任务是否已完成。
choices:
type: array
description: 模型生成的输出内容。此数组仅包含一个元素。
items:
type: object
properties:
finish_reason:
type: string
description: 任务停止原因，自然停止时为 `stop`。
message:
type: object
description: 模型返回的消息。
properties:
role:
type: string
description: 消息的角色，固定为 `assistant`。
content:
type: array
description: 生成的图像列表。
items:
type: object
properties:
type:
type: string
description: 输出内容的类型。固定为 `image`。
image:
type: string
description: 生成图像的URL，图像格式为PNG。链接有效期为30天，请及时下载并保存图像。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 生成图像的数量。
size:
type: string
description: 生成图片的分辨率，格式为`宽*高`。示例值：1360*768。
SR:
type: string
description: 生成图像的分辨率档位。示例值：1080。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
ErrorResponse:
type: object
properties:
code:
type: string
description: 请求失败的错误码。
message:
type: string
description: 请求失败的详细信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-kling-image-generation-query-result.md
+308
View File
@@ -0,0 +1,308 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 查询图像生成任务结果
> 通过 task_id 轮询查询可灵图像生成任务的执行状态与生成图像。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: 可灵图像生成 API
description: 可灵图像生成模型支持文生图、参考图生图两种任务。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
paths:
/tasks/{task_id}:
get:
summary: 查询图像生成任务结果
description: 查询可灵图像生成任务的执行状态与结果。建议采用轮询机制，并设置合理的查询间隔（如5秒）。task_id 查询有效期为24小时。
operationId: queryKlingImageGenerationTask
parameters:
- name: task_id
in: path
required: true
description: 任务ID，由创建任务接口返回。
schema:
type: string
responses:
"200":
description: 查询成功
content:
application/json:
schema:
$ref: "#/components/schemas/QueryTaskResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: 95146d89-9d70-481a-8c16-xxxxxx
output:
task_id: 2c502d25-12a9-4517-8972-xxxxxx
task_status: SUCCEEDED
submit_time: 2026-03-27 22:46:01.536
scheduled_time: 2026-03-27 22:46:01.580
end_time: 2026-03-27 22:46:24.831
finished: true
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://p4-fdl.klingai.com/xxx.png?xxx
type: image
- image: https://p4-fdl.klingai.com/xxx.png?xxx
type: image
usage:
size: 1024*1024
image_count: 2
SR: "1080"
FAILED:
summary: 任务执行异常
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
RUNNING:
summary: 任务处理中
value:
request_id: b5e89c60-766g-0740-9548-yyyyyy
output:
task_id: 3d613e36-23ba-5628-9083-yyyyyy
task_status: RUNNING
security:
- BearerAuth: []
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
KlingImageGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- kling/kling-v3-image-generation
- kling/kling-v3-omni-image-generation
input:
type: object
required:
- messages
description: 输入参数对象。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，因此数组内有且只有一个对象，该对象包含 `role` 和 `content` 两个属性。
items:
type: object
properties:
role:
type: string
description: 消息的角色。此参数必须设置为 `user`。
enum:
- user
content:
type: array
description: 消息内容，包含文本提示词（text）和可选的参考图像（image，支持多张）。
items:
type: object
properties:
text:
type: string
description: 正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过2500个字符，每个汉字、字母、数字或符号计为一个字符，超过将返回错误。注意：仅支持传入一个text，不传或传入多个将报错。示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。
image:
type: string
description: 参考图像的URL。支持 HTTP 或 HTTPS 协议。示例值：https://xxx/xxx.png。图像限制：格式为JPEG、JPG、PNG（不支持透明通道）；宽和高的范围为[300, 8000]像素；宽高比在1:2.5 ~ 2.5:1之间；文件大小不超过10MB；参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
element_list:
type: array
description: 主体列表，用于指定需要保持的主体。参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
items:
type: object
properties:
element_id:
type: integer
description: 传 element_list 时必填，表示主体ID。请在可灵-主体ID列表获取主体ID。参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。
parameters:
type: object
description: 控制图像生成，比如图像张数、宽高比等。
properties:
n:
type: integer
description: |-
生成的图像张数。
- kling/kling-v3-image-generation：取值范围为1～9，默认值为1。
- kling/kling-v3-omni-image-generation：当且仅当 `result_type=single` 时生效，取值范围为1～9，默认值为1。
result_type:
type: string
description: |-
生成图像的类型。仅支持模型 kling/kling-v3-omni-image-generation。
- `single`（默认值）：单图。批量生成时仅风格相似，无分镜关联。
- `series`：组图。生成具有叙事/视觉连续性的分镜系列图像。
enum:
- single
- series
series_amount:
type: integer
description: 组图模式下的输出张数。仅支持模型 kling/kling-v3-omni-image-generation。取值范围为2～9，默认值为4。当且仅当 `result_type=series` 时生效。
aspect_ratio:
type: string
description: 输出图像的宽高比。示例值：16:9。
enum:
- 16:9
- 9:16
- 1:1
default: 16:9
resolution:
type: string
description: |-
输出图像分辨率。
- kling/kling-v3-image-generation：可选值为 `1k`、`2k`，默认值为 `1k`。
- kling/kling-v3-omni-image-generation：可选值为 `1k`、`2k`、`4k`，默认值为 `1k`。
示例值：1k。
enum:
- 1k
- 2k
- 4k
watermark:
type: boolean
description: |-
是否同时生成含水印的图像。水印位于图像右下角，文案固定为"可灵AI"。
- `false`（默认值）：不生成含水印的图像。
- `true`：同时生成含水印的图像。
示例值：false。
default: false
CreateTaskResponse:
type: object
properties:
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
QueryTaskResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
finished:
type: boolean
description: 任务是否已完成。
choices:
type: array
description: 模型生成的输出内容。此数组仅包含一个元素。
items:
type: object
properties:
finish_reason:
type: string
description: 任务停止原因，自然停止时为 `stop`。
message:
type: object
description: 模型返回的消息。
properties:
role:
type: string
description: 消息的角色，固定为 `assistant`。
content:
type: array
description: 生成的图像列表。
items:
type: object
properties:
type:
type: string
description: 输出内容的类型。固定为 `image`。
image:
type: string
description: 生成图像的URL，图像格式为PNG。链接有效期为30天，请及时下载并保存图像。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 生成图像的数量。
size:
type: string
description: 生成图片的分辨率，格式为`宽*高`。示例值：1360*768。
SR:
type: string
description: 生成图像的分辨率档位。示例值：1080。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
ErrorResponse:
type: object
properties:
code:
type: string
description: 请求失败的错误码。
message:
type: string
description: 请求失败的详细信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-kling-subject-id-list.md
+169
View File
@@ -0,0 +1,169 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 可灵-主体ID列表
> 可灵（Kling）图像生成和视频生成API支持的主体ID（element_id）完整列表及参考图。
可灵主体ID仅支持在以下API中调用：
- [可灵-图像生成API](/api-reference/image-generation/kling-image-generation/create-task)
- [可灵-视频生成API](/api-reference/video-generation/kling-video-generation/create-task)
## 主体ID列表
<Note>
一个主体ID对应多个参考图。
</Note>
<table style={{width: "100%", borderCollapse: "collapse", tableLayout: "fixed"}}>
<thead>
<tr>
<th style={{textAlign: "center", width: "12%", paddingBottom: "8px"}}>主体ID（`element_id`）</th>
<th style={{textAlign: "center", width: "10%", paddingBottom: "8px"}}>主体名称</th>
<th style={{textAlign: "center", width: "40%", paddingBottom: "8px"}}>参考图</th>
<th style={{textAlign: "left", width: "38%", paddingBottom: "8px"}}>参考图描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>101</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>代码雨</td>
<td style={{verticalAlign: "top"}}>
<img alt="代码雨-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063156.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="代码雨-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063158.jpeg" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>密集的绿色代码从上向下流动，形成垂直的光流线，字符由数字与字母组成，发出柔和的荧光。整体呈现数字雨般的流动效果，光线有深浅变化，部分字符闪烁或模糊。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>103</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>雷电</td>
<td style={{verticalAlign: "top"}}>
<img alt="雷电-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063159.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="雷电-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063160.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>蓝色电弧雷电，闪电状光线交织，电流明亮炽烈，边缘伴随发光与能量辉光效果。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>104</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>魔法法阵</td>
<td style={{verticalAlign: "top"}}>
<img alt="魔法法阵-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063162.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="魔法法阵-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063161.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>魔法法阵，整体由复杂的几何图形组成，包括同心圆、六芒星与多层符号环。法阵内部刻有神秘符文与象征文字，中间燃烧着光焰状的能量符号。整体发出炽热的金色光芒，边缘有微微流动的能量波纹与火花效果。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>105</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>落叶</td>
<td style={{verticalAlign: "top"}}>
<img alt="落叶-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063163.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="落叶-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063164.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="落叶-3" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063165.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>多片金黄色枫叶在空中飘落，叶片呈掌状分裂结构，边缘略带不规则曲线。叶柄细长，叶脉分布清晰，各叶片均为黄色调。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>106</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>时空传送门</td>
<td style={{verticalAlign: "top"}}>
<img alt="时空传送门-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063182.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="时空传送门-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063183.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>能量传送门，形状为横向长方形，边缘由燃烧的金色火花与电弧组成，光流沿边缘快速流动，产生粒子飞溅与能量扭曲效果。传送门中央略带淡淡的光雾与空间折射感，内部呈现微弱的光线波动。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>107</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>花瓣</td>
<td style={{verticalAlign: "top"}}>
<img alt="花瓣-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063167.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="花瓣-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063168.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="花瓣-3" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063169.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>多片处于下落状态的红色花瓣，形状呈不规则曲面结构，边缘略微卷曲。花瓣表面纹理细密，颜色由中心向边缘分布为红色调。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>108</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>雪花</td>
<td style={{verticalAlign: "top"}}>
<img alt="雪花-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063170.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="雪花-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063171.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>飘落的雪花，雪花主要呈六角对称结构，枝状分叉清晰，部分晶体展示板状或星形轮廓。雪花之间大小存在差异，边缘纹理细密，部分呈现冻结水分形成的透明结构。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>109</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>虫洞</td>
<td style={{verticalAlign: "top"}}>
<img alt="虫洞-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063172.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="虫洞-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063178.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="虫洞-3" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063177.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>一个呈旋涡状结构的宇宙洞口，外围由环形发光带包围，洞口周围分布紫色与蓝色的气体状物质，背景为深色星空并点缀少量星体。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>111</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>怀旧婚纱</td>
<td style={{verticalAlign: "top"}}>
<img alt="怀旧婚纱-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063179.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="怀旧婚纱-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063180.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="怀旧婚纱-3" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063181.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>一套粉色复古婚纱服饰，婚纱为柔和浅粉色缎面材质，光泽细腻，上身为复古宫廷风设计，带蓬松泡泡袖与浅透纱拼接，饰以精致蕾丝与刺绣花纹。腰线略高，裙身宽大丰盈，布料自然形成柔和的波浪褶皱。裙摆两侧带荷叶边装饰。</td>
</tr>
<tr>
<td style={{verticalAlign: "top", textAlign: "center"}}>171</td>
<td style={{verticalAlign: "top", textAlign: "center"}}>天台</td>
<td style={{verticalAlign: "top"}}>
<img alt="天台-1" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063187.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
<img alt="天台-2" src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8655364771/p1063186.png" style={{display: "block", width: "100%", margin: "0 0 8px 0"}} />
</td>
<td style={{verticalAlign: "top"}}>一处带栏杆的露天平台，平台上有多根造型一致的路灯立柱，灯头发出黄色光线，地面因降雨而形成大面积积水，远处可见城市建筑的发光，天空中在下着雨。</td>
</tr>
</tbody>
</table>
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-person-instance-segmentation-create-tas.md
+311
View File
@@ -0,0 +1,311 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物实例分割 — 创建任务
> 提交人物实例分割任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: Person Instance Segmentation API
description: 人物实例分割 API。对输入图像中的每个人物实例进行分割，输出每个实例的分割掩码图像和可视化结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: Beijing
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createPersonInstanceSegmentationTask
summary: 提交人物实例分割任务
description: 提交异步人物实例分割任务。API 立即返回 `task_id`，通过 `GET /tasks/{task_id}` 轮询获取结果。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步任务提交标识，必须设置为 `enable`。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PersonInstanceSegmentationRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
examples:
success:
summary: 任务已接收
value:
output:
task_status: PENDING
task_id: 53950fb7-281a-4e60-xxxxxxxxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter.JsonPhrase:
summary: JSON 解析错误
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter.JsonPhrase
message: input json error
InvalidParameter.FileDownload:
summary: 图像下载失败
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter.FileDownload
message: oss download error
InvalidParameter.ImageFormat:
summary: 图像格式错误
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter.ImageFormat
message: read image error
InvalidParameter.ImageContent:
summary: 图像内容不合规
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter.ImageContent
message: The image content does not comply with green network verification
InvalidParameter:
summary: 参数超出范围
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: "the parameters must conform to the specification: xxx"
"401":
description: 认证失败 — API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"429":
description: 超出速率限制
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"500":
description: 服务端内部错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InternalError.Algo:
summary: 算法处理错误
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InternalError.Algo
message: algorithm process error
InternalError.FileUpload:
summary: 文件上传失败
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InternalError.FileUpload
message: oss upload error
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "image-instance-segmentation",
"input": {
"image_url": "http://xxx/image.png"
},
"parameters": {}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
PersonInstanceSegmentationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称，固定为 `image-instance-segmentation`。
enum:
- image-instance-segmentation
example: image-instance-segmentation
input:
type: object
required:
- image_url
description: 输入图像参数。
properties:
image_url:
type: string
format: uri
description: |-
待分割图像的公网可访问 URL。URL 中不能包含中文字符。
- **格式**：JPEG、PNG、JPG、BMP、WEBP
- **分辨率**：宽和高必须在 512 到 4096 像素之间
- **文件大小**：不超过 10 MB
example: http://xxx/image.png
parameters:
type: object
description: 生成参数。当前无可用参数，传空对象 `{}` 即可。
properties: {}
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于链路追踪和问题排查。
example: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于通过 `GET /tasks/{task_id}` 轮询任务状态。有效期 24 小时。
example: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status:
type: string
description: 初始任务状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态查询响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于链路追踪和问题排查。
example: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。
example: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:01.247
scheduled_time:
type: string
description: 任务开始执行时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:01.354
end_time:
type: string
description: 任务完成时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:27.795
output_image_url:
type: string
format: uri
description: |-
分割掩码图像 URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。**有效期 24 小时**，请及时下载。
掩码图像中，每个人物实例用不同灰度值（1, 2, 3...）表示，背景为 0。
example: http://xxx/result1.png
output_vis_image_url:
type: string
format: uri
description: |-
可视化结果图像 URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。**有效期 24 小时**，请及时下载。
可视化图像中，不同人物实例用不同颜色叠加显示在原图上。
example: http://xxx/result2.png
code:
type: string
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
example: InvalidParameter.FileDownload
message:
type: string
description: 错误详细信息。仅在 `task_status` 为 `FAILED` 时返回。
example: download for input_image error
task_metrics:
type: object
description: 任务完成指标。
properties:
TOTAL:
type: integer
description: 子任务总数。
example: 1
SUCCEEDED:
type: integer
description: 成功的子任务数。
example: 1
FAILED:
type: integer
description: 失败的子任务数。
example: 0
usage:
type: object
description: 使用量统计。仅在任务成功时返回。
properties:
image_count:
type: integer
description: 处理的图像数量。
example: 1
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识符。
example: a4d78a5f-655f-9639-8437-xxxxxx
code:
type: string
description: 错误码。可能的值包括：`InvalidParameter.JsonPhrase`、`InvalidParameter.FileDownload`、`InvalidParameter.ImageFormat`、`InvalidParameter.ImageContent`、`InvalidParameter`、`InternalError.Algo`、`InternalError.FileUpload`。
example: InvalidParameter
message:
type: string
description: 错误描述信息。
example: the parameters must conform to the specification
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-person-instance-segmentation-query-resu.md
+264
View File
@@ -0,0 +1,264 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人物实例分割 — 查询结果
> 查询人物实例分割任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Person Instance Segmentation API
description: 人物实例分割 API。对输入图像中的每个人物实例进行分割，输出每个实例的分割掩码图像和可视化结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: Beijing
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getPersonInstanceSegmentationTaskStatus
summary: 查询任务结果
description: 轮询人物实例分割任务的状态和结果。持续轮询直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。结果中的图片 URL 有效期为 24 小时。
parameters:
- name: task_id
in: path
required: true
description: 由 `POST /services/aigc/image2image/image-synthesis` 接口返回的任务 ID。
schema:
type: string
example: 53950fb7-281a-4e60-xxxxxxxxxxxx
responses:
"200":
description: 成功获取任务状态
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
task_id: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status: SUCCEEDED
submit_time: 2024-05-16 13:50:01.247
scheduled_time: 2024-05-16 13:50:01.354
end_time: 2024-05-16 13:50:27.795
output_image_url: http://xxx/result1.png
output_vis_image_url: http://xxx/result2.png
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: dccfdf23-b38e-97a6-a07b-f35118c1ada6
output:
task_id: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status: FAILED
submit_time: 2024-05-16 14:15:14.103
scheduled_time: 2024-05-16 14:15:14.154
end_time: 2024-05-16 14:15:14.694
code: InvalidParameter.FileDownload
message: download for input_image error
RUNNING:
summary: 任务运行中
value:
request_id: 7574ee8f-38a3-4b1e-xxxxxxxxxxxx
output:
task_id: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL — 查询任务结果
source: |-
# 将 {task_id} 替换为提交任务时返回的实际任务 ID
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
PersonInstanceSegmentationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称，固定为 `image-instance-segmentation`。
enum:
- image-instance-segmentation
example: image-instance-segmentation
input:
type: object
required:
- image_url
description: 输入图像参数。
properties:
image_url:
type: string
format: uri
description: |-
待分割图像的公网可访问 URL。URL 中不能包含中文字符。
- **格式**：JPEG、PNG、JPG、BMP、WEBP
- **分辨率**：宽和高必须在 512 到 4096 像素之间
- **文件大小**：不超过 10 MB
example: http://xxx/image.png
parameters:
type: object
description: 生成参数。当前无可用参数，传空对象 `{}` 即可。
properties: {}
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于链路追踪和问题排查。
example: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于通过 `GET /tasks/{task_id}` 轮询任务状态。有效期 24 小时。
example: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status:
type: string
description: 初始任务状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态查询响应。
properties:
request_id:
type: string
description: 请求唯一标识符，用于链路追踪和问题排查。
example: b67df059-ca6a-9d51-afcd-9b3c4456b1e2
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。
example: 53950fb7-281a-4e60-xxxxxxxxxxxx
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:01.247
scheduled_time:
type: string
description: 任务开始执行时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:01.354
end_time:
type: string
description: 任务完成时间。UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
example: 2024-05-16 13:50:27.795
output_image_url:
type: string
format: uri
description: |-
分割掩码图像 URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。**有效期 24 小时**，请及时下载。
掩码图像中，每个人物实例用不同灰度值（1, 2, 3...）表示，背景为 0。
example: http://xxx/result1.png
output_vis_image_url:
type: string
format: uri
description: |-
可视化结果图像 URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。**有效期 24 小时**，请及时下载。
可视化图像中，不同人物实例用不同颜色叠加显示在原图上。
example: http://xxx/result2.png
code:
type: string
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
example: InvalidParameter.FileDownload
message:
type: string
description: 错误详细信息。仅在 `task_status` 为 `FAILED` 时返回。
example: download for input_image error
task_metrics:
type: object
description: 任务完成指标。
properties:
TOTAL:
type: integer
description: 子任务总数。
example: 1
SUCCEEDED:
type: integer
description: 成功的子任务数。
example: 1
FAILED:
type: integer
description: 失败的子任务数。
example: 0
usage:
type: object
description: 使用量统计。仅在任务成功时返回。
properties:
image_count:
type: integer
description: 处理的图像数量。
example: 1
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识符。
example: a4d78a5f-655f-9639-8437-xxxxxx
code:
type: string
description: 错误码。可能的值包括：`InvalidParameter.JsonPhrase`、`InvalidParameter.FileDownload`、`InvalidParameter.ImageFormat`、`InvalidParameter.ImageContent`、`InvalidParameter`、`InternalError.Algo`、`InternalError.FileUpload`。
example: InvalidParameter
message:
type: string
description: 错误描述信息。
example: the parameters must conform to the specification
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-image-editing.md
+660
View File
@@ -0,0 +1,660 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen
> 通过文本编辑图片
<Note>
先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。如果使用 SDK，还需[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Qwen-Image 图像编辑 API
description: Qwen-Image 图像编辑 API，支持单图编辑、多图融合、风格迁移、文字编辑、元素操控等多种图像处理功能。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createQwenImageEdit
summary: 使用 Qwen-Image 编辑图像
description: |-
使用 Qwen-Image 模型编辑图像，支持单图编辑、多图融合（最多 3 张输入图像）、风格迁移、文字编辑、元素操控、姿态迁移和细节增强。
纯文本生成图像（无输入图像）请参阅 [Qwen-Image 文生图](/api-reference/image-generation/qwen-text-to-image)。
## 模型概览
| 模型 | 说明 | 输出 |
|-------|-------------|--------|
| qwen-image-3.0-pro（推荐） | 3.0 系列。支持长文本输入与复杂版面生成，10 像素小字精准渲染，12 国语言与 20+ 字体。也支持[文生图](/api-reference/image-generation/qwen-text-to-image)。 | 宽高各 512–2048 像素，不指定时由模型自动推荐分辨率。PNG 格式，1-6 张。 |
| qwen-image-3.0（推荐） | 3.0 系列标准版。兼顾质量与速度。也支持[文生图](/api-reference/image-generation/qwen-text-to-image)。 | 宽高各 512–2048 像素，不指定时由模型自动推荐分辨率。PNG 格式，1-6 张。 |
| qwen-image-2.0-pro | Pro 系列。增强了文字渲染、真实感和语义遵从度。也支持[文生图](/api-reference/image-generation/qwen-text-to-image)。 | 宽高各 512–2048 像素，默认与输入图像相同。PNG 格式，1-6 张。 |
| qwen-image-2.0 | 加速版本，兼顾质量与速度。也支持[文生图](/api-reference/image-generation/qwen-text-to-image)。 | 宽高各 512–2048 像素，默认与输入图像相同。PNG 格式，1-6 张。 |
| qwen-image-edit-max | Max 系列。增强了工业设计、几何推理和人物一致性。 | 宽高各 512–2048 像素，默认约 1024×1024（与输入图像宽高比相近）。PNG 格式，1-6 张。 |
| qwen-image-edit-plus | Plus 系列。支持多图输出和自定义分辨率。 | 宽高各 512–2048 像素，默认约 1024×1024（与输入图像宽高比相近）。PNG 格式，1-6 张。 |
| qwen-image-edit | 支持单图编辑和多图融合。 | 仅默认分辨率。PNG 格式，1 张。 |
## 注意事项
- 生成的图像 URL 有效期为 **24 小时**，请及时下载。
- 仅支持单轮对话，`messages` 数组必须包含且仅包含一条消息。
- 每次请求可提供 1 到 3 张输入图像。
- 多图输入时，图像按位置引用（图像 1、图像 2、图像 3），输出图像的宽高比由最后一张图像决定。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImageEditRequest"
responses:
"200":
description: 图像编辑成功
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImageEditResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL（单图）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-3.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/fpakfo/image36.webp"
},
{
"text": "Generate an image that matches the depth map, following this description: A dilapidated red bicycle is parked on a muddy path with a dense primeval forest in the background."
}
]
}
]
},
"parameters": {
"n": 2,
"negative_prompt": " ",
"prompt_extend": true,
"watermark": false,
"size": "1536*1024"
}
}'
- lang: curl
label: cURL（多图融合）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-3.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/thtclx/input1.png"
},
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/iclsnx/input2.png"
},
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/gborgw/input3.png"
},
{
"text": "Make the girl from Image 1 wear the black dress from Image 2 and sit in the pose from Image 3."
}
]
}
]
},
"parameters": {
"n": 2,
"negative_prompt": " ",
"prompt_extend": true,
"watermark": false,
"size": "1024*1536"
}
}'
- lang: python
label: Python（DashScope SDK）
source: |-
import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
# 模型支持输入 1 到 3 张图像
messages = [
{
"role": "user",
"content": [
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/thtclx/input1.png"},
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/iclsnx/input2.png"},
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/gborgw/input3.png"},
{"text": "Make the girl from Image 1 wear the black dress from Image 2 and sit in the pose from Image 3."}
]
}
]
api_key = os.getenv("DASHSCOPE_API_KEY")
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-3.0-pro",
messages=messages,
stream=False,
n=2,
watermark=False,
negative_prompt=" ",
prompt_extend=True,
size="1024*1536",
)
if response.status_code == 200:
for i, content in enumerate(response.output.choices[0].message.content):
print(f"URL of output image {i+1}: {content['image']}")
else:
print(f"HTTP status code: {response.status_code}")
print(f"Error code: {response.code}")
print(f"Error message: {response.message}")
- lang: java
label: Java（DashScope SDK）
source: |-
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
import java.util.*;
public class QwenImageEdit {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void main(String[] args) throws Exception {
MultiModalConversation conv = new MultiModalConversation();
// 模型支持输入 1 到 3 张图像
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/thtclx/input1.png"),
Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/iclsnx/input2.png"),
Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/gborgw/input3.png"),
Collections.singletonMap("text", "Make the girl from Image 1 wear the black dress from Image 2 and sit in the pose from Image 3.")
)).build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("negative_prompt", " ");
parameters.put("n", 2);
parameters.put("prompt_extend", true);
parameters.put("size", "1024*1536");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-3.0-pro")
.messages(Collections.singletonList(userMessage))
.parameters(parameters)
.build();
MultiModalConversationResult result = conv.call(param);
List<Map<String, Object>> contentList = result.getOutput().getChoices().get(0).getMessage().getContent();
int imageIndex = 1;
for (Map<String, Object> content : contentList) {
if (content.containsKey("image")) {
System.out.println("URL of output image " + imageIndex + ": " + content.get("image"));
imageIndex++;
}
}
}
}
- lang: python
label: Python（Base64 输入）
source: |-
import os
import dashscope
from dashscope import MultiModalConversation
import base64
import mimetypes
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
# --- Base64 编码 ---
# 格式：data:{mime_type};base64,{base64_data}
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
try:
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(
image_file.read()).decode('utf-8')
return f"data:{mime_type};base64,{encoded_string}"
except IOError as e:
raise IOError(f"Error reading file: {file_path}, Error: {str(e)}")
# 获取图像的 Base64 编码
# 将 "/path/to/your/image.png" 替换为本地图像文件路径
image = encode_file("/path/to/your/image.png")
messages = [
{
"role": "user",
"content": [
{"image": image},
{"text": "Generate an image that matches the depth map, following this description: A dilapidated red bicycle is parked on a muddy path with a dense primeval forest in the background."}
]
}
]
api_key = os.getenv("DASHSCOPE_API_KEY")
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-3.0-pro",
messages=messages,
stream=False,
n=2,
watermark=False,
negative_prompt=" ",
prompt_extend=True,
size="1536*1024",
)
if response.status_code == 200:
for i, content in enumerate(response.output.choices[0].message.content):
print(f"URL of output image {i+1}: {content['image']}")
else:
print(f"HTTP status code: {response.status_code}")
print(f"Error code: {response.code}")
print(f"Error message: {response.message}")
- lang: java
label: Java（Base64 输入）
source: |-
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.List;
public class QwenImageEditBase64 {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {
// 将 "/path/to/your/image.png" 替换为本地图像文件路径
String image = encodeFile("/path/to/your/image.png");
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", image),
Collections.singletonMap("text", "Generate an image that matches the depth map, following this description: A dilapidated red bicycle is parked on a muddy path with a dense primeval forest in the background.")
)).build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("negative_prompt", " ");
parameters.put("n", 2);
parameters.put("prompt_extend", true);
parameters.put("size", "1536*1024");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-3.0-pro")
.messages(Collections.singletonList(userMessage))
.parameters(parameters)
.build();
MultiModalConversationResult result = conv.call(param);
List<Map<String, Object>> contentList = result.getOutput().getChoices().get(0).getMessage().getContent();
int imageIndex = 1;
for (Map<String, Object> content : contentList) {
if (content.containsKey("image")) {
System.out.println("URL of output image " + imageIndex + ": " + content.get("image"));
imageIndex++;
}
}
}
/**
* 将文件编码为 Base64 字符串。
* @param filePath 文件路径。
* @return Base64 字符串，格式为：data:{mime_type};base64,{base64_data}
*/
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) {
throw new IllegalArgumentException("File does not exist: " + filePath);
}
String mimeType = null;
try {
mimeType = Files.probeContentType(path);
} catch (IOException e) {
throw new IllegalArgumentException("Unable to detect file type: " + filePath);
}
if (mimeType == null || !mimeType.startsWith("image/")) {
throw new IllegalArgumentException("Unsupported or unrecognized image format");
}
byte[] fileBytes = null;
try {
fileBytes = Files.readAllBytes(path);
} catch (IOException e) {
throw new IllegalArgumentException("Unable to read file content: " + filePath);
}
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
public static void main(String[] args) {
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
QwenImageEditRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
- qwen-image-2.0-pro
- qwen-image-2.0-pro-2026-06-22
- qwen-image-2.0-pro-2026-04-22
- qwen-image-2.0-pro-2026-03-03
- qwen-image-2.0
- qwen-image-2.0-2026-03-03
- qwen-image-edit-max
- qwen-image-edit-max-2026-01-16
- qwen-image-edit-plus
- qwen-image-edit-plus-2025-12-15
- qwen-image-edit-plus-2025-10-30
- qwen-image-edit
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含 messages 数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话，messages 数组必须包含且仅包含一条 role 为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageEditMessage"
parameters:
$ref: "#/components/schemas/QwenImageEditParameters"
QwenImageEditMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 消息内容数组，须包含图像对象和恰好 1 个文本对象：qwen-image-2.1-pro 支持 1 到 10 个图像对象，其他模型支持 1 到 3 个。多图输入时，图像按位置引用（图像 1、图像 2、图像 3……），输出图像的宽高比由最后一张图像决定。
minItems: 2
maxItems: 11
items:
$ref: "#/components/schemas/QwenImageEditContentPart"
QwenImageEditContentPart:
type: object
description: 图像或文本内容部分。
properties:
image:
type: string
description: 输入图像，支持公开可访问的 URL（HTTP/HTTPS）或 Base64 编码字符串（格式：`data:{mime_type};base64,{data}`）。支持的格式：JPG、JPEG、PNG、BMP、TIFF、WEBP、GIF（仅第一帧）。建议图像宽高在 384 到 3072 像素之间以获得最佳效果。最大文件大小：10 MB。
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/fpakfo/image36.webp
text:
type: string
description: 图像编辑指令，描述期望输出图像包含的元素和视觉特征。支持中英文，qwen-image-3.0 系列和 qwen-image-2.1-pro 推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。仅支持传入一条文本输入，不传或传入多条将报错。
example: "Generate an image that matches the depth map, following this description: A dilapidated red bicycle is parked on a muddy path with a dense primeval forest in the background."
QwenImageEditParameters:
type: object
description: 图像编辑参数。
properties:
n:
type: integer
description: |-
生成图像的数量。默认值：1。
- **qwen-image-3.0 系列、qwen-image-2.1-pro、qwen-image-2.0 / qwen-image-edit-max / qwen-image-edit-plus 系列**：1-6 张。
- **qwen-image-edit**：仅支持 1 张。
minimum: 1
maximum: 6
default: 1
negative_prompt:
type: string
description: 描述不希望出现在图像中的内容。支持中英文，最多 500 个字符，超出部分自动截断。
maxLength: 500
size:
type: string
description: |-
输出分辨率，格式为 `宽*高`。
- **qwen-image-3.0 系列、qwen-image-2.1-pro**：总像素在 512\*512 到 2048\*2048 之间，宽高比在 1:8 到 8:1 之间，不指定时由模型根据提示词自动推荐分辨率。
- **qwen-image-2.0 系列**：总像素在 512\*512 到 2048\*2048 之间，默认与输入图像相同（多图请求以最后一张图像为准）。
- **qwen-image-edit-max/plus**：宽和高均在 [512, 2048] 范围内，默认约 1024\*1024，宽高比与输入图像相近，自动调整为最近的 16 的倍数。
- **qwen-image-edit**：不支持此参数。
推荐尺寸：`1024*1024`（1:1）、`768*1152` / `1024*1536`（2:3）、`1152*768` / `1536*1024`（3:2）、`720*1280` / `1080*1920`（9:16）、`1280*720` / `1920*1080`（16:9）。
example: 1024*1536
prompt_extend:
type: boolean
description: 启用提示词优化。开启后模型将对编辑指令进行优化，当提示词描述不够详细时效果提升显著；qwen-image-3.0 系列和 qwen-image-2.1-pro 按 `prompt_extend_mode` 指定的方式改写。`qwen-image-edit` 不支持此参数。
default: true
prompt_extend_mode:
type: string
description: |-
提示词改写方式。仅 qwen-image-3.0 系列和 qwen-image-2.1-pro 支持。
- `direct`（默认）：直接提示词增强（DPE），适用于大多数场景。
- `agent`：智能体提示词增强（APE），仅文生图支持；图像编辑场景传入将返回 400 错误。
enum:
- direct
- agent
default: direct
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围：[0, 2147483647]。相同的种子可生成较为一致（但不完全相同）的结果。不指定时使用随机种子。
minimum: 0
maximum: 2147483647
QwenImageEditResponse:
type: object
description: Qwen-Image 图像编辑响应。
example:
output:
rewrite_status: not_use
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx
- image: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx
role: assistant
usage:
output_height: 1024
output_width: 1536
input_image_count: 1
input_image_type: qima_input_1k
output_image_count: 2
output_image_type: qima_output_1k
request_id: bf37ca26-0abe-98e4-8065-xxxxxx
properties:
output:
type: object
properties:
rewrite_status:
type: string
description: 提示词改写状态。具体取值由请求是否开启改写以及改写执行结果决定。
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/QwenImageEditChoice"
usage:
type: object
description: 用量统计（仅统计成功结果）。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，其他系列返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 请求中输入图片的数量。文生图为 0，图像编辑按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_input_1k`，大于 2,250,000 为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_output_1k`，大于 2,250,000 为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
request_id:
type: string
description: 请求的唯一标识符，用于追踪和排查问题。
example: bf37ca26-0abe-98e4-8065-xxxxxx
QwenImageEditChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成。"
example: stop
message:
type: object
properties:
role:
type: string
description: 固定为 `assistant`。
enum:
- assistant
content:
type: array
description: 包含生成图像 URL 的响应内容数组。
items:
$ref: "#/components/schemas/QwenImageEditResponseContentPart"
QwenImageEditResponseContentPart:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
example:
request_id: 31f808fd-8eef-9004-xxxxx
code: InvalidApiKey
message: Invalid API-key provided.
properties:
request_id:
type: string
description: 请求的唯一标识符。
code:
type: string
description: 错误码（例如 `InvalidParameter`、`Throttling`、`InvalidApiKey`）。
example: InvalidApiKey
message:
type: string
description: 可读的错误信息。
example: Invalid API-key provided.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-text-to-image-30-async.md
+662
View File
@@ -0,0 +1,662 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen — 异步图像生成（3.0 系列与 2.1-pro）
> qwen-image-3.0 系列和 qwen-image-2.1-pro 的异步图像生成接口
<Note>
先[获取 API Key](/api-reference/preparation/api-key) 并[配置环境变量](/api-reference/preparation/export-api-key-env)。如果使用 SDK，还需[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
## 调用流程
1. **提交任务**：通过 `POST /services/aigc/image-generation/generation` 提交任务，请求头中需包含 `X-DashScope-Async: enable`。
2. **轮询结果**：通过 [`GET /tasks/{task_id}`](/api-reference/image-generation/qwen-text-to-image-task-query) 查询任务状态，直到 `task_status` 变为 `SUCCEEDED` 或 `FAILED`。建议每 10 秒轮询一次。
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.1.0
info:
title: Qwen-Image API
description: Qwen-Image 文生图 API，支持所有模型的同步调用，以及旧版模型的异步调用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createQwenImage30Async
summary: 异步生成图像（3.0 系列与 2.1-pro）
description: "qwen-image-3.0 系列和 qwen-image-2.1-pro 的异步调用接口。与同步接口共用相同的请求参数结构，仅需在请求头中增加 `X-DashScope-Async: enable`，服务受理后返回任务 ID（`task_id`），再通过任务 ID 轮询查询接口获取最终结果。"
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置参数。必须设置为 `enable`。缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImage30AsyncRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL（文生图 - 提交任务）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "qwen-image-3.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass."
}
]
}
]
},
"parameters": {
"prompt_extend": true
}
}'
- lang: curl
label: cURL（查询结果）
source: |-
# 将 {task_id} 替换为第 1 步返回的实际任务 ID
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
- lang: python
label: Python (DashScope SDK)
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
prompt = ("A healing-style hand-drawn poster featuring three puppies "
"playing with a ball on lush green grass.")
api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [
{
"role": "user",
"content": [{"text": prompt}]
}
]
print('----正在调用接口，请等待任务完成。----')
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-3.0-pro",
messages=messages,
result_format='message',
stream=False,
prompt_extend=True
)
if response.status_code == HTTPStatus.OK:
content = response.output.choices[0].message.content
for item in content:
if 'image' in item:
image_url = item['image']
file_name = PurePosixPath(
unquote(urlparse(image_url).path)
).parts[-1]
with open(f'./{file_name}', 'wb+') as f:
f.write(requests.get(image_url).content)
print(f"Image saved: {file_name}")
else:
print(f"Failed: {response.code}, {response.message}")
- lang: java
label: Java (DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.*;
public class QwenImage30Async {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void main(String[] args) throws Exception {
String prompt = "A healing-style hand-drawn poster featuring three puppies "
+ "playing with a ball on lush green grass.";
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(List.of(Map.of("text", prompt)))
.build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-3.0-pro")
.messages(List.of(userMessage))
.parameters(parameters)
.build();
MultiModalConversation conversation = new MultiModalConversation();
System.out.println("---正在调用接口，请等待任务完成。----");
MultiModalConversationResult result = conversation.call(param);
System.out.println(JsonUtils.toJson(result));
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
QwenImageSyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
- qwen-image-2.0-pro
- qwen-image-2.0-pro-2026-06-22
- qwen-image-2.0-pro-2026-04-22
- qwen-image-2.0-pro-2026-03-03
- qwen-image-2.0
- qwen-image-2.0-2026-03-03
- qwen-image-max
- qwen-image-max-2025-12-30
- qwen-image-plus
- qwen-image-plus-2026-01-09
- qwen-image
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话。必须包含且只包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 消息内容数组，必须且只包含一个文本对象。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageContentPart"
QwenImageContentPart:
type: object
required:
- text
properties:
text:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列和 qwen-image-2.1-pro 推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: 画面是一张竖幅户外人像摄影，左上方深蓝色招牌上以白色哥特体大字写着 Il Messaggero，招牌下方是报刊亭的玻璃展示窗，内部陈列着许多报纸与杂志封面。
QwenImageSyncParameters:
type: object
description: 图像生成参数。
properties:
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符，超出部分自动截断。
maxLength: 500
size:
type: string
description: |-
输出分辨率，格式为 `宽*高`。
- **qwen-image-3.0 系列、qwen-image-2.1-pro**：总像素在 512\*512 到 2048\*2048 之间，宽高比在 1:8 到 8:1 之间，不指定时由模型根据提示词自动推荐分辨率。
- **qwen-image-2.0 系列**：总像素在 512\*512 到 2048\*2048 之间，默认 `2048*2048`。推荐分辨率：`2688*1536`（16:9）、`1536*2688`（9:16）、`2048*2048`（1:1，默认值）、`2368*1728`（4:3）、`1728*2368`（3:4）。
- **qwen-image-max、qwen-image-plus 系列**：默认 `1664*928`。可选分辨率：`1664*928`（16:9，默认值）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 2048*2048
example: 2048*2048
n:
type: integer
description: |-
生成图像数量。默认值：1。
- **qwen-image-3.0 系列、qwen-image-2.1-pro、qwen-image-2.0 系列**：1-6 张。
- **qwen-image-max/plus 系列**：固定为 1 张。
minimum: 1
maximum: 6
default: 1
prompt_extend:
type: boolean
description: 启用提示词改写。`true`（默认）：模型先优化提示词再生成；qwen-image-3.0 系列和 qwen-image-2.1-pro 按 `prompt_extend_mode` 指定的方式改写。`false`：直接使用原始提示词。
default: true
prompt_extend_mode:
type: string
description: |-
提示词改写方式。仅 qwen-image-3.0 系列和 qwen-image-2.1-pro 支持。
- `direct`（默认）：直接提示词增强（DPE），适用于大多数场景。
- `agent`：智能体提示词增强（APE），改写更精细，仅文生图支持。
enum:
- direct
- agent
default: direct
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImageAsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。异步调用仅支持 `qwen-image-plus` 和 `qwen-image`。
enum:
- qwen-image-plus
- qwen-image
example: qwen-image-plus
input:
type: object
required:
- prompt
description: 输入数据。
properties:
prompt:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: A cute orange cat sitting on a windowsill, realistic style
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符。
maxLength: 500
parameters:
$ref: "#/components/schemas/QwenImageAsyncParameters"
QwenImageAsyncParameters:
type: object
description: Qwen-Image 异步调用的生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`。可选尺寸：`1664*928`（16:9，默认）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 1664*928
enum:
- 1664*928
- 1472*1104
- 1328*1328
- 1104*1472
- 928*1664
example: 1664*928
n:
type: integer
description: 生成图像数量，固定为 1，填写其他值将报错。
enum:
- 1
default: 1
prompt_extend:
type: boolean
description: 启用智能提示词改写。`true`（默认）：模型优化提示词后再生成。`false`：直接使用原始提示词。
default: true
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImage30AsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，数组内有且只有一个对象。
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageSyncResponse:
type: object
description: Qwen-Image 同步生成的响应结果。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
role: assistant
usage:
output_height: 2048
output_width: 2048
input_image_count: 0
input_image_type: qima_input_2k
output_image_count: 1
output_image_type: qima_output_2k
request_id: d0250a3d-b07f-49e1-bdc8-6793f4929xxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表，每张生成图像对应一个元素。
items:
$ref: "#/components/schemas/QwenImageChoice"
rewrite_status:
type: string
description: 提示词改写状态，具体取值由请求是否开启改写以及改写执行结果决定。仅 qwen-image-3.0 系列返回此字段。
task_metric:
type: object
description: 任务结果统计信息。qwen-image-2.0 和 qwen-image-3.0 系列不返回此字段。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
usage:
type: object
description: 用量统计（仅统计成功结果）。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，其他系列返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 请求中输入图片的数量。文生图为 0，图像编辑按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_input_1k`，大于 2,250,000 为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_output_1k`，大于 2,250,000 为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
request_id:
type: string
description: 唯一请求标识符，用于追踪和排查问题。
example: abf1645b-b630-433a-92f6-xxxxxx
QwenImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常结束。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组。
items:
$ref: "#/components/schemas/QwenImageResponseContentPart"
QwenImageResponseContentPart:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交后的响应结果。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询状态。配合 `GET /tasks/{task_id}` 使用。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
AsyncTaskStatusResponse:
type: object
description: 异步任务状态及结果。
example:
request_id: 7434edb2-3cba-44e6-a772-xxxxxx
output:
task_id: 878f591e-ebdf-4e45-97eb-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:39:19.484
results:
- orig_prompt: Healing-style hand-drawn poster...
actual_prompt: Childhood-inspired hand-drawn poster design...
url: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/7d/xxx.png?Expires=xxxx
usage:
image_count: 1
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: |-
当前任务状态。
- `PENDING`：任务排队中
- `RUNNING`：任务处理中
- `SUCCEEDED`：任务执行成功
- `FAILED`：任务执行失败
- `CANCELED`：任务已取消
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
message:
type: string
description: 错误信息。仅当 `task_status` 为 `FAILED` 时返回。
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
AsyncTaskResult:
type: object
description: 异步任务中的单条生成结果。
properties:
orig_prompt:
type: string
description: 用户提交的原始提示词。
actual_prompt:
type: string
description: 实际用于生成的提示词（启用 `prompt_extend` 时可能与原始提示词不同）。
url:
type: string
description: 生成图像的 URL。**有效期 24 小时。**
TaskMetrics:
type: object
description: 任务完成度统计。
properties:
TOTAL:
type: integer
description: 请求生成的图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-text-to-image-async.md
+649
View File
@@ -0,0 +1,649 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen — 异步图像生成
> 异步图像生成
<Note>
先[获取 API Key](/api-reference/preparation/api-key) 并[配置环境变量](/api-reference/preparation/export-api-key-env)。如果使用 SDK，还需[安装 SDK](/api-reference/preparation/install-sdk)。此异步接口仅支持 `qwen-image-plus` 和 `qwen-image` 模型，其他模型请使用[同步接口](/api-reference/image-generation/qwen-text-to-image)。
</Note>
## 调用流程
1. **提交任务**：通过 `POST /services/aigc/text2image/image-synthesis` 提交任务，请求头中需包含 `X-DashScope-Async: enable`。
2. **轮询结果**：通过 [`GET /tasks/{task_id}`](/api-reference/image-generation/qwen-text-to-image-task-query) 查询任务状态，直到 `task_status` 变为 `SUCCEEDED` 或 `FAILED`。建议每 10 秒轮询一次。
## OpenAPI
````yaml post /services/aigc/text2image/image-synthesis
openapi: 3.1.0
info:
title: Qwen-Image API
description: Qwen-Image 文生图 API，支持所有模型的同步调用，以及旧版模型的异步调用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/text2image/image-synthesis:
post:
operationId: createQwenImageAsync
summary: 创建图像生成任务
description: 使用 Qwen-Image 创建异步图像生成任务。仅支持 `qwen-image-plus` 和 `qwen-image` 模型，qwen-image-3.0 系列和 qwen-image-2.1-pro 请使用[异步生成图像（3.0 系列与 2.1-pro）](#createQwenImage30Async)接口。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步任务提交时必须设置为 `enable`。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImageAsyncRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL（提交任务）
source: |-
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen-image-plus",
"input": {
"prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass."
},
"parameters": {
"negative_prompt": "",
"size": "1664*928",
"n": 1,
"prompt_extend": true,
"watermark": false
}
}'
- lang: curl
label: cURL（查询结果）
source: |-
# 将 {task_id} 替换为第 1 步返回的实际任务 ID
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
- lang: python
label: Python (DashScope SDK)
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
prompt = ("Healing-style hand-drawn poster featuring three puppies "
"playing with a ball on lush green grass. The main title "
"'Come Play Ball!' is prominently displayed at the top.")
api_key = os.getenv("DASHSCOPE_API_KEY")
print('----正在调用接口，请等待任务完成。----')
rsp = ImageSynthesis.call(
api_key=api_key,
model="qwen-image-plus",
prompt=prompt,
negative_prompt="",
n=1,
size='1664*928',
prompt_extend=True,
watermark=False
)
if rsp.status_code == HTTPStatus.OK:
for result in rsp.output.results:
file_name = PurePosixPath(
unquote(urlparse(result.url).path)
).parts[-1]
with open(f'./{file_name}', 'wb+') as f:
f.write(requests.get(result.url).content)
print(f"Image saved: {file_name}")
else:
print(f"Failed: {rsp.code}, {rsp.message}")
- lang: java
label: Java (DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class QwenImageAsync {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void main(String[] args) throws Exception {
String prompt = "Healing-style hand-drawn poster featuring three puppies "
+ "playing with a ball on lush green grass. The main title "
+ "'Come Play Ball!' is prominently displayed at the top.";
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("negative_prompt", "");
ImageSynthesisParam param = ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("qwen-image-plus")
.prompt(prompt)
.n(1)
.size("1664*928")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
System.out.println("---正在调用接口，请等待任务完成。----");
ImageSynthesisResult result = imageSynthesis.call(param);
System.out.println(JsonUtils.toJson(result));
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
QwenImageSyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
- qwen-image-2.0-pro
- qwen-image-2.0-pro-2026-06-22
- qwen-image-2.0-pro-2026-04-22
- qwen-image-2.0-pro-2026-03-03
- qwen-image-2.0
- qwen-image-2.0-2026-03-03
- qwen-image-max
- qwen-image-max-2025-12-30
- qwen-image-plus
- qwen-image-plus-2026-01-09
- qwen-image
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话。必须包含且只包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 消息内容数组，必须且只包含一个文本对象。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageContentPart"
QwenImageContentPart:
type: object
required:
- text
properties:
text:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列和 qwen-image-2.1-pro 推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: 画面是一张竖幅户外人像摄影，左上方深蓝色招牌上以白色哥特体大字写着 Il Messaggero，招牌下方是报刊亭的玻璃展示窗，内部陈列着许多报纸与杂志封面。
QwenImageSyncParameters:
type: object
description: 图像生成参数。
properties:
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符，超出部分自动截断。
maxLength: 500
size:
type: string
description: |-
输出分辨率，格式为 `宽*高`。
- **qwen-image-3.0 系列、qwen-image-2.1-pro**：总像素在 512\*512 到 2048\*2048 之间，宽高比在 1:8 到 8:1 之间，不指定时由模型根据提示词自动推荐分辨率。
- **qwen-image-2.0 系列**：总像素在 512\*512 到 2048\*2048 之间，默认 `2048*2048`。推荐分辨率：`2688*1536`（16:9）、`1536*2688`（9:16）、`2048*2048`（1:1，默认值）、`2368*1728`（4:3）、`1728*2368`（3:4）。
- **qwen-image-max、qwen-image-plus 系列**：默认 `1664*928`。可选分辨率：`1664*928`（16:9，默认值）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 2048*2048
example: 2048*2048
n:
type: integer
description: |-
生成图像数量。默认值：1。
- **qwen-image-3.0 系列、qwen-image-2.1-pro、qwen-image-2.0 系列**：1-6 张。
- **qwen-image-max/plus 系列**：固定为 1 张。
minimum: 1
maximum: 6
default: 1
prompt_extend:
type: boolean
description: 启用提示词改写。`true`（默认）：模型先优化提示词再生成；qwen-image-3.0 系列和 qwen-image-2.1-pro 按 `prompt_extend_mode` 指定的方式改写。`false`：直接使用原始提示词。
default: true
prompt_extend_mode:
type: string
description: |-
提示词改写方式。仅 qwen-image-3.0 系列和 qwen-image-2.1-pro 支持。
- `direct`（默认）：直接提示词增强（DPE），适用于大多数场景。
- `agent`：智能体提示词增强（APE），改写更精细，仅文生图支持。
enum:
- direct
- agent
default: direct
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImageAsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。异步调用仅支持 `qwen-image-plus` 和 `qwen-image`。
enum:
- qwen-image-plus
- qwen-image
example: qwen-image-plus
input:
type: object
required:
- prompt
description: 输入数据。
properties:
prompt:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: A cute orange cat sitting on a windowsill, realistic style
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符。
maxLength: 500
parameters:
$ref: "#/components/schemas/QwenImageAsyncParameters"
QwenImageAsyncParameters:
type: object
description: Qwen-Image 异步调用的生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`。可选尺寸：`1664*928`（16:9，默认）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 1664*928
enum:
- 1664*928
- 1472*1104
- 1328*1328
- 1104*1472
- 928*1664
example: 1664*928
n:
type: integer
description: 生成图像数量，固定为 1，填写其他值将报错。
enum:
- 1
default: 1
prompt_extend:
type: boolean
description: 启用智能提示词改写。`true`（默认）：模型优化提示词后再生成。`false`：直接使用原始提示词。
default: true
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImage30AsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，数组内有且只有一个对象。
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageSyncResponse:
type: object
description: Qwen-Image 同步生成的响应结果。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
role: assistant
usage:
output_height: 2048
output_width: 2048
input_image_count: 0
input_image_type: qima_input_2k
output_image_count: 1
output_image_type: qima_output_2k
request_id: d0250a3d-b07f-49e1-bdc8-6793f4929xxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表，每张生成图像对应一个元素。
items:
$ref: "#/components/schemas/QwenImageChoice"
rewrite_status:
type: string
description: 提示词改写状态，具体取值由请求是否开启改写以及改写执行结果决定。仅 qwen-image-3.0 系列返回此字段。
task_metric:
type: object
description: 任务结果统计信息。qwen-image-2.0 和 qwen-image-3.0 系列不返回此字段。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
usage:
type: object
description: 用量统计（仅统计成功结果）。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，其他系列返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 请求中输入图片的数量。文生图为 0，图像编辑按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_input_1k`，大于 2,250,000 为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_output_1k`，大于 2,250,000 为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
request_id:
type: string
description: 唯一请求标识符，用于追踪和排查问题。
example: abf1645b-b630-433a-92f6-xxxxxx
QwenImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常结束。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组。
items:
$ref: "#/components/schemas/QwenImageResponseContentPart"
QwenImageResponseContentPart:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交后的响应结果。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询状态。配合 `GET /tasks/{task_id}` 使用。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
AsyncTaskStatusResponse:
type: object
description: 异步任务状态及结果。
example:
request_id: 7434edb2-3cba-44e6-a772-xxxxxx
output:
task_id: 878f591e-ebdf-4e45-97eb-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:39:19.484
results:
- orig_prompt: Healing-style hand-drawn poster...
actual_prompt: Childhood-inspired hand-drawn poster design...
url: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/7d/xxx.png?Expires=xxxx
usage:
image_count: 1
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: |-
当前任务状态。
- `PENDING`：任务排队中
- `RUNNING`：任务处理中
- `SUCCEEDED`：任务执行成功
- `FAILED`：任务执行失败
- `CANCELED`：任务已取消
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
message:
type: string
description: 错误信息。仅当 `task_status` 为 `FAILED` 时返回。
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
AsyncTaskResult:
type: object
description: 异步任务中的单条生成结果。
properties:
orig_prompt:
type: string
description: 用户提交的原始提示词。
actual_prompt:
type: string
description: 实际用于生成的提示词（启用 `prompt_extend` 时可能与原始提示词不同）。
url:
type: string
description: 生成图像的 URL。**有效期 24 小时。**
TaskMetrics:
type: object
description: 任务完成度统计。
properties:
TOTAL:
type: integer
description: 请求生成的图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-text-to-image-openai.md
+332
View File
@@ -0,0 +1,332 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen — OpenAI 兼容图像生成
> 通过 OpenAI Images 兼容协议调用千问图像生成与编辑模型进行文生图与图生图/图像编辑
<Note>
先[获取 API Key](/api-reference/preparation/api-key) 并[配置环境变量](/api-reference/preparation/export-api-key-env)。如果使用 SDK，还需[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
<Tip>
图像生成耗时较长，请显式设置足够大的客户端超时时间。多图输出（较大的 `n`）或并发场景建议从 600 秒起配置，避免客户端提前断开连接。
</Tip>
## OpenAPI
````yaml post /compatible-mode/v1/images/generations
openapi: 3.1.0
info:
title: 千问-图像生成与编辑 OpenAI 兼容 API
description: 通过 OpenAI Images 兼容协议调用千问-图像生成与编辑模型，支持文生图（T2I）与图生图/图像编辑（I2I）。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com
description: DashScope API 服务器
security:
- bearer: []
paths:
/compatible-mode/v1/images/generations:
post:
operationId: createQwenImageOpenAICompatible
summary: OpenAI 兼容图像生成与编辑
description: |-
如果您的应用已基于 OpenAI Images 协议或 OpenAI SDK 开发，可通过 OpenAI 兼容模式调用千问-图像生成与编辑模型，无需改造请求结构。文生图（T2I）与图生图/图像编辑（I2I）共用同一个接口：**不传** `image` 为文生图，**传** `image` 为图生图。
该模式为**同步、非流式**接口，图生图通过 `image` 扩展字段实现，**不使用** OpenAI 官方 `/images/edits` 的 multipart 上传形式。暂不支持：异步调用、流式输出、partial image、`/images/edits`、multipart 与 mask。传入 `response_format=b64_json` 不会报错，但会被忽略，响应中仍返回图像 URL。如需异步调用，请使用 DashScope 异步调用。
`image`、`negative_prompt`、`seed`、`prompt_extend`、`prompt_extend_mode`、`enable_thinking`、`watermark` 为千问AI平台扩展字段，非 OpenAI 官方参数：直接发送 HTTP 请求时放在请求体顶层；使用 OpenAI SDK 时通过 `extra_body` 传入。
security:
- bearer: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- prompt
properties:
model:
type: string
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
description: 模型名称。
example: qwen-image-3.0-pro
prompt:
type: string
description: 正向提示词，描述期望生成或编辑的图像内容、风格和构图。支持中英文，推荐不超过 4500 Token，不能为空字符串。
example: 画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。
image:
anyOf:
- type: string
- type: array
items:
type: string
description: |-
输入图像的 URL 或 Base64 编码数据。不传为文生图（T2I）；传入为图生图（I2I），qwen-image-3.0 系列支持 1-3 张，qwen-image-2.1-pro 支持 1-10 张。单张可传字符串，多张传字符串数组（数组顺序即图像顺序）。不能传 `null` 或空数组，否则返回 400。格式支持 JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF，宽高建议 384-2048 像素，大小不超过 10MB。
支持的输入格式：
1. 公网 URL：支持 HTTP 和 HTTPS 协议。
2. Base64 编码：格式为 `data:{MIME_type};base64,{base64_data}`。
n:
type: integer
minimum: 1
maximum: 6
default: 1
description: 输出图像数量。字符串形式（如 `"1"`）会返回 400，必须传整数。
size:
type: string
default: auto
description: 输出分辨率，格式 `宽x高`（**字母 x 分隔**）。也可传 `auto` 由模型自动推荐。像素面积 512x512 至 2048x2048，宽高比 1:8 至 8:1。注意与 DashScope 协议的 `*` 分隔符不同，迁移时请修改。
example: 1024x1024
negative_prompt:
type: string
description: 反向提示词，描述不希望在画面中出现的内容。
seed:
type: integer
minimum: 0
maximum: 2147483647
description: 随机数种子。未传入时服务随机选择；固定种子可使结果相对稳定。
prompt_extend:
type: boolean
default: true
description: 是否开启提示词智能改写（建议开启）。开启后按 `prompt_extend_mode` 优化正向提示词。
prompt_extend_mode:
type: string
enum:
- direct
- agent
default: direct
description: 提示词改写方式。`direct`：直接提示词增强（DPE），T2I/I2I 均支持；`agent`：智能体提示词增强（APE），仅 T2I，I2I 传入返回 400。
enable_thinking:
type: boolean
default: true
description: 是否开启思考模式。开启时增强推理以提升出图质量，但增加耗时。仅在 `prompt_extend=true` 时生效，I2I Agent 暂不支持。
watermark:
type: boolean
default: false
description: 是否添加水印。
examples:
文生图（T2I）:
summary: 文生图（T2I）
value:
model: qwen-image-3.0-pro
prompt: 画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。
size: 1024x1024
n: 1
prompt_extend: true
图生图/图像编辑（I2I）:
summary: 图生图/图像编辑（I2I）
value:
model: qwen-image-3.0-pro
prompt: 帮我生成一张充满高级感的都市风格女性写真，画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物脱下原本的米色针织上衣，换上一套彰显高雅气质的都市职场穿搭，身穿一件质感垂顺的香槟色真丝衬衫，外搭一件剪裁利落的深灰色休闲西装外套，下身搭配同色系的高腰阔腿裤，整体造型既干练又富有女人味。场景设定在一家装修现代简约的高端咖啡店内，背景是通透的落地玻璃窗，窗外隐约可见繁华的城市街景，室内摆放着深色实木长桌和舒适的皮质座椅，桌面上放置着一台打开的银色笔记本电脑、一份文件和一杯热气腾腾的美式咖啡。人物呈现出慵懒而放松的办公姿态，身体微微后仰倚靠在椅背上，一只手臂自然搭在扶手上，另一只手轻轻握着咖啡杯置于桌边，头部微侧，眼神清澈从容且带有一丝慵懒地直视镜头，嘴角挂着一抹优雅自信的微笑。人物化着精致得体的正式场合妆容，底妆清透干净，眉眼线条清晰利落，唇部涂抹着显气色的豆沙色口红，展现出成熟知性的魅力。光线采用午后柔和的自然光，从侧面透过落地窗洒入，在人物的面部轮廓和衣物褶皱上留下细腻的光影过渡，背景呈现自然的景深虚化效果，色彩以大地色、灰色和暖白色为主调，营造出宁静、高级且充满故事感的都市办公氛围，构图采用经典的竖幅七分身人像视角，人物位于画面视觉中心略偏右，比例协调，画质清晰细腻。
image: https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png
size: 1024x1024
n: 1
prompt_extend: true
responses:
"200":
description: 成功响应
content:
application/json:
schema:
type: object
properties:
created:
type: integer
description: 响应创建时间的 Unix 时间戳（秒）。
data:
type: array
description: 生成结果列表。`n` 大于 1 时包含多个元素。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL（PNG 格式）。**链接有效期为 24 小时**，请及时下载并保存。
usage:
type: object
description: 本次调用的资源使用情况，仅调用成功时返回。此处为**图片输入/输出计量信息，不是 Token 用量**。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，qwen-image-2.1-pro 返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 输入图片数量。T2I 时为 0，I2I 按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位。面积≤2,250,000 为 `qima_input_1k`，否则为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位。面积≤2,250,000 为 `qima_output_1k`，否则为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
error:
type: object
description: 错误信息，仅调用失败时返回。OpenAI 兼容模式不在响应体返回 `request_id`，请求唯一标识通过 HTTP 响应头 `x-request-id` 返回。使用 OpenAI Python SDK 时，成功可读 `response._request_id`，失败可从 `APIStatusError.request_id` 读取。
properties:
message:
type: string
description: 请求失败的详细信息。
type:
type: string
description: 错误类型，如 `invalid_request_error`。
param:
type:
- string
- "null"
description: 出错的参数名，无法定位时为 `null`。
code:
type: string
description: 请求失败的错误码。详情请参见[错误码](/api-reference/preparation/error-messages)。
examples:
任务执行成功:
summary: 任务执行成功
value:
created: 1788339600
data:
- url: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx
usage:
output_height: 1024
output_width: 1024
input_image_count: 0
input_image_type: qima_input_1k
output_image_count: 1
output_image_type: qima_output_1k
任务执行异常:
summary: 任务执行异常
value:
error:
message: Field 'prompt' is required
type: invalid_request_error
param: null
code: InvalidParameter
x-codeSamples:
- lang: bash
label: 文生图（T2I）
source: |-
curl --location 'https://maas.qianwenaiapi.com/compatible-mode/v1/images/generations' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。",
"size": "1024x1024",
"n": 1,
"prompt_extend": true
}'
- lang: bash
label: 图生图/图像编辑（I2I）
source: |-
curl --location 'https://maas.qianwenaiapi.com/compatible-mode/v1/images/generations' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "帮我生成一张充满高级感的都市风格女性写真，画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物脱下原本的米色针织上衣，换上一套彰显高雅气质的都市职场穿搭，身穿一件质感垂顺的香槟色真丝衬衫，外搭一件剪裁利落的深灰色休闲西装外套，下身搭配同色系的高腰阔腿裤，整体造型既干练又富有女人味。场景设定在一家装修现代简约的高端咖啡店内，背景是通透的落地玻璃窗，窗外隐约可见繁华的城市街景，室内摆放着深色实木长桌和舒适的皮质座椅，桌面上放置着一台打开的银色笔记本电脑、一份文件和一杯热气腾腾的美式咖啡。人物呈现出慵懒而放松的办公姿态，身体微微后仰倚靠在椅背上，一只手臂自然搭在扶手上，另一只手轻轻握着咖啡杯置于桌边，头部微侧，眼神清澈从容且带有一丝慵懒地直视镜头，嘴角挂着一抹优雅自信的微笑。人物化着精致得体的正式场合妆容，底妆清透干净，眉眼线条清晰利落，唇部涂抹着显气色的豆沙色口红，展现出成熟知性的魅力。光线采用午后柔和的自然光，从侧面透过落地窗洒入，在人物的面部轮廓和衣物褶皱上留下细腻的光影过渡，背景呈现自然的景深虚化效果，色彩以大地色、灰色和暖白色为主调，营造出宁静、高级且充满故事感的都市办公氛围，构图采用经典的竖幅七分身人像视角，人物位于画面视觉中心略偏右，比例协调，画质清晰细腻。",
"image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png",
"size": "1024x1024",
"n": 1,
"prompt_extend": true
}'
- lang: python
label: 文生图（T2I）
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。",
size="1024x1024",
n=1,
# 以上均为 OpenAI 官方参数。image、prompt_extend 等扩展字段需通过 extra_body 传入，参见图生图示例
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
- lang: python
label: 图生图/图像编辑（I2I）
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="帮我生成一张充满高级感的都市风格女性写真，画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物换上一套彰显高雅气质的都市职场穿搭，场景设定在一家装修现代简约的高端咖啡店内。",
size="1024x1024",
n=1,
extra_body={
# 单张图像也可直接传字符串；也支持 Base64：data:{MIME_type};base64,{base64_data}
"image": [
"https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png",
],
"prompt_extend": True,
},
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
- lang: python
label: 读取失败请求的 request_id
source: |-
import os
from openai import OpenAI, APIStatusError
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
timeout=600.0,
)
try:
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。",
)
print(response.data[0].url)
except APIStatusError as exc:
print(f"status_code: {exc.status_code}")
print(f"request_id: {exc.request_id}")
print(exc)
components:
securitySchemes:
bearer:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-text-to-image-task-query.md
+600
View File
@@ -0,0 +1,600 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen — 查询图像生成结果
> 查询图像生成任务状态
<Note>
通过[异步接口](/api-reference/image-generation/qwen-text-to-image-async)提交请求后，使用此接口轮询任务状态。任务结果将在 **24 小时**后过期，请及时下载生成的图像。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Qwen-Image API
description: Qwen-Image 文生图 API，支持所有模型的同步调用，以及旧版模型的异步调用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getQwenImageTaskStatus
summary: 查询任务结果
description: 查询 Qwen-Image 异步任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 异步任务提交时返回的任务 ID。
schema:
type: string
responses:
"200":
description: 任务状态和结果
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: 7434edb2-3cba-44e6-a772-xxxxxxxxxxxx
output:
task_id: 878f591e-ebdf-4e45-97eb-xxxxxxxxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:39:19.484
results:
- orig_prompt: a cute cat
actual_prompt: a cute cat, high quality
url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
usage:
image_count: 1
FAILED:
summary: 任务执行失败
value:
request_id: dccfdf23-b38e-97a6-a07b-xxxxxxxxxxxx
output:
task_id: 4cbabbdf-2c1f-43f4-b983-xxxxxxxxxxxx
task_status: FAILED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:38:55.200
code: InvalidParameter
message: invalid parameter
RUNNING:
summary: 任务执行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-xxxxxxxxxxxx
output:
task_id: 13b1848b-5493-4c0e-xxxxxxxxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
SUCCEEDED_3.0:
summary: 任务执行成功（3.0系列）
value:
output:
task_id: 17d7d840-82b9-485b-a954-724d06bc88d2
task_status: SUCCEEDED
submit_time: 2026-08-07 15:50:14.837
scheduled_time: 2026-08-07 15:50:14.884
end_time: 2026-08-07 15:50:33.607
rewrite_status: not_use
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx
type: image
usage:
output_height: 1024
output_width: 1024
input_image_count: 0
input_image_type: qima_input_1k
output_image_count: 1
output_image_type: qima_output_1k
request_id: 2bd94002-5624-9129-916b-fbdde107b4ba
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
# 将 {task_id} 替换为提交响应中返回的实际任务 ID
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
QwenImageSyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
- qwen-image-2.0-pro
- qwen-image-2.0-pro-2026-06-22
- qwen-image-2.0-pro-2026-04-22
- qwen-image-2.0-pro-2026-03-03
- qwen-image-2.0
- qwen-image-2.0-2026-03-03
- qwen-image-max
- qwen-image-max-2025-12-30
- qwen-image-plus
- qwen-image-plus-2026-01-09
- qwen-image
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话。必须包含且只包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 消息内容数组，必须且只包含一个文本对象。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageContentPart"
QwenImageContentPart:
type: object
required:
- text
properties:
text:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列和 qwen-image-2.1-pro 推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: 画面是一张竖幅户外人像摄影，左上方深蓝色招牌上以白色哥特体大字写着 Il Messaggero，招牌下方是报刊亭的玻璃展示窗，内部陈列着许多报纸与杂志封面。
QwenImageSyncParameters:
type: object
description: 图像生成参数。
properties:
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符，超出部分自动截断。
maxLength: 500
size:
type: string
description: |-
输出分辨率，格式为 `宽*高`。
- **qwen-image-3.0 系列、qwen-image-2.1-pro**：总像素在 512\*512 到 2048\*2048 之间，宽高比在 1:8 到 8:1 之间，不指定时由模型根据提示词自动推荐分辨率。
- **qwen-image-2.0 系列**：总像素在 512\*512 到 2048\*2048 之间，默认 `2048*2048`。推荐分辨率：`2688*1536`（16:9）、`1536*2688`（9:16）、`2048*2048`（1:1，默认值）、`2368*1728`（4:3）、`1728*2368`（3:4）。
- **qwen-image-max、qwen-image-plus 系列**：默认 `1664*928`。可选分辨率：`1664*928`（16:9，默认值）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 2048*2048
example: 2048*2048
n:
type: integer
description: |-
生成图像数量。默认值：1。
- **qwen-image-3.0 系列、qwen-image-2.1-pro、qwen-image-2.0 系列**：1-6 张。
- **qwen-image-max/plus 系列**：固定为 1 张。
minimum: 1
maximum: 6
default: 1
prompt_extend:
type: boolean
description: 启用提示词改写。`true`（默认）：模型先优化提示词再生成；qwen-image-3.0 系列和 qwen-image-2.1-pro 按 `prompt_extend_mode` 指定的方式改写。`false`：直接使用原始提示词。
default: true
prompt_extend_mode:
type: string
description: |-
提示词改写方式。仅 qwen-image-3.0 系列和 qwen-image-2.1-pro 支持。
- `direct`（默认）：直接提示词增强（DPE），适用于大多数场景。
- `agent`：智能体提示词增强（APE），改写更精细，仅文生图支持。
enum:
- direct
- agent
default: direct
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImageAsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。异步调用仅支持 `qwen-image-plus` 和 `qwen-image`。
enum:
- qwen-image-plus
- qwen-image
example: qwen-image-plus
input:
type: object
required:
- prompt
description: 输入数据。
properties:
prompt:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: A cute orange cat sitting on a windowsill, realistic style
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符。
maxLength: 500
parameters:
$ref: "#/components/schemas/QwenImageAsyncParameters"
QwenImageAsyncParameters:
type: object
description: Qwen-Image 异步调用的生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`。可选尺寸：`1664*928`（16:9，默认）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 1664*928
enum:
- 1664*928
- 1472*1104
- 1328*1328
- 1104*1472
- 928*1664
example: 1664*928
n:
type: integer
description: 生成图像数量，固定为 1，填写其他值将报错。
enum:
- 1
default: 1
prompt_extend:
type: boolean
description: 启用智能提示词改写。`true`（默认）：模型优化提示词后再生成。`false`：直接使用原始提示词。
default: true
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImage30AsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，数组内有且只有一个对象。
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageSyncResponse:
type: object
description: Qwen-Image 同步生成的响应结果。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
role: assistant
usage:
output_height: 2048
output_width: 2048
input_image_count: 0
input_image_type: qima_input_2k
output_image_count: 1
output_image_type: qima_output_2k
request_id: d0250a3d-b07f-49e1-bdc8-6793f4929xxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表，每张生成图像对应一个元素。
items:
$ref: "#/components/schemas/QwenImageChoice"
rewrite_status:
type: string
description: 提示词改写状态，具体取值由请求是否开启改写以及改写执行结果决定。仅 qwen-image-3.0 系列返回此字段。
task_metric:
type: object
description: 任务结果统计信息。qwen-image-2.0 和 qwen-image-3.0 系列不返回此字段。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
usage:
type: object
description: 用量统计（仅统计成功结果）。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，其他系列返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 请求中输入图片的数量。文生图为 0，图像编辑按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_input_1k`，大于 2,250,000 为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_output_1k`，大于 2,250,000 为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
request_id:
type: string
description: 唯一请求标识符，用于追踪和排查问题。
example: abf1645b-b630-433a-92f6-xxxxxx
QwenImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常结束。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组。
items:
$ref: "#/components/schemas/QwenImageResponseContentPart"
QwenImageResponseContentPart:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交后的响应结果。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询状态。配合 `GET /tasks/{task_id}` 使用。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
AsyncTaskStatusResponse:
type: object
description: 异步任务状态及结果。
example:
request_id: 7434edb2-3cba-44e6-a772-xxxxxx
output:
task_id: 878f591e-ebdf-4e45-97eb-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:39:19.484
results:
- orig_prompt: Healing-style hand-drawn poster...
actual_prompt: Childhood-inspired hand-drawn poster design...
url: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/7d/xxx.png?Expires=xxxx
usage:
image_count: 1
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: |-
当前任务状态。
- `PENDING`：任务排队中
- `RUNNING`：任务处理中
- `SUCCEEDED`：任务执行成功
- `FAILED`：任务执行失败
- `CANCELED`：任务已取消
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
message:
type: string
description: 错误信息。仅当 `task_status` 为 `FAILED` 时返回。
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
AsyncTaskResult:
type: object
description: 异步任务中的单条生成结果。
properties:
orig_prompt:
type: string
description: 用户提交的原始提示词。
actual_prompt:
type: string
description: 实际用于生成的提示词（启用 `prompt_extend` 时可能与原始提示词不同）。
url:
type: string
description: 生成图像的 URL。**有效期 24 小时。**
TaskMetrics:
type: object
description: 任务完成度统计。
properties:
TOTAL:
type: integer
description: 请求生成的图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-qwen-text-to-image.md
+666
View File
@@ -0,0 +1,666 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen — 同步图像生成
> 同步图像生成
<Note>
先[获取 API Key](/api-reference/preparation/api-key) 并[配置环境变量](/api-reference/preparation/export-api-key-env)。如果使用 SDK，还需[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Qwen-Image API
description: Qwen-Image 文生图 API，支持所有模型的同步调用，以及旧版模型的异步调用。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createQwenImageSync
summary: 同步生成图像
description: 使用 Qwen-Image 同步生成图像。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImageSyncRequest"
responses:
"200":
description: 图像生成成功
content:
application/json:
schema:
$ref: "#/components/schemas/QwenImageSyncResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-3.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。"
}
]
}
]
},
"parameters": {
"negative_prompt": "",
"prompt_extend": true,
"watermark": false,
"size": "2048*2048"
}
}'
- lang: python
label: Python (DashScope SDK)
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
prompt = ("画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，"
"受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，"
"上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。"
"招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，"
"形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。"
"画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，"
"发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，"
"唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。"
"画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，"
"花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，"
"均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。")
api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [
{
"role": "user",
"content": [{"text": prompt}]
}
]
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-3.0-pro",
messages=messages,
result_format='message',
stream=False,
watermark=False,
prompt_extend=True,
negative_prompt="",
size='2048*2048'
)
if response.status_code == HTTPStatus.OK:
content = response.output.choices[0].message.content
for item in content:
if 'image' in item:
image_url = item['image']
file_name = PurePosixPath(
unquote(urlparse(image_url).path)
).parts[-1]
with open(f'./{file_name}', 'wb+') as f:
f.write(requests.get(image_url).content)
print(f"Image saved: {file_name}")
else:
print(f"Failed: {response.code}, {response.message}")
- lang: java
label: Java (DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.*;
public class QwenImageSync {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void main(String[] args) throws Exception {
String prompt = "画面是一张竖幅户外人像摄影，整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖，花叶从建筑檐口自然垂落，"
+ "受阳光照射的叶片呈黄绿色高光，阴影处则偏深绿，形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌，招牌表面较暗、略带磨砂质感，"
+ "上面以白色哥特体大字写着 Il Messaggero，文字位于画面左侧偏上，部分被前景花叶轻微遮挡，字体高对比、带装饰性尖角和粗细变化。"
+ "招牌下方是报刊亭或书报摊的玻璃展示窗，黑色金属框架将橱窗分隔成多个矩形区域，内部陈列着许多报纸、杂志和书刊封面，但大多因景深虚化和光线反射而难以辨读，"
+ "形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域，阳光从街道尽头照入，背景建筑被虚化成米灰色块面，边缘柔和，呈现明显的浅景深效果。"
+ "画面中部偏右是一名年轻成年女性的半身至膝上人像，她回头面向镜头微笑，身体略向右转，肩背朝向观者，姿态自然放松。她有长而浓密的黑色波浪卷发，"
+ "发丝被逆光勾勒出金色轮廓光，发梢在右侧向外散开，显得轻盈蓬松。她肤色白皙，脸型柔和偏鹅蛋形，眉形细致，眼睛明亮，眼妆清透，睫毛明显，面部带有自然高光，"
+ "唇部为柔和珊瑚红色，笑容露齿，表情亲切明朗。她佩戴小巧耳饰，身穿黑色细肩带露背连衣裙，面料颜色深黑、轮廓简洁，细肩带从肩部向背部延伸，背部线条清晰。"
+ "画面下部偏左到中部，她双手抱着一束玫瑰花，花束体积较大，主要由橙色、杏色、粉色和浅桃色玫瑰组成，花瓣层层卷曲，边缘被阳光照亮，绿色叶片和长花茎从花束下方垂出，"
+ "花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道，地面呈暖灰与金黄色调，远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景，"
+ "均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理，带有细腻颗粒、柔和对比和明显逆光边缘光，人物位于视觉焦点，背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。";
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(List.of(Map.of("text", prompt)))
.build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("prompt_extend", true);
parameters.put("negative_prompt", "");
parameters.put("size", "2048*2048");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-3.0-pro")
.messages(List.of(userMessage))
.parameters(parameters)
.build();
MultiModalConversation conversation = new MultiModalConversation();
MultiModalConversationResult result = conversation.call(param);
System.out.println(JsonUtils.toJson(result));
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
QwenImageSyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
- qwen-image-2.0-pro
- qwen-image-2.0-pro-2026-06-22
- qwen-image-2.0-pro-2026-04-22
- qwen-image-2.0-pro-2026-03-03
- qwen-image-2.0
- qwen-image-2.0-2026-03-03
- qwen-image-max
- qwen-image-max-2025-12-30
- qwen-image-plus
- qwen-image-plus-2026-01-09
- qwen-image
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话。必须包含且只包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 消息内容数组，必须且只包含一个文本对象。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/QwenImageContentPart"
QwenImageContentPart:
type: object
required:
- text
properties:
text:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列和 qwen-image-2.1-pro 推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: 画面是一张竖幅户外人像摄影，左上方深蓝色招牌上以白色哥特体大字写着 Il Messaggero，招牌下方是报刊亭的玻璃展示窗，内部陈列着许多报纸与杂志封面。
QwenImageSyncParameters:
type: object
description: 图像生成参数。
properties:
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符，超出部分自动截断。
maxLength: 500
size:
type: string
description: |-
输出分辨率，格式为 `宽*高`。
- **qwen-image-3.0 系列、qwen-image-2.1-pro**：总像素在 512\*512 到 2048\*2048 之间，宽高比在 1:8 到 8:1 之间，不指定时由模型根据提示词自动推荐分辨率。
- **qwen-image-2.0 系列**：总像素在 512\*512 到 2048\*2048 之间，默认 `2048*2048`。推荐分辨率：`2688*1536`（16:9）、`1536*2688`（9:16）、`2048*2048`（1:1，默认值）、`2368*1728`（4:3）、`1728*2368`（3:4）。
- **qwen-image-max、qwen-image-plus 系列**：默认 `1664*928`。可选分辨率：`1664*928`（16:9，默认值）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 2048*2048
example: 2048*2048
n:
type: integer
description: |-
生成图像数量。默认值：1。
- **qwen-image-3.0 系列、qwen-image-2.1-pro、qwen-image-2.0 系列**：1-6 张。
- **qwen-image-max/plus 系列**：固定为 1 张。
minimum: 1
maximum: 6
default: 1
prompt_extend:
type: boolean
description: 启用提示词改写。`true`（默认）：模型先优化提示词再生成；qwen-image-3.0 系列和 qwen-image-2.1-pro 按 `prompt_extend_mode` 指定的方式改写。`false`：直接使用原始提示词。
default: true
prompt_extend_mode:
type: string
description: |-
提示词改写方式。仅 qwen-image-3.0 系列和 qwen-image-2.1-pro 支持。
- `direct`（默认）：直接提示词增强（DPE），适用于大多数场景。
- `agent`：智能体提示词增强（APE），改写更精细，仅文生图支持。
enum:
- direct
- agent
default: direct
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImageAsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。异步调用仅支持 `qwen-image-plus` 和 `qwen-image`。
enum:
- qwen-image-plus
- qwen-image
example: qwen-image-plus
input:
type: object
required:
- prompt
description: 输入数据。
properties:
prompt:
type: string
description: 描述目标内容、风格和构图的正向提示词。支持中英文。qwen-image-3.0 系列推荐不超过 4500 Token；qwen-image-2.0 系列上限为 1300 Token；其他模型为 800 Token。超出部分将自动截断。
example: A cute orange cat sitting on a windowsill, realistic style
negative_prompt:
type: string
description: 描述不希望在图像中出现的内容。最多 500 个字符。
maxLength: 500
parameters:
$ref: "#/components/schemas/QwenImageAsyncParameters"
QwenImageAsyncParameters:
type: object
description: Qwen-Image 异步调用的生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`。可选尺寸：`1664*928`（16:9，默认）、`1472*1104`（4:3）、`1328*1328`（1:1）、`1104*1472`（3:4）、`928*1664`（9:16）。
default: 1664*928
enum:
- 1664*928
- 1472*1104
- 1328*1328
- 1104*1472
- 928*1664
example: 1664*928
n:
type: integer
description: 生成图像数量，固定为 1，填写其他值将报错。
enum:
- 1
default: 1
prompt_extend:
type: boolean
description: 启用智能提示词改写。`true`（默认）：模型优化提示词后再生成。`false`：直接使用原始提示词。
default: true
watermark:
type: boolean
description: 在图像右下角添加 "Qwen-Image" 水印。默认值：`false`。
default: false
enable_thinking:
type: boolean
description: 是否开启思考模式，默认值为 `true`。开启时，模型将增强推理能力以提升出图质量，但会增加生成耗时。仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 和 Agent T2I，I2I Agent 暂不支持。
default: true
seed:
type: integer
description: 随机数种子，范围为 [0, 2147483647]，未传入时服务会随机选择种子。相同种子可产生更一致（但不完全相同）的结果。
minimum: 0
maximum: 2147483647
QwenImage30AsyncRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- qwen-image-3.0-pro
- qwen-image-3.0
- qwen-image-2.1-pro
example: qwen-image-3.0-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。当前仅支持单轮对话，数组内有且只有一个对象。
items:
$ref: "#/components/schemas/QwenImageMessage"
parameters:
$ref: "#/components/schemas/QwenImageSyncParameters"
QwenImageSyncResponse:
type: object
description: Qwen-Image 同步生成的响应结果。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
role: assistant
usage:
output_height: 2048
output_width: 2048
input_image_count: 0
input_image_type: qima_input_2k
output_image_count: 1
output_image_type: qima_output_2k
request_id: d0250a3d-b07f-49e1-bdc8-6793f4929xxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表，每张生成图像对应一个元素。
items:
$ref: "#/components/schemas/QwenImageChoice"
rewrite_status:
type: string
description: 提示词改写状态，具体取值由请求是否开启改写以及改写执行结果决定。仅 qwen-image-3.0 系列返回此字段。
task_metric:
type: object
description: 任务结果统计信息。qwen-image-2.0 和 qwen-image-3.0 系列不返回此字段。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
usage:
type: object
description: 用量统计（仅统计成功结果）。字段随模型系列不同：qwen-image-3.0 系列返回 `output_*` / `input_*` 字段，其他系列返回 `image_count` / `width` / `height`。
properties:
output_width:
type: integer
description: 最终输出图片的宽度（像素）。仅 qwen-image-3.0 系列返回。
output_height:
type: integer
description: 最终输出图片的高度（像素）。仅 qwen-image-3.0 系列返回。
input_image_count:
type: integer
description: 请求中输入图片的数量。文生图为 0，图像编辑按实际输入图片数返回。仅 qwen-image-3.0 系列返回。
input_image_type:
type: string
description: 输入图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_input_1k`，大于 2,250,000 为 `qima_input_2k`。仅 qwen-image-3.0 系列返回。
output_image_count:
type: integer
description: 实际返回的输出图片数量。仅 qwen-image-3.0 系列返回。
output_image_type:
type: string
description: 输出图片计量档位，按输出分辨率像素面积判断：面积不大于 2,250,000 为 `qima_output_1k`，大于 2,250,000 为 `qima_output_2k`。仅 qwen-image-3.0 系列返回。
image_count:
type: integer
description: 已生成的图像数量。qwen-image-3.0 系列不返回此字段，改用 `output_image_count`。
width:
type: integer
description: 生成图像的宽度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_width`。
height:
type: integer
description: 生成图像的高度（像素）。qwen-image-3.0 系列不返回此字段，改用 `output_height`。
request_id:
type: string
description: 唯一请求标识符，用于追踪和排查问题。
example: abf1645b-b630-433a-92f6-xxxxxx
QwenImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常结束。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组。
items:
$ref: "#/components/schemas/QwenImageResponseContentPart"
QwenImageResponseContentPart:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交后的响应结果。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询状态。配合 `GET /tasks/{task_id}` 使用。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
AsyncTaskStatusResponse:
type: object
description: 异步任务状态及结果。
example:
request_id: 7434edb2-3cba-44e6-a772-xxxxxx
output:
task_id: 878f591e-ebdf-4e45-97eb-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-09 11:38:54.741
scheduled_time: 2025-09-09 11:38:54.781
end_time: 2025-09-09 11:39:19.484
results:
- orig_prompt: Healing-style hand-drawn poster...
actual_prompt: Childhood-inspired hand-drawn poster design...
url: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/7d/xxx.png?Expires=xxxx
usage:
image_count: 1
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: |-
当前任务状态。
- `PENDING`：任务排队中
- `RUNNING`：任务处理中
- `SUCCEEDED`：任务执行成功
- `FAILED`：任务执行失败
- `CANCELED`：任务已取消
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度执行时间。
end_time:
type: string
description: 任务完成时间。
code:
type: string
description: 错误码。仅当 `task_status` 为 `FAILED` 时返回。
message:
type: string
description: 错误信息。仅当 `task_status` 为 `FAILED` 时返回。
results:
type: array
description: 生成的图像结果。仅当 `task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
AsyncTaskResult:
type: object
description: 异步任务中的单条生成结果。
properties:
orig_prompt:
type: string
description: 用户提交的原始提示词。
actual_prompt:
type: string
description: 实际用于生成的提示词（启用 `prompt_extend` 时可能与原始提示词不同）。
url:
type: string
description: 生成图像的 URL。**有效期 24 小时。**
TaskMetrics:
type: object
description: 任务完成度统计。
properties:
TOTAL:
type: integer
description: 请求生成的图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-shoe-model-create-task.md
+266
View File
@@ -0,0 +1,266 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 鞋靴模特 — 创建任务
> 异步鞋靴模特图像生成
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
上传模特模板图和鞋靴商品图，自动生成模特上脚效果图。支持多角度鞋靴图片输入（最多3张），可批量生成多张结果图。
## 前提条件
鞋靴模特为免费试用服务。
## OpenAPI
````yaml post /services/aigc/virtualmodel/generation
openapi: 3.1.0
info:
title: 鞋靴模特 API
description: AI 鞋靴模特上脚效果图生成。上传模特模板图和鞋靴商品图，自动生成模特上脚效果图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 华北2（北京）
security:
- BearerAuth: []
paths:
/services/aigc/virtualmodel/generation:
post:
summary: 创建鞋靴模特任务
operationId: createShoeModelTask
description: 提交鞋靴模特上脚效果图生成任务，返回任务 ID 用于轮询。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 启用异步模式，必须设置为 `enable`。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ShoeModelRequest"
responses:
"200":
description: 任务提交成功。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_id: d76ec1e8-ea27-4038-8913-xxxxxxxxxxxx
task_status: PENDING
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
"400":
description: 请求无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
x-codeSamples:
- lang: curl
label: curl
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "shoemodel-v1",
"input": {
"template_image_url": "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809310.webp",
"shoe_image_url": ["https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809301.webp"]
},
"parameters": {
"n": 1
}
}'
components:
schemas:
ShoeModelRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 调用的模型名称，固定为 `shoemodel-v1`。
enum:
- shoemodel-v1
example: shoemodel-v1
input:
$ref: "#/components/schemas/ShoeModelInput"
parameters:
$ref: "#/components/schemas/ShoeModelParameters"
ShoeModelInput:
type: object
required:
- template_image_url
- shoe_image_url
description: 输入图片。
properties:
template_image_url:
type: string
description: |-
模特模板图的 URL 地址，须为可公开访问的 HTTP/HTTPS 地址。
图片要求：
- 大小：< 5 MB
- 格式：jpg、png、jpeg、bmp、webp、avif
- 宽高比：介于 2:3 与 3:2 之间（推荐 4:3）
example: https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809310.webp
shoe_image_url:
type: array
items:
type: string
maxItems: 3
description: |-
多角度鞋靴商品图的 URL 列表，最多 3 张，须为可公开访问的 HTTP/HTTPS 地址。
图片要求：
- 大小：< 5 MB
- 格式：jpg、png、jpeg、bmp、webp、avif
- 宽高比：介于 2:3 与 3:2 之间（推荐 4:3，与模板图保持一致）
example:
- https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809301.webp
ShoeModelParameters:
type: object
description: 生成参数。
properties:
n:
type: integer
minimum: 1
maximum: 4
default: 1
description: 生成图片数量，取值范围：1~4。
example: 1
scale:
type: number
format: float
minimum: 2
maximum: 8
default: 5
description: 生成强度，取值范围：[2.0, 8.0]。值越大，颜色越鲜艳。
example: 5
AsyncTaskSubmitResponse:
type: object
description: 任务提交响应。
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
ShoeModelTaskStatusResponse:
type: object
description: 任务状态响应。
properties:
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: 任务状态：`PENDING`（排队中）、`RUNNING`（处理中）、`SUCCEEDED`（成功）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（task_id 无效或已过期）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务完成时间。
results:
type: array
description: 生成的图片列表，每项包含 `url` 字段。
items:
type: object
properties:
url:
type: string
description: 生成图片的下载 URL，24 小时后过期。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功数量。
FAILED:
type: integer
description: 失败数量。
code:
type: string
description: 错误码（仅任务失败时存在）。
message:
type: string
description: 错误信息（仅任务失败时存在）。
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 本次生成的图片数量。
DashScopeErrorResponse:
type: object
description: 错误响应。
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-shoe-model-query-result.md
+285
View File
@@ -0,0 +1,285 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 鞋靴模特 — 查询结果
> 查询鞋靴模特图像生成任务状态
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
查询任务状态和结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/shoe-model/create-task)接口提交请求，获取 `task_id`。
2. 每 **10 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`SUSPENDED`（任务已暂停）、`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
- **部分失败**：当 `n > 1` 时，只要有一张图片生成成功，任务状态即为 `SUCCEEDED`。失败的图片会在 `results` 中包含错误详情，仅成功的图片计入用量。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 鞋靴模特 API
description: AI 鞋靴模特上脚效果图生成。上传模特模板图和鞋靴商品图，自动生成模特上脚效果图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 华北2（北京）
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
summary: 查询鞋靴模特任务
operationId: getShoeModelTaskResult
description: 查询鞋靴模特上脚效果图生成任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 创建任务接口返回的任务 ID。
schema:
type: string
responses:
"200":
description: 任务状态和结果。
content:
application/json:
schema:
$ref: "#/components/schemas/ShoeModelTaskStatusResponse"
examples:
SUCCEEDED:
summary: SUCCEEDED
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
submit_time: 2024-05-16 13:50:00.000
scheduled_time: 2024-05-16 13:50:01.000
end_time: 2024-05-16 13:50:30.000
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/res_img.png?Expires=xxx&OSSAccessKeyId=xxx&Signature=xxx
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
usage:
image_count: 1
RUNNING:
summary: RUNNING
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
FAILED:
summary: FAILED
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: FAILED
submit_time: 2024-05-16 13:50:00.000
scheduled_time: 2024-05-16 13:50:01.000
end_time: 2024-05-16 13:50:30.000
code: InvalidFile.Resolution
message: The image resolution is invalid, please make sure that the aspect ratio is smaller than 3:2, and largest length of image is smaller than 4096.
usage:
image_count: 0
x-codeSamples:
- lang: curl
label: curl
source: |-
curl --location --request GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
schemas:
ShoeModelRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 调用的模型名称，固定为 `shoemodel-v1`。
enum:
- shoemodel-v1
example: shoemodel-v1
input:
$ref: "#/components/schemas/ShoeModelInput"
parameters:
$ref: "#/components/schemas/ShoeModelParameters"
ShoeModelInput:
type: object
required:
- template_image_url
- shoe_image_url
description: 输入图片。
properties:
template_image_url:
type: string
description: |-
模特模板图的 URL 地址，须为可公开访问的 HTTP/HTTPS 地址。
图片要求：
- 大小：< 5 MB
- 格式：jpg、png、jpeg、bmp、webp、avif
- 宽高比：介于 2:3 与 3:2 之间（推荐 4:3）
example: https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809310.webp
shoe_image_url:
type: array
items:
type: string
maxItems: 3
description: |-
多角度鞋靴商品图的 URL 列表，最多 3 张，须为可公开访问的 HTTP/HTTPS 地址。
图片要求：
- 大小：< 5 MB
- 格式：jpg、png、jpeg、bmp、webp、avif
- 宽高比：介于 2:3 与 3:2 之间（推荐 4:3，与模板图保持一致）
example:
- https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809301.webp
ShoeModelParameters:
type: object
description: 生成参数。
properties:
n:
type: integer
minimum: 1
maximum: 4
default: 1
description: 生成图片数量，取值范围：1~4。
example: 1
scale:
type: number
format: float
minimum: 2
maximum: 8
default: 5
description: 生成强度，取值范围：[2.0, 8.0]。值越大，颜色越鲜艳。
example: 5
AsyncTaskSubmitResponse:
type: object
description: 任务提交响应。
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于轮询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
ShoeModelTaskStatusResponse:
type: object
description: 任务状态响应。
properties:
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: 任务状态：`PENDING`（排队中）、`RUNNING`（处理中）、`SUCCEEDED`（成功）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（task_id 无效或已过期）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务完成时间。
results:
type: array
description: 生成的图片列表，每项包含 `url` 字段。
items:
type: object
properties:
url:
type: string
description: 生成图片的下载 URL，24 小时后过期。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功数量。
FAILED:
type: integer
description: 失败数量。
code:
type: string
description: 错误码（仅任务失败时存在）。
message:
type: string
description: 错误信息（仅任务失败时存在）。
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 本次生成的图片数量。
DashScopeErrorResponse:
type: object
description: 错误响应。
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识，可用于问题排查。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-vidu-image-generation-create-task.md
+400
View File
@@ -0,0 +1,400 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vidu -- 创建任务
> 使用 Vidu 模型提交图像生成任务（文生图/参考图生图），异步生成图像。
提交图像生成任务后，服务将异步生成图像。提交任务后，使用[查询任务结果](/api-reference/image-generation/vidu-image-generation/query-result)接口轮询任务状态，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
## 模型列表
| 模型 | 能力 | 输入模态 | 输出图像规格 |
| -------------------------------------- | ------------------------------------ | ----- | ---------------- |
| `vidu/vidu-image_reference2image` | 参考生图、文生图、图片编辑，中英文字精准渲染、UI/图表像素级还原 | 文本、图像 | 1K/2K/4K，1 张，PNG |
| `vidu/vidu-image-pro_reference2image` | 参考生图、文生图、图片编辑，中英文字精准渲染、UI/图表像素级还原 | 文本、图像 | 1K/2K/4K，1 张，PNG |
| `vidu/vidu-image-lite_reference2image` | 参考生图、文生图、图片编辑，中英文字精准渲染、UI/图表像素级还原 | 文本、图像 | 1K/2K/4K，1 张，PNG |
| `vidu/viduq3-fast_reference2image` | 参考生图、文生图、图片编辑，高速高质低成本（比 Pro 降低约 50%） | 文本、图像 | 1K/2K/4K，1 张，PNG |
| `vidu/viduq2-pro_reference2image` | 参考生图、文生图、图片编辑，复杂逻辑处理、上下文一致性 | 文本、图像 | 1K/2K/4K，1 张，PNG |
| `vidu/viduq2-fast_reference2image` | 参考生图、文生图、图片编辑，语义理解增强 | 文本、图像 | 1K，1 张，PNG |
## HTTP 调用
图像生成接口仅支持异步调用，请求时必须携带请求头 `X-DashScope-Async: enable`。
任务提交成功后返回 `task_id`，使用[查询任务结果](/api-reference/image-generation/vidu-image-generation/query-result)接口获取生成结果。
## 可用尺寸列表
### vidu-image、vidu-image-pro、vidu-image-lite
| 分辨率 | 支持尺寸 |
| --- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 1K | 1024\*1024, 720\*1440, 1440\*720, 1024\*768, 768\*1024, 1920\*1088, 1088\*1920, 1536\*1024, 1024\*1536, 1920\*816, 816\*1920 |
| 2K | 2048\*2048, 1088\*2160, 2160\*1088, 2736\*2048, 2048\*2736, 2560\*1440, 1440\*2560, 3072\*2048, 2048\*3072, 2560\*1104, 1104\*2560 |
| 4K | 2880\*2880, 1440\*2880, 2880\*1440, 3312\*2480, 2480\*3312, 3840\*2160, 2160\*3840, 3520\*2352, 2352\*3520, 3840\*1648, 1648\*3840 |
### viduq3-fast
| 分辨率 | 支持尺寸 |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1K | 1024\*1024, 768\*1376, 848\*1264, 896\*1200, 928\*1152, 1152\*928, 1200\*896, 1264\*848, 1376\*768, 1584\*672, 512\*2064, 2064\*512, 352\*2928, 2928\*352 |
| 2K | 2048\*2048, 1536\*2752, 1696\*2528, 1792\*2400, 1856\*2304, 2304\*1856, 2400\*1792, 2528\*1696, 2752\*1536, 3168\*1344, 1024\*4128, 4128\*1024, 704\*5856, 5856\*704 |
| 4K | 4096\*4096, 3072\*5504, 3392\*5056, 3584\*4800, 3712\*4608, 4608\*3712, 4800\*3584, 5056\*3392, 5504\*3072, 6336\*2688, 2048\*8256, 8256\*2048, 1408\*11712, 11712\*1408 |
### viduq2-pro
| 分辨率 | 支持尺寸 |
| --- | ---------------------------------------------------------------------------------------------------------------------- |
| 1K | 1024\*1024, 768\*1376, 848\*1264, 896\*1200, 928\*1152, 1152\*928, 1200\*896, 1264\*848, 1376\*768, 1584\*672 |
| 2K | 2048\*2048, 1536\*2752, 1696\*2528, 1792\*2400, 1856\*2304, 2304\*1856, 2400\*1792, 2528\*1696, 2752\*1536, 3168\*1344 |
| 4K | 4096\*4096, 3072\*5504, 3392\*5056, 3584\*4800, 3712\*4608, 4608\*3712, 4800\*3584, 5056\*3392, 5504\*3072, 6336\*2688 |
### viduq2-fast
| 分辨率 | 支持尺寸 |
| --- | ------------------------------------------------------------------------------------------------------------- |
| 1K | 1024\*1024, 768\*1376, 848\*1264, 896\*1200, 928\*1152, 1152\*928, 1200\*896, 1264\*848, 1376\*768, 1584\*672 |
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.0.0
info:
title: Vidu 图像生成 API
description: Vidu 参考生图模型支持文生图、图片编辑、参考图生图等任务。API 采用异步调用模式，包含"创建任务"和"查询结果"两个步骤。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createViduImageGenerationTask
summary: 创建图像生成任务
description: 提交图像生成任务，返回 task_id 用于后续轮询查询。
parameters:
- name: Content-Type
in: header
required: true
description: 请求内容类型，必须设置为 application/json。
schema:
type: string
enum:
- application/json
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置参数。HTTP 请求只支持异步，必须设置为 enable。缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ViduImageGenerationRequest"
responses:
"200":
description: 任务创建成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求失败
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 文生图
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "vidu/vidu-image_reference2image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵"
}
]
}
]
},
"parameters": {
"size": "1024*1024",
"n": 1,
"watermark": false
}
}'
- lang: curl
label: 参考图生图
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "vidu/vidu-image_reference2image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "参考图片的风格，生成一只坐着的橘黄色的猫"
},
{
"image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
}
]
}
]
},
"parameters": {
"size": "2048*2048",
"n": 1,
"watermark": false
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ViduImageGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- vidu/vidu-image_reference2image
- vidu/vidu-image-pro_reference2image
- vidu/vidu-image-lite_reference2image
- vidu/viduq3-fast_reference2image
- vidu/viduq2-pro_reference2image
- vidu/viduq2-fast_reference2image
example: vidu/vidu-image_reference2image
input:
type: object
required:
- messages
description: 输入参数对象。
properties:
messages:
type: array
description: 消息列表。数组内有且只有一个对象，该对象包含 role 和 content 两个属性。服务端会提取第一个非空 text 作为提示词，并提取全部 image 作为参考图。
items:
type: object
properties:
role:
type: string
description: 消息的角色，建议设置为 user。
example: user
content:
type: array
description: 消息内容，包含文本提示词（text）和可选的参考图像（image，最多 14 张）。
items:
type: object
properties:
text:
type: string
description: 正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过 5000 个字符。整个 messages 中至少需要一个非空文本。
example: 一间有着精致窗户的花店,漂亮的木质门,摆放着花朵
image:
type: string
description: 参考图像的 URL。支持 HTTP 或 HTTPS 协议。所有模型最多支持输入 14 张参考图。图像格式：PNG、JPG、WEBP。宽高比：1:4 ~ 4:1。文件大小：所有图片总和不超过 50MB。
example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png
parameters:
$ref: "#/components/schemas/ViduImageGenerationParameters"
ViduImageGenerationParameters:
type: object
description: 控制图像生成参数。
properties:
size:
type: string
description: 图片尺寸，格式为宽*高（如 2048*2048）。不传时默认 1024*1024。不同模型支持的尺寸列表请参见页面下方的可用尺寸列表。
default: 1024*1024
example: 1024*1024
n:
type: integer
description: 生成图片数量，当前仅支持 1。
enum:
- 1
default: 1
example: 1
seed:
type: integer
description: 随机数种子，取值范围 [0, 2147483647]，0 表示随机。使用相同的 seed 参数值可使生成内容保持相对稳定。若不提供，算法将自动使用随机数种子。
minimum: 0
maximum: 2147483647
example: 12345
watermark:
type: boolean
description: 是否添加水印标识。false（默认）：不添加水印。true：添加水印。
default: false
example: false
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。用于查询任务状态与结果，有效期 24 小时。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。初始状态通常为 PENDING。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: PENDING
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
TaskStatusResponse:
type: object
description: 任务查询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: f584a817-6e00-9841-961a-49f7382a03d4
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
example: 6404d4ec-4cdf-45b5-8d7d-3d429c6baed5
task_status:
type: string
description: 任务状态。状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:27:41.291
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:27:41.320
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:28:39.767
finished:
type: boolean
description: 是否完成，仅在 task_status=SUCCEEDED 时返回。
choices:
type: array
description: 图片输出候选列表，仅在 task_status=SUCCEEDED 时返回。
items:
type: object
properties:
finish_reason:
type: string
description: 结束原因，成功时通常为 stop。
example: stop
message:
type: object
description: 模型返回的消息。
properties:
role:
type: string
description: 消息的角色，固定为 assistant。
example: assistant
content:
type: array
description: 消息内容。
items:
type: object
properties:
type:
type: string
description: 输出内容的类型，固定为 image。
example: image
image:
type: string
description: 生成图像的下载链接，图像格式为 PNG。链接有效期为 24 小时，请及时下载并保存图像。
example: https://example.com/generated-image.png
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
usage:
type: object
description: 资源用量信息。只对成功的结果计数。
properties:
image_count:
type: integer
description: 生成图像的数量。
example: 1
size:
type: string
description: 生成图片的分辨率，格式为宽*高。
example: 2048*2048
SR:
type: string
description: 生成图像的分辨率档位。
example: 2K
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: 7438d53d-6eb8-4596-8835-xxxxxx
code:
type: string
description: 错误码。
example: InvalidApiKey
message:
type: string
description: 错误详细信息。
example: No API-key provided.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-vidu-image-generation-query-result.md
+362
View File
@@ -0,0 +1,362 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vidu -- 查询结果
> 查询 Vidu 图像生成任务的状态与结果。
提交任务后，建议每隔 **5 秒**轮询一次该接口，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
## 任务状态流转
`PENDING` -> `RUNNING` -> `SUCCEEDED` 或 `FAILED`
| 状态 | 说明 |
| ----------- | --------------------------------- |
| `PENDING` | 任务排队等待中 |
| `RUNNING` | 任务生成中 |
| `SUCCEEDED` | 任务成功，可获取图片链接 |
| `FAILED` | 任务失败，查看 `code` 和 `message` 字段获取原因 |
| `CANCELED` | 任务已取消 |
| `UNKNOWN` | 任务不存在或已过期（超过 24 小时） |
<Note>
- 成功响应中的图片下载链接有效期为 **24 小时**，请及时下载保存。
- 支持配置异步回调，免去主动轮询。详见[配置异步回调](/developer-guides/run-and-scale/async-task-management)。
</Note>
## 错误码
请参见[错误信息](/api-reference/preparation/error-messages)。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: Vidu 图像生成 API
description: Vidu 参考生图模型支持文生图、图片编辑、参考图生图等任务。API 采用异步调用模式，包含"创建任务"和"查询结果"两个步骤。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getViduImageGenerationTaskStatus
summary: 查询任务结果
description: 根据 task_id 查询任务状态与结果。task_id 有效期为 24 小时。建议设置合理的查询间隔（如 5 秒）进行轮询。
parameters:
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
- name: task_id
in: path
required: true
description: 任务 ID。将上一步接口返回的 task_id 完整替换。查询有效期为 24 小时。
schema:
type: string
responses:
"200":
description: 查询成功
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: f584a817-6e00-9841-961a-49f7382a03d4
output:
task_id: 6404d4ec-4cdf-45b5-8d7d-3d429c6baed5
task_status: SUCCEEDED
submit_time: 2026-07-13 20:27:41.291
scheduled_time: 2026-07-13 20:27:41.320
end_time: 2026-07-13 20:28:39.767
finished: true
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://example.com/generated-image.png
type: image
usage:
SR: 2K
size: 2048*2048
image_count: 1
RUNNING:
summary: 任务生成中
value:
request_id: b3c41e52-9d1a-4f87-bc23-xxxxxx
output:
task_id: 6404d4ec-4cdf-45b5-8d7d-3d429c6baed5
task_status: RUNNING
submit_time: 2026-07-13 20:27:41.291
scheduled_time: 2026-07-13 20:27:41.320
FAILED:
summary: 任务执行失败
value:
request_id: 1f015514-b04c-9190-b4dd-8ba11bb15708
output:
task_id: ccae6c03-fe9f-48fd-b3d6-a524c4707f17
task_status: FAILED
submit_time: 2026-07-13 20:27:50.654
scheduled_time: 2026-07-13 20:27:50.689
end_time: 2026-07-13 20:27:51.090
code: InvalidParameter
message: Missing required field 'parameters.n' in request body
UNKNOWN:
summary: 任务查询过期
value:
request_id: a4de7c32-7057-9f82-8581-xxxxxx
output:
task_id: 502a00b1-19d9-4839-a82f-xxxxxx
task_status: UNKNOWN
"400":
description: 请求失败
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ViduImageGenerationRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- vidu/vidu-image_reference2image
- vidu/vidu-image-pro_reference2image
- vidu/vidu-image-lite_reference2image
- vidu/viduq3-fast_reference2image
- vidu/viduq2-pro_reference2image
- vidu/viduq2-fast_reference2image
example: vidu/vidu-image_reference2image
input:
type: object
required:
- messages
description: 输入参数对象。
properties:
messages:
type: array
description: 消息列表。数组内有且只有一个对象，该对象包含 role 和 content 两个属性。服务端会提取第一个非空 text 作为提示词，并提取全部 image 作为参考图。
items:
type: object
properties:
role:
type: string
description: 消息的角色，建议设置为 user。
example: user
content:
type: array
description: 消息内容，包含文本提示词（text）和可选的参考图像（image，最多 14 张）。
items:
type: object
properties:
text:
type: string
description: 正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过 5000 个字符。整个 messages 中至少需要一个非空文本。
example: 一间有着精致窗户的花店,漂亮的木质门,摆放着花朵
image:
type: string
description: 参考图像的 URL。支持 HTTP 或 HTTPS 协议。所有模型最多支持输入 14 张参考图。图像格式：PNG、JPG、WEBP。宽高比：1:4 ~ 4:1。文件大小：所有图片总和不超过 50MB。
example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png
parameters:
$ref: "#/components/schemas/ViduImageGenerationParameters"
ViduImageGenerationParameters:
type: object
description: 控制图像生成参数。
properties:
size:
type: string
description: 图片尺寸，格式为宽*高（如 2048*2048）。不传时默认 1024*1024。不同模型支持的尺寸列表请参见页面下方的可用尺寸列表。
default: 1024*1024
example: 1024*1024
n:
type: integer
description: 生成图片数量，当前仅支持 1。
enum:
- 1
default: 1
example: 1
seed:
type: integer
description: 随机数种子，取值范围 [0, 2147483647]，0 表示随机。使用相同的 seed 参数值可使生成内容保持相对稳定。若不提供，算法将自动使用随机数种子。
minimum: 0
maximum: 2147483647
example: 12345
watermark:
type: boolean
description: 是否添加水印标识。false（默认）：不添加水印。true：添加水印。
default: false
example: false
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。用于查询任务状态与结果，有效期 24 小时。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。初始状态通常为 PENDING。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: PENDING
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
TaskStatusResponse:
type: object
description: 任务查询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: f584a817-6e00-9841-961a-49f7382a03d4
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
example: 6404d4ec-4cdf-45b5-8d7d-3d429c6baed5
task_status:
type: string
description: 任务状态。状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:27:41.291
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:27:41.320
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
example: 2026-07-13 20:28:39.767
finished:
type: boolean
description: 是否完成，仅在 task_status=SUCCEEDED 时返回。
choices:
type: array
description: 图片输出候选列表，仅在 task_status=SUCCEEDED 时返回。
items:
type: object
properties:
finish_reason:
type: string
description: 结束原因，成功时通常为 stop。
example: stop
message:
type: object
description: 模型返回的消息。
properties:
role:
type: string
description: 消息的角色，固定为 assistant。
example: assistant
content:
type: array
description: 消息内容。
items:
type: object
properties:
type:
type: string
description: 输出内容的类型，固定为 image。
example: image
image:
type: string
description: 生成图像的下载链接，图像格式为 PNG。链接有效期为 24 小时，请及时下载并保存图像。
example: https://example.com/generated-image.png
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
usage:
type: object
description: 资源用量信息。只对成功的结果计数。
properties:
image_count:
type: integer
description: 生成图像的数量。
example: 1
size:
type: string
description: 生成图片的分辨率，格式为宽*高。
example: 2048*2048
SR:
type: string
description: 生成图像的分辨率档位。
example: 2K
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: 7438d53d-6eb8-4596-8835-xxxxxx
code:
type: string
description: 错误码。
example: InvalidApiKey
message:
type: string
description: 错误详细信息。
example: No API-key provided.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-virtual-model-create-task.md
+467
View File
@@ -0,0 +1,467 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 虚拟模特 — 创建任务
> 提交虚拟模特试衣任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml post /services/aigc/virtualmodel/generation
openapi: 3.0.0
info:
title: 万相-虚拟模特 API
description: 万相-虚拟模特可以对上传的真人实拍商品展示图进行智能生成，将其中的模特和背景替换为心仪的内容，在保持人物姿态不变的情况下，使用虚拟模特对商品进行更加精美、多样的展示。支持各种与模特产生互动的商品，如手持小商品、服装、鞋靴、配饰等。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/virtualmodel/generation:
post:
operationId: createVirtualModelTask
summary: 创建虚拟模特任务
description: 提交一个异步虚拟模特任务，该请求会返回任务ID。请使用任务ID轮询 GET /tasks/{task_id} 获取结果。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 是否使用异步调用。HTTP只支持异步调用，设置为 `enable`。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualModelRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
examples:
success:
summary: 任务已接受
value:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 参数无效
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: The request is missing required parameters or in a wrong format, please check the parameters that you send.
InvalidFileContent:
summary: 图片内容无效
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidFile.Content
message: The input image has no human body or has unclear human body. Please upload other image
"401":
description: 认证失败
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidApiKey:
summary: 无效API密钥
value:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
"429":
description: 请求超过限流阈值
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL（V1 — wanx-virtualmodel）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-virtualmodel",
"input": {
"base_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E7%9C%9F%E4%BA%BA%E6%A8%A1%E7%89%B9%E5%AE%9E%E6%8B%8D-%E5%A5%B3%20%281%29.jpeg",
"mask_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/image.jpg",
"prompt": "一名年轻女子，身穿白色短裤，极简风格调色板，长镜头，双色效果（暗银色和浅粉色）",
"face_prompt": "年轻女子，面容姣好，最高品质"
},
"parameters": {
"short_side_size": "512",
"n": 1
}
}'
- lang: curl
label: cURL（V2 — virtualmodel-v2）
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "virtualmodel-v2",
"input": {
"base_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E7%9C%9F%E4%BA%BA%E6%A8%A1%E7%89%B9%E5%AE%9E%E6%8B%8D-%E5%A5%B3%20%281%29.jpeg",
"mask_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/image.jpg",
"background_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E8%99%9A%E6%8B%9F%E6%A8%A1%E7%89%B9%E7%94%9F%E6%88%90%E8%83%8C%E6%99%AF%E5%9B%BE.png",
"prompt": "a beautiful chinese woman stands in front of a plain white background",
"face_prompt": "a beautiful chinese woman, good face, best face, best quality"
},
"parameters": {
"short_side_size": "1024",
"n": 1
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
VirtualModelRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: |-
调用的模型名称。
- `wanx-virtualmodel`：虚拟模特V1版本，支持 `short_side_size` 取值 `"512"` 和 `"1024"`，支持 `predefined_face_id`。
- `virtualmodel-v2`：虚拟模特V2版本，支持 `short_side_size` 取值 `"1024"` 和 `"2048"`，支持 `bgstyle_scale`、`realPerson`、`style`、`seed`、`aspect_ratio`。
enum:
- wanx-virtualmodel
- virtualmodel-v2
example: virtualmodel-v2
input:
type: object
required:
- base_image_url
- mask_image_url
- prompt
- face_prompt
description: 输入图像的基本信息，比如图像URL地址。
properties:
base_image_url:
type: string
format: uri
description: |-
原始真人展示图像URL地址。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图像限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：不低于256×256像素且不超过4096×4096像素，人脸占比不低于128×128像素。
- 长宽比：大于1:2且小于2:1。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/model.jpg
mask_image_url:
type: string
format: uri
description: |-
对应原图的期望保留区域mask图URL，图片为（0,255）的黑白图，其中白色表示商品主体区域。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：与base_image_url参数对应的图像保持一致。
- 长宽比：大于1:2且小于2:1。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/mask.png
prompt:
type: string
description: |-
针对生成图像背景环境、模特的全身形象描述。支持中英文，小于100字符。
示例：一名年轻女子，身穿白色短裤，极简风格调色板，长镜头，双色效果，暗银色和浅粉色。
maxLength: 100
example: 一名年轻女子，身穿白色短裤，极简风格调色板
face_prompt:
type: string
description: |-
生成人像面部描述。支持中英文，小于100字符。
示例：年轻女子，面容姣好，最高品质。
maxLength: 100
example: 年轻女子，面容姣好，最高品质
predefined_face_id:
type: string
description: |-
预设人物ID。仅在V1版本（wanx-virtualmodel）使用。优先级高于face_image_url。
枚举值：`girl1`、`girl2`、`girl3`、`boy1`、`boy2`、`boy3`。
enum:
- girl1
- girl2
- girl3
- boy1
- boy2
- boy3
face_image_url:
type: string
format: uri
description: |-
期望替换的人物图像URL地址。优先级低于predefined_face_id参数。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：长边像素不大于2048，人脸区域大于128×128像素。
- 图像大小：建议不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/face.jpg
background_image_url:
type: string
format: uri
description: |-
背景环境参考图像URL地址。仅在V2版本（virtualmodel-v2）使用。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：图像长边像素不大于4096。
- 图像比例：长宽比小于等于2。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/background.jpg
bgstyle_scale:
type: number
description: |-
背景参考图像权重控制。仅在V2版本（virtualmodel-v2）使用。
取值范围：[0.0, 1.0]，默认0.7。数值越大表示参考程度越大。
minimum: 0
maximum: 1
default: 0.7
example: 0.7
realPerson:
type: boolean
description: |-
输入图片是否是真人。仅在V2版本（virtualmodel-v2）使用。
- `true`（默认）：表示输入图像是真人。
- `false`：表示输入图像是人台或者非真人。
default: true
style:
type: string
description: |-
生成图片风格。仅在V2版本（virtualmodel-v2）使用。
- `"portrait"`（默认）：增加景深，突出人像效果。
- `""`（空字符串）：标准风格。
enum:
- portrait
- ""
default: portrait
seed:
type: integer
description: |-
控制生成seed。仅在V2版本（virtualmodel-v2）使用。
取值范围：[-1,10000000]。默认值为-1，表示系统随机内置seed。同样的seed值会生成相同的结果。
minimum: -1
maximum: 10000000
aspect_ratio:
type: string
description: |-
生成图片长宽比例。仅在V2版本（virtualmodel-v2）使用。
可选值：`unchanged`（比例不变，默认值）、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`1:2`。
enum:
- unchanged
- 2:1
- 16:9
- 4:3
- 1:1
- 3:4
- 9:16
- 1:2
default: unchanged
parameters:
type: object
description: 生成参数。
properties:
short_side_size:
type: string
description: |-
指定生成的图像短边大小，单位：像素。生成图片和输入原图会保持相同的长宽比。
- V1版本（wanx-virtualmodel）可选值：`"512"` 和 `"1024"`。
- V2版本（virtualmodel-v2）可选值：`"1024"` 和 `"2048"`。
enum:
- "512"
- "1024"
- "2048"
example: "1024"
n:
type: integer
description: 生成图像的数量。取值范围：[1, 4]，默认值 1。
minimum: 1
maximum: 4
default: 1
example: 1
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。用于轮询 GET /tasks/{task_id} 查询结果。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。初始状态通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态查询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: f24149fe-4722-9763-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。
example: 9d62befa-0139-4e4d-xxxxxx
task_status:
type: string
description: |-
任务状态。
- `PENDING`：排队中
- `RUNNING`：处理中
- `SUSPENDED`：挂起
- `SUCCEEDED`：执行成功
- `FAILED`：执行失败
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
example: 2025-04-24 10:51:35.004
scheduled_time:
type: string
description: 任务排期执行时间。
example: 2025-04-24 10:51:35.033
end_time:
type: string
description: 任务完成时间。
example: 2025-04-24 10:51:59.424
results:
type: array
description: 任务结果列表，包括图像URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。
items:
type: object
properties:
url:
type: string
format: uri
description: 模型生成图片的URL地址。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_1.png
result_url:
type: string
format: uri
description: 输出图片URL。
code:
type: string
description: 任务执行失败的错误码。仅在 `task_status` 为 `FAILED` 时返回。
example: InvalidImageResolution
message:
type: string
description: 任务执行失败的详细信息。仅在 `task_status` 为 `FAILED` 时返回。
example: The input image resolution is too large or small
task_metrics:
type: object
description: 任务信息统计指标。
properties:
TOTAL:
type: integer
description: 总的任务数。
example: 2
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
example: 2
FAILED:
type: integer
description: 任务状态为失败的任务数。
example: 0
usage:
type: object
description: 输出信息统计。仅在任务成功时返回。
properties:
image_count:
type: integer
description: 模型生成图像的数量。
example: 2
DashScopeErrorResponse:
type: object
description: DashScope API错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code:
type: string
description: 接口错误码。接口成功请求不会返回该参数。
example: InvalidParameter
message:
type: string
description: 接口错误信息。接口成功请求不会返回该参数。
example: The request is missing required parameters or in a wrong format, please check the parameters that you send.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-virtual-model-query-result.md
+429
View File
@@ -0,0 +1,429 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 虚拟模特 — 查询结果
> 查询虚拟模特任务的状态和结果
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: 万相-虚拟模特 API
description: 万相-虚拟模特可以对上传的真人实拍商品展示图进行智能生成，将其中的模特和背景替换为心仪的内容，在保持人物姿态不变的情况下，使用虚拟模特对商品进行更加精美、多样的展示。支持各种与模特产生互动的商品，如手持小商品、服装、鞋靴、配饰等。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getVirtualModelTaskStatus
summary: 根据任务ID查询结果
description: 使用任务ID查询模型生成的结果。请持续轮询直至 `task_status` 为 `SUCCEEDED` 或 `FAILED`。任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除，请及时保存生成的图像。
parameters:
- name: task_id
in: path
required: true
description: 创建任务接口返回的任务ID。
schema:
type: string
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
responses:
"200":
description: 获取任务状态成功
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: f24149fe-4722-9763-xxxxxx
output:
task_id: 9d62befa-0139-4e4d-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-04-24 10:51:35.004
scheduled_time: 2025-04-24 10:51:35.033
end_time: 2025-04-24 10:51:59.424
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_1.png
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_2.png
task_metrics:
TOTAL: 2
SUCCEEDED: 2
FAILED: 0
usage:
image_count: 2
FAILED:
summary: 任务执行失败
value:
request_id: f24149fe-4722-9763-xxxxxx
output:
task_id: 9d62befa-0139-4e4d-xxxxxx
task_status: FAILED
submit_time: 2024-05-16 13:50:23.001
scheduled_time: 2024-05-16 13:50:23.033
end_time: 2024-05-16 13:51:05.412
code: InvalidImageResolution
message: The input image resolution is too large or small
usage:
image_count: 0
RUNNING:
summary: 任务处理中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL — 获取任务结果
source: |-
curl --location --request GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
VirtualModelRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: |-
调用的模型名称。
- `wanx-virtualmodel`：虚拟模特V1版本，支持 `short_side_size` 取值 `"512"` 和 `"1024"`，支持 `predefined_face_id`。
- `virtualmodel-v2`：虚拟模特V2版本，支持 `short_side_size` 取值 `"1024"` 和 `"2048"`，支持 `bgstyle_scale`、`realPerson`、`style`、`seed`、`aspect_ratio`。
enum:
- wanx-virtualmodel
- virtualmodel-v2
example: virtualmodel-v2
input:
type: object
required:
- base_image_url
- mask_image_url
- prompt
- face_prompt
description: 输入图像的基本信息，比如图像URL地址。
properties:
base_image_url:
type: string
format: uri
description: |-
原始真人展示图像URL地址。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图像限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：不低于256×256像素且不超过4096×4096像素，人脸占比不低于128×128像素。
- 长宽比：大于1:2且小于2:1。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/model.jpg
mask_image_url:
type: string
format: uri
description: |-
对应原图的期望保留区域mask图URL，图片为（0,255）的黑白图，其中白色表示商品主体区域。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：与base_image_url参数对应的图像保持一致。
- 长宽比：大于1:2且小于2:1。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/mask.png
prompt:
type: string
description: |-
针对生成图像背景环境、模特的全身形象描述。支持中英文，小于100字符。
示例：一名年轻女子，身穿白色短裤，极简风格调色板，长镜头，双色效果，暗银色和浅粉色。
maxLength: 100
example: 一名年轻女子，身穿白色短裤，极简风格调色板
face_prompt:
type: string
description: |-
生成人像面部描述。支持中英文，小于100字符。
示例：年轻女子，面容姣好，最高品质。
maxLength: 100
example: 年轻女子，面容姣好，最高品质
predefined_face_id:
type: string
description: |-
预设人物ID。仅在V1版本（wanx-virtualmodel）使用。优先级高于face_image_url。
枚举值：`girl1`、`girl2`、`girl3`、`boy1`、`boy2`、`boy3`。
enum:
- girl1
- girl2
- girl3
- boy1
- boy2
- boy3
face_image_url:
type: string
format: uri
description: |-
期望替换的人物图像URL地址。优先级低于predefined_face_id参数。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：长边像素不大于2048，人脸区域大于128×128像素。
- 图像大小：建议不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/face.jpg
background_image_url:
type: string
format: uri
description: |-
背景环境参考图像URL地址。仅在V2版本（virtualmodel-v2）使用。
URL需为公网可访问的地址，并支持HTTP或HTTPS协议。
图片限制：
- 图像格式：JPEG、JPG、PNG、WEBP。
- 图像分辨率：图像长边像素不大于4096。
- 图像比例：长宽比小于等于2。
- 图像大小：不超过5MB。
- URL地址中不能包含中文字符。
example: https://example.com/background.jpg
bgstyle_scale:
type: number
description: |-
背景参考图像权重控制。仅在V2版本（virtualmodel-v2）使用。
取值范围：[0.0, 1.0]，默认0.7。数值越大表示参考程度越大。
minimum: 0
maximum: 1
default: 0.7
example: 0.7
realPerson:
type: boolean
description: |-
输入图片是否是真人。仅在V2版本（virtualmodel-v2）使用。
- `true`（默认）：表示输入图像是真人。
- `false`：表示输入图像是人台或者非真人。
default: true
style:
type: string
description: |-
生成图片风格。仅在V2版本（virtualmodel-v2）使用。
- `"portrait"`（默认）：增加景深，突出人像效果。
- `""`（空字符串）：标准风格。
enum:
- portrait
- ""
default: portrait
seed:
type: integer
description: |-
控制生成seed。仅在V2版本（virtualmodel-v2）使用。
取值范围：[-1,10000000]。默认值为-1，表示系统随机内置seed。同样的seed值会生成相同的结果。
minimum: -1
maximum: 10000000
aspect_ratio:
type: string
description: |-
生成图片长宽比例。仅在V2版本（virtualmodel-v2）使用。
可选值：`unchanged`（比例不变，默认值）、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`1:2`。
enum:
- unchanged
- 2:1
- 16:9
- 4:3
- 1:1
- 3:4
- 9:16
- 1:2
default: unchanged
parameters:
type: object
description: 生成参数。
properties:
short_side_size:
type: string
description: |-
指定生成的图像短边大小，单位：像素。生成图片和输入原图会保持相同的长宽比。
- V1版本（wanx-virtualmodel）可选值：`"512"` 和 `"1024"`。
- V2版本（virtualmodel-v2）可选值：`"1024"` 和 `"2048"`。
enum:
- "512"
- "1024"
- "2048"
example: "1024"
n:
type: integer
description: 生成图像的数量。取值范围：[1, 4]，默认值 1。
minimum: 1
maximum: 4
default: 1
example: 1
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: 4909100c-7b5a-9f92-bfe5-28c7cece6b47
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。用于轮询 GET /tasks/{task_id} 查询结果。
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: 任务状态。初始状态通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
TaskStatusResponse:
type: object
description: 任务状态查询响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
example: f24149fe-4722-9763-xxxxxx
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。
example: 9d62befa-0139-4e4d-xxxxxx
task_status:
type: string
description: |-
任务状态。
- `PENDING`：排队中
- `RUNNING`：处理中
- `SUSPENDED`：挂起
- `SUCCEEDED`：执行成功
- `FAILED`：执行失败
- `UNKNOWN`：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- SUSPENDED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。
example: 2025-04-24 10:51:35.004
scheduled_time:
type: string
description: 任务排期执行时间。
example: 2025-04-24 10:51:35.033
end_time:
type: string
description: 任务完成时间。
example: 2025-04-24 10:51:59.424
results:
type: array
description: 任务结果列表，包括图像URL。仅在 `task_status` 为 `SUCCEEDED` 时返回。
items:
type: object
properties:
url:
type: string
format: uri
description: 模型生成图片的URL地址。
example: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_1.png
result_url:
type: string
format: uri
description: 输出图片URL。
code:
type: string
description: 任务执行失败的错误码。仅在 `task_status` 为 `FAILED` 时返回。
example: InvalidImageResolution
message:
type: string
description: 任务执行失败的详细信息。仅在 `task_status` 为 `FAILED` 时返回。
example: The input image resolution is too large or small
task_metrics:
type: object
description: 任务信息统计指标。
properties:
TOTAL:
type: integer
description: 总的任务数。
example: 2
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
example: 2
FAILED:
type: integer
description: 任务状态为失败的任务数。
example: 0
usage:
type: object
description: 输出信息统计。仅在任务成功时返回。
properties:
image_count:
type: integer
description: 模型生成图像的数量。
example: 2
DashScopeErrorResponse:
type: object
description: DashScope API错误响应。
properties:
request_id:
type: string
description: 请求唯一标识。
example: fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1
code:
type: string
description: 接口错误码。接口成功请求不会返回该参数。
example: InvalidParameter
message:
type: string
description: 接口错误信息。接口成功请求不会返回该参数。
example: The request is missing required parameters or in a wrong format, please check the parameters that you send.
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan-text-to-image-v2-create-task.md
+940
View File
@@ -0,0 +1,940 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan v2 — 创建任务
> Wan 异步图像生成
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
## 支持的模型
Wan 文生图系列各版本使用不同的端点和请求格式：
| 模型 | 端点 | 输入格式 | 分辨率 | 最大提示词长度 |
| -------------------- | -------------------------------------------- | ------------- | ------------------------------------ | -------- |
| `wan2.6-t2i` | `/services/aigc/image-generation/generation` | `messages` 数组 | 1280\*1280 到 1440\*1440，比例 1:4 到 4:1 | 2,100 字符 |
| `wan2.5-t2i-preview` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 1280\*1280 到 1440\*1440，比例 1:4 到 4:1 | 2,000 字符 |
| `wan2.2-t2i-plus` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 每边 512–1440，最大 1440\*1440 | 500 字符 |
| `wan2.2-t2i-flash` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 每边 512–1440，最大 1440\*1440 | 500 字符 |
| `wan2.1-t2i-plus` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 每边 512–1440，最大 1440\*1440 | 500 字符 |
| `wan2.1-t2i-turbo` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 每边 512–1440，最大 1440\*1440 | 500 字符 |
| `wanx2.0-t2i-turbo` | `/services/aigc/text2image/image-synthesis` | `prompt` 字符串 | 每边 512–1440，最大 1440\*1440 | 800 字符 |
<Note>
**wan2.6-t2i** 还支持[同步端点](/api-reference/image-generation/wan-text-to-image-v2/synchronous)（单次请求，即时响应）。
</Note>
## SDK 版本要求
- **wan2.6-t2i**：DashScope Python SDK **1.25.7+**，Java SDK **2.22.6+**
- **wan2.5 及更早版本**：DashScope Python SDK **1.25.2+**，Java SDK **2.22.2+**
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.1.0
info:
title: Wan 文生图 V2 API
description: 使用 Wan 文生图模型系列，根据文本描述生成图像。支持多种艺术风格和写实摄影效果，满足多样化的创意需求。本 API 采用异步任务模式：先通过 POST 请求提交任务，再通过 GET 请求轮询结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 阿里云 DashScope
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createWanTextToImage
summary: 创建文生图任务
description: 创建一个文生图生成任务。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 必须设置为 `enable` 以创建异步任务。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Wan26TextToImageRequest"
- $ref: "#/components/schemas/WanLegacyTextToImageRequest"
responses:
"200":
description: 任务创建成功。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - wan2.6-t2i (async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.6-t2i",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
}
]
}
]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"negative_prompt": "",
"size": "1280*1280"
}
}'
- lang: curl
label: cURL - wan2.5-t2i-preview (async, legacy endpoint)
source: |-
# 注意：wan2.5 及更早版本的模型使用不同的端点路径：
# POST /services/aigc/text2image/image-synthesis
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wan2.5-t2i-preview",
"input": {
"prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
},
"parameters": {
"size": "1280*1280",
"n": 1
}
}'
- lang: curl
label: cURL - wan2.2-t2i-flash with negative prompt (async, legacy endpoint)
source: |-
# 注意：wan2.2 及更早版本的模型使用不同的端点路径：
# POST /services/aigc/text2image/image-synthesis
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wan2.2-t2i-flash",
"input": {
"prompt": "Snowy ground, a small white chapel, aurora borealis, winter scene, soft light.",
"negative_prompt": "person"
},
"parameters": {
"size": "1024*1024",
"n": 1
}
}'
- lang: python
label: Python - wan2.6-t2i (async, DashScope SDK)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Role, Message
from http import HTTPStatus
# wan2.6-t2i 需要 SDK 版本 1.25.7 或更高版本
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
# 创建异步任务
def create_async_task():
print("Creating async task...")
message = Message(
role="user",
content=[{'text': 'A flower shop with exquisite windows, a beautiful wooden door, and flowers on display'}]
)
response = ImageGeneration.async_call(
model="wan2.6-t2i",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
if response.status_code == 200:
print("Task created successfully:", response)
return response
else:
raise Exception(f"Failed to create task: {response.code} - {response.message}")
# 等待任务完成
def wait_for_completion(task_response):
print("Waiting for task completion...")
status = ImageGeneration.wait(task=task_response, api_key=api_key)
if status.output.task_status == "SUCCEEDED":
print("Task succeeded!")
print("Response:", status)
else:
raise Exception(f"Task failed with status: {status.output.task_status}")
# 获取异步任务信息
def fetch_task_status(task):
print("Fetching task status...")
status = ImageGeneration.fetch(task=task, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print("Task status:", status.output.task_status)
print("Response details:", status)
else:
print(f"Failed to fetch status: {status.code} - {status.message}")
# 取消异步任务
def cancel_task(task):
print("Canceling task...")
response = ImageGeneration.cancel(task=task, api_key=api_key)
if response.status_code == HTTPStatus.OK:
print("Task canceled successfully:", response.output.task_status)
else:
print(f"Failed to cancel task: {response.code} - {response.message}")
# 主执行流程
if __name__ == "__main__":
task = create_async_task()
wait_for_completion(task)
- lang: python
label: Python - wan2.5 and earlier (sync, DashScope SDK)
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# wan2.5 及更早版本的模型需要 SDK 版本 1.25.2 或更高版本
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=api_key,
model="wan2.5-t2i-preview",
prompt="A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
# 将图像保存到当前目录
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: python
label: Python - wan2.5 and earlier (async, DashScope SDK)
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# wan2.5 及更早版本的模型需要 SDK 版本 1.25.2 或更高版本
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
# 创建异步任务
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="wan2.5-t2i-preview",
prompt="A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# 等待异步任务完成
def wait_async_task(task):
rsp = ImageSynthesis.wait(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
# 将文件保存到当前目录
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
# 获取异步任务信息
def fetch_task_status(task):
status = ImageSynthesis.fetch(task=task, api_key=api_key)
print(status)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
# 取消异步任务。只有处于 PENDING 状态的任务才能被取消。
def cancel_task(task):
rsp = ImageSynthesis.cancel(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: java
label: Java - wan2.6-t2i (async, DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
// wan2.6-t2i 需要 SDK 版本 2.22.6 或更高版本
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---async call, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
// 等待任务完成
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - wan2.5 and earlier (sync, DashScope SDK)
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// wan2.5 及更早版本的模型需要 SDK 版本 2.22.2 或更高版本。
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException {
// 设置参数
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
.n(1)
.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args){
try{
basicCall();
}catch(ApiException|NoApiKeyException e){
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - wan2.5 and earlier (async, DashScope SDK)
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// wan2.5 及更早版本的模型需要 SDK 版本 2.22.2 或更高版本。
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* 创建异步任务
* @return taskId
*/
public String createAsyncTask() {
// 设置参数
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
.n(1)
.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* 等待异步任务完成
* @param taskId 任务 ID
*/
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.wait(taskId, apiKey);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void main(String[] args){
Main main = new Main();
main.asyncCall();
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26TextToImageRequest:
type: object
description: wan2.6-t2i 模型的请求体，`input` 对象中使用 `messages` 格式。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。wan2.6-t2i 模型请填写 `wan2.6-t2i`。
enum:
- wan2.6-t2i
example: wan2.6-t2i
input:
type: object
description: 包含消息数组的输入对象。
required:
- messages
properties:
messages:
type: array
description: 请求内容数组，仅支持单轮对话（一组 role 和 content）。
items:
type: object
required:
- role
- content
properties:
role:
type: string
description: 消息角色，必须为 `user`。
enum:
- user
content:
type: array
description: 消息内容数组。
items:
type: object
required:
- text
properties:
text:
type: string
description: 正向提示词，描述生成图像的内容、风格和构图。支持中英文，最多 2,100 个字符。每次请求只允许一个 text。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
parameters:
$ref: "#/components/schemas/Wan26Parameters"
WanLegacyTextToImageRequest:
type: object
description: wan2.5 及更早版本模型的请求体，`input` 对象中使用 `prompt` 格式。**注意**：这些模型使用端点 `POST /services/aigc/text2image/image-synthesis`，而非主端点。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。支持以下模型：`wan2.5-t2i-preview`、`wan2.2-t2i-plus`、`wan2.2-t2i-flash`、`wanx2.1-t2i-plus`、`wanx2.1-t2i-turbo`。
enum:
- wan2.5-t2i-preview
- wan2.2-t2i-plus
- wan2.2-t2i-flash
- wanx2.1-t2i-plus
- wanx2.1-t2i-turbo
example: wan2.5-t2i-preview
input:
type: object
description: 包含提示词字符串的输入对象。
required:
- prompt
properties:
prompt:
type: string
description: 正向提示词，描述期望的图像内容。支持中英文。各模型最大长度不同：wan2.5-t2i-preview（2,000 字符）、wan2.2、wan2.1 系列（500 字符）。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容。最多 500 字符，支持中英文。
example: low resolution, low quality, deformed limbs
parameters:
$ref: "#/components/schemas/WanLegacyParameters"
Wan26Parameters:
type: object
description: wan2.6-t2i 模型的参数。
properties:
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容，最多 500 字符，支持中英文。示例：低分辨率、低质量、肢体变形、手指变形、过度饱和、蜡质感、无面部细节、过度平滑、AI 感、构图混乱、文字模糊、文字扭曲。
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。默认值：`1280*1280`。总像素数须在 1280*1280 至 1440*1440 之间，宽高比须在 1:4 至 4:1 之间。推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
WanLegacyParameters:
type: object
description: wan2.5 及更早版本模型的参数。
properties:
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。wan2.5-t2i-preview 默认为 `1280*1280`（总像素 1280*1280 至 1440*1440，宽高比 1:4 至 4:1）。wan2.2 及更早版本默认为 `1024*1024`（边长 512 至 1440，最大 1440*1440）。wan2.5 推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
Wan26SyncResponse:
type: object
description: wan2.6-t2i 模型的同步响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-463f.oss-accelerate.aliyuncs.com/xxxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1280*1280
total_tokens: 0
request_id: 815505c6-7c3d-49d7-b197-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 包含生成图像 URL 的响应内容数组。
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
type:
type: string
description: 内容类型，始终为 `image`。
enum:
- image
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计信息。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 输入 token 数量，当前固定为 0。
output_tokens:
type: integer
description: 输出 token 数量，当前固定为 0。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的 token 总量，当前固定为 0。
request_id:
type: string
description: 唯一请求标识符，用于追踪和问题排查。
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。可通过 `GET /tasks/{task_id}` 查询任务状态，有效期 24 小时。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
TaskStatusResponse:
type: object
description: 查询任务状态时返回的响应，输出格式取决于所用模型。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
choices:
type: array
description: 输出内容（wan2.6-t2i 格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
finish_reason:
type: string
description: 任务停止原因，`stop` 表示正常完成。
message:
type: object
properties:
role:
type: string
description: 角色，始终为 `assistant`。
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL，有效期 24 小时。
type:
type: string
description: 内容类型，始终为 `image`。
results:
type: array
description: 输出内容（wan2.5 及更早版本格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL，有效期 24 小时。
orig_prompt:
type: string
description: 原始输入提示词。
actual_prompt:
type: string
description: 生成时实际使用的优化后提示词（仅在开启提示词扩写时返回）。
code:
type: string
description: 错误码（仅当单张图像生成失败时返回）。
message:
type: string
description: 错误信息（仅当单张图像生成失败时返回）。
finished:
type: boolean
description: 任务是否已完成（wan2.6 格式）。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务完成时间。
task_metrics:
type: object
description: 任务结果统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅当任务失败时返回）。
message:
type: string
description: 错误信息（仅当任务失败时返回）。
usage:
type: object
description: 用量统计信息，仅统计成功结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
size:
type: string
description: 生成图像的分辨率。
input_tokens:
type: integer
description: 输入 token 数量（wan2.6 格式）。
output_tokens:
type: integer
description: 输出 token 数量（wan2.6 格式）。
total_tokens:
type: integer
description: Token 总量（wan2.6 格式）。
DashScopeErrorResponse:
type: object
description: 请求失败时返回的错误响应。
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 详细错误信息。
request_id:
type: string
description: 唯一请求 ID，用于问题排查。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan-text-to-image-v2-query-result.md
+536
View File
@@ -0,0 +1,536 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan v2 — 查询结果
> 查询 Wan 图像生成任务状态
查询任务状态并获取生成的图像。
## 轮询策略
1. 通过[生成图像](/api-reference/image-generation/wan-text-to-image-v2/create-task)接口提交任务，获取 `task_id`。
2. 每 **5 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED`、`FAILED` 或 `CANCELLED`。
3. 任务成功后，从响应中获取图像。
## 响应格式差异
不同模型的响应格式有所不同：
- **wan2.6-t2i**：结果采用 chat completion 格式：`output.choices[].message.content[].image`。
- **wan2.5 及更早版本**：结果采用 `output.results[].url` 格式，包含 `orig_prompt` 和 `actual_prompt` 字段。
## 注意事项
- **URL 有效期**：生成的图像 URL 有效期为 **24 小时**，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED`、`FAILED` 或 `CANCELLED`。
- **任务 ID 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交创建任务请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan 文生图 V2 API
description: 使用 Wan 文生图模型系列，根据文本描述生成图像。支持多种艺术风格和写实摄影效果，满足多样化的创意需求。本 API 采用异步任务模式：先通过 POST 请求提交任务，再通过 GET 请求轮询结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 阿里云 DashScope
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWanTextToImageTaskStatus
summary: 查询任务结果
description: 查询异步任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 文生图创建端点返回的任务标识符。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED (wan2.6):
summary: 任务成功（wan2.6-t2i 格式）
value:
request_id: 815505c6-7c3d-49d7-b197-xxxxxx
output:
task_id: f470bbfd-d955-4165-935b-d35b8exxxxxx
task_status: SUCCEEDED
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-463f.oss-accelerate.aliyuncs.com/xxxxxx.png?Expires=xxxxxx
type: image
finished: true
submit_time: 2026-01-09 17:18:17.901
scheduled_time: 2026-01-09 17:18:17.941
end_time: 2026-01-09 17:18:45.544
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1280*1280
total_tokens: 0
SUCCEEDED (wan2.5 and earlier):
summary: 任务成功（wan2.5 及更早版本格式）
value:
request_id: 9d634fda-5fe9-9968-a908-xxxxxx
output:
task_id: d35658e4-483f-453b-b8dc-xxxxxx
task_status: SUCCEEDED
results:
- url: https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png
orig_prompt: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
actual_prompt: An exquisite flower shop, with windows decorated with elegant carvings and a beautiful wooden door with a brass handle. Inside, various colorful flowers such as roses, tulips, and lilies are on display.
submit_time: 2025-01-08 19:36:01.521
scheduled_time: 2025-01-08 19:36:01.542
end_time: 2025-01-08 19:36:13.270
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: FAILED
code: InvalidParameter
message: The specified parameter is not valid.
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 1
RUNNING:
summary: 任务运行中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
PENDING:
summary: 任务等待中
value:
request_id: c4f11410-ea42-4996-957d-9c82f9xxxxxx
output:
task_id: f470bbfd-d955-4165-935b-d35b8eexxxxxx
task_status: PENDING
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Query task result
source: |-
# 将 {task_id} 替换为提交响应中的实际任务 ID
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26TextToImageRequest:
type: object
description: wan2.6-t2i 模型的请求体，`input` 对象中使用 `messages` 格式。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。wan2.6-t2i 模型请填写 `wan2.6-t2i`。
enum:
- wan2.6-t2i
example: wan2.6-t2i
input:
type: object
description: 包含消息数组的输入对象。
required:
- messages
properties:
messages:
type: array
description: 请求内容数组，仅支持单轮对话（一组 role 和 content）。
items:
type: object
required:
- role
- content
properties:
role:
type: string
description: 消息角色，必须为 `user`。
enum:
- user
content:
type: array
description: 消息内容数组。
items:
type: object
required:
- text
properties:
text:
type: string
description: 正向提示词，描述生成图像的内容、风格和构图。支持中英文，最多 2,100 个字符。每次请求只允许一个 text。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
parameters:
$ref: "#/components/schemas/Wan26Parameters"
WanLegacyTextToImageRequest:
type: object
description: wan2.5 及更早版本模型的请求体，`input` 对象中使用 `prompt` 格式。**注意**：这些模型使用端点 `POST /services/aigc/text2image/image-synthesis`，而非主端点。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。支持以下模型：`wan2.5-t2i-preview`、`wan2.2-t2i-plus`、`wan2.2-t2i-flash`、`wanx2.1-t2i-plus`、`wanx2.1-t2i-turbo`。
enum:
- wan2.5-t2i-preview
- wan2.2-t2i-plus
- wan2.2-t2i-flash
- wanx2.1-t2i-plus
- wanx2.1-t2i-turbo
example: wan2.5-t2i-preview
input:
type: object
description: 包含提示词字符串的输入对象。
required:
- prompt
properties:
prompt:
type: string
description: 正向提示词，描述期望的图像内容。支持中英文。各模型最大长度不同：wan2.5-t2i-preview（2,000 字符）、wan2.2、wan2.1 系列（500 字符）。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容。最多 500 字符，支持中英文。
example: low resolution, low quality, deformed limbs
parameters:
$ref: "#/components/schemas/WanLegacyParameters"
Wan26Parameters:
type: object
description: wan2.6-t2i 模型的参数。
properties:
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容，最多 500 字符，支持中英文。示例：低分辨率、低质量、肢体变形、手指变形、过度饱和、蜡质感、无面部细节、过度平滑、AI 感、构图混乱、文字模糊、文字扭曲。
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。默认值：`1280*1280`。总像素数须在 1280*1280 至 1440*1440 之间，宽高比须在 1:4 至 4:1 之间。推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
WanLegacyParameters:
type: object
description: wan2.5 及更早版本模型的参数。
properties:
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。wan2.5-t2i-preview 默认为 `1280*1280`（总像素 1280*1280 至 1440*1440，宽高比 1:4 至 4:1）。wan2.2 及更早版本默认为 `1024*1024`（边长 512 至 1440，最大 1440*1440）。wan2.5 推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
Wan26SyncResponse:
type: object
description: wan2.6-t2i 模型的同步响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-463f.oss-accelerate.aliyuncs.com/xxxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1280*1280
total_tokens: 0
request_id: 815505c6-7c3d-49d7-b197-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 包含生成图像 URL 的响应内容数组。
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
type:
type: string
description: 内容类型，始终为 `image`。
enum:
- image
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计信息。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 输入 token 数量，当前固定为 0。
output_tokens:
type: integer
description: 输出 token 数量，当前固定为 0。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的 token 总量，当前固定为 0。
request_id:
type: string
description: 唯一请求标识符，用于追踪和问题排查。
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。可通过 `GET /tasks/{task_id}` 查询任务状态，有效期 24 小时。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
TaskStatusResponse:
type: object
description: 查询任务状态时返回的响应，输出格式取决于所用模型。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
choices:
type: array
description: 输出内容（wan2.6-t2i 格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
finish_reason:
type: string
description: 任务停止原因，`stop` 表示正常完成。
message:
type: object
properties:
role:
type: string
description: 角色，始终为 `assistant`。
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL，有效期 24 小时。
type:
type: string
description: 内容类型，始终为 `image`。
results:
type: array
description: 输出内容（wan2.5 及更早版本格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL，有效期 24 小时。
orig_prompt:
type: string
description: 原始输入提示词。
actual_prompt:
type: string
description: 生成时实际使用的优化后提示词（仅在开启提示词扩写时返回）。
code:
type: string
description: 错误码（仅当单张图像生成失败时返回）。
message:
type: string
description: 错误信息（仅当单张图像生成失败时返回）。
finished:
type: boolean
description: 任务是否已完成（wan2.6 格式）。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务完成时间。
task_metrics:
type: object
description: 任务结果统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅当任务失败时返回）。
message:
type: string
description: 错误信息（仅当任务失败时返回）。
usage:
type: object
description: 用量统计信息，仅统计成功结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
size:
type: string
description: 生成图像的分辨率。
input_tokens:
type: integer
description: 输入 token 数量（wan2.6 格式）。
output_tokens:
type: integer
description: 输出 token 数量（wan2.6 格式）。
total_tokens:
type: integer
description: Token 总量（wan2.6 格式）。
DashScopeErrorResponse:
type: object
description: 请求失败时返回的错误响应。
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 详细错误信息。
request_id:
type: string
description: 唯一请求 ID，用于问题排查。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan-text-to-image-v2-synchronous.md
+561
View File
@@ -0,0 +1,561 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan v2 — 同步调用
> Wan 文生图同步接口
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[将其设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
该同步接口仅适用于 **wan2.6-t2i** 模型，可在单次请求中直接返回生成的图像，无需轮询。
wan2.5 及更早版本，或需要异步处理时，请使用[异步提交](/api-reference/image-generation/wan-text-to-image-v2/create-task)接口。
## SDK 版本要求
- **DashScope Python SDK**：需 **1.25.7** 或更高版本。
- **DashScope Java SDK**：需 **2.22.6** 或更高版本。
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Wan 文生图 V2 API
description: 使用 Wan 文生图模型系列，根据文本描述生成图像。支持多种艺术风格和写实摄影效果，满足多样化的创意需求。本 API 采用异步任务模式：先通过 POST 请求提交任务，再通过 GET 请求轮询结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 阿里云 DashScope
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createWanT2ISyncGeneration
summary: 同步生成图像
description: 使用 Wan2.6 模型同步生成图像。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26TextToImageRequest"
responses:
"200":
description: 图像生成成功。
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26SyncResponse"
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - wan2.6-t2i (sync)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.6-t2i",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
}
]
}
]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"negative_prompt": "",
"size": "1280*1280"
}
}'
- lang: python
label: Python - wan2.6-t2i (sync, DashScope SDK)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# wan2.6-t2i 需要 SDK 版本 1.25.7 或更高版本
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
message = Message(
role="user",
content=[
{
'text': 'A flower shop with exquisite windows, a beautiful wooden door, and flowers on display'
}
]
)
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
model="wan2.6-t2i",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
print(rsp)
- lang: java
label: Java - wan2.6-t2i (sync, DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
// wan2.6-t2i 需要 SDK 版本 2.22.6 或更高版本
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26TextToImageRequest:
type: object
description: wan2.6-t2i 模型的请求体，`input` 对象中使用 `messages` 格式。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。wan2.6-t2i 模型请填写 `wan2.6-t2i`。
enum:
- wan2.6-t2i
example: wan2.6-t2i
input:
type: object
description: 包含消息数组的输入对象。
required:
- messages
properties:
messages:
type: array
description: 请求内容数组，仅支持单轮对话（一组 role 和 content）。
items:
type: object
required:
- role
- content
properties:
role:
type: string
description: 消息角色，必须为 `user`。
enum:
- user
content:
type: array
description: 消息内容数组。
items:
type: object
required:
- text
properties:
text:
type: string
description: 正向提示词，描述生成图像的内容、风格和构图。支持中英文，最多 2,100 个字符。每次请求只允许一个 text。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
parameters:
$ref: "#/components/schemas/Wan26Parameters"
WanLegacyTextToImageRequest:
type: object
description: wan2.5 及更早版本模型的请求体，`input` 对象中使用 `prompt` 格式。**注意**：这些模型使用端点 `POST /services/aigc/text2image/image-synthesis`，而非主端点。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。支持以下模型：`wan2.5-t2i-preview`、`wan2.2-t2i-plus`、`wan2.2-t2i-flash`、`wanx2.1-t2i-plus`、`wanx2.1-t2i-turbo`。
enum:
- wan2.5-t2i-preview
- wan2.2-t2i-plus
- wan2.2-t2i-flash
- wanx2.1-t2i-plus
- wanx2.1-t2i-turbo
example: wan2.5-t2i-preview
input:
type: object
description: 包含提示词字符串的输入对象。
required:
- prompt
properties:
prompt:
type: string
description: 正向提示词，描述期望的图像内容。支持中英文。各模型最大长度不同：wan2.5-t2i-preview（2,000 字符）、wan2.2、wan2.1 系列（500 字符）。
example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容。最多 500 字符，支持中英文。
example: low resolution, low quality, deformed limbs
parameters:
$ref: "#/components/schemas/WanLegacyParameters"
Wan26Parameters:
type: object
description: wan2.6-t2i 模型的参数。
properties:
negative_prompt:
type: string
description: 可选。描述不希望出现在图像中的内容，最多 500 字符，支持中英文。示例：低分辨率、低质量、肢体变形、手指变形、过度饱和、蜡质感、无面部细节、过度平滑、AI 感、构图混乱、文字模糊、文字扭曲。
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。默认值：`1280*1280`。总像素数须在 1280*1280 至 1440*1440 之间，宽高比须在 1:4 至 4:1 之间。推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
WanLegacyParameters:
type: object
description: wan2.5 及更早版本模型的参数。
properties:
size:
type: string
description: 输出图像的分辨率，格式为 `宽*高`。wan2.5-t2i-preview 默认为 `1280*1280`（总像素 1280*1280 至 1440*1440，宽高比 1:4 至 4:1）。wan2.2 及更早版本默认为 `1024*1024`（边长 512 至 1440，最大 1440*1440）。wan2.5 推荐分辨率：1:1（1280*1280）、3:4（1104*1472）、4:3（1472*1104）、9:16（960*1696）、16:9（1696*960）。
example: 1280*1280
n:
type: integer
description: 生成图像的数量，取值范围 1 至 4，默认值 `4`。注意：按图计费（费用 = 单价 × 图像数量），测试时建议设为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: |-
是否开启提示词扩写。开启后，系统将使用大模型优化正向提示词，对较短提示词效果提升明显，但会增加几秒处理时间。默认值：`true`。
注意：开启智能改写后，改写生成的提示词可能引入受版权保护的内容，从而触发内容审核，返回 `IPInfringementSuspect` 或 `DataInspectionFailed` 报错。遇到上述报错时，可将 `prompt_extend` 设置为 `false` 后重试。若提示词本身直接包含受版权保护的角色名或作品名，关闭智能改写仍会报错，需修改提示词本身。
default: true
watermark:
type: boolean
description: 是否在图像右下角添加 "AI 生成" 水印。默认值：`false`。
default: false
seed:
type: integer
description: 可选。随机数种子，取值范围 [0, 2147483647]。相同种子可获得更一致的结果，但不保证完全相同。不填时系统随机生成。
minimum: 0
maximum: 2147483647
Wan26SyncResponse:
type: object
description: wan2.6-t2i 模型的同步响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-463f.oss-accelerate.aliyuncs.com/xxxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1280*1280
total_tokens: 0
request_id: 815505c6-7c3d-49d7-b197-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成。"
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 包含生成图像 URL 的响应内容数组。
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
type:
type: string
description: 内容类型，始终为 `image`。
enum:
- image
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计信息。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 输入 token 数量，当前固定为 0。
output_tokens:
type: integer
description: 输出 token 数量，当前固定为 0。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的 token 总量，当前固定为 0。
request_id:
type: string
description: 唯一请求标识符，用于追踪和问题排查。
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。可通过 `GET /tasks/{task_id}` 查询任务状态，有效期 24 小时。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
TaskStatusResponse:
type: object
description: 查询任务状态时返回的响应，输出格式取决于所用模型。
properties:
request_id:
type: string
description: 唯一请求标识符，用于问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
choices:
type: array
description: 输出内容（wan2.6-t2i 格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
finish_reason:
type: string
description: 任务停止原因，`stop` 表示正常完成。
message:
type: object
properties:
role:
type: string
description: 角色，始终为 `assistant`。
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL，有效期 24 小时。
type:
type: string
description: 内容类型，始终为 `image`。
results:
type: array
description: 输出内容（wan2.5 及更早版本格式），当 task_status 为 SUCCEEDED 时返回。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL，有效期 24 小时。
orig_prompt:
type: string
description: 原始输入提示词。
actual_prompt:
type: string
description: 生成时实际使用的优化后提示词（仅在开启提示词扩写时返回）。
code:
type: string
description: 错误码（仅当单张图像生成失败时返回）。
message:
type: string
description: 错误信息（仅当单张图像生成失败时返回）。
finished:
type: boolean
description: 任务是否已完成（wan2.6 格式）。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务完成时间。
task_metrics:
type: object
description: 任务结果统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅当任务失败时返回）。
message:
type: string
description: 错误信息（仅当任务失败时返回）。
usage:
type: object
description: 用量统计信息，仅统计成功结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
size:
type: string
description: 生成图像的分辨率。
input_tokens:
type: integer
description: 输入 token 数量（wan2.6 格式）。
output_tokens:
type: integer
description: 输出 token 数量（wan2.6 格式）。
total_tokens:
type: integer
description: Token 总量（wan2.6 格式）。
DashScopeErrorResponse:
type: object
description: 请求失败时返回的错误响应。
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 详细错误信息。
request_id:
type: string
description: 唯一请求 ID，用于问题排查。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan21-general-image-editing-create-task.md
+788
View File
@@ -0,0 +1,788 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.1 — 创建任务
> 异步 Wan 2.1 通用图像编辑
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
支持 10 种图像编辑功能：
| 功能 | `function` 值 | 说明 |
| ------ | ---------------------------- | ---------- |
| 整图风格化 | `stylization_all` | 整体风格迁移 |
| 局部风格化 | `stylization_local` | 局部风格迁移 |
| 指令编辑 | `description_edit` | 根据文字描述编辑图像 |
| 蒙版编辑 | `description_edit_with_mask` | 结合蒙版的精准编辑 |
| 去水印 | `remove_watermark` | 去除图片水印 |
| 扩图 | `expand` | 向四个方向扩展画布 |
| 超分辨率 | `super_resolution` | 提高图像分辨率 |
| 上色 | `colorization` | 为黑白图片上色 |
| 涂鸦成图 | `doodle` | 基于涂鸦生成图像 |
| 卡通特征控制 | `control_cartoon_feature` | 保持人物特征的卡通化 |
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: Wan2.1 通用图像编辑 API
description: Wan 2.1 通用图像编辑 API。支持 10 种编辑功能：整图风格化、局部风格化、指令编辑、蒙版编辑、去水印、扩图、超分辨率、上色、涂鸦成图、卡通特征控制。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createWan21ImageEdit
summary: 创建图像编辑任务
description: 使用 Wan 2.1 创建图像编辑任务。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 启用异步处理，必须设置为 `enable`。HTTP 请求仅支持异步调用，省略此 Header 会返回错误。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan21ImageEditRequest"
responses:
"200":
description: 任务提交成功。使用 `task_id` 轮询结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: Invalid request parameters.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败，API Key 无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: Invalid API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: 整图风格化 stylization_all
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "stylization_all",
"prompt": "转换成法国绘本风格",
"base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: Base64 编码输入
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "stylization_all",
"prompt": "转换成法国绘本风格",
"base_image_url": "data:image/jpeg;base64,/9j/4AAQSkZJR......"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 局部风格化 stylization_local
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "stylization_local",
"prompt": "把房子变成木板风格。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 指令编辑 description_edit
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "description_edit",
"prompt": "把她的头发修改为红色。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_2.png"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 蒙版编辑 description_edit_with_mask
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "description_edit_with_mask",
"prompt": "陶瓷兔子拿着陶瓷小花。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg",
"mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 去水印 remove_watermark
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "remove_watermark",
"prompt": "去除图像中的文字",
"base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 扩图 expand
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "expand",
"prompt": "一位绿色仙子",
"base_image_url": "http://wanx.alicdn.com/material/20250318/expand_2.jpg"
},
"parameters": {
"top_scale": 1.5,
"bottom_scale": 1.5,
"left_scale": 1.5,
"right_scale": 1.5,
"n": 1
}
}'
- lang: curl
label: 超分辨率 super_resolution
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "super_resolution",
"prompt": "图像超分。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"
},
"parameters": {
"upscale_factor": 2,
"n": 1
}
}'
- lang: curl
label: 上色 colorization
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "colorization",
"prompt": "蓝色背景，黄色的叶子。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 涂鸦成图 doodle
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "doodle",
"prompt": "北欧极简风格的客厅。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_1.png"
},
"parameters": {
"n": 1
}
}'
- lang: curl
label: 卡通特征控制 control_cartoon_feature
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx2.1-imageedit",
"input": {
"function": "control_cartoon_feature",
"prompt": "卡通形象小心翼翼地探出头，窥视着房间内一颗璀璨的蓝色宝石。",
"base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
},
"parameters": {
"n": 1
}
}'
- lang: python
label: Python SDK（同步）
source: |-
import base64
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
import mimetypes
api_key = os.getenv("DASHSCOPE_API_KEY")
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("不支持或无法识别的图像格式")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
return f"data:{mime_type};base64,{encoded_string}"
# 【方式一】使用公网图片 URL
mask_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
base_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg"
# 【方式二】使用本地文件
# mask_image_url = "file://" + "/path/to/your/mask_image.png"
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"
# 【方式三】使用Base64编码的图片
# mask_image_url = encode_file("./mask_image.png")
# base_image_url = encode_file("./base_image.jpeg")
def sample_sync_call_imageedit():
print('please wait...')
rsp = ImageSynthesis.call(api_key=api_key,
model="wanx2.1-imageedit",
function="description_edit_with_mask",
prompt="陶瓷兔子拿着陶瓷小花",
mask_image_url=mask_image_url,
base_image_url=base_image_url,
n=1)
assert rsp.status_code == HTTPStatus.OK
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
for result in rsp.output.results:
print("---------------------------")
print(result.url)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_sync_call_imageedit()
- lang: python
label: Python SDK（异步）
source: |-
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
api_key = os.getenv("DASHSCOPE_API_KEY")
mask_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
base_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg"
def sample_async_call_imageedit():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="wanx2.1-imageedit",
function="description_edit_with_mask",
prompt="陶瓷兔子拿着陶瓷小花",
mask_image_url=mask_image_url,
base_image_url=base_image_url,
n=1)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print("task_id: %s" % rsp.output.task_id)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
status = ImageSynthesis.fetch(task=rsp, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
rsp = ImageSynthesis.wait(rsp)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
for result in rsp.output.results:
print("---------------------------")
print(result.url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_async_call_imageedit()
- lang: java
label: Java SDK（同步）
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
public class ImageEditSync {
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
static String maskImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png";
static String baseImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg";
public static void syncCall() {
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wanx2.1-imageedit")
.function(ImageSynthesis.ImageEditFunction.DESCRIPTION_EDIT_WITH_MASK)
.prompt("陶瓷兔子拿着陶瓷小花")
.maskImageUrl(maskImageUrl)
.baseImageUrl(baseImageUrl)
.n(1)
.size("1024*1024")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) { throw new IllegalArgumentException("文件不存在: " + filePath); }
String mimeType = null;
try { mimeType = Files.probeContentType(path); } catch (IOException e) { throw new IllegalArgumentException("无法检测文件类型: " + filePath); }
if (mimeType == null || !mimeType.startsWith("image/")) { throw new IllegalArgumentException("不支持或无法识别的图像格式"); }
byte[] fileBytes = null;
try { fileBytes = Files.readAllBytes(path); } catch (IOException e) { throw new IllegalArgumentException("无法读取文件内容: " + filePath); }
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
public static void main(String[] args) { syncCall(); }
}
- lang: java
label: Java SDK（异步）
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class ImageEditAsync {
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
static String maskImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png";
static String baseImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg";
public static void asyncCall() {
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wanx2.1-imageedit")
.function(ImageSynthesis.ImageEditFunction.DESCRIPTION_EDIT_WITH_MASK)
.prompt("陶瓷兔子拿着陶瓷小花")
.maskImageUrl(maskImageUrl)
.baseImageUrl(baseImageUrl)
.n(1)
.size("1024*1024")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---async call, please wait a moment----");
result = imageSynthesis.asyncCall(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
try {
result = imageSynthesis.wait(taskId, apiKey);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void listTask() throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
param.setApiKey(apiKey);
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public void fetchTask(String taskId) throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
ImageSynthesisResult result = is.fetch(taskId, apiKey);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args) { asyncCall(); }
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan21ImageEditRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- wanx2.1-imageedit
example: wanx2.1-imageedit
input:
$ref: "#/components/schemas/Wan21ImageEditInput"
parameters:
$ref: "#/components/schemas/Wan21ImageEditParameters"
Wan21ImageEditInput:
type: object
required:
- function
- prompt
- base_image_url
description: 图像编辑的输入数据。
properties:
function:
type: string
description: |-
编辑功能类型。
| 值 | 功能 |
|---|---|
| `stylization_all` | 整图风格化 |
| `stylization_local` | 局部风格化 |
| `description_edit` | 指令编辑 |
| `description_edit_with_mask` | 蒙版编辑（需要 `mask_image_url`） |
| `remove_watermark` | 去水印 |
| `expand` | 扩图 |
| `super_resolution` | 超分辨率 |
| `colorization` | 上色 |
| `doodle` | 涂鸦成图 |
| `control_cartoon_feature` | 卡通特征控制 |
enum:
- stylization_all
- stylization_local
- description_edit
- description_edit_with_mask
- remove_watermark
- expand
- super_resolution
- colorization
- doodle
- control_cartoon_feature
example: description_edit_with_mask
prompt:
type: string
description: 文本提示词，描述对图像的编辑要求。支持中英文。最大长度：800 字符，超出部分将被截断。
maxLength: 800
example: 陶瓷兔子拿着陶瓷小花。
base_image_url:
type: string
description: |-
待编辑的原始图像 URL 或 Base64 编码字符串。
**图像要求：**
- 支持格式：JPG、JPEG、PNG、BMP、TIFF、WEBP
- 分辨率：宽高各需在 512~4096 像素之间
- 最大文件大小：10 MB
**支持的输入格式：**
- **公网 URL**：支持 HTTP 和 HTTPS
- **Base64 编码**：格式为 `data:{MIME_type};base64,{base64_data}`
example: http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg
mask_image_url:
type: string
description: 蒙版图像 URL 或 Base64 编码字符串。仅当 `function` 为 `description_edit_with_mask` 时需要。蒙版图像中白色区域为需要编辑的区域，黑色区域为保留区域。蒙版图像的尺寸应与原始图像一致。
example: http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png
Wan21ImageEditParameters:
type: object
description: 控制输出数量、随机种子、水印等处理选项。不同编辑功能支持不同的参数。
properties:
n:
type: integer
description: 生成图片的数量。取值范围：1~4，默认值：1。
default: 1
minimum: 1
maximum: 4
example: 1
seed:
type: integer
description: 随机种子。取值范围：[0, 2147483647]。不设置时算法自动生成。固定种子可复现结果，但由于固有随机性，相同种子不保证完全一致的结果。
minimum: 0
maximum: 2147483647
watermark:
type: boolean
description: 是否在图片右下角添加固定文字 "AI生成" 水印。默认值：false。
default: false
example: false
strength:
type: number
description: 图像修改强度。仅适用于 `stylization_all` 和 `description_edit` 功能。取值范围：0.0~1.0，默认值：0.5。值越大，生成图像与原图差异越大。
minimum: 0
maximum: 1
default: 0.5
example: 0.5
top_scale:
type: number
description: 向上扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。例如 1.5 表示向上扩展原图高度的 50%。
minimum: 1
maximum: 2
default: 1
example: 1.5
bottom_scale:
type: number
description: 向下扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
left_scale:
type: number
description: 向左扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
right_scale:
type: number
description: 向右扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
upscale_factor:
type: integer
description: 超分辨率放大倍数。仅适用于 `super_resolution` 功能。取值范围：1~4，默认值：1。
minimum: 1
maximum: 4
default: 1
example: 2
is_sketch:
type: boolean
description: 是否为线稿输入。仅适用于 `doodle` 功能。默认值：false。当为 false 时，模型会先从输入图像中提取线稿；当为 true 时，直接将输入图像作为线稿使用。
default: false
example: false
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求的唯一标识符，用于问题排查。
ImageEditTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求的唯一标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
results:
type: array
description: 生成结果数组。每个条目包含图片 URL，或失败时的错误详情。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL，有效期 24 小时。
code:
type: string
description: 单张图片生成失败的错误码。仅在部分失败时返回。
message:
type: string
description: 单张图片生成失败的错误信息。仅在部分失败时返回。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功数。
FAILED:
type: integer
description: 失败数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误详情。仅在任务失败时返回。
usage:
type: object
description: 用量统计。仅统计成功的结果。
properties:
image_count:
type: integer
description: 成功生成的图片数量。计费公式：费用 = 图片数量 x 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误详情。
request_id:
type: string
description: 请求的唯一标识符，用于问题排查。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan21-general-image-editing-query-resul.md
+371
View File
@@ -0,0 +1,371 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.1 — 查询结果
> 查询 Wan 2.1 图像编辑任务状态
查询任务状态和结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wan21-general-image-editing/create-task)接口提交请求，获取 `task_id`。
2. 每 **10 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan2.1 通用图像编辑 API
description: Wan 2.1 通用图像编辑 API。支持 10 种编辑功能：整图风格化、局部风格化、指令编辑、蒙版编辑、去水印、扩图、超分辨率、上色、涂鸦成图、卡通特征控制。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan21ImageEditTaskStatus
summary: 查询任务结果
description: 查询图像编辑任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 创建任务时返回的任务标识符。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/ImageEditTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: eeef0935-02e9-9742-bb55-xxxxxx
output:
task_id: a425c46f-dc0a-400f-879e-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-02-21 17:56:31.786
scheduled_time: 2025-02-21 17:56:31.821
end_time: 2025-02-21 17:56:42.530
results:
- url: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.png
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-xxxxxx
task_status: FAILED
code: InvalidParameter
message: xxxxxx
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 4
RUNNING:
summary: 任务运行中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 查询任务结果
source: |-
# 将 {task_id} 替换为提交任务时返回的实际任务 ID
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan21ImageEditRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- wanx2.1-imageedit
example: wanx2.1-imageedit
input:
$ref: "#/components/schemas/Wan21ImageEditInput"
parameters:
$ref: "#/components/schemas/Wan21ImageEditParameters"
Wan21ImageEditInput:
type: object
required:
- function
- prompt
- base_image_url
description: 图像编辑的输入数据。
properties:
function:
type: string
description: |-
编辑功能类型。
| 值 | 功能 |
|---|---|
| `stylization_all` | 整图风格化 |
| `stylization_local` | 局部风格化 |
| `description_edit` | 指令编辑 |
| `description_edit_with_mask` | 蒙版编辑（需要 `mask_image_url`） |
| `remove_watermark` | 去水印 |
| `expand` | 扩图 |
| `super_resolution` | 超分辨率 |
| `colorization` | 上色 |
| `doodle` | 涂鸦成图 |
| `control_cartoon_feature` | 卡通特征控制 |
enum:
- stylization_all
- stylization_local
- description_edit
- description_edit_with_mask
- remove_watermark
- expand
- super_resolution
- colorization
- doodle
- control_cartoon_feature
example: description_edit_with_mask
prompt:
type: string
description: 文本提示词，描述对图像的编辑要求。支持中英文。最大长度：800 字符，超出部分将被截断。
maxLength: 800
example: 陶瓷兔子拿着陶瓷小花。
base_image_url:
type: string
description: |-
待编辑的原始图像 URL 或 Base64 编码字符串。
**图像要求：**
- 支持格式：JPG、JPEG、PNG、BMP、TIFF、WEBP
- 分辨率：宽高各需在 512~4096 像素之间
- 最大文件大小：10 MB
**支持的输入格式：**
- **公网 URL**：支持 HTTP 和 HTTPS
- **Base64 编码**：格式为 `data:{MIME_type};base64,{base64_data}`
example: http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg
mask_image_url:
type: string
description: 蒙版图像 URL 或 Base64 编码字符串。仅当 `function` 为 `description_edit_with_mask` 时需要。蒙版图像中白色区域为需要编辑的区域，黑色区域为保留区域。蒙版图像的尺寸应与原始图像一致。
example: http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png
Wan21ImageEditParameters:
type: object
description: 控制输出数量、随机种子、水印等处理选项。不同编辑功能支持不同的参数。
properties:
n:
type: integer
description: 生成图片的数量。取值范围：1~4，默认值：1。
default: 1
minimum: 1
maximum: 4
example: 1
seed:
type: integer
description: 随机种子。取值范围：[0, 2147483647]。不设置时算法自动生成。固定种子可复现结果，但由于固有随机性，相同种子不保证完全一致的结果。
minimum: 0
maximum: 2147483647
watermark:
type: boolean
description: 是否在图片右下角添加固定文字 "AI生成" 水印。默认值：false。
default: false
example: false
strength:
type: number
description: 图像修改强度。仅适用于 `stylization_all` 和 `description_edit` 功能。取值范围：0.0~1.0，默认值：0.5。值越大，生成图像与原图差异越大。
minimum: 0
maximum: 1
default: 0.5
example: 0.5
top_scale:
type: number
description: 向上扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。例如 1.5 表示向上扩展原图高度的 50%。
minimum: 1
maximum: 2
default: 1
example: 1.5
bottom_scale:
type: number
description: 向下扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
left_scale:
type: number
description: 向左扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
right_scale:
type: number
description: 向右扩展比例。仅适用于 `expand` 功能。取值范围：1.0~2.0，默认值：1.0。
minimum: 1
maximum: 2
default: 1
example: 1.5
upscale_factor:
type: integer
description: 超分辨率放大倍数。仅适用于 `super_resolution` 功能。取值范围：1~4，默认值：1。
minimum: 1
maximum: 4
default: 1
example: 2
is_sketch:
type: boolean
description: 是否为线稿输入。仅适用于 `doodle` 功能。默认值：false。当为 false 时，模型会先从输入图像中提取线稿；当为 true 时，直接将输入图像作为线稿使用。
default: false
example: false
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求的唯一标识符，用于问题排查。
ImageEditTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求的唯一标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间。时区为 UTC+8，格式：`YYYY-MM-DD HH:mm:ss.SSS`。
results:
type: array
description: 生成结果数组。每个条目包含图片 URL，或失败时的错误详情。
items:
type: object
properties:
url:
type: string
description: 生成图像的 URL，有效期 24 小时。
code:
type: string
description: 单张图片生成失败的错误码。仅在部分失败时返回。
message:
type: string
description: 单张图片生成失败的错误信息。仅在部分失败时返回。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功数。
FAILED:
type: integer
description: 失败数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误详情。仅在任务失败时返回。
usage:
type: object
description: 用量统计。仅统计成功的结果。
properties:
image_count:
type: integer
description: 成功生成的图片数量。计费公式：费用 = 图片数量 x 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误详情。
request_id:
type: string
description: 请求的唯一标识符，用于问题排查。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan25-general-image-editing-create-task.md
+694
View File
@@ -0,0 +1,694 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.5 — 创建任务
> 异步 Wan 2.5 图像编辑
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
通过文本提示词编辑图像，同时保持主体一致性。支持多图融合，最多可使用三张参考图像。
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: Wan2.5 通用图像编辑 API
description: Wan2.5 通用图像编辑 API。通过文本提示词对图像进行编辑，保持主体一致性。支持单图编辑和多图融合，最多支持三张参考图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createWan25ImageEdit
summary: 创建图像编辑任务
description: 使用 Wan2.5 创建图像编辑任务。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 开启异步处理模式，必须设置为 `enable`。HTTP 请求仅支持异步处理。省略此请求头将返回 "current user api does not support synchronous calls" 错误。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan25ImageEditRequest"
responses:
"200":
description: 任务提交成功。使用 `task_id` 轮询任务结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: Invalid request parameters.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 鉴权失败，API Key 无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: 单图编辑
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wan2.5-i2i-preview",
"input": {
"prompt": "Change the floral dress to a vintage-style lace long dress with exquisite embroidery details on the collar and cuffs.",
"images": [
"https://img.alicdn.com/imgextra/i2/O1CN01vHOj4h28jOxUJPwY8_!!6000000007968-49-tps-1344-896.webp"
]
},
"parameters": {
"prompt_extend": true,
"n": 1
}
}'
- lang: curl
label: 多图融合
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wan2.5-i2i-preview",
"input": {
"prompt": "Place the alarm clock from Image 1 next to the vase on the dining table in Image 2.",
"images": [
"https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp",
"https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
]
},
"parameters": {
"n": 1
}
}'
- lang: python
label: Python SDK - 同步调用
source: |-
import base64
import mimetypes
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import dashscope
import requests
from dashscope import ImageSynthesis
import os
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
# --- 图像输入：使用 Base64 编码 ---
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
return f"data:{mime_type};base64,{encoded_string}"
"""
图像输入方式：
1. 使用公开 URL - 适合可公开访问的图像。
2. 使用本地文件 - 适合本地开发和测试。
3. 使用 Base64 编码 - 适合私有图像或需要加密传输的场景。
"""
# [方式一] 使用公开图像 URL
image_url_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"
image_url_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
# [方式二] 使用本地文件（支持绝对路径和相对路径）
# image_url_1 = "file://" + "/path/to/your/image_1.png" # Linux/macOS
# image_url_2 = "file://" + "C:/path/to/your/image_2.png" # Windows
# [方式三] 使用 Base64 编码图像
# image_url_1 = encode_file("./image_1.png")
# image_url_2 = encode_file("./image_2.png")
print('----同步调用，请稍候----')
rsp = ImageSynthesis.call(api_key=api_key,
model="wan2.5-i2i-preview",
prompt="Place the alarm clock from Image 1 next to the vase on the dining table in Image 2.",
images=[image_url_1, image_url_2],
negative_prompt="",
n=1,
# size="1280*1280",
prompt_extend=True,
watermark=False,
seed=12345)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('同步调用失败，status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: python
label: Python SDK - 异步调用
source: |-
import os
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import dashscope
import requests
from dashscope import ImageSynthesis
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
image_url_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"
image_url_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
def async_call():
print('----创建任务----')
task_info = create_async_task()
print('----等待任务----')
wait_async_task(task_info)
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="wan2.5-i2i-preview",
prompt="Place the alarm clock from Image 1 next to the vase on the dining table in Image 2.",
images=[image_url_1, image_url_2],
negative_prompt="",
n=1,
# size="1280*1280",
prompt_extend=True,
watermark=False,
seed=12345)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('调用失败，status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
def wait_async_task(task):
rsp = ImageSynthesis.wait(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('调用失败，status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
def fetch_task_status(task):
status = ImageSynthesis.fetch(task=task, api_key=api_key)
print(status)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('调用失败，status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
def cancel_task(task):
rsp = ImageSynthesis.cancel(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print('调用失败，status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: java
label: Java SDK - 同步调用
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.*;
// 需要 SDK 版本 >= 2.22.2
public class Image2Image {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* 图像输入方式：
* 1. 使用公开 URL - 适合可公开访问的图像。
* 2. 使用本地文件 - 适合本地开发和测试。
* 3. 使用 Base64 编码 - 适合私有图像或需要加密传输的场景。
*/
//[方式一] 公开 URL
static String imageUrl_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp";
static String imageUrl_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp";
//[方式二] 本地文件路径（file://+绝对路径 或 file:///+绝对路径）
// static String imageUrl_1 = "file://" + "/your/path/to/image_1.png";
// static String imageUrl_2 = "file:///" + "C:/your/path/to/image_2.png";
//[方式三] Base64 编码
// static String imageUrl_1 = encodeFile("/your/path/to/image_1.png");
// static String imageUrl_2 = encodeFile("/your/path/to/image_2.png");
static List<String> imageUrls = new ArrayList<>();
static {
imageUrls.add(imageUrl_1);
imageUrls.add(imageUrl_2);
}
public static void syncCall() {
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-i2i-preview")
.prompt("Place the alarm clock from Image 1 next to the vase on the dining table in Image 2.")
.images(imageUrls)
.n(1)
//.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---同步调用，请稍候----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
/**
* 将文件编码为 Base64 字符串。
* @param filePath 文件路径。
* @return 格式为 data:{MIME_type};base64,{base64_data} 的 Base64 字符串。
*/
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) {
throw new IllegalArgumentException("File does not exist: " + filePath);
}
String mimeType = null;
try {
mimeType = Files.probeContentType(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot detect file type: " + filePath);
}
if (mimeType == null || !mimeType.startsWith("image/")) {
throw new IllegalArgumentException("Unsupported or unrecognized image format");
}
byte[] fileBytes = null;
try{
fileBytes = Files.readAllBytes(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot read file content: " + filePath);
}
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
public static void main(String[] args) {
syncCall();
}
}
- lang: java
label: Java SDK - 异步调用
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
// 需要 SDK 版本 >= 2.22.2
public class Image2Image {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
static String imageUrl_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp";
static String imageUrl_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp";
static List<String> imageUrls = new ArrayList<>();
static {
imageUrls.add(imageUrl_1);
imageUrls.add(imageUrl_2);
}
public static void asyncCall() {
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-i2i-preview")
.prompt("Place the alarm clock from Image 1 next to the vase on the dining table in Image 2.")
.images(imageUrls)
.n(1)
//.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---异步调用，请稍候----");
result = imageSynthesis.asyncCall(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
try {
result = imageSynthesis.wait(taskId, apiKey);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void listTask() throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
param.setApiKey(apiKey);
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public void fetchTask(String taskId) throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
ImageSynthesisResult result = is.fetch(taskId, apiKey);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args) {
asyncCall();
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan25ImageEditRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- wan2.5-i2i-preview
example: wan2.5-i2i-preview
input:
$ref: "#/components/schemas/Wan25ImageEditInput"
parameters:
$ref: "#/components/schemas/Wan25ImageEditParameters"
Wan25ImageEditInput:
type: object
required:
- prompt
- images
description: 图像编辑的输入数据。
properties:
prompt:
type: string
description: 正向提示词，描述生成图像中需要包含的元素和视觉特征。支持中英文。最多 2,000 个字符，超出部分将被截断。
example: Change the floral dress to a vintage-style lace long dress with exquisite embroidery details on the collar and cuffs.
images:
type: array
description: |-
输入图像 URL 数组。每次请求最多支持 3 张图像。多张图像时，数组顺序定义图像序号（图像 1、图像 2 等）。
**图像限制：**
- 支持格式：JPEG、JPG、PNG、BMP 和 WEBP。PNG alpha 通道将被忽略。
- 分辨率：宽和高均须在 384 到 5,000 像素之间。
- 最大文件大小：10 MB。
**支持的输入格式：**
- **公开 URL**：支持 HTTP 和 HTTPS。
- **Base64 编码字符串**：格式：`data:{MIME_type};base64,{base64_data}`。
- **本地文件路径**：格式：`file://{绝对路径}`（仅适用于 SDK 调用）。
items:
type: string
minItems: 1
maxItems: 3
example:
- https://img.alicdn.com/imgextra/i2/O1CN01vHOj4h28jOxUJPwY8_!!6000000007968-49-tps-1344-896.webp
negative_prompt:
type: string
description: 反向提示词，描述生成图像中需要排除的元素。支持中英文。最多 500 个字符，超出部分将被截断。
example: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions
Wan25ImageEditParameters:
type: object
description: 控制输出分辨率、提示词改写、水印及其他处理选项。
properties:
size:
type: string
description: |-
输出分辨率，格式为 `{宽度}*{高度}`。默认值：`1280*1280`。总像素数须在 589,824（768*768）到 1,638,400（1280*1280）之间，宽高比须在 1:4 到 4:1 之间。
推荐分辨率：
- 1280*1280 (1:1)
- 1024*1024 (1:1)
- 800*1200 (2:3)
- 1200*800 (3:2)
- 960*1280 (3:4)
- 1280*960 (4:3)
- 720*1280 (9:16)
- 1280*720 (16:9)
- 1344*576 (21:9)
未指定时，系统默认输出 1280*1280 总像素数的图像，并保留与输入图像相近的宽高比：
- 单图输入：宽高比与输入图像保持一致。
- 多图输入：宽高比与最后一张输入图像保持一致。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像的数量。有效范围：1 到 4。默认值：4。`n` 参数直接影响计费，值越大费用越高。建议测试时明确设置为 1 以控制成本。
default: 4
minimum: 1
maximum: 4
example: 1
watermark:
type: boolean
description: 是否添加水印标识，水印位于图片右下角，文案固定为"AI生成"。
default: false
example: false
prompt_extend:
type: boolean
description: 开启智能提示词改写。启用后，大语言模型将优化您的提示词以获得更好的效果，但会增加处理时间。默认值：true。
default: true
example: true
seed:
type: integer
description: 随机数种子。取值范围：[0, 2147483647]。未指定时，算法自动生成随机数作为种子。指定后，算法为每张图像（共 `n` 张）分别生成一个种子值（seed、seed+1、seed+2……）。若需复现特定结果，请使用固定种子值。注意：由于固有随机性，相同种子不一定能生成完全相同的结果。
minimum: 0
maximum: 2147483647
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求的唯一标识符，可用于问题追踪与排查。
ImageEditTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求的唯一标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
results:
type: array
description: 生成结果数组。每个条目包含图像 URL、提示词，或生成失败时的错误信息。
items:
type: object
properties:
orig_prompt:
type: string
description: 原始输入提示词。
actual_prompt:
type: string
description: 启用提示词改写时实际使用的优化后提示词。未启用该功能时不返回。
url:
type: string
description: 生成图像的 URL。有效期 24 小时。
code:
type: string
description: 图像生成失败时的错误码。仅在部分失败时返回。
message:
type: string
description: 图像生成失败时的错误信息。仅在部分失败时返回。
task_metrics:
type: object
description: 任务结果统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 详细错误信息。仅在任务失败时返回。
usage:
type: object
description: 输出统计信息。仅统计成功生成的结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 标识错误类型的错误码。
message:
type: string
description: 详细错误信息。
request_id:
type: string
description: 用于问题排查的唯一请求标识符。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan25-general-image-editing-query-resul.md
+334
View File
@@ -0,0 +1,334 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.5 — 查询结果
> 查询 Wan 2.5 图像编辑任务状态
查询任务状态和结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wan25-general-image-editing/create-task)接口提交请求，获取 `task_id`。
2. 每 **10 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
- **部分失败**：当 `n > 1` 时，只要有一张图片生成成功，任务状态即为 `SUCCEEDED`。失败的图片会在 `results` 中包含错误详情，仅成功的图片计入用量。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan2.5 通用图像编辑 API
description: Wan2.5 通用图像编辑 API。通过文本提示词对图像进行编辑，保持主体一致性。支持单图编辑和多图融合，最多支持三张参考图。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan25ImageEditTaskStatus
summary: 查询任务结果
description: 查询图像编辑任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 图像编辑创建接口返回的任务标识符。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/ImageEditTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: d1f2a1be-9c58-48af-b43f-xxxxxx
output:
task_id: 7f4836cd-1c47-41b3-b3a4-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-09-23 22:14:10.800
scheduled_time: 2025-09-23 22:14:10.825
end_time: 2025-09-23 22:15:23.456
results:
- orig_prompt: Change the floral dress to a vintage-style lace long dress with exquisite embroidery details on the collar and cuffs.
actual_prompt: Replace the pink pleated dress with a vintage-style lace long dress with exquisite embroidery details on the collar and cuffs. Keep the person's hairstyle, makeup, and posture unchanged. The overall style should be consistent with the soft tones and classic atmosphere of the original image.
url: https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
task_metrics:
TOTAL: 1
FAILED: 0
SUCCEEDED: 1
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-xxxxxx
task_status: FAILED
code: InvalidParameter
message: The specified parameter is not valid.
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 4
RUNNING:
summary: 任务执行中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 查询任务结果
source: |-
# 将 {task_id} 替换为提交响应中返回的实际任务 ID
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan25ImageEditRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- wan2.5-i2i-preview
example: wan2.5-i2i-preview
input:
$ref: "#/components/schemas/Wan25ImageEditInput"
parameters:
$ref: "#/components/schemas/Wan25ImageEditParameters"
Wan25ImageEditInput:
type: object
required:
- prompt
- images
description: 图像编辑的输入数据。
properties:
prompt:
type: string
description: 正向提示词，描述生成图像中需要包含的元素和视觉特征。支持中英文。最多 2,000 个字符，超出部分将被截断。
example: Change the floral dress to a vintage-style lace long dress with exquisite embroidery details on the collar and cuffs.
images:
type: array
description: |-
输入图像 URL 数组。每次请求最多支持 3 张图像。多张图像时，数组顺序定义图像序号（图像 1、图像 2 等）。
**图像限制：**
- 支持格式：JPEG、JPG、PNG、BMP 和 WEBP。PNG alpha 通道将被忽略。
- 分辨率：宽和高均须在 384 到 5,000 像素之间。
- 最大文件大小：10 MB。
**支持的输入格式：**
- **公开 URL**：支持 HTTP 和 HTTPS。
- **Base64 编码字符串**：格式：`data:{MIME_type};base64,{base64_data}`。
- **本地文件路径**：格式：`file://{绝对路径}`（仅适用于 SDK 调用）。
items:
type: string
minItems: 1
maxItems: 3
example:
- https://img.alicdn.com/imgextra/i2/O1CN01vHOj4h28jOxUJPwY8_!!6000000007968-49-tps-1344-896.webp
negative_prompt:
type: string
description: 反向提示词，描述生成图像中需要排除的元素。支持中英文。最多 500 个字符，超出部分将被截断。
example: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions
Wan25ImageEditParameters:
type: object
description: 控制输出分辨率、提示词改写、水印及其他处理选项。
properties:
size:
type: string
description: |-
输出分辨率，格式为 `{宽度}*{高度}`。默认值：`1280*1280`。总像素数须在 589,824（768*768）到 1,638,400（1280*1280）之间，宽高比须在 1:4 到 4:1 之间。
推荐分辨率：
- 1280*1280 (1:1)
- 1024*1024 (1:1)
- 800*1200 (2:3)
- 1200*800 (3:2)
- 960*1280 (3:4)
- 1280*960 (4:3)
- 720*1280 (9:16)
- 1280*720 (16:9)
- 1344*576 (21:9)
未指定时，系统默认输出 1280*1280 总像素数的图像，并保留与输入图像相近的宽高比：
- 单图输入：宽高比与输入图像保持一致。
- 多图输入：宽高比与最后一张输入图像保持一致。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像的数量。有效范围：1 到 4。默认值：4。`n` 参数直接影响计费，值越大费用越高。建议测试时明确设置为 1 以控制成本。
default: 4
minimum: 1
maximum: 4
example: 1
watermark:
type: boolean
description: 是否添加水印标识，水印位于图片右下角，文案固定为"AI生成"。
default: false
example: false
prompt_extend:
type: boolean
description: 开启智能提示词改写。启用后，大语言模型将优化您的提示词以获得更好的效果，但会增加处理时间。默认值：true。
default: true
example: true
seed:
type: integer
description: 随机数种子。取值范围：[0, 2147483647]。未指定时，算法自动生成随机数作为种子。指定后，算法为每张图像（共 `n` 张）分别生成一个种子值（seed、seed+1、seed+2……）。若需复现特定结果，请使用固定种子值。注意：由于固有随机性，相同种子不一定能生成完全相同的结果。
minimum: 0
maximum: 2147483647
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求的唯一标识符，可用于问题追踪与排查。
ImageEditTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求的唯一标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。可在 24 小时内用于查询任务状态。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始执行时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成时间，北京时间（UTC+8）。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
results:
type: array
description: 生成结果数组。每个条目包含图像 URL、提示词，或生成失败时的错误信息。
items:
type: object
properties:
orig_prompt:
type: string
description: 原始输入提示词。
actual_prompt:
type: string
description: 启用提示词改写时实际使用的优化后提示词。未启用该功能时不返回。
url:
type: string
description: 生成图像的 URL。有效期 24 小时。
code:
type: string
description: 图像生成失败时的错误码。仅在部分失败时返回。
message:
type: string
description: 图像生成失败时的错误信息。仅在部分失败时返回。
task_metrics:
type: object
description: 任务结果统计信息。
properties:
TOTAL:
type: integer
description: 任务总数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 详细错误信息。仅在任务失败时返回。
usage:
type: object
description: 输出统计信息。仅统计成功生成的结果。
properties:
image_count:
type: integer
description: 成功生成的图像数量。计费公式：费用 = 图像数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 标识错误类型的错误码。
message:
type: string
description: 详细错误信息。
request_id:
type: string
description: 用于问题排查的唯一请求标识符。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan26-image-gen-edit-create-task.md
+795
View File
@@ -0,0 +1,795 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.6 — 创建任务
> Wan 2.6 异步图像生成与编辑
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
图像生成任务通常需要 1 到 2 分钟。为避免请求超时，可使用异步 API 将流程拆分为两步：
1. **创建任务**（本接口），获取 `task_id`。
2. **[查询结果](/api-reference/image-generation/wan26-image-gen-edit/query-result)**，使用 `task_id` 轮询任务状态。
请求体与[同步接口](/api-reference/image-generation/wan26-image-gen-edit/synchronous)使用相同的 `messages` 格式和参数，但需要添加 `X-DashScope-Async: enable` 请求头。
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.1.0
info:
title: Wan2.6 图像生成与编辑 API
description: Wan2.6 图像生成与编辑 API，支持多图输入、图像编辑及图文交织输出。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createWan26ImageTask
summary: 创建图像生成任务
description: 创建异步图像生成或编辑任务。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置。**必须设置为 `enable`**。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26ImageAsyncRequest"
responses:
"200":
description: 任务创建成功。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (image editing, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.6-image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"
},
{
"image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
}
]
}
]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"enable_interleave": false,
"size": "1K"
}
}'
- lang: curl
label: cURL (interleaved text-image, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.6-image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Give me a three-image tutorial for stir-fried pork with chili peppers"
}
]
}
]
},
"parameters": {
"max_images": 3,
"size": "1280*1280",
"n": 1,
"enable_interleave": true
}
}'
- lang: python
label: Python - image editing (async)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
from http import HTTPStatus
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
# 创建异步任务
def create_async_task():
print("Creating async task...")
message = Message(
role="user",
content=[
{'text': 'Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2'},
{'image': 'https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png'},
{'image': 'https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp'}
]
)
response = ImageGeneration.async_call(
model="wan2.6-image",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
enable_interleave=False,
size="1K"
)
if response.status_code == 200:
print("Task created successfully:", response)
return response
else:
raise Exception(f"Failed to create task: {response.code} - {response.message}")
# 等待任务完成
def wait_for_completion(task_response):
print("Waiting for task completion...")
status = ImageGeneration.wait(task=task_response, api_key=api_key)
if status.output.task_status == "SUCCEEDED":
print("Task succeeded!")
print("Response:", status)
else:
raise Exception(f"Task failed with status: {status.output.task_status}")
# 查询异步任务状态
def fetch_task_status(task):
print("Fetching task status...")
status = ImageGeneration.fetch(task=task, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print("Task status:", status.output.task_status)
print("Response details:", status)
else:
print(f"Failed to fetch status: {status.code} - {status.message}")
# 取消异步任务
def cancel_task(task):
print("Canceling task...")
response = ImageGeneration.cancel(task=task, api_key=api_key)
if response.status_code == HTTPStatus.OK:
print("Task canceled successfully:", response.output.task_status)
else:
print(f"Failed to cancel task: {response.code} - {response.message}")
# 主执行流程
if __name__ == "__main__":
task = create_async_task()
wait_for_completion(task)
- lang: python
label: Python - interleaved text-image (async)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
from http import HTTPStatus
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def main():
"""Asynchronous call - Text-image output"""
print("========== wan2.6-image Asynchronous call - Text-image output ==========")
image_message = Message(
role="user",
content=[
{
"text": "Give me a three-image tutorial for stir-fried pork with chili peppers"
}
]
)
# 创建异步任务
print("---async call, creating task----")
response = ImageGeneration.async_call(
model="wan2.6-image",
api_key=api_key,
messages=[image_message],
# 异步调用无需 stream 参数
negative_prompt="",
n=1,
enable_interleave=True,
max_images=3,
size="1280*1280"
)
if response.status_code == HTTPStatus.OK:
print(f"Task created successfully:")
print(response)
# 等待任务完成
print("\n---waiting for task completion----")
status = ImageGeneration.wait(task=response, api_key=api_key)
if status.output.task_status == "SUCCEEDED":
print("Task completed!")
print(f"Results:")
print(status)
else:
print(f"Task failed, status: {status.output.task_status}")
else:
print(f"Task creation failed: {response.code} - {response.message}")
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"Execution error: {str(e)}")
import traceback
traceback.print_exc()
- lang: java
label: Java - image editing (async)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Arrays;
import java.util.Collections;
/**
* wan2.6-image 图像编辑 - 异步调用示例
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Arrays.asList(
Collections.singletonMap("text", "Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"),
Collections.singletonMap("image", "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"),
Collections.singletonMap("image", "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-image")
.n(1)
.size("1K")
.negativePrompt("")
.promptExtend(true)
.messages(Arrays.asList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---async call for image editing, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println("Task creation result:");
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
// 等待任务完成
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
System.out.println("\n---waiting for task completion----");
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println("Task completion result:");
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - interleaved text-image (async)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
/**
* wan2.6-image 图文交织输出 - 异步调用示例
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "Give me a three-image tutorial for stir-fried pork with chili peppers")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-image")
.size("1280*1280")
.enableInterleave(true)
.maxImages(3)
.negativePrompt("")
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---async call for image interleave, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println("Task creation result:");
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
// 等待任务完成
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
System.out.println("\n---waiting for task completion----");
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println("Task completion result:");
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
Wan26ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含且仅包含一个 `text` 对象。图像对象的数量取决于模式：
- 图像编辑模式（`enable_interleave=false`）：需要 **1 到 4** 个图像对象。
- 图文交织模式（`enable_interleave=true`）：**0 到 1** 个图像对象。
使用多张图像时，在数组中包含多个 `image` 对象，图像顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan26ImageContentPart"
Wan26ImageContentPart:
type: object
description: 图像或文本内容部分。
properties:
text:
type: string
description: 正向提示词，描述期望的图像内容、风格和构图。支持中英文，最多 2,000 个字符（每个汉字、字母、数字或符号均计为一个字符），超出部分将自动截断。`content` 数组中必须且仅包含一个 `text` 对象。
maxLength: 2000
example: Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2
image:
type: string
description: |-
输入图像，可以是公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图像限制：**
- 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。
- 分辨率：宽和高各在 240 到 8,000 像素之间。
- 文件大小：最大 10 MB。
**图像数量限制：**
- `enable_interleave=false`（图像编辑）：需输入 1 到 4 张图像。
- `enable_interleave=true`（图文交织）：可输入 0 到 1 张图像。
example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png
Wan26ImageParameters:
type: object
description: 图像处理参数。
properties:
negative_prompt:
type: string
description: |-
反向提示词，描述不希望出现在图像中的内容。支持中英文，最多 500 个字符，超出部分将自动截断。
示例：`低分辨率、低质量、肢体变形、手指变形、颜色过度饱和、蜡像感、面部细节缺失、皮肤过度光滑、AI 痕迹明显、构图混乱、文字模糊或扭曲。`
maxLength: 500
size:
type: string
description: |-
输出图像分辨率。支持两种方式：参考输入图像比例或直接指定尺寸。
**图像编辑模式**（`enable_interleave=false`）：
- 方式一（推荐）：`1K`（默认）或 `2K`。输出总像素接近 1280\*1280 或 2048\*2048，并保持最后一张输入图像的宽高比。
- 方式二：直接指定 `宽*高`（像素）。总像素需在 [768\*768, 2048\*2048] 范围内，宽高比在 [1:4, 4:1] 之间，实际值为 16 的倍数。
**图文交织模式**（`enable_interleave=true`）：
- 方式一（默认）：参考输入图像比例。若总像素 <= 1280\*1280，输出与输入一致；若 > 1280\*1280，则缩放至约 1280\*1280。
- 方式二：指定 `宽*高`。总像素需在 [768\*768, 1280\*1280] 范围内，宽高比在 [1:4, 4:1] 之间。
**推荐分辨率：** 1280\*1280（1:1）、800\*1200（2:3）、1200\*800（3:2）、960\*1280（3:4）、1280\*960（4:3）、720\*1280（9:16）、1280\*720（16:9）、1344\*576（21:9）。
example: 1K
enable_interleave:
type: boolean
description: |-
控制图像生成模式：
- `false`（默认）：图像编辑模式。支持多图输入（1-4 张），可进行主体一致性生成，可生成 1 到 4 张结果图像。
- `true`：图文交织输出模式。支持 0-1 张输入图像，生成包含文本和图像的混合内容。**仅同步调用时**，必须同时设置 `stream=true` 并添加 `X-DashScope-Sse: enable` 请求头；异步调用无需设置。
default: false
n:
type: integer
description: |-
生成图像数量。行为取决于模式：
- 图像编辑模式（`enable_interleave=false`）：范围 1-4，默认值为 4。
- 图文交织模式（`enable_interleave=true`）：必须为 1，使用 `max_images` 控制图像数量。
**注意：** `n` 直接影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 4
default: 4
max_images:
type: integer
description: |-
仅在图文交织模式（`enable_interleave=true`）下生效。指定模型在单次响应中最多可生成的图像数量，范围 1-5，默认值为 5。实际生成数量由模型推理决定，可能少于该值。
**注意：** `max_images` 影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 5
default: 5
prompt_extend:
type: boolean
description: 仅在图像编辑模式（`enable_interleave=false`）下生效。启用智能提示词改写，对正向提示词进行优化扩展。反向提示词不受影响。
default: true
stream:
type: boolean
description: 控制是否使用流式输出。仅同步调用时，在图文交织模式（`enable_interleave=true`）下**必须**设置为 `true`；异步调用无需设置此参数。
default: false
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子，范围 [0, 2147483647]。相同种子可产生更一致（但不完全相同）的结果。若不指定，则使用随机种子。
minimum: 0
maximum: 2147483647
Wan26ImageResponse:
type: object
description: Wan2.6 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1376*768
total_tokens: 0
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
finished:
type: boolean
description: 是否已完成生成。
usage:
type: object
description: 用量统计。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
request_id:
type: string
description: 用于追踪和排查问题的唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan26ImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成；`null` 表示流式输出仍在进行中。"
example: stop
message:
type: object
properties:
role:
type: string
description: 固定为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组，包含生成的图像 URL 和/或文本（图文交织模式下）。
items:
$ref: "#/components/schemas/Wan26ImageResponseContentPart"
Wan26ImageResponseContentPart:
type: object
description: 响应中的内容部分，可以是图像或文本。
properties:
type:
type: string
description: 内容类型：`image` 或 `text`。
enum:
- image
- text
image:
type: string
description: 生成的图像 URL（PNG 格式）。**有效期为 24 小时**，请及时下载。
text:
type: string
description: 文本内容（仅在图文交织输出模式下存在）。
Wan26ImageAsyncRequest:
type: object
description: Wan2.6 图像生成/编辑异步任务的请求体。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。通过 `GET /tasks/{task_id}` 查询任务状态，有效期为 24 小时。
task_status:
type: string
description: 初始任务状态，通常为 `PENDING`。
enum:
- PENDING
Wan26TaskStatusResponse:
type: object
description: 查询异步任务状态时返回的响应。
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间，采用 UTC+8 时区。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始运行的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
finished:
type: boolean
description: 任务是否已完成。
choices:
type: array
description: 生成结果列表。`task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
usage:
type: object
description: 用量统计，仅统计成功生成的结果。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`，其中 `image_count` 为该任务生成的图片总数。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
code:
type: string
description: 错误码，仅在请求失败时返回。
message:
type: string
description: 详细错误信息，仅在请求失败时返回。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
example:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`InvalidApiKey`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan26-image-gen-edit-query-result.md
+492
View File
@@ -0,0 +1,492 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.6 — 查询结果
> 查询 Wan 2.6 图像任务状态
查询任务状态和结果。
## 轮询策略
使用返回的 `task_id` 轮询此接口，建议轮询间隔为 **5-10 秒**。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（task\_id 无效或已过期）。
- **task\_id 有效期**：task\_id 有效期为 24 小时，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan2.6 图像生成与编辑 API
description: Wan2.6 图像生成与编辑 API，支持多图输入、图像编辑及图文交织输出。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan26ImageTaskResult
summary: 查询任务结果
description: 查询异步图像任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 异步任务创建接口返回的任务标识符。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-12-16 04:21:02.275
scheduled_time: 2025-12-16 04:21:02.304
end_time: 2025-12-16 04:24:46.658
finished: true
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/1xxx.png?Expires=xxx
type: image
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/2xxx.png?Expires=xxx
type: image
usage:
size: 1376*768
total_tokens: 0
image_count: 2
output_tokens: 0
input_tokens: 0
FAILED:
summary: 任务失败
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: FAILED
code: InvalidParameter
message: num_images_per_prompt must be 1
RUNNING:
summary: 任务运行中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: RUNNING
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Query task result
source: |-
# 将 {task_id} 替换为前一个 API 调用返回的 task_id 值。
# task_id 有效期为 24 小时。
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
Wan26ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含且仅包含一个 `text` 对象。图像对象的数量取决于模式：
- 图像编辑模式（`enable_interleave=false`）：需要 **1 到 4** 个图像对象。
- 图文交织模式（`enable_interleave=true`）：**0 到 1** 个图像对象。
使用多张图像时，在数组中包含多个 `image` 对象，图像顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan26ImageContentPart"
Wan26ImageContentPart:
type: object
description: 图像或文本内容部分。
properties:
text:
type: string
description: 正向提示词，描述期望的图像内容、风格和构图。支持中英文，最多 2,000 个字符（每个汉字、字母、数字或符号均计为一个字符），超出部分将自动截断。`content` 数组中必须且仅包含一个 `text` 对象。
maxLength: 2000
example: Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2
image:
type: string
description: |-
输入图像，可以是公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图像限制：**
- 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。
- 分辨率：宽和高各在 240 到 8,000 像素之间。
- 文件大小：最大 10 MB。
**图像数量限制：**
- `enable_interleave=false`（图像编辑）：需输入 1 到 4 张图像。
- `enable_interleave=true`（图文交织）：可输入 0 到 1 张图像。
example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png
Wan26ImageParameters:
type: object
description: 图像处理参数。
properties:
negative_prompt:
type: string
description: |-
反向提示词，描述不希望出现在图像中的内容。支持中英文，最多 500 个字符，超出部分将自动截断。
示例：`低分辨率、低质量、肢体变形、手指变形、颜色过度饱和、蜡像感、面部细节缺失、皮肤过度光滑、AI 痕迹明显、构图混乱、文字模糊或扭曲。`
maxLength: 500
size:
type: string
description: |-
输出图像分辨率。支持两种方式：参考输入图像比例或直接指定尺寸。
**图像编辑模式**（`enable_interleave=false`）：
- 方式一（推荐）：`1K`（默认）或 `2K`。输出总像素接近 1280\*1280 或 2048\*2048，并保持最后一张输入图像的宽高比。
- 方式二：直接指定 `宽*高`（像素）。总像素需在 [768\*768, 2048\*2048] 范围内，宽高比在 [1:4, 4:1] 之间，实际值为 16 的倍数。
**图文交织模式**（`enable_interleave=true`）：
- 方式一（默认）：参考输入图像比例。若总像素 <= 1280\*1280，输出与输入一致；若 > 1280\*1280，则缩放至约 1280\*1280。
- 方式二：指定 `宽*高`。总像素需在 [768\*768, 1280\*1280] 范围内，宽高比在 [1:4, 4:1] 之间。
**推荐分辨率：** 1280\*1280（1:1）、800\*1200（2:3）、1200\*800（3:2）、960\*1280（3:4）、1280\*960（4:3）、720\*1280（9:16）、1280\*720（16:9）、1344\*576（21:9）。
example: 1K
enable_interleave:
type: boolean
description: |-
控制图像生成模式：
- `false`（默认）：图像编辑模式。支持多图输入（1-4 张），可进行主体一致性生成，可生成 1 到 4 张结果图像。
- `true`：图文交织输出模式。支持 0-1 张输入图像，生成包含文本和图像的混合内容。**仅同步调用时**，必须同时设置 `stream=true` 并添加 `X-DashScope-Sse: enable` 请求头；异步调用无需设置。
default: false
n:
type: integer
description: |-
生成图像数量。行为取决于模式：
- 图像编辑模式（`enable_interleave=false`）：范围 1-4，默认值为 4。
- 图文交织模式（`enable_interleave=true`）：必须为 1，使用 `max_images` 控制图像数量。
**注意：** `n` 直接影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 4
default: 4
max_images:
type: integer
description: |-
仅在图文交织模式（`enable_interleave=true`）下生效。指定模型在单次响应中最多可生成的图像数量，范围 1-5，默认值为 5。实际生成数量由模型推理决定，可能少于该值。
**注意：** `max_images` 影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 5
default: 5
prompt_extend:
type: boolean
description: 仅在图像编辑模式（`enable_interleave=false`）下生效。启用智能提示词改写，对正向提示词进行优化扩展。反向提示词不受影响。
default: true
stream:
type: boolean
description: 控制是否使用流式输出。仅同步调用时，在图文交织模式（`enable_interleave=true`）下**必须**设置为 `true`；异步调用无需设置此参数。
default: false
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子，范围 [0, 2147483647]。相同种子可产生更一致（但不完全相同）的结果。若不指定，则使用随机种子。
minimum: 0
maximum: 2147483647
Wan26ImageResponse:
type: object
description: Wan2.6 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1376*768
total_tokens: 0
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
finished:
type: boolean
description: 是否已完成生成。
usage:
type: object
description: 用量统计。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
request_id:
type: string
description: 用于追踪和排查问题的唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan26ImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成；`null` 表示流式输出仍在进行中。"
example: stop
message:
type: object
properties:
role:
type: string
description: 固定为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组，包含生成的图像 URL 和/或文本（图文交织模式下）。
items:
$ref: "#/components/schemas/Wan26ImageResponseContentPart"
Wan26ImageResponseContentPart:
type: object
description: 响应中的内容部分，可以是图像或文本。
properties:
type:
type: string
description: 内容类型：`image` 或 `text`。
enum:
- image
- text
image:
type: string
description: 生成的图像 URL（PNG 格式）。**有效期为 24 小时**，请及时下载。
text:
type: string
description: 文本内容（仅在图文交织输出模式下存在）。
Wan26ImageAsyncRequest:
type: object
description: Wan2.6 图像生成/编辑异步任务的请求体。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。通过 `GET /tasks/{task_id}` 查询任务状态，有效期为 24 小时。
task_status:
type: string
description: 初始任务状态，通常为 `PENDING`。
enum:
- PENDING
Wan26TaskStatusResponse:
type: object
description: 查询异步任务状态时返回的响应。
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间，采用 UTC+8 时区。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始运行的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
finished:
type: boolean
description: 任务是否已完成。
choices:
type: array
description: 生成结果列表。`task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
usage:
type: object
description: 用量统计，仅统计成功生成的结果。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`，其中 `image_count` 为该任务生成的图片总数。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
code:
type: string
description: 错误码，仅在请求失败时返回。
message:
type: string
description: 详细错误信息，仅在请求失败时返回。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
example:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`InvalidApiKey`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan26-image-gen-edit-synchronous.md
+702
View File
@@ -0,0 +1,702 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.6 — 同步调用
> Wan 2.6 同步图像生成与编辑
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
此同步接口仅适用于 **wan2.6-image** 模型，可在单次请求中直接获取生成的图像，无需轮询。
如需异步处理，请使用[异步提交](/api-reference/image-generation/wan26-image-gen-edit/create-task)接口。
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Wan2.6 图像生成与编辑 API
description: Wan2.6 图像生成与编辑 API，支持多图输入、图像编辑及图文交织输出。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createWan26Image
summary: 同步生成或编辑图像
description: 使用 Wan2.6 同步生成或编辑图像。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26ImageRequest"
responses:
"200":
description: 图像生成或编辑成功
content:
application/json:
schema:
$ref: "#/components/schemas/Wan26ImageResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (image editing)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.6-image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"
},
{
"image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
}
]
}
]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"enable_interleave": false,
"size": "1K"
}
}'
- lang: curl
label: cURL (interleaved text-image, streaming)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Sse: enable' \
--data '{
"model": "wan2.6-image",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Give me a three-image tutorial for stir-fried pork with chili peppers"
}
]
}
]
},
"parameters": {
"max_images": 3,
"size": "1280*1280",
"stream": true,
"enable_interleave": true
}
}'
- lang: python
label: Python - image editing (sync)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
message = Message(
role="user",
# 支持本地文件，例如 "image": "file://umbrella1.png"
content=[
{
"text": "Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"
},
{
"image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
}
]
)
print("----sync call, wait a moment----")
rsp = ImageGeneration.call(
model='wan2.6-image',
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
enable_interleave=False,
size="1K"
)
print(rsp)
- lang: python
label: Python - interleaved text-image (streaming)
source: |-
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def sync_call_with_stream():
print("\n========== Synchronous call - Streaming text-image output ==========")
image_message = Message(
role="user",
content=[
{
"text": "Give me a three-image tutorial for stir-fried pork with chili peppers"
}
]
)
image_stream_res = ImageGeneration.call(
model="wan2.6-image",
api_key=api_key,
messages=[image_message],
stream=True, # 仅支持流式输出
negative_prompt="",
enable_interleave=True,
max_images=3,
size="1280*1280"
)
print("Streaming output results:")
for stream_res in image_stream_res:
print(stream_res)
if __name__ == "__main__":
sync_call_with_stream()
- lang: java
label: Java - image editing (sync)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Arrays;
import java.util.Collections;
/**
* wan2.6-image 图像编辑 - 同步调用示例
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
// 构建多图输入消息
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Arrays.asList(
Collections.singletonMap("text", "Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"),
Collections.singletonMap("image", "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"),
Collections.singletonMap("image", "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-image")
.messages(Collections.singletonList(message))
.n(1)
.size("1K")
.negativePrompt("")
.promptExtend(true)
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---sync call for image editing, wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - interleaved text-image (streaming)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import io.reactivex.Flowable;
import java.util.Collections;
/**
* wan2.6-image 图文交织输出 - 流式调用示例
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void streamCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "Give me a three-image tutorial for stir-fried pork with chili peppers")
)).build();
// 图文交织输出需要使用流式调用
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-image")
.messages(Collections.singletonList(message))
.stream(true) // 必须开启流式输出
.enableInterleave(true)
.size("1280*1280")
.negativePrompt("")
.maxImages(3)
.build();
ImageGeneration imageGeneration = new ImageGeneration();
try {
System.out.println("---stream call for image interleave----");
Flowable<ImageGenerationResult> resultFlowable = imageGeneration.streamCall(param);
resultFlowable.blockingForEach(result -> {
System.out.println(JsonUtils.toJson(result));
});
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
}
public static void main(String[] args) {
try {
streamCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan26ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
Wan26ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含且仅包含一个 `text` 对象。图像对象的数量取决于模式：
- 图像编辑模式（`enable_interleave=false`）：需要 **1 到 4** 个图像对象。
- 图文交织模式（`enable_interleave=true`）：**0 到 1** 个图像对象。
使用多张图像时，在数组中包含多个 `image` 对象，图像顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan26ImageContentPart"
Wan26ImageContentPart:
type: object
description: 图像或文本内容部分。
properties:
text:
type: string
description: 正向提示词，描述期望的图像内容、风格和构图。支持中英文，最多 2,000 个字符（每个汉字、字母、数字或符号均计为一个字符），超出部分将自动截断。`content` 数组中必须且仅包含一个 `text` 对象。
maxLength: 2000
example: Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2
image:
type: string
description: |-
输入图像，可以是公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图像限制：**
- 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。
- 分辨率：宽和高各在 240 到 8,000 像素之间。
- 文件大小：最大 10 MB。
**图像数量限制：**
- `enable_interleave=false`（图像编辑）：需输入 1 到 4 张图像。
- `enable_interleave=true`（图文交织）：可输入 0 到 1 张图像。
example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png
Wan26ImageParameters:
type: object
description: 图像处理参数。
properties:
negative_prompt:
type: string
description: |-
反向提示词，描述不希望出现在图像中的内容。支持中英文，最多 500 个字符，超出部分将自动截断。
示例：`低分辨率、低质量、肢体变形、手指变形、颜色过度饱和、蜡像感、面部细节缺失、皮肤过度光滑、AI 痕迹明显、构图混乱、文字模糊或扭曲。`
maxLength: 500
size:
type: string
description: |-
输出图像分辨率。支持两种方式：参考输入图像比例或直接指定尺寸。
**图像编辑模式**（`enable_interleave=false`）：
- 方式一（推荐）：`1K`（默认）或 `2K`。输出总像素接近 1280\*1280 或 2048\*2048，并保持最后一张输入图像的宽高比。
- 方式二：直接指定 `宽*高`（像素）。总像素需在 [768\*768, 2048\*2048] 范围内，宽高比在 [1:4, 4:1] 之间，实际值为 16 的倍数。
**图文交织模式**（`enable_interleave=true`）：
- 方式一（默认）：参考输入图像比例。若总像素 <= 1280\*1280，输出与输入一致；若 > 1280\*1280，则缩放至约 1280\*1280。
- 方式二：指定 `宽*高`。总像素需在 [768\*768, 1280\*1280] 范围内，宽高比在 [1:4, 4:1] 之间。
**推荐分辨率：** 1280\*1280（1:1）、800\*1200（2:3）、1200\*800（3:2）、960\*1280（3:4）、1280\*960（4:3）、720\*1280（9:16）、1280\*720（16:9）、1344\*576（21:9）。
example: 1K
enable_interleave:
type: boolean
description: |-
控制图像生成模式：
- `false`（默认）：图像编辑模式。支持多图输入（1-4 张），可进行主体一致性生成，可生成 1 到 4 张结果图像。
- `true`：图文交织输出模式。支持 0-1 张输入图像，生成包含文本和图像的混合内容。**仅同步调用时**，必须同时设置 `stream=true` 并添加 `X-DashScope-Sse: enable` 请求头；异步调用无需设置。
default: false
n:
type: integer
description: |-
生成图像数量。行为取决于模式：
- 图像编辑模式（`enable_interleave=false`）：范围 1-4，默认值为 4。
- 图文交织模式（`enable_interleave=true`）：必须为 1，使用 `max_images` 控制图像数量。
**注意：** `n` 直接影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 4
default: 4
max_images:
type: integer
description: |-
仅在图文交织模式（`enable_interleave=true`）下生效。指定模型在单次响应中最多可生成的图像数量，范围 1-5，默认值为 5。实际生成数量由模型推理决定，可能少于该值。
**注意：** `max_images` 影响计费。费用 = 单价 × 成功生成的图像数量。
minimum: 1
maximum: 5
default: 5
prompt_extend:
type: boolean
description: 仅在图像编辑模式（`enable_interleave=false`）下生效。启用智能提示词改写，对正向提示词进行优化扩展。反向提示词不受影响。
default: true
stream:
type: boolean
description: 控制是否使用流式输出。仅同步调用时，在图文交织模式（`enable_interleave=true`）下**必须**设置为 `true`；异步调用无需设置此参数。
default: false
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子，范围 [0, 2147483647]。相同种子可产生更一致（但不完全相同）的结果。若不指定，则使用随机种子。
minimum: 0
maximum: 2147483647
Wan26ImageResponse:
type: object
description: Wan2.6 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 0
output_tokens: 0
size: 1376*768
total_tokens: 0
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
finished:
type: boolean
description: 是否已完成生成。
usage:
type: object
description: 用量统计。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
request_id:
type: string
description: 用于追踪和排查问题的唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan26ImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` 表示正常完成；`null` 表示流式输出仍在进行中。"
example: stop
message:
type: object
properties:
role:
type: string
description: 固定为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容数组，包含生成的图像 URL 和/或文本（图文交织模式下）。
items:
$ref: "#/components/schemas/Wan26ImageResponseContentPart"
Wan26ImageResponseContentPart:
type: object
description: 响应中的内容部分，可以是图像或文本。
properties:
type:
type: string
description: 内容类型：`image` 或 `text`。
enum:
- image
- text
image:
type: string
description: 生成的图像 URL（PNG 格式）。**有效期为 24 小时**，请及时下载。
text:
type: string
description: 文本内容（仅在图文交织输出模式下存在）。
Wan26ImageAsyncRequest:
type: object
description: Wan2.6 图像生成/编辑异步任务的请求体。
required:
- model
- input
properties:
model:
type: string
description: 模型名称。设置为 `wan2.6-image`。
enum:
- wan2.6-image
example: wan2.6-image
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: "请求内容数组。仅支持单轮对话，提供一条 `role: user` 的消息。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan26ImageMessage"
parameters:
$ref: "#/components/schemas/Wan26ImageParameters"
AsyncTaskSubmitResponse:
type: object
description: 异步任务创建成功后返回的响应。
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。通过 `GET /tasks/{task_id}` 查询任务状态，有效期为 24 小时。
task_status:
type: string
description: 初始任务状态，通常为 `PENDING`。
enum:
- PENDING
Wan26TaskStatusResponse:
type: object
description: 查询异步任务状态时返回的响应。
properties:
request_id:
type: string
description: 用于排查问题的唯一请求标识符。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务标识符。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间，采用 UTC+8 时区。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始运行的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
end_time:
type: string
description: 任务完成的时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`。
finished:
type: boolean
description: 任务是否已完成。
choices:
type: array
description: 生成结果列表。`task_status` 为 `SUCCEEDED` 时返回。
items:
$ref: "#/components/schemas/Wan26ImageChoice"
usage:
type: object
description: 用量统计，仅统计成功生成的结果。用量统计在与 `output` 同级的顶层 `usage` 字段中返回，读取方式为 `response.usage["image_count"]`，其中 `image_count` 为该任务生成的图片总数。`output` 对象中不包含用量统计：`response.output.usage` 返回 `{}`，其中没有 `image_count`。
properties:
image_count:
type: integer
description: 生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
size:
type: string
description: 生成图像的分辨率。
total_tokens:
type: integer
description: 消耗的总 token 数量（输入 + 输出）。
code:
type: string
description: 错误码，仅在请求失败时返回。
message:
type: string
description: 详细错误信息，仅在请求失败时返回。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
example:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`InvalidApiKey`）。
example: InvalidParameter
message:
type: string
description: 人类可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan27-image-gen-edit-create-task.md
+863
View File
@@ -0,0 +1,863 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.7 — 创建任务
> Wan 2.7 异步图像生成与编辑
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
图像生成任务通常需要 1 到 2 分钟。为避免请求超时，可使用异步 API 将流程拆分为两步：
1. **创建任务**（本接口），获取 `task_id`。
2. **[查询结果](/api-reference/image-generation/wan27-image-gen-edit/query-result)**，使用 `task_id` 轮询任务状态。
请求体与[同步接口](/api-reference/image-generation/wan27-image-gen-edit/synchronous)使用相同的 `messages` 格式和参数，但需要添加 `X-DashScope-Async: enable` 请求头。
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.1.0
info:
title: Wan2.7 图像生成与编辑 API
description: Wan2.7 图像生成与编辑 API，支持文生图、多图编辑、边界框交互式编辑以及图像集生成。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createWan27ImageTask
summary: 创建图像生成任务
description: |-
创建异步图像生成或编辑任务。请求体格式与同步接口相同，但需要在请求头中添加 `X-DashScope-Async: enable`。
图像生成任务通常需要 1 到 2 分钟。建议使用异步 API 以避免请求超时。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置。**必须设置为 `enable`**。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27ImageRequest"
responses:
"200":
description: 任务创建成功。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (text-to-image, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false,
"thinking_mode": true
}
}'
- lang: curl
label: cURL (image editing, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
},
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"
},
{
"text": "Spray the graffiti from image 2 onto the car in image 1"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false
}
}'
- lang: curl
label: cURL (interactive editing, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
},
{
"text": "Place the alarm clock from image 1 in the selected area of image 2, ensuring the scene and lighting blend naturally"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false,
"bbox_list": [[], [[989, 515, 1138, 681]]]
}
}'
- lang: curl
label: cURL (image set generation, async)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints."
}
]
}
]
},
"parameters": {
"enable_sequential": true,
"n": 4,
"size": "2K"
}
}'
- lang: python
label: Python - image editing (async)
source: |-
import os
import base64
import mimetypes
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# 需要 SDK 版本 >= 1.25.15
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded_string}"
# 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
image_1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
image_2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"
# image_1 = "file:///path/to/your/car.png"
# image_1 = encode_file("/path/to/your/car.png")
message = Message(
role="user",
content=[
{"text": "Spray the graffiti from image 2 onto the car in image 1"},
{"image": image_1},
{"image": image_2}
]
)
print("---async call for image editing, creating task----")
response = ImageGeneration.async_call(
model='wan2.7-image-pro',
api_key=api_key,
messages=[message],
n=1,
# wan2.7-image-pro 文生图支持 1K、2K 或 4K；
# 图像编辑和图像集生成最高支持 2K
size="2K",
watermark=False
)
print("Task created:", response)
# 等待任务完成
result = ImageGeneration.wait(task=response, api_key=api_key)
print(result)
- lang: python
label: Python - image set generation (async)
source: |-
import os
import base64
import mimetypes
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# 需要 SDK 版本 >= 1.25.15
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded_string}"
# 文生图像集（默认）
message = Message(
role="user",
content=[
{"text": "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints."}
]
)
# 图生图像集（取消注释后使用）
# 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
# image_1 = "https://example.com/your-image.png"
# image_1 = "file:///path/to/your/image.png"
# image_1 = encode_file("/path/to/your/image.png")
# message = Message(
# role="user",
# content=[
# {"text": "Generate a sequential image set based on the input image"},
# {"image": image_1}
# ]
# )
print("---async call for image set generation, creating task----")
response = ImageGeneration.async_call(
model='wan2.7-image-pro',
api_key=api_key,
messages=[message],
enable_sequential=True,
n=4,
# wan2.7-image-pro 文生图支持 1K、2K 或 4K；
# 图像编辑和图像集生成最高支持 2K
size="2K"
)
print("Task created:", response)
# 等待任务完成
result = ImageGeneration.wait(task=response, api_key=api_key)
print(result)
- lang: java
label: Java - image editing (async)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
/**
* wan2.7-image-pro 图像编辑 - 异步调用示例
* 需要 SDK 版本 >= 2.22.13
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static String encodeFile(String filePath) throws IOException {
byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
String base64String = Base64.getEncoder().encodeToString(fileContent);
String mimeType = Files.probeContentType(Paths.get(filePath));
return "data:" + mimeType + ";base64," + base64String;
}
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
// 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
String image1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp";
String image2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp";
// String image1 = "file:///path/to/your/car.png";
// String image1 = encodeFile("/path/to/your/car.png");
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Arrays.asList(
Collections.singletonMap("text", "Spray the graffiti from image 2 onto the car in image 1"),
Collections.singletonMap("image", image1),
Collections.singletonMap("image", image2)
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.7-image-pro")
.n(1)
// wan2.7-image-pro 文生图支持 1K、2K 或 4K；
// 图像编辑和图像集生成最高支持 2K
.size("2K")
.messages(Arrays.asList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---asynchronous call for image editing, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println("Task creation result:");
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
System.out.println("\n---waiting for task completion----");
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println("Task completion result:");
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - image set generation (async)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
/**
* wan2.7-image-pro 图像集生成 - 异步调用示例
* 需要 SDK 版本 >= 2.22.13
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static String encodeFile(String filePath) throws IOException {
byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
String base64String = Base64.getEncoder().encodeToString(fileContent);
String mimeType = Files.probeContentType(Paths.get(filePath));
return "data:" + mimeType + ";base64," + base64String;
}
public static ImageGenerationResult waitTask(String taskId)
throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
return imageGeneration.wait(taskId, apiKey);
}
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
// 文生图像集（默认）
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints.")
)).build();
// 图生图像集（取消注释后使用）
// 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
// String image1 = "https://example.com/your-image.png";
// String image1 = "file:///path/to/your/image.png";
// String image1 = encodeFile("/path/to/your/image.png");
// ImageGenerationMessage message = ImageGenerationMessage.builder()
// .role("user")
// .content(Arrays.asList(
// Collections.singletonMap("text", "Generate a sequential image set based on the input image"),
// Collections.singletonMap("image", image1)
// )).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.7-image-pro")
.messages(Collections.singletonList(message))
.enableSequential(true)
.n(4)
// wan2.7-image-pro 文生图支持 1K、2K 或 4K；
// 图像编辑和图像集生成最高支持 2K
.size("2K")
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult taskResult = null;
try {
System.out.println("----async call, creating task----");
taskResult = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println("Task created: " + JsonUtils.toJson(taskResult));
String taskId = taskResult.getOutput().getTaskId();
ImageGenerationResult result = waitTask(taskId);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan27ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。可选值：wan2.7-image-pro、wan2.7-image。
enum:
- wan2.7-image-pro
- wan2.7-image
example: wan2.7-image-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。目前仅支持单轮对话，即只能传入一组 role 和 content 参数，不支持多轮对话。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan27ImageMessage"
parameters:
$ref: "#/components/schemas/Wan27ImageParameters"
Wan27ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含一个 `text` 对象和 0 到 9 个 `image` 对象。
使用多张图片时，在数组中放入多个 `image` 对象。图片顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan27ImageContentPart"
Wan27ImageContentPart:
type: object
description: 图片或文本内容部分。
properties:
text:
type: string
description: 用户输入的提示词。支持中英文。长度不超过 5000 个字符（每个中文字符、字母、数字或符号均计为一个字符，超出部分自动截断）。`content` 数组中必须包含且仅包含一个 `text` 对象。
maxLength: 5000
example: Spray the graffiti from image 2 onto the car in image 1
image:
type: string
description: |-
输入图片，支持公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图片约束：**
- 格式：JPEG、JPG、PNG（不支持 Alpha 通道）、BMP、WEBP。
- 分辨率：宽和高各自在 240 到 8000 像素之间，宽高比在 [1:8, 8:1] 范围内。
- 文件大小：最大 20 MB。
- 数量：每次请求最多 9 张图片。
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp
Wan27ImageParameters:
type: object
description: 图像处理参数。
properties:
size:
type: string
description: |-
输出图像分辨率。支持两种指定方式，不可同时使用。
**wan2.7-image-pro：**
- 方式一（推荐）：`1K`、`2K`（默认）或 `4K`。
- 适用范围：文生图（无图片输入，且非图像集生成模式）支持 1K、2K 和 4K；其他场景仅支持 1K 和 2K。
- 总像素数：1K = 1024×1024，2K = 2048×2048，4K = 4096×4096。
- 宽高比：有图片输入时，输出图像按最后一张输入图片的宽高比缩放到对应分辨率；无图片输入时，输出为正方形。
- 方式二：以 `width*height` 形式指定像素数，宽高比在 [1:8, 8:1] 范围内。
- 文生图：总像素数在 [768×768, 4096×4096] 范围内。
- 其他场景：总像素数在 [768×768, 2048×2048] 范围内。
**wan2.7-image：**
- 方式一（推荐）：`1K` 或 `2K`（默认），不支持 4K。
- 方式二：以 `width*height` 形式指定像素数。所有场景总像素数在 [768×768, 2048×2048] 范围内，宽高比在 [1:8, 8:1] 范围内。
输出图像的实际像素值可能与指定值略有差异。
example: 2K
n:
type: integer
description: |-
生成图像的数量。
**注意：** `n` 的值直接影响费用。费用 = 单价 × 成功生成的图像数量。
- 未启用图像集模式（`enable_sequential=false`）：表示生成图像的数量，范围 1–4，默认为 1。
- 启用图像集模式（`enable_sequential=true`）：表示最多生成的图像数量，范围 1–12，默认为 12。实际数量由模型决定，不超过 `n`。
minimum: 1
maximum: 12
default: 1
enable_sequential:
type: boolean
description: |-
控制图像生成模式。
- `false`：默认值。
- `true`：启用图像集输出模式。
default: false
thinking_mode:
type: boolean
description: 是否启用思考模式。默认为 `true`（启用）。仅在未启用图像集模式且无图片输入时生效。启用后，模型将增强推理能力以提升图像质量，但会增加生成时间。
default: true
bbox_list:
type: array
description: |-
交互式编辑的选区。
- 对应关系：列表长度必须与输入图片数量一致。若某张图片无需编辑，对应位置传入空列表 `[]`。
- 坐标格式：`[x1, y1, x2, y2]`（左上角 x、左上角 y、右下角 x、右下角 y），使用原始图片的绝对像素坐标，左上角为 (0, 0)。
- 限制：单张图片最多支持 2 个边界框。
items:
type: array
description: 单张输入图片的边界框列表。空数组表示无边界框。
items:
type: array
description: 单个边界框 [x1, y1, x2, y2]。
items:
type: integer
minItems: 4
maxItems: 4
maxItems: 2
color_palette:
type: array
description: 自定义色彩主题。由颜色（`hex`）和比例（`ratio`）对象组成的数组，须包含 3 到 10 种颜色（推荐设置为 8 种）。仅在未启用图像集模式（`enable_sequential=false`）时可用。
minItems: 3
maxItems: 10
items:
type: object
required:
- hex
- ratio
properties:
hex:
type: string
description: 十六进制（HEX）格式的颜色值。示例：`#C2D1E6`。
ratio:
type: string
description: 该颜色的占比，精确到小数点后两位（例如 `"25.00%"`）。所有 `ratio` 值之和必须为 100.00%。
example:
- hex: "#C2D1E6"
ratio: 60.00%
- hex: "#636574"
ratio: 25.00%
- hex: "#CBD4E4"
ratio: 15.00%
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子。有效范围：[0, 2147483647]。使用相同种子可生成相似结果。若不指定，算法将使用随机种子。注意：图像生成具有概率性，即使使用相同种子，结果也可能存在差异。
minimum: 0
maximum: 2147483647
Wan27ImageResponse:
type: object
description: Wan2.7 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 18790
output_tokens: 2
size: 2985*1405
total_tokens: 18792
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸（宽×高）。
example: 2985*1405
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan27ImageChoice:
type: object
properties:
finish_reason:
type: string
description: 生成完成的原因。
example: stop
message:
type: object
properties:
role:
type: string
example: assistant
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL。**URL 在 24 小时后失效，请及时下载保存。**
example: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type:
type: string
example: image
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交成功后返回的响应。
example:
request_id: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
task_id: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status: PENDING
properties:
request_id:
type: string
description: 唯一请求标识符。
example: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。用于轮询结果接口，24 小时内有效。
example: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status:
type: string
description: 初始任务状态。创建完成后始终为 `PENDING`。
example: PENDING
Wan27TaskStatusResponse:
type: object
description: 任务状态查询接口的响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
example: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。
example: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status:
type: string
description: 当前任务状态：`PENDING`（排队中）、`RUNNING`（处理中）、`SUCCEEDED`（已完成）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（任务 ID 无效或已过期）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: SUCCEEDED
submit_time:
type: string
description: 任务提交时间。
example: 2026-03-31 19:57:58.840
scheduled_time:
type: string
description: 任务调度时间。
example: 2026-03-31 19:57:58.877
end_time:
type: string
description: 任务完成时间。
example: 2026-03-31 19:58:11.563
finished:
type: boolean
description: 任务是否已结束。
example: true
choices:
type: array
description: 已生成的图像。仅在 `task_status` 为 `SUCCEEDED` 时存在。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
code:
type: string
description: 错误码。仅在 `task_status` 为 `FAILED` 时存在。
message:
type: string
description: 错误信息。仅在 `task_status` 为 `FAILED` 时存在。
usage:
type: object
description: 用量统计。仅在 `task_status` 为 `SUCCEEDED` 时存在。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸。
example: 2985*1405
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
example: InvalidParameter
message:
type: string
description: 错误信息。
example: Invalid parameter value
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan27-image-gen-edit-query-result.md
+477
View File
@@ -0,0 +1,477 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.7 — 查询结果
> 查询 Wan 2.7 图像任务状态
查询任务状态和结果。
## 轮询策略
使用返回的 `task_id` 轮询此接口，建议每 **5-10 秒**轮询一次。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（任务 ID 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan2.7 图像生成与编辑 API
description: Wan2.7 图像生成与编辑 API，支持文生图、多图编辑、边界框交互式编辑以及图像集生成。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan27ImageTaskResult
summary: 查询任务结果
description: 查询异步图像任务的状态和结果。
parameters:
- name: task_id
in: path
required: true
description: 异步任务创建接口返回的任务标识符。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: SUCCEEDED
submit_time: 2026-03-31 19:57:58.840
scheduled_time: 2026-03-31 19:57:58.877
end_time: 2026-03-31 19:58:11.563
finished: true
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/1xxx.png?Expires=xxx
type: image
usage:
size: 2985*1405
total_tokens: 18792
image_count: 1
output_tokens: 2
input_tokens: 18790
FAILED:
summary: 任务失败
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: FAILED
code: InvalidParameter
message: Invalid parameter value
RUNNING:
summary: 任务执行中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: RUNNING
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Query task result
source: |-
# 将 {task_id} 替换为上一次 API 调用返回的 task_id 值。
# task_id 在 24 小时内有效。
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan27ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。可选值：wan2.7-image-pro、wan2.7-image。
enum:
- wan2.7-image-pro
- wan2.7-image
example: wan2.7-image-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。目前仅支持单轮对话，即只能传入一组 role 和 content 参数，不支持多轮对话。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan27ImageMessage"
parameters:
$ref: "#/components/schemas/Wan27ImageParameters"
Wan27ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含一个 `text` 对象和 0 到 9 个 `image` 对象。
使用多张图片时，在数组中放入多个 `image` 对象。图片顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan27ImageContentPart"
Wan27ImageContentPart:
type: object
description: 图片或文本内容部分。
properties:
text:
type: string
description: 用户输入的提示词。支持中英文。长度不超过 5000 个字符（每个中文字符、字母、数字或符号均计为一个字符，超出部分自动截断）。`content` 数组中必须包含且仅包含一个 `text` 对象。
maxLength: 5000
example: Spray the graffiti from image 2 onto the car in image 1
image:
type: string
description: |-
输入图片，支持公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图片约束：**
- 格式：JPEG、JPG、PNG（不支持 Alpha 通道）、BMP、WEBP。
- 分辨率：宽和高各自在 240 到 8000 像素之间，宽高比在 [1:8, 8:1] 范围内。
- 文件大小：最大 20 MB。
- 数量：每次请求最多 9 张图片。
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp
Wan27ImageParameters:
type: object
description: 图像处理参数。
properties:
size:
type: string
description: |-
输出图像分辨率。支持两种指定方式，不可同时使用。
**wan2.7-image-pro：**
- 方式一（推荐）：`1K`、`2K`（默认）或 `4K`。
- 适用范围：文生图（无图片输入，且非图像集生成模式）支持 1K、2K 和 4K；其他场景仅支持 1K 和 2K。
- 总像素数：1K = 1024×1024，2K = 2048×2048，4K = 4096×4096。
- 宽高比：有图片输入时，输出图像按最后一张输入图片的宽高比缩放到对应分辨率；无图片输入时，输出为正方形。
- 方式二：以 `width*height` 形式指定像素数，宽高比在 [1:8, 8:1] 范围内。
- 文生图：总像素数在 [768×768, 4096×4096] 范围内。
- 其他场景：总像素数在 [768×768, 2048×2048] 范围内。
**wan2.7-image：**
- 方式一（推荐）：`1K` 或 `2K`（默认），不支持 4K。
- 方式二：以 `width*height` 形式指定像素数。所有场景总像素数在 [768×768, 2048×2048] 范围内，宽高比在 [1:8, 8:1] 范围内。
输出图像的实际像素值可能与指定值略有差异。
example: 2K
n:
type: integer
description: |-
生成图像的数量。
**注意：** `n` 的值直接影响费用。费用 = 单价 × 成功生成的图像数量。
- 未启用图像集模式（`enable_sequential=false`）：表示生成图像的数量，范围 1–4，默认为 1。
- 启用图像集模式（`enable_sequential=true`）：表示最多生成的图像数量，范围 1–12，默认为 12。实际数量由模型决定，不超过 `n`。
minimum: 1
maximum: 12
default: 1
enable_sequential:
type: boolean
description: |-
控制图像生成模式。
- `false`：默认值。
- `true`：启用图像集输出模式。
default: false
thinking_mode:
type: boolean
description: 是否启用思考模式。默认为 `true`（启用）。仅在未启用图像集模式且无图片输入时生效。启用后，模型将增强推理能力以提升图像质量，但会增加生成时间。
default: true
bbox_list:
type: array
description: |-
交互式编辑的选区。
- 对应关系：列表长度必须与输入图片数量一致。若某张图片无需编辑，对应位置传入空列表 `[]`。
- 坐标格式：`[x1, y1, x2, y2]`（左上角 x、左上角 y、右下角 x、右下角 y），使用原始图片的绝对像素坐标，左上角为 (0, 0)。
- 限制：单张图片最多支持 2 个边界框。
items:
type: array
description: 单张输入图片的边界框列表。空数组表示无边界框。
items:
type: array
description: 单个边界框 [x1, y1, x2, y2]。
items:
type: integer
minItems: 4
maxItems: 4
maxItems: 2
color_palette:
type: array
description: 自定义色彩主题。由颜色（`hex`）和比例（`ratio`）对象组成的数组，须包含 3 到 10 种颜色（推荐设置为 8 种）。仅在未启用图像集模式（`enable_sequential=false`）时可用。
minItems: 3
maxItems: 10
items:
type: object
required:
- hex
- ratio
properties:
hex:
type: string
description: 十六进制（HEX）格式的颜色值。示例：`#C2D1E6`。
ratio:
type: string
description: 该颜色的占比，精确到小数点后两位（例如 `"25.00%"`）。所有 `ratio` 值之和必须为 100.00%。
example:
- hex: "#C2D1E6"
ratio: 60.00%
- hex: "#636574"
ratio: 25.00%
- hex: "#CBD4E4"
ratio: 15.00%
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子。有效范围：[0, 2147483647]。使用相同种子可生成相似结果。若不指定，算法将使用随机种子。注意：图像生成具有概率性，即使使用相同种子，结果也可能存在差异。
minimum: 0
maximum: 2147483647
Wan27ImageResponse:
type: object
description: Wan2.7 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 18790
output_tokens: 2
size: 2985*1405
total_tokens: 18792
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸（宽×高）。
example: 2985*1405
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan27ImageChoice:
type: object
properties:
finish_reason:
type: string
description: 生成完成的原因。
example: stop
message:
type: object
properties:
role:
type: string
example: assistant
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL。**URL 在 24 小时后失效，请及时下载保存。**
example: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type:
type: string
example: image
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交成功后返回的响应。
example:
request_id: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
task_id: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status: PENDING
properties:
request_id:
type: string
description: 唯一请求标识符。
example: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。用于轮询结果接口，24 小时内有效。
example: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status:
type: string
description: 初始任务状态。创建完成后始终为 `PENDING`。
example: PENDING
Wan27TaskStatusResponse:
type: object
description: 任务状态查询接口的响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
example: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。
example: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status:
type: string
description: 当前任务状态：`PENDING`（排队中）、`RUNNING`（处理中）、`SUCCEEDED`（已完成）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（任务 ID 无效或已过期）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: SUCCEEDED
submit_time:
type: string
description: 任务提交时间。
example: 2026-03-31 19:57:58.840
scheduled_time:
type: string
description: 任务调度时间。
example: 2026-03-31 19:57:58.877
end_time:
type: string
description: 任务完成时间。
example: 2026-03-31 19:58:11.563
finished:
type: boolean
description: 任务是否已结束。
example: true
choices:
type: array
description: 已生成的图像。仅在 `task_status` 为 `SUCCEEDED` 时存在。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
code:
type: string
description: 错误码。仅在 `task_status` 为 `FAILED` 时存在。
message:
type: string
description: 错误信息。仅在 `task_status` 为 `FAILED` 时存在。
usage:
type: object
description: 用量统计。仅在 `task_status` 为 `SUCCEEDED` 时存在。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸。
example: 2985*1405
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
example: InvalidParameter
message:
type: string
description: 错误信息。
example: Invalid parameter value
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wan27-image-gen-edit-synchronous.md
+814
View File
@@ -0,0 +1,814 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan 2.7 — 同步调用
> Wan 2.7 同步图像生成与编辑
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
该同步接口支持 **wan2.7-image-pro** 和 **wan2.7-image** 模型。通过单次请求即可直接获取生成的图像，无需轮询。
如需异步处理，请使用[异步提交](/api-reference/image-generation/wan27-image-gen-edit/create-task)接口。
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Wan2.7 图像生成与编辑 API
description: Wan2.7 图像生成与编辑 API，支持文生图、多图编辑、边界框交互式编辑以及图像集生成。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createWan27Image
summary: 同步生成或编辑图像
description: 使用 Wan2.7 同步生成或编辑图像。支持文生图、多图编辑、边界框交互式编辑和图像集生成。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27ImageRequest"
responses:
"200":
description: 图像已成功生成或编辑
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27ImageResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (text-to-image)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A serene mountain lake at sunrise, with mist rising from the water, surrounded by pine trees, photorealistic"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false,
"thinking_mode": true
}
}'
- lang: curl
label: cURL (image editing)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
},
{
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"
},
{
"text": "Spray the graffiti from image 2 onto the car in image 1"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false
}
}'
- lang: curl
label: cURL (interactive editing)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"
},
{
"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
},
{
"text": "Place the alarm clock from image 1 in the selected area of image 2, ensuring the scene and lighting blend naturally"
}
]
}
]
},
"parameters": {
"n": 1,
"size": "2K",
"watermark": false,
"bbox_list": [[], [[989, 515, 1138, 681]]]
}
}'
- lang: curl
label: cURL (image set generation)
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints."
}
]
}
]
},
"parameters": {
"enable_sequential": true,
"n": 4,
"size": "2K"
}
}'
- lang: python
label: Python - image editing (sync)
source: |-
import os
import base64
import mimetypes
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# 需要 SDK 版本 >= 1.25.15
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded_string}"
# 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
image_1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
image_2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"
# image_1 = "file:///path/to/your/car.png"
# image_1 = encode_file("/path/to/your/car.png")
message = Message(
role="user",
content=[
{"text": "Spray the graffiti from image 2 onto the car in image 1"},
{"image": image_1},
{"image": image_2}
]
)
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
model='wan2.7-image-pro',
api_key=api_key,
messages=[message],
n=1,
# wan2.7-image-pro 文生图支持 1K、2K 或 4K；
# 图像编辑和图像集生成最高支持 2K
size="2K",
watermark=False
)
print(rsp)
- lang: python
label: Python - image set generation (sync)
source: |-
import os
import base64
import mimetypes
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# 需要 SDK 版本 >= 1.25.15
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded_string}"
# 文生图像集（默认）
message = Message(
role="user",
content=[
{"text": "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints."}
]
)
# 图生图像集（取消注释后使用）
# 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
# image_1 = "https://example.com/your-image.png"
# image_1 = "file:///path/to/your/image.png"
# image_1 = encode_file("/path/to/your/image.png")
# message = Message(
# role="user",
# content=[
# {"text": "Generate a sequential image set based on the input image"},
# {"image": image_1}
# ]
# )
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
model='wan2.7-image-pro',
api_key=api_key,
messages=[message],
enable_sequential=True,
n=4,
# wan2.7-image-pro 文生图支持 1K、2K 或 4K；
# 图像编辑和图像集生成最高支持 2K
size="2K"
)
print(rsp)
- lang: java
label: Java - image editing (sync)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
/**
* wan2.7-image-pro 图像编辑 - 同步调用示例
* 需要 SDK 版本 >= 2.22.13
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static String encodeFile(String filePath) throws IOException {
byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
String base64String = Base64.getEncoder().encodeToString(fileContent);
String mimeType = Files.probeContentType(Paths.get(filePath));
return "data:" + mimeType + ";base64," + base64String;
}
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
// 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
String image1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp";
String image2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp";
// String image1 = "file:///path/to/your/car.png";
// String image1 = encodeFile("/path/to/your/car.png");
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Arrays.asList(
Collections.singletonMap("text", "Spray the graffiti from image 2 onto the car in image 1"),
Collections.singletonMap("image", image1),
Collections.singletonMap("image", image2)
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.7-image-pro")
.messages(Arrays.asList(message))
.n(1)
// wan2.7-image-pro 文生图支持 1K、2K 或 4K；
// 图像编辑和图像集生成最高支持 2K
.size("2K")
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---synchronous call for image editing, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - image set generation (sync)
source: |-
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
/**
* wan2.7-image-pro 图像集生成 - 同步调用示例
* 需要 SDK 版本 >= 2.22.13
*/
public class Main {
static {
Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
}
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static String encodeFile(String filePath) throws IOException {
byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
String base64String = Base64.getEncoder().encodeToString(fileContent);
String mimeType = Files.probeContentType(Paths.get(filePath));
return "data:" + mimeType + ";base64," + base64String;
}
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
// 文生图像集（默认）
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints.")
)).build();
// 图生图像集（取消注释后使用）
// 图片输入支持三种方式：公开 URL、本地文件路径、Base64 编码
// String image1 = "https://example.com/your-image.png";
// String image1 = "file:///path/to/your/image.png";
// String image1 = encodeFile("/path/to/your/image.png");
// ImageGenerationMessage message = ImageGenerationMessage.builder()
// .role("user")
// .content(Arrays.asList(
// Collections.singletonMap("text", "Generate a sequential image set based on the input image"),
// Collections.singletonMap("image", image1)
// )).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.7-image-pro")
.messages(Collections.singletonList(message))
.enableSequential(true)
.n(4)
// wan2.7-image-pro 文生图支持 1K、2K 或 4K；
// 图像编辑和图像集生成最高支持 2K
.size("2K")
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("----sync call, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
Wan27ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。可选值：wan2.7-image-pro、wan2.7-image。
enum:
- wan2.7-image-pro
- wan2.7-image
example: wan2.7-image-pro
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 请求内容数组。目前仅支持单轮对话，即只能传入一组 role 和 content 参数，不支持多轮对话。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan27ImageMessage"
parameters:
$ref: "#/components/schemas/Wan27ImageParameters"
Wan27ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: |-
消息内容数组。必须包含一个 `text` 对象和 0 到 9 个 `image` 对象。
使用多张图片时，在数组中放入多个 `image` 对象。图片顺序由数组位置决定。
items:
$ref: "#/components/schemas/Wan27ImageContentPart"
Wan27ImageContentPart:
type: object
description: 图片或文本内容部分。
properties:
text:
type: string
description: 用户输入的提示词。支持中英文。长度不超过 5000 个字符（每个中文字符、字母、数字或符号均计为一个字符，超出部分自动截断）。`content` 数组中必须包含且仅包含一个 `text` 对象。
maxLength: 5000
example: Spray the graffiti from image 2 onto the car in image 1
image:
type: string
description: |-
输入图片，支持公开 URL（HTTP/HTTPS）或 Base64 编码字符串（`data:{mime_type};base64,{data}`）。
**图片约束：**
- 格式：JPEG、JPG、PNG（不支持 Alpha 通道）、BMP、WEBP。
- 分辨率：宽和高各自在 240 到 8000 像素之间，宽高比在 [1:8, 8:1] 范围内。
- 文件大小：最大 20 MB。
- 数量：每次请求最多 9 张图片。
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp
Wan27ImageParameters:
type: object
description: 图像处理参数。
properties:
size:
type: string
description: |-
输出图像分辨率。支持两种指定方式，不可同时使用。
**wan2.7-image-pro：**
- 方式一（推荐）：`1K`、`2K`（默认）或 `4K`。
- 适用范围：文生图（无图片输入，且非图像集生成模式）支持 1K、2K 和 4K；其他场景仅支持 1K 和 2K。
- 总像素数：1K = 1024×1024，2K = 2048×2048，4K = 4096×4096。
- 宽高比：有图片输入时，输出图像按最后一张输入图片的宽高比缩放到对应分辨率；无图片输入时，输出为正方形。
- 方式二：以 `width*height` 形式指定像素数，宽高比在 [1:8, 8:1] 范围内。
- 文生图：总像素数在 [768×768, 4096×4096] 范围内。
- 其他场景：总像素数在 [768×768, 2048×2048] 范围内。
**wan2.7-image：**
- 方式一（推荐）：`1K` 或 `2K`（默认），不支持 4K。
- 方式二：以 `width*height` 形式指定像素数。所有场景总像素数在 [768×768, 2048×2048] 范围内，宽高比在 [1:8, 8:1] 范围内。
输出图像的实际像素值可能与指定值略有差异。
example: 2K
n:
type: integer
description: |-
生成图像的数量。
**注意：** `n` 的值直接影响费用。费用 = 单价 × 成功生成的图像数量。
- 未启用图像集模式（`enable_sequential=false`）：表示生成图像的数量，范围 1–4，默认为 1。
- 启用图像集模式（`enable_sequential=true`）：表示最多生成的图像数量，范围 1–12，默认为 12。实际数量由模型决定，不超过 `n`。
minimum: 1
maximum: 12
default: 1
enable_sequential:
type: boolean
description: |-
控制图像生成模式。
- `false`：默认值。
- `true`：启用图像集输出模式。
default: false
thinking_mode:
type: boolean
description: 是否启用思考模式。默认为 `true`（启用）。仅在未启用图像集模式且无图片输入时生效。启用后，模型将增强推理能力以提升图像质量，但会增加生成时间。
default: true
bbox_list:
type: array
description: |-
交互式编辑的选区。
- 对应关系：列表长度必须与输入图片数量一致。若某张图片无需编辑，对应位置传入空列表 `[]`。
- 坐标格式：`[x1, y1, x2, y2]`（左上角 x、左上角 y、右下角 x、右下角 y），使用原始图片的绝对像素坐标，左上角为 (0, 0)。
- 限制：单张图片最多支持 2 个边界框。
items:
type: array
description: 单张输入图片的边界框列表。空数组表示无边界框。
items:
type: array
description: 单个边界框 [x1, y1, x2, y2]。
items:
type: integer
minItems: 4
maxItems: 4
maxItems: 2
color_palette:
type: array
description: 自定义色彩主题。由颜色（`hex`）和比例（`ratio`）对象组成的数组，须包含 3 到 10 种颜色（推荐设置为 8 种）。仅在未启用图像集模式（`enable_sequential=false`）时可用。
minItems: 3
maxItems: 10
items:
type: object
required:
- hex
- ratio
properties:
hex:
type: string
description: 十六进制（HEX）格式的颜色值。示例：`#C2D1E6`。
ratio:
type: string
description: 该颜色的占比，精确到小数点后两位（例如 `"25.00%"`）。所有 `ratio` 值之和必须为 100.00%。
example:
- hex: "#C2D1E6"
ratio: 60.00%
- hex: "#636574"
ratio: 25.00%
- hex: "#CBD4E4"
ratio: 15.00%
watermark:
type: boolean
description: 在图像右下角添加固定文字水印"AI生成"。
default: false
seed:
type: integer
description: 随机数种子。有效范围：[0, 2147483647]。使用相同种子可生成相似结果。若不指定，算法将使用随机种子。注意：图像生成具有概率性，即使使用相同种子，结果也可能存在差异。
minimum: 0
maximum: 2147483647
Wan27ImageResponse:
type: object
description: Wan2.7 图像生成响应。
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 18790
output_tokens: 2
size: 2985*1405
total_tokens: 18792
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
finished:
type: boolean
description: 生成是否已完成。
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸（宽×高）。
example: 2985*1405
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan27ImageChoice:
type: object
properties:
finish_reason:
type: string
description: 生成完成的原因。
example: stop
message:
type: object
properties:
role:
type: string
example: assistant
content:
type: array
items:
type: object
properties:
image:
type: string
description: 生成图像的 URL。**URL 在 24 小时后失效，请及时下载保存。**
example: https://dashscope-result.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx
type:
type: string
example: image
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交成功后返回的响应。
example:
request_id: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
task_id: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status: PENDING
properties:
request_id:
type: string
description: 唯一请求标识符。
example: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。用于轮询结果接口，24 小时内有效。
example: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status:
type: string
description: 初始任务状态。创建完成后始终为 `PENDING`。
example: PENDING
Wan27TaskStatusResponse:
type: object
description: 任务状态查询接口的响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
example: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
type: object
properties:
task_id:
type: string
description: 任务标识符。
example: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status:
type: string
description: 当前任务状态：`PENDING`（排队中）、`RUNNING`（处理中）、`SUCCEEDED`（已完成）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（任务 ID 无效或已过期）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: SUCCEEDED
submit_time:
type: string
description: 任务提交时间。
example: 2026-03-31 19:57:58.840
scheduled_time:
type: string
description: 任务调度时间。
example: 2026-03-31 19:57:58.877
end_time:
type: string
description: 任务完成时间。
example: 2026-03-31 19:58:11.563
finished:
type: boolean
description: 任务是否已结束。
example: true
choices:
type: array
description: 已生成的图像。仅在 `task_status` 为 `SUCCEEDED` 时存在。
items:
$ref: "#/components/schemas/Wan27ImageChoice"
code:
type: string
description: 错误码。仅在 `task_status` 为 `FAILED` 时存在。
message:
type: string
description: 错误信息。仅在 `task_status` 为 `FAILED` 时存在。
usage:
type: object
description: 用量统计。仅在 `task_status` 为 `SUCCEEDED` 时存在。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数量。
output_tokens:
type: integer
description: 消耗的输出 token 数量。
total_tokens:
type: integer
description: 消耗的总 token 数量。
size:
type: string
description: 实际输出图像尺寸。
example: 2985*1405
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
example: InvalidParameter
message:
type: string
description: 错误信息。
example: Invalid parameter value
request_id:
type: string
description: 唯一请求标识符。
example: a3f4befe-cacd-49c9-8298-xxxxxx
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-sketch-to-image-create-task.md
+482
View File
@@ -0,0 +1,482 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 万相涂鸦作画 — 创建任务
> 提交涂鸦作画任务，获取任务 ID。
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.0.0
info:
title: 万相-涂鸦作画
description: 本文介绍万相-涂鸦作画模型的API输入输出参数。万相-涂鸦作画通过手绘图案和文字描述，生成精美的涂鸦绘画作品。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
security:
- ApiKeyAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
summary: 创建任务获取任务ID
description: 发起创建任务请求，该请求会返回任务ID（task_id）。图像模型处理时间较长，HTTP调用仅支持异步获取模型结果。
operationId: createSketchToImageTask
requestBody:
required: true
description: 创建涂鸦作画任务的请求体
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTaskRequest"
responses:
"200":
description: 成功创建任务
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTaskResponse"
examples:
success:
summary: 成功响应
value:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
error:
summary: 异常响应
value:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: cURL
label: curl
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-sketch-to-image-lite",
"input": {
"sketch_image_url": "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg",
"prompt": "一棵参天大树"
},
"parameters": {
"size": "768*768",
"n": 2,
"sketch_weight": 3,
"style": "<watercolor>"
}
}'
- lang: Python
label: Python SDK 同步调用
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "一棵参天大树"
sketch_image_url = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg"
model = "wanx-sketch-to-image-lite"
task = "image2image"
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=os.getenv("DASHSCOPE_API_KEY"),
model=model,
prompt=prompt,
n=1,
style='<watercolor>',
size='768*768',
sketch_image_url=sketch_image_url,
task=task)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: Python
label: Python SDK 异步调用
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "一棵参天大树"
sketch_image_url = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg"
model = "wanx-sketch-to-image-lite"
task = "image2image"
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=os.getenv("DASHSCOPE_API_KEY"),
model=model,
prompt=prompt,
n=1,
style='<watercolor>',
size='768*768',
sketch_image_url=sketch_image_url,
task=task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('create_async_task Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
def wait_async_task(task):
rsp = ImageSynthesis.wait(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: Java
label: Java SDK 同步调用
source: |-
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public void syncCall() {
String prompt = "一棵参天大树";
String sketchImageUrl = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg";
String model = "wanx-sketch-to-image-lite";
ImageSynthesisParam param = ImageSynthesisParam.builder()
.model(model)
.prompt(prompt)
.n(1)
.size("768*768")
.sketchImageUrl(sketchImageUrl)
.style("<watercolor>")
.build();
String task = "image2image";
ImageSynthesis imageSynthesis = new ImageSynthesis(task);
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.syncCall();
}
}
- lang: Java
label: Java SDK 异步调用
source: |-
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
public String createAsyncTask() {
String prompt = "一棵参天大树";
String sketchImageUrl = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg";
String model = "wanx-sketch-to-image-lite";
ImageSynthesisParam param = ImageSynthesisParam.builder()
.model(model)
.prompt(prompt)
.n(1)
.size("768*768")
.sketchImageUrl(sketchImageUrl)
.style("<watercolor>")
.build();
String task = "image2image";
ImageSynthesis imageSynthesis = new ImageSynthesis(task);
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.wait(taskId, null);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result.getOutput()));
System.out.println(JsonUtils.toJson(result.getUsage()));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.asyncCall();
}
}
components:
schemas:
CreateTaskRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 调用模型，固定为 wanx-sketch-to-image-lite。
example: wanx-sketch-to-image-lite
input:
$ref: "#/components/schemas/Input"
parameters:
$ref: "#/components/schemas/Parameters"
Input:
type: object
required:
- prompt
- sketch_image_url
description: 输入的基本信息，比如提示词、图像URL地址。
properties:
prompt:
type: string
description: 提示词，用来描述生成图像中期望包含的元素和视觉特点。支持中英文，长度不超过75个字符，超过部分会自动截断。
example: 一棵参天大树
sketch_image_url:
type: string
description: 输入草图的URL地址。输入草图需要与输出图像的分辨率比例保持一致，否则会导致图片拉伸变形，建议使用白色背景图。URL需为公网可访问的地址，并支持HTTP或HTTPS协议，URL地址中不能包含中文字符。图像格式支持JPG、JPEG、PNG、TIFF、WEBP。图像分辨率不小于256×256像素且不超过2048×2048像素。图像大小不超过10 MB。
Parameters:
type: object
description: 图像处理参数。
properties:
style:
type: string
description: 输出图像的风格。
enum:
- <auto>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
x-enumDescriptions:
<auto>: 默认值，由模型随机输出图像风格。
<3d cartoon>: 3D卡通。
<anime>: 二次元。
<oil painting>: 油画。
<watercolor>: 水彩。
<sketch>: 素描。
<chinese painting>: 中国画。
<flat illustration>: 扁平插画。
size:
type: string
description: 输出图像的分辨率。目前仅支持一种图像分辨率：768*768，且为默认值。
default: 768*768
n:
type: integer
description: 生成图片的数量。取值范围为1~4张，默认为4。
default: 4
minimum: 1
maximum: 4
sketch_weight:
type: integer
description: 输入草图对输出图像的约束程度。取值范围为0-10，取值间隔为1，默认值为10。取值越大表示输出图像跟输入草图越相似。
default: 10
minimum: 0
maximum: 10
sketch_extraction:
type: boolean
description: 如果上传图片是RGB图片，而非草图（sketch线稿），此参数可控制是否对输入图片进行sketch边缘提取。默认值为False，表示不进行提取。设置为True时，表示进行提取，此时sketch_color字段失效。
default: false
sketch_color:
type: array
description: 此字段在sketch_extraction=false时生效，所包含数值均被视为画笔色，其余数值均会视为背景色。模型会基于一种或多种画笔色描绘的区域生成新的画作。默认值为[]。当sketch_image_url线稿中的线条不是黑色，而是包含其他一种或多种颜色时，可以指定一个或多个RGB颜色数值作为画笔色。
default: []
items:
type: array
items:
type: integer
minItems: 3
maxItems: 3
example:
- - 134
- 134
- 134
- - 0
- 0
- 0
CreateTaskResponse:
type: object
properties:
output:
$ref: "#/components/schemas/CreateTaskOutput"
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
CreateTaskOutput:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
x-enumDescriptions:
PENDING: 任务排队中
RUNNING: 任务处理中
SUCCEEDED: 任务执行成功
FAILED: 任务执行失败
CANCELED: 任务已取消
UNKNOWN: 任务不存在或状态未知
QueryTaskResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
$ref: "#/components/schemas/QueryTaskOutput"
usage:
$ref: "#/components/schemas/Usage"
QueryTaskOutput:
type: object
description: 任务输出信息。任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的图像。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
x-enumDescriptions:
PENDING: 任务排队中
RUNNING: 任务处理中
SUCCEEDED: 任务执行成功
FAILED: 任务执行失败
CANCELED: 任务已取消
UNKNOWN: 任务不存在或状态未知
results:
type: array
description: 任务结果列表，包括图像URL、部分任务执行失败报错信息等。
items:
$ref: "#/components/schemas/ResultItem"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
ResultItem:
type: object
description: 单个任务结果。
properties:
url:
type: string
description: 生成图像的URL地址。
code:
type: string
description: 该任务结果失败的错误码。
message:
type: string
description: 该任务结果失败的详细信息。
TaskMetrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
Usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: token
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-sketch-to-image-query-result.md
+338
View File
@@ -0,0 +1,338 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 万相涂鸦作画 — 查询结果
> 通过任务 ID 查询涂鸦作画任务的状态和结果。
查询任务状态和生成结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wanx-sketch-to-image/create-task)接口提交请求，获取 `task_id`。
2. 每 **3 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: 万相-涂鸦作画
description: 本文介绍万相-涂鸦作画模型的API输入输出参数。万相-涂鸦作画通过手绘图案和文字描述，生成精美的涂鸦绘画作品。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
security:
- ApiKeyAuth: []
paths:
/tasks/{task_id}:
get:
summary: 根据任务ID查询结果
description: 使用任务ID查询任务状态及结果。任务成功执行时将返回图像URL，有效期24小时。
operationId: getSketchToImageTaskResult
parameters:
- name: task_id
in: path
required: true
description: 任务ID。查询有效期24小时。
schema:
type: string
responses:
"200":
description: 成功查询任务
content:
application/json:
schema:
$ref: "#/components/schemas/QueryTaskResponse"
examples:
succeeded:
summary: 任务执行成功
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238846
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png
task_metrics:
TOTAL: 2
SUCCEEDED: 2
FAILED: 0
usage:
image_count: 2
failed:
summary: 任务执行失败
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: FAILED
code: InvalidParameter
message: The size is not match the allowed size ['1024*1024', '720*1280', '1280*720']
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 4
partial_failed:
summary: 任务部分失败
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238846
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- code: InternalError.Timeout
message: An internal timeout error has occurred during execution, please try again later or contact service support.
task_metrics:
TOTAL: 2
SUCCEEDED: 1
FAILED: 1
usage:
image_count: 1
running:
summary: 任务处理中
value:
request_id: c5d70b02-ebd3-98ce-9fe8-759d7d7b107e
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 2
SUCCEEDED: 0
FAILED: 0
x-codeSamples:
- lang: cURL
label: curl
source: |-
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
schemas:
CreateTaskRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 调用模型，固定为 wanx-sketch-to-image-lite。
example: wanx-sketch-to-image-lite
input:
$ref: "#/components/schemas/Input"
parameters:
$ref: "#/components/schemas/Parameters"
Input:
type: object
required:
- prompt
- sketch_image_url
description: 输入的基本信息，比如提示词、图像URL地址。
properties:
prompt:
type: string
description: 提示词，用来描述生成图像中期望包含的元素和视觉特点。支持中英文，长度不超过75个字符，超过部分会自动截断。
example: 一棵参天大树
sketch_image_url:
type: string
description: 输入草图的URL地址。输入草图需要与输出图像的分辨率比例保持一致，否则会导致图片拉伸变形，建议使用白色背景图。URL需为公网可访问的地址，并支持HTTP或HTTPS协议，URL地址中不能包含中文字符。图像格式支持JPG、JPEG、PNG、TIFF、WEBP。图像分辨率不小于256×256像素且不超过2048×2048像素。图像大小不超过10 MB。
Parameters:
type: object
description: 图像处理参数。
properties:
style:
type: string
description: 输出图像的风格。
enum:
- <auto>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
x-enumDescriptions:
<auto>: 默认值，由模型随机输出图像风格。
<3d cartoon>: 3D卡通。
<anime>: 二次元。
<oil painting>: 油画。
<watercolor>: 水彩。
<sketch>: 素描。
<chinese painting>: 中国画。
<flat illustration>: 扁平插画。
size:
type: string
description: 输出图像的分辨率。目前仅支持一种图像分辨率：768*768，且为默认值。
default: 768*768
n:
type: integer
description: 生成图片的数量。取值范围为1~4张，默认为4。
default: 4
minimum: 1
maximum: 4
sketch_weight:
type: integer
description: 输入草图对输出图像的约束程度。取值范围为0-10，取值间隔为1，默认值为10。取值越大表示输出图像跟输入草图越相似。
default: 10
minimum: 0
maximum: 10
sketch_extraction:
type: boolean
description: 如果上传图片是RGB图片，而非草图（sketch线稿），此参数可控制是否对输入图片进行sketch边缘提取。默认值为False，表示不进行提取。设置为True时，表示进行提取，此时sketch_color字段失效。
default: false
sketch_color:
type: array
description: 此字段在sketch_extraction=false时生效，所包含数值均被视为画笔色，其余数值均会视为背景色。模型会基于一种或多种画笔色描绘的区域生成新的画作。默认值为[]。当sketch_image_url线稿中的线条不是黑色，而是包含其他一种或多种颜色时，可以指定一个或多个RGB颜色数值作为画笔色。
default: []
items:
type: array
items:
type: integer
minItems: 3
maxItems: 3
example:
- - 134
- 134
- 134
- - 0
- 0
- 0
CreateTaskResponse:
type: object
properties:
output:
$ref: "#/components/schemas/CreateTaskOutput"
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
CreateTaskOutput:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
x-enumDescriptions:
PENDING: 任务排队中
RUNNING: 任务处理中
SUCCEEDED: 任务执行成功
FAILED: 任务执行失败
CANCELED: 任务已取消
UNKNOWN: 任务不存在或状态未知
QueryTaskResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
$ref: "#/components/schemas/QueryTaskOutput"
usage:
$ref: "#/components/schemas/Usage"
QueryTaskOutput:
type: object
description: 任务输出信息。任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的图像。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
x-enumDescriptions:
PENDING: 任务排队中
RUNNING: 任务处理中
SUCCEEDED: 任务执行成功
FAILED: 任务执行失败
CANCELED: 任务已取消
UNKNOWN: 任务不存在或状态未知
results:
type: array
description: 任务结果列表，包括图像URL、部分任务执行失败报错信息等。
items:
$ref: "#/components/schemas/ResultItem"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
ResultItem:
type: object
description: 单个任务结果。
properties:
url:
type: string
description: 生成图像的URL地址。
code:
type: string
description: 该任务结果失败的错误码。
message:
type: string
description: 该任务结果失败的详细信息。
TaskMetrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
Usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: token
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-style-repaint-create-task.md
+365
View File
@@ -0,0 +1,365 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人像风格重绘 — 创建任务
> 异步人像风格重绘
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
将人像照片转换为多种艺术风格，同时保留面部特征和构图。支持预设风格和自定义参考图风格。
本 API 仅支持异步调用模式，暂不提供 SDK。
## OpenAPI
````yaml post /services/aigc/image-generation/generation
openapi: 3.1.0
info:
title: 人像风格重绘 API
description: 人像风格重绘模型支持将人物照片转换为多种预设或自定义的艺术风格。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API 端点
security:
- BearerAuth: []
paths:
/services/aigc/image-generation/generation:
post:
operationId: createWanxStyleRepaint
summary: 创建人像风格重绘任务
description: 创建人像风格重绘任务，获取唯一任务ID（task_id）。本模型采用异步模式，提交任务后需轮询获取结果。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 异步处理配置参数。HTTP请求只支持异步，必须设置为 `enable`。缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WanxStyleRepaintRequest"
responses:
"200":
description: 任务提交成功。请保存 task_id，用于查询任务状态与结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: Invalid request parameters.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败。API Key 无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: 使用预置风格
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-style-repaint-v1",
"input": {
"image_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/image_demo_input.png",
"style_index": 3
}
}'
- lang: curl
label: 使用自定义风格
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-style-repaint-v1",
"input": {
"image_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/input_example.png",
"style_ref_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/style_example.png",
"style_index": -1
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxStyleRepaintRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。示例值：wanx-style-repaint-v1。
enum:
- wanx-style-repaint-v1
example: wanx-style-repaint-v1
input:
$ref: "#/components/schemas/WanxStyleRepaintInput"
WanxStyleRepaintInput:
type: object
required:
- image_url
- style_index
description: 输入图像的基本信息，比如图像URL地址。
properties:
image_url:
type: string
description: |-
输入的图像URL地址。
- 支持公网可访问的HTTP/HTTPS地址，不包含中文字符。
- 支持传入Base64编码字符串。
- 对于本地文件，可通过以下方式获取合法参数值：
- 获取URL：请参见上传文件获取临时URL。
- 生成Base64编码字符串：请参见图像Base64编码传值方式。
**图像限制：**
- 图像分辨率：不低于256×256像素，不超过5760×3240像素。
- 图像格式：JPEG、PNG、JPG、BMP、WEBP。
- 图像比例：长短边比例不超过2:1。
- 图像大小：不超过10M。
- 图像质量：为确保生成质量，请上传脸部清晰照片，人脸比例不宜过小，并避免夸张姿势和表情。
example: https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/image_demo_input.png
style_index:
type: integer
description: |-
选择一个预置的风格索引值，即可生成风格化人像。
**枚举值：**
- `-1`：使用参考图像风格（需提供 `style_ref_url`）
- `0`：复古漫画
- `1`：3D童话
- `2`：二次元
- `3`：小清新
- `4`：未来科技
- `5`：国画古风
- `6`：将军百战
- `7`：炫彩卡通
- `8`：清雅国风
- `9`：喜迎新年
- `14`：国风工笔
- `15`：恭贺新禧
- `30`：童话世界
- `31`：黏土世界
- `32`：像素世界
- `33`：冒险世界
- `34`：日漫世界
- `35`：3D世界
- `36`：二次元世界
- `37`：手绘世界
- `38`：蜡笔世界
- `39`：冰箱贴世界
- `40`：吧唧世界
enum:
- -1
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 14
- 15
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
example: 3
style_ref_url:
type: string
description: |-
风格参考图像URL地址。当 `style_index=-1` 时必须传入，其他风格无需传入。
- 支持公网可访问的HTTP/HTTPS地址，不包含中文字符。
- 支持传入Base64编码字符串。
- 对于本地文件，可通过以下方式获取合法参数值：
- 获取URL：请参见上传文件获取临时URL。
- 生成Base64编码字符串：请参见图像Base64编码传值方式。
**图像限制：**
- 图像分辨率：不低于256×256像素且不超过5760×3240像素。
- 图像比例：为取得最佳效果，建议图像长短边比例不超过2:1，否则可能影响生成或导致报错。
- 图像格式：JPEG、PNG、JPG、BMP、WEBP。
- 图像大小：不超过10M。
example: https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/style_example.png
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
StyleRepaintTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
start_time:
type: string
description: 任务开始时间。
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
style_index:
type: integer
description: 返回指定所选风格的索引值。
error_code:
type: integer
description: 错误码。正常请求时返回，可忽略。
error_message:
type: string
description: 错误信息。正常请求时返回，可忽略。
results:
type: array
description: 任务结果列表，包括图像URL、prompt、部分任务执行失败报错信息等。
items:
type: object
properties:
url:
type: string
description: 生成的图像URL地址。有效期为24小时，请及时下载并保存。
orig_prompt:
type: string
description: 原始prompt。
actual_prompt:
type: string
description: 实际使用的prompt。
code:
type: string
description: 部分任务执行失败的错误码。
message:
type: string
description: 部分任务执行失败的错误信息。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码，标识错误类型。
message:
type: string
description: 错误详细信息。
request_id:
type: string
description: 请求唯一标识，用于排查问题。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-style-repaint-query-result.md
+384
View File
@@ -0,0 +1,384 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 人像风格重绘 — 查询结果
> 查询人像风格重绘任务状态
查询任务状态和结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wanx-style-repaint/create-task)接口提交请求，获取 `task_id`。
2. 每 **3 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## 错误码
| 错误码 | HTTP 状态码 | 说明 |
| ------------------------ | -------- | ------------------------------------------------------- |
| `InvalidURL` | 400 | 图片 URL 无效或无法访问。请检查 URL 是否可公开访问。 |
| `InvalidImageFormat` | 400 | 图片格式不支持。支持的格式：JPEG、JPG、PNG、BMP、WEBP。 |
| `InvalidImageResolution` | 400 | 图片分辨率过大或过小。宽高最小 256 像素，最大不超过 5760×3240 像素，长短边比例不超过 2:1。 |
## 常见问题
**图片报错 InvalidImageFormat 怎么办？**
请确保图片格式为 JPEG、JPG、PNG、BMP 或 WEBP。如果后缀名正确但仍报错，请检查文件实际编码格式是否与后缀名一致。
**输出图片的尺寸是多少？**
输出图片的短边固定为 1536 像素，长边根据原图比例自动计算。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 人像风格重绘 API
description: 人像风格重绘模型支持将人物照片转换为多种预设或自定义的艺术风格。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API 端点
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWanxStyleRepaintTaskStatus
summary: 查询人像风格重绘任务结果
description: 使用 task_id 轮询任务状态，直至完成并获取生成的图像URL。图像URL有效期为24小时。模型耗时约15秒，建议采用轮询机制并设置合理的查询间隔（如3秒）。
parameters:
- name: task_id
in: path
required: true
description: 任务ID。创建任务接口返回的唯一标识。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/StyleRepaintTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: f7fee4f1-1f68-9f17-85df-xxxxx
output:
task_id: 316c7af0-e91f-476f-99bd-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-08-12 10:55:43.768
scheduled_time: 2025-08-12 10:55:43.799
end_time: 2025-08-12 10:55:48
error_message: Success
start_time: 2025-08-12 10:55:43
style_index: 0
error_code: 0
results:
- url: https://oss.aliyuncs.com/xxx/abc.jpg
usage:
image_count: 1
FAILED:
summary: 任务执行失败
value:
request_id: a3b4c5d6-e7f8-9012-abcd-xxxxxx
output:
task_id: 1a2b3c4d-5e6f-7890-bcde-xxxxxx
task_status: FAILED
submit_time: 2025-08-12 10:55:43.768
scheduled_time: 2025-08-12 10:55:43.799
end_time: 2025-08-12 10:55:44
code: InvalidImageResolution
message: The input image resolution is too large or small
usage:
image_count: 0
RUNNING:
summary: 任务执行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 1
FAILED: 0
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
# 将 {task_id} 替换为上一步接口返回的 task_id 的值
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxStyleRepaintRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。示例值：wanx-style-repaint-v1。
enum:
- wanx-style-repaint-v1
example: wanx-style-repaint-v1
input:
$ref: "#/components/schemas/WanxStyleRepaintInput"
WanxStyleRepaintInput:
type: object
required:
- image_url
- style_index
description: 输入图像的基本信息，比如图像URL地址。
properties:
image_url:
type: string
description: |-
输入的图像URL地址。
- 支持公网可访问的HTTP/HTTPS地址，不包含中文字符。
- 支持传入Base64编码字符串。
- 对于本地文件，可通过以下方式获取合法参数值：
- 获取URL：请参见上传文件获取临时URL。
- 生成Base64编码字符串：请参见图像Base64编码传值方式。
**图像限制：**
- 图像分辨率：不低于256×256像素，不超过5760×3240像素。
- 图像格式：JPEG、PNG、JPG、BMP、WEBP。
- 图像比例：长短边比例不超过2:1。
- 图像大小：不超过10M。
- 图像质量：为确保生成质量，请上传脸部清晰照片，人脸比例不宜过小，并避免夸张姿势和表情。
example: https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/image_demo_input.png
style_index:
type: integer
description: |-
选择一个预置的风格索引值，即可生成风格化人像。
**枚举值：**
- `-1`：使用参考图像风格（需提供 `style_ref_url`）
- `0`：复古漫画
- `1`：3D童话
- `2`：二次元
- `3`：小清新
- `4`：未来科技
- `5`：国画古风
- `6`：将军百战
- `7`：炫彩卡通
- `8`：清雅国风
- `9`：喜迎新年
- `14`：国风工笔
- `15`：恭贺新禧
- `30`：童话世界
- `31`：黏土世界
- `32`：像素世界
- `33`：冒险世界
- `34`：日漫世界
- `35`：3D世界
- `36`：二次元世界
- `37`：手绘世界
- `38`：蜡笔世界
- `39`：冰箱贴世界
- `40`：吧唧世界
enum:
- -1
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 14
- 15
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
example: 3
style_ref_url:
type: string
description: |-
风格参考图像URL地址。当 `style_index=-1` 时必须传入，其他风格无需传入。
- 支持公网可访问的HTTP/HTTPS地址，不包含中文字符。
- 支持传入Base64编码字符串。
- 对于本地文件，可通过以下方式获取合法参数值：
- 获取URL：请参见上传文件获取临时URL。
- 生成Base64编码字符串：请参见图像Base64编码传值方式。
**图像限制：**
- 图像分辨率：不低于256×256像素且不超过5760×3240像素。
- 图像比例：为取得最佳效果，建议图像长短边比例不超过2:1，否则可能影响生成或导致报错。
- 图像格式：JPEG、PNG、JPG、BMP、WEBP。
- 图像大小：不超过10M。
example: https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/style_example.png
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
StyleRepaintTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务ID。查询有效期24小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
start_time:
type: string
description: 任务开始时间。
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
style_index:
type: integer
description: 返回指定所选风格的索引值。
error_code:
type: integer
description: 错误码。正常请求时返回，可忽略。
error_message:
type: string
description: 错误信息。正常请求时返回，可忽略。
results:
type: array
description: 任务结果列表，包括图像URL、prompt、部分任务执行失败报错信息等。
items:
type: object
properties:
url:
type: string
description: 生成的图像URL地址。有效期为24小时，请及时下载并保存。
orig_prompt:
type: string
description: 原始prompt。
actual_prompt:
type: string
description: 实际使用的prompt。
code:
type: string
description: 部分任务执行失败的错误码。
message:
type: string
description: 部分任务执行失败的错误信息。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码，标识错误类型。
message:
type: string
description: 错误详细信息。
request_id:
type: string
description: 请求唯一标识，用于排查问题。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-v1-text-to-image-create-task.md
+816
View File
@@ -0,0 +1,816 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# wanx-v1 — 创建文生图任务
> wanx-v1 异步图像生成
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
<Note>
**wanx-v1 已停止迭代更新**，推荐升级至 [Wan 文生图 V2](/api-reference/image-generation/wan-text-to-image-v2/create-task) 以获取更好的效果。
</Note>
## OpenAPI
````yaml post /services/aigc/text2image/image-synthesis
openapi: 3.1.0
info:
title: Wan 文生图 V1 API
description: 使用 wanx-v1 模型根据文本描述生成图像。本 API 采用异步任务模式：先通过 POST 请求提交任务，再通过 GET 请求轮询结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 阿里云 DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/text2image/image-synthesis:
post:
operationId: createWanxV1TextToImageTask
summary: 创建文生图任务
description: 提交 wanx-v1 文生图异步任务。提交后通过 GET /tasks/{task_id} 轮询获取结果。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: 必须设置为 `enable` 以创建异步任务。如未设置，将返回错误："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
- name: X-DashScope-WorkSpace
in: header
required: false
description: 指定工作空间，格式为 `ws_{workspaceId}`。
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WanxV1TextToImageRequest"
responses:
"200":
description: 任务创建成功。
content:
application/json:
schema:
$ref: "#/components/schemas/WanxV1CreateTaskResponse"
examples:
success:
summary: 任务创建成功
value:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
4XX:
description: 请求失败。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
error:
summary: 请求失败示例
value:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: cURL - 文字作画（正向提示词）
source: |-
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx-v1",
"input": {
"prompt": "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
},
"parameters": {
"style": "<auto>",
"size": "1024*1024",
"n": 1
}
}'
- lang: curl
label: cURL - 文字作画（正向+反向提示词）
source: |-
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx-v1",
"input": {
"prompt": "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。",
"negative_prompt": "不要使用红色元素"
},
"parameters": {
"style": "<auto>",
"size": "1024*1024",
"n": 1
}
}'
- lang: curl
label: cURL - 参考图生成（基于参考图内容）
source: |-
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx-v1",
"input": {
"prompt": "一个英气的黑发女人，飞舞着金色的蝴蝶，背景中有若隐若现的水墨竹林，高细节，高质量。",
"ref_img": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/rguyzt/girl.png"
},
"parameters": {
"style": "<auto>",
"size": "1024*1024",
"n": 1,
"ref_strength": 1.0,
"ref_mode": "repaint"
}
}'
- lang: curl
label: cURL - 参考图生成（基于参考图风格）
source: |-
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "wanx-v1",
"input": {
"prompt": "有一只黑色的小猫",
"ref_img": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/gpqnqy/house.png"
},
"parameters": {
"style": "<auto>",
"size": "1024*1024",
"n": 1,
"ref_strength": 0.7,
"ref_mode": "refonly"
}
}'
- lang: python
label: Python - 同步调用 - 文字作画
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model=ImageSynthesis.Models.wanx_v1,
prompt=prompt,
n=1,
style='<watercolor>',
size='1024*1024'
)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
# 在当前目录下保存图片
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: python
label: Python - 同步调用 - 参考图生成
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
# 上传参考图方式：url链接和本地路径二选一
# 若两者存在，ref_img参数优先级更高
# 使用公网url链接
ref_img = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/rguyzt/girl.png"
# 使用本地文件路径
sketch_image_url = './girl.png'
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model=ImageSynthesis.Models.wanx_v1,
prompt=prompt,
n=1,
style='<auto>',
size='1024*1024',
ref_mode='repaint',
ref_strength=1.0,
# sketch_image_url=sketch_image_url,
ref_img=ref_img
)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
# 保留图片到当前目录
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: python
label: Python - 异步调用 - 文字作画
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
# 创建异步任务
def create_async_task():
rsp = ImageSynthesis.async_call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model=ImageSynthesis.Models.wanx_v1,
prompt=prompt,
n=1,
style='<watercolor>',
size='1024*1024'
)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# 等待异步任务结束
def wait_async_task(task):
rsp = ImageSynthesis.wait(task, api_key=os.getenv("DASHSCOPE_API_KEY"))
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
# 获取异步任务信息
def fetch_task_status(task):
status = ImageSynthesis.fetch(task, api_key=os.getenv("DASHSCOPE_API_KEY"))
print(status)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
# 取消异步任务，只有处于PENDING状态的任务才可以取消
def cancel_task(task):
rsp = ImageSynthesis.cancel(task, api_key=os.getenv("DASHSCOPE_API_KEY"))
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: python
label: Python - 异步调用 - 参考图生成
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。"
# 上传参考图方式：url链接和本地路径二选一
# 若两者存在，ref_img参数优先级更高
# 使用公网url链接
ref_img = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/rguyzt/girl.png"
# 使用本地文件路径
sketch_image_url = './girl.png'
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
# 创建异步任务
def create_async_task():
rsp = ImageSynthesis.async_call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model=ImageSynthesis.Models.wanx_v1,
prompt=prompt,
n=1,
style='<auto>',
size='1024*1024',
ref_mode='repaint',
ref_strength=1.0,
# sketch_image_url=sketch_image_url,
ref_img=ref_img
)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('create_async_task Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# 等待异步任务结束
def wait_async_task(task):
rsp = ImageSynthesis.wait(task, api_key=os.getenv("DASHSCOPE_API_KEY"))
print(rsp)
if rsp.status_code == HTTPStatus.OK:
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: java
label: Java - 同步调用 - 文字作画
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void basicCall() throws ApiException, NoApiKeyException {
String prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。";
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(ImageSynthesis.Models.WANX_V1)
.prompt(prompt)
.style("<watercolor>")
.n(1)
.size("1024*1024")
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void listTask() throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public void fetchTask() throws ApiException, NoApiKeyException {
String taskId = "your task id";
ImageSynthesis is = new ImageSynthesis();
// If set DASHSCOPE_API_KEY environment variable, apiKey can null.
ImageSynthesisResult result = is.fetch(taskId, null);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args){
try{
basicCall();
//listTask();
}catch(ApiException|NoApiKeyException e){
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - 同步调用 - 相似图生成
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
public class Main {
public void syncCall() {
String prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。";
//使用公网url链接
String refImage = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/rguyzt/girl.png";
HashMap<String,Object> parameters = new HashMap<>();
parameters.put("ref_strength", 0.5);
parameters.put("ref_mode", "repaint");
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(ImageSynthesis.Models.WANX_V1)
.prompt(prompt)
.style("<auto>")
.n(1)
.size("1024*1024")
.refImage(refImage)
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException|NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.syncCall();
}
}
- lang: java
label: Java - 异步调用 - 文字作画
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* 创建异步任务
* @return taskId
*/
public String createAsyncTask() {
String prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。";
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(ImageSynthesis.Models.WANX_V1)
.prompt(prompt)
.style("<watercolor>")
.n(1)
.size("1024*1024")
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* 等待异步任务结束
* @param taskId 任务id
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
//环境变量配置后，可在这里将apiKey设置为null
result = imageSynthesis.wait(taskId, null);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void main(String[] args){
Main main = new Main();
main.asyncCall();
}
}
- lang: java
label: Java - 异步调用 - 相似图生成
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* 创建异步任务
* @return taskId
*/
public String createAsyncTask() {
String prompt = "近景镜头，18岁的中国女孩，古代服饰，圆脸，正面看着镜头，民族优雅的服装，商业摄影，室外，电影级光照，半身特写，精致的淡妆，锐利的边缘。";
String refImage = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241031/rguyzt/girl.png";
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(ImageSynthesis.Models.WANX_V1)
.prompt(prompt)
.style("<auto>")
.n(1)
.size("1024*1024")
.refImage(refImage)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* 等待异步任务结束
* @param taskId 任务id
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
// If you have set the DASHSCOPE_API_KEY in the system environment variable, the apiKey can be null.
result = imageSynthesis.wait(taskId, null);
} catch (ApiException|NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.asyncCall();
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxV1TextToImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
example: wanx-v1
input:
type: object
required:
- prompt
description: 输入内容。
properties:
prompt:
type: string
description: 正向文本描述，即期望图像中出现的内容。最大 800 个字符。
maxLength: 800
negative_prompt:
type: string
description: 反向文本描述，即不希望图像中出现的内容。最大 500 个字符。
maxLength: 500
ref_img:
type: string
description: 参考图像 URL。支持 JPG、PNG、BMP、TIFF、WEBP 格式，大小不超过 10 MB，分辨率在 256×256 至 4096×4096 之间，URL 不能包含中文字符。
parameters:
type: object
description: 生成参数（可选）。
properties:
style:
type: string
description: 图像风格。
enum:
- <auto>
- <photography>
- <portrait>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
size:
type: string
description: 图像分辨率，格式为 `宽*高`。
enum:
- 1024*1024
- 720*1280
- 768*1152
- 1280*720
default: 1024*1024
n:
type: integer
description: 生成图像数量。
minimum: 1
maximum: 4
default: 4
seed:
type: integer
description: 随机种子，用于结果复现。范围 [0, 2147483647]。
minimum: 0
maximum: 2147483647
ref_strength:
type: number
description: 参考图强度，控制生成图像与参考图的相似程度。范围 [0.0, 1.0]，值越大越相似。
minimum: 0
maximum: 1
ref_mode:
type: string
description: 参考图模式。`repaint` 基于参考图内容生成，`refonly` 基于参考图风格生成。
enum:
- repaint
- refonly
default: repaint
WanxV1CreateTaskResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。有效期 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。
WanxV1TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: 任务状态：`PENDING`（等待）、`RUNNING`（运行中）、`SUCCEEDED`（成功）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（未知）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
results:
type: array
description: 生成的图像列表。任务成功后返回。
items:
type: object
properties:
url:
type: string
description: 图像 URL，有效期 24 小时，请及时下载。
code:
type: string
description: 当该图像生成失败时，返回错误码。
message:
type: string
description: 当该图像生成失败时，返回错误信息。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
code:
type: string
description: 任务失败时的错误码。
message:
type: string
description: 任务失败时的错误信息。
usage:
type: object
description: 资源用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-v1-text-to-image-query-result.md
+320
View File
@@ -0,0 +1,320 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# wanx-v1 — 查询结果
> 查询 wanx-v1 图像生成任务状态
查询任务状态并获取生成的图像。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wanx-v1-text-to-image/create-task)接口提交任务，获取 `task_id`。
2. 每 **5 秒**轮询一次，直到 `output.task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，从 `output.results[].url` 获取图像链接。
## 注意事项
- **URL 有效期**：生成的图像 URL 有效期为 **24 小时**，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED`、`FAILED`、`CANCELED` 或 `UNKNOWN`。
- **任务 ID 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: Wan 文生图 V1 API
description: 使用 wanx-v1 模型根据文本描述生成图像。本 API 采用异步任务模式：先通过 POST 请求提交任务，再通过 GET 请求轮询结果。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 阿里云 DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWanxV1TaskResult
summary: 查询任务结果
description: 查询异步文生图任务的状态和结果。每 5 秒轮询一次，直到 `output.task_status` 为 `SUCCEEDED` 或 `FAILED`。
parameters:
- name: task_id
in: path
required: true
description: 任务 ID，由创建任务接口返回的 `output.task_id`。
schema:
type: string
responses:
"200":
description: 查询成功。
content:
application/json:
schema:
$ref: "#/components/schemas/WanxV1TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238846
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png
task_metrics:
TOTAL: 2
SUCCEEDED: 2
FAILED: 0
usage:
image_count: 2
SUCCEEDED_PARTIAL:
summary: 任务成功（部分图像生成失败）
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238847
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- code: InternalError.Timeout
message: An internal timeout error has occurred during execution, please try again later or contact service support.
task_metrics:
TOTAL: 2
SUCCEEDED: 1
FAILED: 1
usage:
image_count: 1
FAILED:
summary: 任务失败
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: FAILED
code: InvalidParameter
message: The size is not match the allowed size ['1024*1024', '720*1280', '768*1152', '1280*720']
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 4
RUNNING:
summary: 任务执行中
value:
request_id: f3a91c2d-7b6e-4d5f-a8c2-xxxxxx
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 0
PENDING:
summary: 任务等待中
value:
request_id: c826b6cd-e3f4-4a6f-b3b1-xxxxxx
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: PENDING
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 0
4XX:
description: 请求失败。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxV1TextToImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
example: wanx-v1
input:
type: object
required:
- prompt
description: 输入内容。
properties:
prompt:
type: string
description: 正向文本描述，即期望图像中出现的内容。最大 800 个字符。
maxLength: 800
negative_prompt:
type: string
description: 反向文本描述，即不希望图像中出现的内容。最大 500 个字符。
maxLength: 500
ref_img:
type: string
description: 参考图像 URL。支持 JPG、PNG、BMP、TIFF、WEBP 格式，大小不超过 10 MB，分辨率在 256×256 至 4096×4096 之间，URL 不能包含中文字符。
parameters:
type: object
description: 生成参数（可选）。
properties:
style:
type: string
description: 图像风格。
enum:
- <auto>
- <photography>
- <portrait>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
size:
type: string
description: 图像分辨率，格式为 `宽*高`。
enum:
- 1024*1024
- 720*1280
- 768*1152
- 1280*720
default: 1024*1024
n:
type: integer
description: 生成图像数量。
minimum: 1
maximum: 4
default: 4
seed:
type: integer
description: 随机种子，用于结果复现。范围 [0, 2147483647]。
minimum: 0
maximum: 2147483647
ref_strength:
type: number
description: 参考图强度，控制生成图像与参考图的相似程度。范围 [0.0, 1.0]，值越大越相似。
minimum: 0
maximum: 1
ref_mode:
type: string
description: 参考图模式。`repaint` 基于参考图内容生成，`refonly` 基于参考图风格生成。
enum:
- repaint
- refonly
default: repaint
WanxV1CreateTaskResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。有效期 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。
WanxV1TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: 任务状态：`PENDING`（等待）、`RUNNING`（运行中）、`SUCCEEDED`（成功）、`FAILED`（失败）、`CANCELED`（已取消）、`UNKNOWN`（未知）。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
results:
type: array
description: 生成的图像列表。任务成功后返回。
items:
type: object
properties:
url:
type: string
description: 图像 URL，有效期 24 小时，请及时下载。
code:
type: string
description: 当该图像生成失败时，返回错误码。
message:
type: string
description: 当该图像生成失败时，返回错误信息。
task_metrics:
type: object
description: 任务统计信息。
properties:
TOTAL:
type: integer
description: 图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
code:
type: string
description: 任务失败时的错误码。
message:
type: string
description: 任务失败时的错误信息。
usage:
type: object
description: 资源用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-x-painting-create-task.md
+548
View File
@@ -0,0 +1,548 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wanx — 创建任务
> 异步 wanx-x-painting 图像局部重绘
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装 SDK](/api-reference/preparation/install-sdk)。
</Note>
<Warning>
wanx-x-painting 模型当前仅提供免费体验，免费额度用完后不可调用且不支持付费。免费额度详情请参见[免费额度](/resources/free-quota)。
</Warning>
通过指定掩码区域，使用文本提示词对图像进行局部重绘。支持多种风格，包括 3D 卡通、动画、油画、水彩、素描、中国画和扁平插画。
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.1.0
info:
title: 万相-图像局部重绘 API
description: 图像局部重绘 API。根据用户输入的原始图片、掩码图和 prompt 提示词，在涂抹区域生成与文字描述相对应的内容，而涂抹区域外的部分则基本保持不变。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API 端点
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createWanxXPaintingTask
summary: 创建图像局部重绘任务
description: 创建图像局部重绘任务，使用 wanx-x-painting 模型。根据输入的原始图片、掩码图和提示词，在掩码标记的区域内生成新的图像内容。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: |-
异步处理配置参数。HTTP 请求只支持异步，必须设置为 `enable`。
**重要：** 缺少此请求头将报错："current user api does not support synchronous calls"。
schema:
type: string
enum:
- enable
default: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WanxXPaintingRequest"
responses:
"200":
description: 任务提交成功。使用 `task_id` 轮询获取结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
example:
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidParameter
message: Invalid request parameters.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
"401":
description: 认证失败。API 密钥无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
example:
code: InvalidApiKey
message: No API-key provided.
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-x-painting",
"input": {
"prompt": "一只狗戴着红色眼镜",
"base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
"mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
},
"parameters": {
"size": "1024*1024",
"n": 1
}
}'
- lang: python
label: Python SDK - 同步调用
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
prompt = "一只狗戴着红色眼镜"
model = "wanx-x-painting"
task = "image2image"
extra_input = {
"base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
"mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
}
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(model=model,
prompt=prompt,
n=1,
size='1024*1024',
task=task,
extra_input=extra_input)
if rsp.status_code == HTTPStatus.OK:
print(rsp)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: python
label: Python SDK - 异步调用
source: |-
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
prompt = "一只狗戴着红色眼镜"
model = "wanx-x-painting"
task = "image2image"
extra_input = {
"base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
"mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
}
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
def create_async_task():
rsp = ImageSynthesis.async_call(model=model,
prompt=prompt,
n=1,
size='1024*1024',
task=task,
extra_input=extra_input)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('create_async_task Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
def wait_async_task(task):
rsp = ImageSynthesis.wait(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
- lang: java
label: Java SDK - 同步调用
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
public class Main {
public void syncCall() {
String task = "image2image";
ImageSynthesis imageSynthesis = new ImageSynthesis(task);
ImageSynthesisParam param = genImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
private ImageSynthesisParam genImageSynthesis(){
HashMap<String,Object> extraInputMap = new HashMap<>();
extraInputMap.put("base_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg");
extraInputMap.put("mask_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png");
String prompt = "一只狗戴着红色眼镜";
String model = "wanx-x-painting";
return ImageSynthesisParam.builder()
.model(model)
.prompt(prompt)
.n(1)
.size("1024*1024")
.extraInputs(extraInputMap)
.build();
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.syncCall();
}
}
- lang: java
label: Java SDK - 异步调用
source: |-
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
public class Main {
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
public String createAsyncTask() {
String task = "image2image";
ImageSynthesis imageSynthesis = new ImageSynthesis(task);
ImageSynthesisParam param = genImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
private ImageSynthesisParam genImageSynthesis(){
String prompt = "一只狗戴着红色眼镜";
String model = "wanx-x-painting";
HashMap<String,Object> extraInputMap = new HashMap<>();
extraInputMap.put("base_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg");
extraInputMap.put("mask_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png");
return ImageSynthesisParam.builder()
.model(model)
.prompt(prompt)
.n(1)
.size("1024*1024")
.extraInputs(extraInputMap)
.build();
}
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.wait(taskId, null);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result.getOutput()));
System.out.println(JsonUtils.toJson(result.getUsage()));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.asyncCall();
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxXPaintingRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。示例值：wanx-x-painting。
enum:
- wanx-x-painting
example: wanx-x-painting
input:
$ref: "#/components/schemas/WanxXPaintingInput"
parameters:
$ref: "#/components/schemas/WanxXPaintingParameters"
WanxXPaintingInput:
type: object
required:
- prompt
- base_image_url
- mask_image_url
description: 输入的基本信息，如提示词、图像 URL 等。
properties:
prompt:
type: string
description: |-
正向提示词，用来描述生成图像中期望包含的元素和视觉特点。
支持中英文，长度不超过 75 个字符，超过部分会自动截断。
maxLength: 75
example: 一只狗戴着红色眼镜
base_image_url:
type: string
description: |-
输入图像 URL 地址，不支持填写图像 Base64 数据。
URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。
**图像限制：**
- 图像格式：JPG、JPEG、PNG、BMP。
- 图像分辨率：大于 256×256 像素，小于 4096×4096 像素。
- 图像大小：不超过 10 MB。
- URL 地址中不能包含中文字符。
example: http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg
mask_image_url:
type: string
description: |-
用户标记涂抹区域的图像 URL 地址，需要和 base_image_url 图像分辨率保持一致。不支持填写图像 Base64 数据。
URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。
**图像限制：**
- 图像格式：JPG、JPEG、PNG、BMP。
- 图像分辨率：大于 256×256 像素，小于 4096×4096 像素。
- 图像大小：不超过 10 MB。
- URL 地址中不能包含中文字符。
example: http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png
WanxXPaintingParameters:
type: object
description: 图像处理参数。
properties:
style:
type: string
description: |-
输出图像的风格。目前支持以下风格取值：
- `<auto>`：默认。
- `<3d cartoon>`：3D 卡通。
- `<anime>`：动画。
- `<oil painting>`：油画。
- `<watercolor>`：水彩。
- `<sketch>`：素描。
- `<chinese painting>`：中国画。
- `<flat illustration>`：扁平插画。
enum:
- <auto>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
example: <auto>
size:
type: string
description: |-
输出图像的分辨率。目前支持 3 种图像分辨率：
- `1024*1024`：默认值。
- `720*1280`
- `1280*720`
enum:
- 1024*1024
- 720*1280
- 1280*720
default: 1024*1024
example: 1024*1024
n:
type: integer
description: 生成图片的数量。取值范围为 1~4 张，默认为 1。
minimum: 1
maximum: 4
default: 1
example: 1
mask_color:
type: array
description: |-
RGB 颜色数值列表，用于指定掩码图片中表示涂抹区域的颜色。默认值为 []。
当该字段为空，默认对掩码图片进行二值化处理（处理后白色代表涂抹区域）。当该字段非空时，表示 RGB 颜色数值列表，代表一种或多种颜色。这些 RGB 颜色所描绘的区域即为涂抹区域，如 [0,0,0] 和 [134,134,134]，而未被指定的颜色则视为背景色。
示例值：[[0, 0, 0], [134, 134, 134]]。
items:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 3
maxItems: 3
example:
- - 0
- 0
- 0
- - 134
- 134
- 134
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
WanxXPaintingTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
description: |-
任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行成功
- FAILED：任务执行失败
- CANCELED：任务已取消
- UNKNOWN：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
results:
type: array
description: 任务结果列表，包括图像 URL、部分任务执行失败报错信息等。
items:
type: object
properties:
url:
type: string
description: 生成的图像 URL。有效期 24 小时。
code:
type: string
description: 该条结果请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 该条结果请求失败的详细信息。请求成功时不会返回此参数。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息文档。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息文档。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 标识错误类型的错误码。
message:
type: string
description: 详细的错误信息。
request_id:
type: string
description: 用于排查问题的请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wanx-x-painting-query-result.md
+369
View File
@@ -0,0 +1,369 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Wanx — 查询局部重绘结果
> 查询 wanx-x-painting 图像局部重绘任务状态
查询任务状态和结果。
## 轮询策略
1. 通过[创建任务](/api-reference/image-generation/wanx-x-painting/create-task)接口提交请求，获取 `task_id`。
2. 每 **10 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，`results` 中包含图片下载 URL。
## 注意事项
- **URL 有效期**：图片 URL 在 **24 小时**后过期，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。
- **其他状态**：`CANCELED`（任务已取消）、`UNKNOWN`（`task_id` 无效或已过期）。
- **`task_id` 有效期**：`task_id` 有效期为 **24 小时**，过期后无法查询任务状态和结果。
- **避免重复提交**：请通过轮询获取结果，不要重复提交请求。
- **部分失败**：当 `n > 1` 时，只要有一张图片生成成功，任务状态即为 `SUCCEEDED`。失败的图片会在 `results` 中包含错误详情，仅成功的图片计入用量。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: 万相-图像局部重绘 API
description: 图像局部重绘 API。根据用户输入的原始图片、掩码图和 prompt 提示词，在涂抹区域生成与文字描述相对应的内容，而涂抹区域外的部分则基本保持不变。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API 端点
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWanxXPaintingTaskStatus
summary: 查询任务结果
description: 查询图像局部重绘任务的状态和结果。任务数据（如任务状态、图像 URL 等）仅保留 24 小时，超时后会被自动清除。请务必及时保存生成的图像。
parameters:
- name: task_id
in: path
required: true
description: 任务标识符，由创建任务接口返回。
schema:
type: string
responses:
"200":
description: 成功获取任务状态。
content:
application/json:
schema:
$ref: "#/components/schemas/WanxXPaintingTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238846
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png
task_metrics:
TOTAL: 2
SUCCEEDED: 2
FAILED: 0
usage:
image_count: 2
FAILED:
summary: 任务执行失败
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: FAILED
code: InvalidParameter
message: The size is not match the allowed size ['1024*1024', '720*1280', '1280*720']
task_metrics:
TOTAL: 4
SUCCEEDED: 0
FAILED: 4
PARTIAL_FAILURE:
summary: 任务部分失败
value:
request_id: 85eaba38-0185-99d7-8d16-4d9135238846
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: SUCCEEDED
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
- code: InternalError.Timeout
message: An internal timeout error has occurred during execution, please try again later or contact service support.
task_metrics:
TOTAL: 2
SUCCEEDED: 1
FAILED: 1
usage:
image_count: 1
RUNNING:
summary: 任务处理中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: RUNNING
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 查询任务结果
source: |-
# 将 {task_id} 替换为创建任务接口返回的实际 task_id
curl -X GET 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WanxXPaintingRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。示例值：wanx-x-painting。
enum:
- wanx-x-painting
example: wanx-x-painting
input:
$ref: "#/components/schemas/WanxXPaintingInput"
parameters:
$ref: "#/components/schemas/WanxXPaintingParameters"
WanxXPaintingInput:
type: object
required:
- prompt
- base_image_url
- mask_image_url
description: 输入的基本信息，如提示词、图像 URL 等。
properties:
prompt:
type: string
description: |-
正向提示词，用来描述生成图像中期望包含的元素和视觉特点。
支持中英文，长度不超过 75 个字符，超过部分会自动截断。
maxLength: 75
example: 一只狗戴着红色眼镜
base_image_url:
type: string
description: |-
输入图像 URL 地址，不支持填写图像 Base64 数据。
URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。
**图像限制：**
- 图像格式：JPG、JPEG、PNG、BMP。
- 图像分辨率：大于 256×256 像素，小于 4096×4096 像素。
- 图像大小：不超过 10 MB。
- URL 地址中不能包含中文字符。
example: http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg
mask_image_url:
type: string
description: |-
用户标记涂抹区域的图像 URL 地址，需要和 base_image_url 图像分辨率保持一致。不支持填写图像 Base64 数据。
URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。
**图像限制：**
- 图像格式：JPG、JPEG、PNG、BMP。
- 图像分辨率：大于 256×256 像素，小于 4096×4096 像素。
- 图像大小：不超过 10 MB。
- URL 地址中不能包含中文字符。
example: http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png
WanxXPaintingParameters:
type: object
description: 图像处理参数。
properties:
style:
type: string
description: |-
输出图像的风格。目前支持以下风格取值：
- `<auto>`：默认。
- `<3d cartoon>`：3D 卡通。
- `<anime>`：动画。
- `<oil painting>`：油画。
- `<watercolor>`：水彩。
- `<sketch>`：素描。
- `<chinese painting>`：中国画。
- `<flat illustration>`：扁平插画。
enum:
- <auto>
- <3d cartoon>
- <anime>
- <oil painting>
- <watercolor>
- <sketch>
- <chinese painting>
- <flat illustration>
default: <auto>
example: <auto>
size:
type: string
description: |-
输出图像的分辨率。目前支持 3 种图像分辨率：
- `1024*1024`：默认值。
- `720*1280`
- `1280*720`
enum:
- 1024*1024
- 720*1280
- 1280*720
default: 1024*1024
example: 1024*1024
n:
type: integer
description: 生成图片的数量。取值范围为 1~4 张，默认为 1。
minimum: 1
maximum: 4
default: 1
example: 1
mask_color:
type: array
description: |-
RGB 颜色数值列表，用于指定掩码图片中表示涂抹区域的颜色。默认值为 []。
当该字段为空，默认对掩码图片进行二值化处理（处理后白色代表涂抹区域）。当该字段非空时，表示 RGB 颜色数值列表，代表一种或多种颜色。这些 RGB 颜色所描绘的区域即为涂抹区域，如 [0,0,0] 和 [134,134,134]，而未被指定的颜色则视为背景色。
示例值：[[0, 0, 0], [134, 134, 134]]。
items:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 3
maxItems: 3
example:
- - 0
- 0
- 0
- - 134
- 134
- 134
AsyncTaskSubmitResponse:
type: object
properties:
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
description: 任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
WanxXPaintingTaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
description: |-
任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行成功
- FAILED：任务执行失败
- CANCELED：任务已取消
- UNKNOWN：任务不存在或状态未知
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
results:
type: array
description: 任务结果列表，包括图像 URL、部分任务执行失败报错信息等。
items:
type: object
properties:
url:
type: string
description: 生成的图像 URL。有效期 24 小时。
code:
type: string
description: 该条结果请求失败的错误码。请求成功时不会返回此参数。
message:
type: string
description: 该条结果请求失败的详细信息。请求成功时不会返回此参数。
task_metrics:
type: object
description: 任务结果统计。
properties:
TOTAL:
type: integer
description: 总的任务数。
SUCCEEDED:
type: integer
description: 任务状态为成功的任务数。
FAILED:
type: integer
description: 任务状态为失败的任务数。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息文档。
message:
type: string
description: 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息文档。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 标识错误类型的错误码。
message:
type: string
description: 详细的错误信息。
request_id:
type: string
description: 用于排查问题的请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wordart-semantic-create-task.md
+276
View File
@@ -0,0 +1,276 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 文字变形 — 创建任务
> 提交文字变形异步任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## 模型信息
| 模型 | 描述 |
| ------------------ | -------------------------- |
| `wordart-semantic` | 文字变形模型，根据提示词对文字边缘轮廓进行语义化变形 |
## 输出说明
模型生成的图片为**黑底白色蒙版**，包含 PNG 和 SVG 两种格式。
## 字体列表
通过 `font_name` 参数指定预设字体，或通过 `ttf_url` 参数传入自定义字体文件（两者不可同时使用）。
| 参数值 | 字体名称 |
| ------------------ | -------- |
| `dongfangdakai` | 东方大楷 |
| `puhuiti_m` | 普惠体 |
| `shuheiti` | 书黑体 |
| `jinbuti` | 金簿体 |
| `kuheiti` | 酷黑体 |
| `kuaileti` | 快乐体 |
| `wenyiti` | 文艺体 |
| `logoti` | Logo体 |
| `cangeryuyangti_m` | 仓耳渔阳体 |
| `siyuansongti_b` | 思源宋体 |
| `siyuanheiti_m` | 思源黑体 |
| `fangzhengkaiti` | 方正楷体（默认） |
## OpenAPI
````yaml post /services/aigc/wordart/semantic
openapi: 3.1.0
info:
title: WordArt Semantic API
version: 1.0.0
description: WordArt 锦书-文字变形 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/services/aigc/wordart/semantic:
post:
summary: 提交文字变形任务
operationId: createWordArtSemanticTask
parameters:
- name: X-DashScope-Async
in: header
required: true
schema:
type: string
enum:
- enable
description: 启用异步模式。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WordArtSemanticRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 提交文字变形任务
source: |-
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/wordart/semantic' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data-raw '{
"model": "wordart-semantic",
"input": {
"text": "文字创意",
"prompt": "水果，蔬菜，温暖的色彩空间"
},
"parameters": {
"steps": 80,
"n": 2,
"output_image_ratio": "1024x1024",
"font_name": "dongfangdakai"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WordArtSemanticRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- wordart-semantic
description: 模型名称。
input:
type: object
required:
- text
- prompt
description: 输入参数。
properties:
text:
type: string
description: 用户输入的文字内容。
prompt:
type: string
maxLength: 200
description: 描述提示词，1-200 个字。用于描述文字变形的风格和元素。
parameters:
type: object
description: 模型参数。
properties:
n:
type: integer
minimum: 1
maximum: 4
default: 4
description: 生成的图片数量，取值范围 1~4，默认 4。
steps:
type: integer
minimum: 10
maximum: 100
default: 30
description: 变形迭代次数，数字越大文字变化程度越大。取值范围 10~100，默认 30。
font_name:
type: string
enum:
- dongfangdakai
- puhuiti_m
- shuheiti
- jinbuti
- kuheiti
- kuaileti
- wenyiti
- logoti
- cangeryuyangti_m
- siyuansongti_b
- siyuanheiti_m
- fangzhengkaiti
description: 字体类型。不指定则使用默认字体（方正楷体）。与 `ttf_url` 不能同时使用。
ttf_url:
type: string
description: 自定义 TTF 字体文件 URL，文件大小需小于 30 MB。与 `font_name` 不能同时使用。
output_image_ratio:
type: string
enum:
- 1280x720
- 720x1280
- 1024x1024
default: 1280x720
description: 输出图片比例。默认 `1280x720`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: 任务状态。
results:
type: array
items:
type: object
properties:
png_url:
type: string
description: 生成的 PNG 格式图片 URL。
svg_url:
type: string
description: 生成的 SVG 格式图片 URL。
code:
type: string
description: 单张图片的错误码（仅在该图片生成失败时返回）。
message:
type: string
description: 单张图片的错误信息（仅在该图片生成失败时返回）。
description: 生成结果列表，每个元素包含 `png_url` 和 `svg_url`。部分图片可能因内容安全审核失败，此时返回 `code` 和 `message`。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wordart-semantic-query-result.md
+287
View File
@@ -0,0 +1,287 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 文字变形 — 查询结果
> 查询文字变形任务状态
查询任务状态并获取生成的文字变形图片。
## 轮询策略
1. 通过[提交文字变形任务](/api-reference/image-generation/wordart-semantic/create-task)接口提交任务，获取 `task_id`。
2. 每 **5 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，从 `results` 中获取 `png_url` 和 `svg_url`。
## 响应字段说明
任务成功后，`results` 数组中每个元素包含以下字段：
| 字段 | 说明 |
| --------- | ----------------------- |
| `png_url` | 生成的 PNG 格式图片 URL |
| `svg_url` | 生成的 SVG 格式图片 URL |
| `code` | 单张图片的错误码（仅在该图片生成失败时返回） |
| `message` | 单张图片的错误信息（仅在该图片生成失败时返回） |
## 注意事项
- **部分失败**：当 `n > 1` 时，部分图片可能因内容安全审核未通过而失败，此时对应元素返回 `code` 和 `message`，其余图片正常返回。
- **URL 有效期**：生成的图片 URL 有效期为 **24 小时**，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED`、`FAILED` 或 `UNKNOWN`。
- **任务 ID 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: WordArt Semantic API
version: 1.0.0
description: WordArt 锦书-文字变形 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
summary: 查询文字变形结果
operationId: getWordArtSemanticTaskResult
parameters:
- name: task_id
in: path
required: true
schema:
type: string
description: 任务 ID，由[提交文字变形任务](/api-reference/image-generation/wordart-semantic/create-task)接口返回。
responses:
"200":
description: 任务状态查询结果
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: SUCCEEDED
results:
- png_url: https://xxx/1.png
svg_url: https://xxx/1.svg
- png_url: https://xxx/2.png
svg_url: https://xxx/2.svg
- code: DataInspectionFailed
message: The output image may contain inappropriate content.
- png_url: https://xxx/4.png
svg_url: https://xxx/4.svg
usage:
image_count: 3
FAILED:
summary: 任务失败
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: FAILED
code: xxx
message: xxxxxx
RUNNING:
summary: 任务运行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
task_metrics:
TOTAL: 2
SUCCEEDED: 0
FAILED: 0
PENDING:
summary: 任务排队中
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: PENDING
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WordArtSemanticRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- wordart-semantic
description: 模型名称。
input:
type: object
required:
- text
- prompt
description: 输入参数。
properties:
text:
type: string
description: 用户输入的文字内容。
prompt:
type: string
maxLength: 200
description: 描述提示词，1-200 个字。用于描述文字变形的风格和元素。
parameters:
type: object
description: 模型参数。
properties:
n:
type: integer
minimum: 1
maximum: 4
default: 4
description: 生成的图片数量，取值范围 1~4，默认 4。
steps:
type: integer
minimum: 10
maximum: 100
default: 30
description: 变形迭代次数，数字越大文字变化程度越大。取值范围 10~100，默认 30。
font_name:
type: string
enum:
- dongfangdakai
- puhuiti_m
- shuheiti
- jinbuti
- kuheiti
- kuaileti
- wenyiti
- logoti
- cangeryuyangti_m
- siyuansongti_b
- siyuanheiti_m
- fangzhengkaiti
description: 字体类型。不指定则使用默认字体（方正楷体）。与 `ttf_url` 不能同时使用。
ttf_url:
type: string
description: 自定义 TTF 字体文件 URL，文件大小需小于 30 MB。与 `font_name` 不能同时使用。
output_image_ratio:
type: string
enum:
- 1280x720
- 720x1280
- 1024x1024
default: 1280x720
description: 输出图片比例。默认 `1280x720`。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: 任务状态。
results:
type: array
items:
type: object
properties:
png_url:
type: string
description: 生成的 PNG 格式图片 URL。
svg_url:
type: string
description: 生成的 SVG 格式图片 URL。
code:
type: string
description: 单张图片的错误码（仅在该图片生成失败时返回）。
message:
type: string
description: 单张图片的错误信息（仅在该图片生成失败时返回）。
description: 生成结果列表，每个元素包含 `png_url` 和 `svg_url`。部分图片可能因内容安全审核失败，此时返回 `code` 和 `message`。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wordart-texture-create-task.md
+376
View File
@@ -0,0 +1,376 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创意文字纹理 — 创建任务
> 提交创意文字纹理生成异步任务
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
## 模型信息
| 模型 | 描述 |
| ----------------- | ---------- |
| `wordart-texture` | 创意文字纹理生成模型 |
## 输入模式
支持两种互斥的输入模式：
| 模式 | 说明 |
| ------- | ------------------------- |
| `image` | 图片输入模式，传入黑底白字的文字图片 |
| `text` | 文字输入模式，直接传入文字内容（最多 6 个字符） |
## 纹理风格
通过 `texture_style` 参数指定纹理风格，或通过 `ref_image_url` 传入参考风格图片（将覆盖 `texture_style` 设置）。
**自定义风格**：`material`（立体材质）、`scene`（场景融合）、`lighting`（光影特效）
**预设风格**：`waterfall`、`snow_plateau`、`forest`、`sky`、`chinese_building`、`cartoon`、`lego`、`flower`、`acrylic`、`marble`、`felt`、`oil_painting`、`watercolor_painting`、`chinese_painting`、`claborate_style_painting`、`city_night`、`mountain_lake`、`autumn_leaves`、`green_dragon`、`red_dragon`
## 注意事项
- **QPS 限制**：单账户（含主账号与 RAM 子账号）任务下发接口限制 QPS 为 2，并发任务数量限制为 1。
## OpenAPI
````yaml post /services/aigc/wordart/texture
openapi: 3.1.0
info:
title: WordArt Texture Generation API
version: 1.0.0
description: 创意文字纹理生成 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/services/aigc/wordart/texture:
post:
summary: 生成文字纹理
operationId: createWordArtTextureTask
parameters:
- name: X-DashScope-Async
in: header
required: true
schema:
type: string
enum:
- enable
description: 启用异步模式。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WordArtTextureRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求错误
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: 图片输入
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wordart-texture",
"input": {
"image": {
"image_url": "https://dmshared-new.oss-cn-hangzhou.aliyuncs.com/junyan.hjy/wordart/lcy/example.png"
},
"prompt": "水果，蔬菜，温暖的色彩空间",
"texture_style": "material"
},
"parameters": {
"image_short_size": 704,
"n": 2,
"alpha_channel": false
}
}'
- lang: curl
label: 文字输入
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wordart-texture",
"input": {
"text": {
"text_content": "文字创意",
"font_name": "dongfangdakai",
"output_image_ratio": "1:1"
},
"prompt": "水果，蔬菜，温暖的色彩空间",
"texture_style": "material"
},
"parameters": {
"image_short_size": 704,
"n": 2,
"alpha_channel": false
}
}'
- lang: curl
label: 参考图片输入
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "wordart-texture",
"input": {
"text": {
"text_content": "文字创意",
"font_name": "dongfangdakai",
"output_image_ratio": "16:9"
},
"prompt": "鲜花",
"ref_image_url": "https://dmshared-new.oss-cn-hangzhou.aliyuncs.com/0ximian/transfer_20230801/new_design/tmp/wordposter/ref_images/flower2.png"
},
"parameters": {
"image_short_size": 704,
"n": 2,
"alpha_channel": false
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WordArtTextureRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- wordart-texture
description: 模型名称。
input:
type: object
required:
- prompt
description: 输入参数。
properties:
image:
type: object
description: 图片输入模式，与 `text` 互斥。传入黑底白字的文字图片。
properties:
image_url:
type: string
description: 文字图片 URL。要求：黑底白字、小于 5M、支持 jpg/png/jpeg/bmp、宽高比不超过 2:1、长边不超过 2048 像素。
required:
- image_url
text:
type: object
description: 文字输入模式，与 `image` 互斥。直接传入文字内容。
properties:
text_content:
type: string
maxLength: 6
description: 文字内容，最多 6 个字符，支持中文、阿拉伯数字和英文。
ttf_url:
type: string
description: 自定义字体文件 URL（TTF 格式，小于 30M），与 `font_name` 互斥。
font_name:
type: string
enum:
- dongfangdakai
- puhuiti_m
- shuheiti
- jinbuti
- kuheiti
- kuaileti
- wenyiti
- logoti
- cangeryuyangti_m
- siyuansongti_b
- siyuanheiti_m
- fangzhengkaiti
default: dongfangdakai
description: 预设字体名称，与 `ttf_url` 互斥。默认为 `dongfangdakai`。
output_image_ratio:
type: string
enum:
- 1:1
- 16:9
- 9:16
default: 1:1
description: 输出图片宽高比，默认 `1:1`。
required:
- text_content
prompt:
type: string
maxLength: 200
description: 纹理描述文本，最多 200 个字符，不能为空字符串。
texture_style:
type: string
enum:
- material
- scene
- lighting
- waterfall
- snow_plateau
- forest
- sky
- chinese_building
- cartoon
- lego
- flower
- acrylic
- marble
- felt
- oil_painting
- watercolor_painting
- chinese_painting
- claborate_style_painting
- city_night
- mountain_lake
- autumn_leaves
- green_dragon
- red_dragon
default: material
description: 纹理风格。自定义风格：`material`（立体材质）、`scene`（场景融合）、`lighting`（光影特效）。预设风格：`waterfall`、`snow_plateau`、`forest`、`sky`、`chinese_building`、`cartoon`、`lego`、`flower`、`acrylic`、`marble`、`felt`、`oil_painting`、`watercolor_painting`、`chinese_painting`、`claborate_style_painting`、`city_night`、`mountain_lake`、`autumn_leaves`、`green_dragon`、`red_dragon`。
ref_image_url:
type: string
description: 参考风格图片 URL。传入后将覆盖 `texture_style` 设置。
parameters:
type: object
description: 模型参数。
properties:
image_short_size:
type: integer
minimum: 512
maximum: 1024
default: 704
description: 生成图片短边长度，取值范围 [512, 1024]，必须为 64 的倍数，默认 704。
n:
type: integer
minimum: 1
maximum: 4
default: 1
description: 生成图片数量，取值范围 1~4，默认 1。
alpha_channel:
type: boolean
default: false
description: 是否生成透明背景图片，默认 false。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: 当前任务状态。状态流转：PENDING → RUNNING → SUCCEEDED 或 FAILED。UNKNOWN 表示任务不存在或查询已超过 24 小时。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
results:
type: array
items:
type: object
properties:
url:
type: string
description: 生成的图片 URL。
description: 生成结果列表，每个元素包含一张图片的 URL。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-wordart-texture-query-result.md
+328
View File
@@ -0,0 +1,328 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创意文字纹理 — 查询结果
> 查询创意文字纹理生成任务的状态和结果
查询任务状态并获取生成的文字纹理图片。
## 轮询策略
1. 通过[提交创意文字纹理任务](/api-reference/image-generation/wordart-texture/create-task)接口提交任务，获取 `task_id`。
2. 每 **5 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
3. 任务成功后，从 `results` 数组中获取各图片的 `url`。
## 注意事项
- **URL 有效期**：生成的图片 URL 有效期为 **24 小时**，请及时下载。
- **任务状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED`、`FAILED` 或 `UNKNOWN`。
- **任务 ID 有效期**：`task_id` 有效期为 24 小时，过期后无法查询状态和结果。
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.1.0
info:
title: WordArt Texture Generation API
version: 1.0.0
description: 创意文字纹理生成 API
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 千问AI平台
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
summary: 查询文字纹理生成结果
operationId: getWordArtTextureTaskResult
parameters:
- name: task_id
in: path
required: true
schema:
type: string
description: 任务 ID，由[生成文字纹理](/api-reference/image-generation/wordart-texture/create-task)接口返回。
responses:
"200":
description: 任务状态查询结果
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务成功
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: SUCCEEDED
submit_time: 2025-08-15 10:46:20.054
scheduled_time: 2025-08-15 10:46:20.087
end_time: 2025-08-15 10:46:27.768
results:
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/1.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/2.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/3.jpg
- url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/4.jpg
usage:
image_count: 4
FAILED:
summary: 任务失败
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: FAILED
code: InvalidParameter
message: The request is missing required parameters or the parameters are out of the specified range
RUNNING:
summary: 任务运行中
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: RUNNING
submit_time: 2025-08-15 10:46:20.054
scheduled_time: 2025-08-15 10:46:20.087
task_metrics:
TOTAL: 2
SUCCEEDED: 1
FAILED: 0
PENDING:
summary: 任务排队中
value:
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status: PENDING
x-codeSamples:
- lang: curl
label: 查询任务结果
source: |-
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
WordArtTextureRequest:
type: object
required:
- model
- input
- parameters
properties:
model:
type: string
enum:
- wordart-texture
description: 模型名称。
input:
type: object
required:
- prompt
description: 输入参数。
properties:
image:
type: object
description: 图片输入模式，与 `text` 互斥。传入黑底白字的文字图片。
properties:
image_url:
type: string
description: 文字图片 URL。要求：黑底白字、小于 5M、支持 jpg/png/jpeg/bmp、宽高比不超过 2:1、长边不超过 2048 像素。
required:
- image_url
text:
type: object
description: 文字输入模式，与 `image` 互斥。直接传入文字内容。
properties:
text_content:
type: string
maxLength: 6
description: 文字内容，最多 6 个字符，支持中文、阿拉伯数字和英文。
ttf_url:
type: string
description: 自定义字体文件 URL（TTF 格式，小于 30M），与 `font_name` 互斥。
font_name:
type: string
enum:
- dongfangdakai
- puhuiti_m
- shuheiti
- jinbuti
- kuheiti
- kuaileti
- wenyiti
- logoti
- cangeryuyangti_m
- siyuansongti_b
- siyuanheiti_m
- fangzhengkaiti
default: dongfangdakai
description: 预设字体名称，与 `ttf_url` 互斥。默认为 `dongfangdakai`。
output_image_ratio:
type: string
enum:
- 1:1
- 16:9
- 9:16
default: 1:1
description: 输出图片宽高比，默认 `1:1`。
required:
- text_content
prompt:
type: string
maxLength: 200
description: 纹理描述文本，最多 200 个字符，不能为空字符串。
texture_style:
type: string
enum:
- material
- scene
- lighting
- waterfall
- snow_plateau
- forest
- sky
- chinese_building
- cartoon
- lego
- flower
- acrylic
- marble
- felt
- oil_painting
- watercolor_painting
- chinese_painting
- claborate_style_painting
- city_night
- mountain_lake
- autumn_leaves
- green_dragon
- red_dragon
default: material
description: 纹理风格。自定义风格：`material`（立体材质）、`scene`（场景融合）、`lighting`（光影特效）。预设风格：`waterfall`、`snow_plateau`、`forest`、`sky`、`chinese_building`、`cartoon`、`lego`、`flower`、`acrylic`、`marble`、`felt`、`oil_painting`、`watercolor_painting`、`chinese_painting`、`claborate_style_painting`、`city_night`、`mountain_lake`、`autumn_leaves`、`green_dragon`、`red_dragon`。
ref_image_url:
type: string
description: 参考风格图片 URL。传入后将覆盖 `texture_style` 设置。
parameters:
type: object
description: 模型参数。
properties:
image_short_size:
type: integer
minimum: 512
maximum: 1024
default: 704
description: 生成图片短边长度，取值范围 [512, 1024]，必须为 64 的倍数，默认 704。
n:
type: integer
minimum: 1
maximum: 4
default: 1
description: 生成图片数量，取值范围 1~4，默认 1。
alpha_channel:
type: boolean
default: false
description: 是否生成透明背景图片，默认 false。
AsyncTaskSubmitResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
task_status:
type: string
enum:
- PENDING
description: 任务状态。
TaskStatusResponse:
type: object
properties:
request_id:
type: string
description: 请求唯一标识。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: 当前任务状态。状态流转：PENDING → RUNNING → SUCCEEDED 或 FAILED。UNKNOWN 表示任务不存在或查询已超过 24 小时。
submit_time:
type: string
description: 任务提交时间。
scheduled_time:
type: string
description: 任务调度时间。
end_time:
type: string
description: 任务结束时间。
results:
type: array
items:
type: object
properties:
url:
type: string
description: 生成的图片 URL。
description: 生成结果列表，每个元素包含一张图片的 URL。
task_metrics:
type: object
properties:
TOTAL:
type: integer
description: 总任务数。
SUCCEEDED:
type: integer
description: 成功任务数。
FAILED:
type: integer
description: 失败任务数。
code:
type: string
description: 错误码（仅在任务失败时返回）。
message:
type: string
description: 错误信息（仅在任务失败时返回）。
usage:
type: object
properties:
image_count:
type: integer
description: 生成的图片数量。
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: 错误码。
message:
type: string
description: 错误信息。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-generation-z-image.md
+308
View File
@@ -0,0 +1,308 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Z-Image
> 轻量快速图像生成
<Note>
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。如需使用 SDK，请先[安装](/api-reference/preparation/install-sdk)。
</Note>
Z-Image 是一款轻量级文生图模型，生成速度快。支持中英文文字渲染，适配多种分辨率和宽高比。
**快速链接**：[模型体验](https://platform.qianwenai.com/home/try-ai/chat?models=z-image-turbo) | [技术博客](https://tongyi-mai.github.io/Z-Image-blog/)
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.1.0
info:
title: Z-Image API
description: Z-Image 文生图 API。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: 北京
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createZImage
summary: 生成图像
description: 使用 z-image-turbo 根据文本提示词生成图像。结果同步返回，无需轮询。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ZImageRequest"
responses:
"200":
description: 图像生成结果
content:
application/json:
schema:
$ref: "#/components/schemas/ZImageResponse"
examples:
success:
summary: 生成成功
value:
output:
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx
- text: Photo of a stylish young woman...
reasoning_content: ""
usage:
width: 1024
height: 1024
image_count: 1
input_tokens: 0
output_tokens: 0
total_tokens: 0
request_id: abf1645b-b630-433a-92f6-xxxxxx
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
error:
summary: 参数错误
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
"401":
description: 鉴权失败，API Key 无效或缺失
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"429":
description: 请求频率超限
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "z-image-turbo",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "A sitting orange cat with a happy expression, lively and cute, realistic and accurate"
}
]
}
]
},
"parameters": {
"prompt_extend": false,
"size": "1024*1024"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ZImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。
enum:
- z-image-turbo
example: z-image-turbo
input:
type: object
required:
- messages
description: 输入内容。
properties:
messages:
type: array
description: "请求内容数组。**仅支持单轮对话**，传入一条 `role: user` 的消息，不支持多轮。"
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ZImageMessage"
parameters:
$ref: "#/components/schemas/ZImageParameters"
ZImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 消息角色。必须为 `user`。
content:
type: array
description: 消息内容数组。必须包含且仅包含一个文本对象；传入零个或超过一个对象时将返回错误。
items:
$ref: "#/components/schemas/ZImageContentPart"
ZImageContentPart:
type: object
properties:
text:
type: string
description: 描述所需内容、风格和构图的正向提示词，支持中英文。最多 800 个字符（每个汉字、字母、数字或符号均计为 1 个字符），超出部分将被截断。
maxLength: 800
example: A sitting orange cat with a happy expression, lively and cute, realistic and accurate
ZImageParameters:
type: object
description: 图像生成参数。
properties:
size:
type: string
description: |-
输出图像分辨率，格式为 `宽*高`。范围：512×512 至 2048×2048 像素，推荐范围：1024×1024 至 1536×1536。默认值：`1024*1536`。
推荐分辨率（总像素约 1024×1024）：`1024*1024`（1:1）、`832*1248`（2:3）、`1248*832`（3:2）、`864*1152`（3:4）、`1152*864`（4:3）、`720*1280`（9:16）、`1280*720`（16:9）。
推荐分辨率（总像素约 1280×1280）：`1280*1280`（1:1）、`1024*1536`（2:3）、`1536*1024`（3:2）、`1104*1472`（3:4）、`1472*1104`（4:3）、`864*1536`（9:16）、`1536*864`（16:9）。
推荐分辨率（总像素约 1536×1536）：`1536*1536`（1:1）、`1248*1872`（2:3）、`1872*1248`（3:2）、`1296*1728`（3:4）、`1728*1296`（4:3）、`1152*2048`（9:16）、`2048*1152`（16:9）。
default: 1024*1536
example: 1024*1024
prompt_extend:
type: boolean
description: |-
开启基于大模型的智能提示词改写。
- `false`（默认）：返回图像和原始提示词，不产生额外费用。
- `true`：返回图像、优化后的提示词及推理内容，会增加响应时间和费用。
default: false
seed:
type: integer
description: |-
用于控制生成结果可复现性的随机种子。有效范围：`[0, 2147483647]`。相同种子通常生成相似结果；不填时使用随机种子。
**注意：** 图像生成具有随机性，即使使用相同种子，结果也可能存在差异。
minimum: 0
maximum: 2147483647
ZImageResponse:
type: object
description: 图像生成响应。
properties:
output:
type: object
description: 模型输出。
properties:
choices:
type: array
description: 模型输出内容，数组中包含一个元素。
items:
$ref: "#/components/schemas/ZImageChoice"
usage:
$ref: "#/components/schemas/ZImageUsage"
request_id:
type: string
description: 请求唯一标识符，可用于追踪和排查问题。
example: abf1645b-b630-433a-92f6-xxxxxx
ZImageChoice:
type: object
properties:
finish_reason:
type: string
description: 生成结束原因。`stop` 表示成功。
example: stop
message:
type: object
description: 模型响应消息。
properties:
role:
type: string
description: 消息角色。固定为 `assistant`。
enum:
- assistant
content:
type: array
description: 响应内容项，包含带有生成图像 URL 的 `image` 对象和带有提示词的 `text` 对象。
items:
$ref: "#/components/schemas/ZImageResponseContentPart"
reasoning_content:
type: string
description: 模型推理输出。仅在 `prompt_extend=true` 时返回，否则为空字符串。
ZImageResponseContentPart:
type: object
description: 响应中的内容项，每项包含 `image` 或 `text` 字段之一。
properties:
image:
type: string
description: 生成的图像 URL（PNG 格式）。**有效期 24 小时**，请及时下载。
text:
type: string
description: 原始提示词（当 `prompt_extend=false` 时）或经过优化的提示词（当 `prompt_extend=true` 时）。
ZImageUsage:
type: object
description: 用量统计，仅包含成功生成的数据。
properties:
width:
type: integer
description: 生成图像的宽度（像素）。
height:
type: integer
description: 生成图像的高度（像素）。
image_count:
type: integer
description: 生成图像数量。固定为 1。
input_tokens:
type: integer
description: 消耗的输入 token 数。`prompt_extend=false` 时为 `0`。
output_tokens:
type: integer
description: 消耗的输出 token 数。`prompt_extend=false` 时为 `0`。
output_tokens_details:
type: object
description: 输出 token 明细，仅在 `prompt_extend=true` 时返回。
properties:
reasoning_tokens:
type: integer
description: 用于推理的 token 数。
total_tokens:
type: integer
description: 消耗的总 token 数。`prompt_extend=false` 时为 `0`。
ErrorResponse:
type: object
description: 错误响应，请求失败时返回。
properties:
request_id:
type: string
description: 请求唯一标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 可读的错误说明。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-translation-qwen-mt-image-create-task.md
+282
View File
@@ -0,0 +1,282 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建图像翻译任务
> 提交 qwen-mt-image 图像翻译异步任务
## OpenAPI
````yaml post /services/aigc/image2image/image-synthesis
openapi: 3.0.0
info:
title: 千问-图像翻译 API 参考
description: |-
千问-图像翻译模型（Qwen-MT-Image）可精准翻译图像中的文字，并保留原始排版。该模型还支持领域提示、敏感词过滤、术语干预等自定义功能。
`qwen-mt-image-2.0` 支持同步调用和异步调用两种模式。同步调用详见[同步调用](/api-reference/image-translation/qwen-mt-image/synchronous)。
异步调用流程分两步：
1. **创建任务获取任务 ID**：发送 POST 请求创建任务，返回 task_id。
2. **根据任务 ID 查询结果**：使用 task_id 轮询任务状态，直到任务完成并获得图像 URL。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/image2image/image-synthesis:
post:
operationId: createImageTranslationTask
summary: 创建图像翻译任务
description: 创建一个异步图像翻译任务。输入图像需包含支持语种的文字，且源语种或目标语种中至少有一项为中文或英文。
parameters:
- name: X-DashScope-Async
in: header
required: true
description: |-
异步处理配置参数。异步调用时必须设置为 `enable`。
`qwen-mt-image-2.0` 支持[同步调用](/api-reference/image-translation/qwen-mt-image/synchronous)，不设置此请求头即为同步模式。`qwen-mt-image` 仅支持异步调用。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ImageTranslationRequest"
responses:
"200":
description: 任务创建成功，返回 task_id 用于查询任务状态与结果。
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen-mt-image",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/ordhsk/1.webp",
"source_lang": "zh",
"target_lang": "en",
"ext": {
"config": {
"imageSegment": false
}
}
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ImageTranslationRequest:
type: object
description: 图像翻译请求体。使用 qwen-mt-image 模型进行图像翻译。
required:
- model
- input
properties:
model:
type: string
enum:
- qwen-mt-image
description: 模型名称，必须设置为 `qwen-mt-image`。
input:
type: object
description: 输入参数对象。
required:
- image_url
- source_lang
- target_lang
properties:
image_url:
type: string
description: |-
图像的公网可访问 URL，支持 HTTP 和 HTTPS 协议。
- **格式限制**：JPG、JPEG、PNG、BMP、PNM、PPM、TIFF、WEBP
- **尺寸限制**：图像的宽度和高度均需在 15-8192 像素范围内，宽高比在 1:10 至 10:1 范围内
- **大小限制**：不超过 100MB
- URL 地址中不能包含中文字符
source_lang:
type: string
description: |-
源语种。支持语种全称、语种编码或 `auto`（自动检测），对大小写不敏感。
**qwen-mt-image-2.0**：支持 55 种语言任意组合互译，无语种限制。详见[支持的语种](/api-reference/image-translation/qwen-mt-image/synchronous#支持的语种)。
**qwen-mt-image**（旧版）：与 `target_lang` 不同，且至少有一项为中文或英文。支持的源语种：`zh`、`en`、`ko`、`ja`、`ru`、`es`、`fr`、`pt`、`it`、`vi`、`de`。
示例：`Chinese`、`en`、`auto`
target_lang:
type: string
description: |-
目标语种。支持语种全称或语种编码，对大小写不敏感。
**qwen-mt-image-2.0**：支持 55 种语言任意组合互译，无语种限制。详见[支持的语种](/api-reference/image-translation/qwen-mt-image/synchronous#支持的语种)。
**qwen-mt-image**（旧版）：与 `source_lang` 不同，且至少有一项为中文或英文。支持的目标语种：`zh`、`en`、`ko`、`ja`、`ru`、`es`、`fr`、`pt`、`it`、`vi`、`ms`、`th`、`id`、`ar`。注意：德语（`de`）仅支持作为源语种。
示例：`Chinese`、`en`
ext:
type: object
description: 可选扩展参数。
properties:
domainHint:
type: string
description: |-
领域提示。为使译文风格更贴合特定领域，可以使用英文描述使用场景、译文风格等需求。为确保翻译效果，建议不超过 200 个英文单词。
当前只支持英文。
sensitives:
type: array
description: |-
敏感词列表，用于在翻译前过滤图像中**完全匹配**的文本，**对大小写敏感**。敏感词的语种可与源语种不一致，支持全部源语种和目标语种。建议单次请求添加的敏感词不超过 50 个。
示例：["全场9折", "七天无理由退换"]
items:
type: string
maxItems: 50
terminologies:
type: array
description: |-
术语干预，为特定术语设定译文，以满足特定领域的翻译需求。术语对的语种需要与 `source_lang` 和 `target_lang` 对应。
示例：[{"src": "应用程序接口", "tgt": "API"}, {"src": "机器学习", "tgt": "ML"}]
items:
type: object
required:
- src
- tgt
properties:
src:
type: string
description: 术语的源文本，语种需要与源语种 `source_lang` 一致。
tgt:
type: string
description: 术语的目标文本，语种需要与目标语种 `target_lang` 一致。
config:
type: object
description: 额外配置选项。
properties:
imageSegment:
type: boolean
default: false
description: |-
是否开启图像主体分割。开启后，将跳过对图像中主体（如人物、商品、Logo）上文字的翻译。
- `false`：（默认值）翻译图像中的所有文字
- `true`：不翻译图像主体的文字
旧版本参数名为 `skipImgSegment`，为保持兼容仍受支持，但建议使用新的 `imageSegment` 参数。
AsyncTaskSubmitResponse:
type: object
description: 异步任务成功创建时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
description: 任务状态。新创建的任务始终返回 `PENDING`。
ImageTranslationTaskStatusResponse:
type: object
description: 查询图像翻译任务状态和结果时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
description: |-
任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行成功
- FAILED：任务执行失败
- CANCELED：任务已取消
- UNKNOWN：任务不存在或状态未知
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
image_url:
type: string
description: 模型生成图像的 URL 地址，与原图长宽相同，JPG 格式。有效期为 24 小时，请及时下载并保存图像。
message:
type: string
description: 附加信息。通常不会返回此参数，仅在图像中无可翻译文本时，任务仍会成功并正常计费，但会返回 `No text detected for translation` 的提示；任务失败时会返回失败详情。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型生成图像的数量，固定为 1。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
code:
type: string
description: 错误码（如 `InvalidApiKey`、`InvalidParameter`）。
message:
type: string
description: 人类可读的错误描述。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-translation-qwen-mt-image-query-result.md
+316
View File
@@ -0,0 +1,316 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 查询任务结果
> 查询 qwen-mt-image 图像翻译任务状态和结果
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: 千问-图像翻译 API 参考
description: |-
千问-图像翻译模型（Qwen-MT-Image）可精准翻译图像中的文字，并保留原始排版。该模型还支持领域提示、敏感词过滤、术语干预等自定义功能。
`qwen-mt-image-2.0` 支持同步调用和异步调用两种模式。同步调用详见[同步调用](/api-reference/image-translation/qwen-mt-image/synchronous)。
异步调用流程分两步：
1. **创建任务获取任务 ID**：发送 POST 请求创建任务，返回 task_id。
2. **根据任务 ID 查询结果**：使用 task_id 轮询任务状态，直到任务完成并获得图像 URL。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getImageTranslationTaskStatus
summary: 根据任务 ID 查询结果
description: |-
查询图像翻译任务的状态和结果。
注意事项：
- `task_id` 有效期为 **24 小时**，若 ID 不存在或已过期，任务状态将返回 `UNKNOWN`。
- 任务成功后返回的 `image_url` 有效期为 **24 小时**，请及时下载并保存图像。
parameters:
- name: task_id
in: path
required: true
description: 任务标识。由创建接口返回的 task_id。
schema:
type: string
responses:
"200":
description: 成功获取任务状态和结果。
content:
application/json:
schema:
$ref: "#/components/schemas/ImageTranslationTaskStatusResponse"
examples:
SUCCEEDED:
summary: 任务执行成功（存在可翻译内容）
value:
request_id: 5fec62eb-bf94-91f8-b9f4-f7f758e4e27e
output:
task_id: 72c52225-8444-4cab-ad0c-xxxxxx
task_status: SUCCEEDED
submit_time: 2025-08-13 18:11:16.954
scheduled_time: 2025-08-13 18:11:17.003
end_time: 2025-08-13 18:11:23.860
image_url: http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx
usage:
image_count: 1
SUCCEEDED (no text):
summary: 任务执行成功（无可翻译内容）
value:
request_id: 0ccb84aa-e034-431d-9d54-08e14fxxxxxx
output:
task_id: 34ec4208-97d6-498b-a390-9173f7xxxxxx
task_status: SUCCEEDED
submit_time: 2026-01-12 17:56:23.625
scheduled_time: 2026-01-12 17:56:23.656
end_time: 2026-01-12 17:56:25.324
image_url: http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx
message: No text detected for translation
usage:
image_count: 1
FAILED:
summary: 任务执行失败
value:
request_id: daad9007-6acd-9fb3-a6bc-d55902b9c9ff
output:
task_id: fe8aa114-d9f1-4f76-b598-xxxxxx
task_status: FAILED
submit_time: 2025-08-20 09:54:21.911
scheduled_time: 2025-08-20 09:54:21.984
end_time: 2025-08-20 12:55:00.818
code: InternalError
message: xxxxxx
RUNNING:
summary: 任务处理中
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 72c52225-8444-4cab-ad0c-xxxxxx
task_status: RUNNING
PENDING:
summary: 任务排队中
value:
request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
task_status: PENDING
task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 查询任务结果
source: |-
# 将 86ecf553-d340-4e21-xxxxxxxxx 替换为真实的 task_id
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
ImageTranslationRequest:
type: object
description: 图像翻译请求体。使用 qwen-mt-image 模型进行图像翻译。
required:
- model
- input
properties:
model:
type: string
enum:
- qwen-mt-image
description: 模型名称，必须设置为 `qwen-mt-image`。
input:
type: object
description: 输入参数对象。
required:
- image_url
- source_lang
- target_lang
properties:
image_url:
type: string
description: |-
图像的公网可访问 URL，支持 HTTP 和 HTTPS 协议。
- **格式限制**：JPG、JPEG、PNG、BMP、PNM、PPM、TIFF、WEBP
- **尺寸限制**：图像的宽度和高度均需在 15-8192 像素范围内，宽高比在 1:10 至 10:1 范围内
- **大小限制**：不超过 100MB
- URL 地址中不能包含中文字符
source_lang:
type: string
description: |-
源语种。支持语种全称、语种编码或 `auto`（自动检测），对大小写不敏感。
**qwen-mt-image-2.0**：支持 55 种语言任意组合互译，无语种限制。详见[支持的语种](/api-reference/image-translation/qwen-mt-image/synchronous#支持的语种)。
**qwen-mt-image**（旧版）：与 `target_lang` 不同，且至少有一项为中文或英文。支持的源语种：`zh`、`en`、`ko`、`ja`、`ru`、`es`、`fr`、`pt`、`it`、`vi`、`de`。
示例：`Chinese`、`en`、`auto`
target_lang:
type: string
description: |-
目标语种。支持语种全称或语种编码，对大小写不敏感。
**qwen-mt-image-2.0**：支持 55 种语言任意组合互译，无语种限制。详见[支持的语种](/api-reference/image-translation/qwen-mt-image/synchronous#支持的语种)。
**qwen-mt-image**（旧版）：与 `source_lang` 不同，且至少有一项为中文或英文。支持的目标语种：`zh`、`en`、`ko`、`ja`、`ru`、`es`、`fr`、`pt`、`it`、`vi`、`ms`、`th`、`id`、`ar`。注意：德语（`de`）仅支持作为源语种。
示例：`Chinese`、`en`
ext:
type: object
description: 可选扩展参数。
properties:
domainHint:
type: string
description: |-
领域提示。为使译文风格更贴合特定领域，可以使用英文描述使用场景、译文风格等需求。为确保翻译效果，建议不超过 200 个英文单词。
当前只支持英文。
sensitives:
type: array
description: |-
敏感词列表，用于在翻译前过滤图像中**完全匹配**的文本，**对大小写敏感**。敏感词的语种可与源语种不一致，支持全部源语种和目标语种。建议单次请求添加的敏感词不超过 50 个。
示例：["全场9折", "七天无理由退换"]
items:
type: string
maxItems: 50
terminologies:
type: array
description: |-
术语干预，为特定术语设定译文，以满足特定领域的翻译需求。术语对的语种需要与 `source_lang` 和 `target_lang` 对应。
示例：[{"src": "应用程序接口", "tgt": "API"}, {"src": "机器学习", "tgt": "ML"}]
items:
type: object
required:
- src
- tgt
properties:
src:
type: string
description: 术语的源文本，语种需要与源语种 `source_lang` 一致。
tgt:
type: string
description: 术语的目标文本，语种需要与目标语种 `target_lang` 一致。
config:
type: object
description: 额外配置选项。
properties:
imageSegment:
type: boolean
default: false
description: |-
是否开启图像主体分割。开启后，将跳过对图像中主体（如人物、商品、Logo）上文字的翻译。
- `false`：（默认值）翻译图像中的所有文字
- `true`：不翻译图像主体的文字
旧版本参数名为 `skipImgSegment`，为保持兼容仍受支持，但建议使用新的 `imageSegment` 参数。
AsyncTaskSubmitResponse:
type: object
description: 异步任务成功创建时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
description: 任务状态。新创建的任务始终返回 `PENDING`。
ImageTranslationTaskStatusResponse:
type: object
description: 查询图像翻译任务状态和结果时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
description: |-
任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行成功
- FAILED：任务执行失败
- CANCELED：任务已取消
- UNKNOWN：任务不存在或状态未知
submit_time:
type: string
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
scheduled_time:
type: string
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
end_time:
type: string
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
image_url:
type: string
description: 模型生成图像的 URL 地址，与原图长宽相同，JPG 格式。有效期为 24 小时，请及时下载并保存图像。
message:
type: string
description: 附加信息。通常不会返回此参数，仅在图像中无可翻译文本时，任务仍会成功并正常计费，但会返回 `No text detected for translation` 的提示；任务失败时会返回失败详情。
code:
type: string
description: 请求失败的错误码。请求成功时不会返回此参数。
usage:
type: object
description: 输出信息统计。只对成功的结果计数。
properties:
image_count:
type: integer
description: 模型生成图像的数量，固定为 1。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
code:
type: string
description: 错误码（如 `InvalidApiKey`、`InvalidParameter`）。
message:
type: string
description: 人类可读的错误描述。
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-image-translation-qwen-mt-image-synchronous.md
+250
View File
@@ -0,0 +1,250 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen-MT-Image — 同步调用
> 同步模式调用 qwen-mt-image-2.0 图像翻译，直接返回翻译后的图像 URL
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
同步模式下，请求会等待处理完成后直接返回翻译后的图像 URL，无需轮询任务状态。仅 `qwen-mt-image-2.0` 支持同步调用。
与[异步调用](/api-reference/image-translation/qwen-mt-image/create-task)的区别：同步调用不需要设置 `X-DashScope-Async` 请求头，响应直接包含翻译后的图像地址。
## 请求
`POST https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis`
### 请求头
| 参数 | 类型 | 必选 | 说明 |
| ------------- | ------ | -- | ----------------------------------------- |
| Content-Type | string | 是 | 固定为 `application/json` |
| Authorization | string | 是 | API Key 认证，格式：`Bearer $DASHSCOPE_API_KEY` |
<Warning>
同步调用时**不要**设置 `X-DashScope-Async: enable` 请求头。设置该请求头将切换为异步模式。
</Warning>
### 请求体
| 参数 | 类型 | 必选 | 说明 |
| ----------------------------- | ------- | -- | --------------------------------------------------------------------------------- |
| model | string | 是 | 模型名称。同步调用仅支持 `qwen-mt-image-2.0` |
| input | object | 是 | 输入参数 |
| input.image\_url | string | 是 | 图像的公网 URL。支持 JPG/JPEG/PNG/BMP/TIFF/WEBP 格式，宽高 15-8192px，宽高比 1:10 至 10:1，不超过 100MB |
| input.source\_lang | string | 是 | 源语种。支持语种全称、语种编码或 `auto`（自动检测），大小写不敏感 |
| input.target\_lang | string | 是 | 目标语种。支持语种全称或语种编码，大小写不敏感 |
| input.ext | object | 否 | 扩展参数 |
| input.ext.domainHint | string | 否 | 领域提示，用英文描述翻译场景和风格需求，建议不超过 200 个英文单词 |
| input.ext.sensitives | array | 否 | 敏感词列表，完全匹配的文本将被跳过不翻译，大小写敏感 |
| input.ext.terminologies | array | 否 | 术语干预列表，每项包含 `src`（源文本）和 `tgt`（目标文本） |
| input.ext.config.imageSegment | boolean | 否 | 是否开启图像主体分割。开启后跳过图像主体（人物、商品、Logo）上文字的翻译。默认 `false` |
### 请求示例
<CodeGroup>
```bash cURL
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-mt-image-2.0",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/ordhsk/1.webp",
"source_lang": "zh",
"target_lang": "en"
}
}'
```
```python Python
import requests
import os
url = "https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis"
headers = {
"Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "qwen-mt-image-2.0",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/ordhsk/1.webp",
"source_lang": "zh",
"target_lang": "en"
}
}
response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(f"翻译完成: {result['output']['image_url']}")
```
```java Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;
public class ImageTranslationSync {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv("DASHSCOPE_API_KEY");
String body = """
{
"model": "qwen-mt-image-2.0",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/ordhsk/1.webp",
"source_lang": "zh",
"target_lang": "en"
}
}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis"))
.header("Authorization", "Bearer " + apiKey)
.header("Content-Type", "application/json")
.POST(BodyPublishers.ofString(body))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
</CodeGroup>
## 响应
### 响应参数
| 参数 | 类型 | 说明 |
| ------------------ | ------- | ------------------------------------------- |
| output.image\_url | string | 翻译后的图像 URL，与原图尺寸相同，JPG 格式。有效期 24 小时，请及时下载保存 |
| usage.image\_count | integer | 生成图像数量，固定为 1 |
| request\_id | string | 请求唯一标识，用于问题排查 |
### 成功响应
```json
{
"output": {
"image_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx"
},
"usage": {
"image_count": 1
},
"request_id": "b60d747a-adee-940a-aa3e-ac55b957189a"
}
```
### 错误响应
```json
{
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}
```
## 支持的语种
`qwen-mt-image-2.0` 支持以下 55 种语言的任意组合互译，无需源语种或目标语种为中文或英文。所有语种均可同时作为源语种和目标语种。
若不确定源语种，可将 `source_lang` 设置为 `auto` 进行自动检测。
<Accordion title="完整语种列表">
| 语种 | English | 编码 |
| ------ | ------------------- | ----- |
| 简体中文 | Simplified Chinese | zh |
| 繁体中文 | Traditional Chinese | zh-tw |
| 英语 | English | en |
| 日语 | Japanese | ja |
| 韩语 | Korean | ko |
| 德语 | German | de |
| 西班牙语 | Spanish | es |
| 俄语 | Russian | ru |
| 法语 | French | fr |
| 葡萄牙语 | Portuguese | pt |
| 意大利语 | Italian | it |
| 越南语 | Vietnamese | vi |
| 印度尼西亚语 | Indonesian | id |
| 马来语 | Malay | ms |
| 泰语 | Thai | th |
| 阿拉伯语 | Arabic | ar |
| 荷兰语 | Dutch | nl |
| 波兰语 | Polish | pl |
| 土耳其语 | Turkish | tr |
| 乌克兰语 | Ukrainian | uk |
| 希腊语 | Greek | el |
| 匈牙利语 | Hungarian | hu |
| 罗马尼亚语 | Romanian | ro |
| 捷克语 | Czech | cs |
| 瑞典语 | Swedish | sv |
| 丹麦语 | Danish | da |
| 芬兰语 | Finnish | fi |
| 挪威语 | Norwegian | no |
| 印地语 | Hindi | hi |
| 泰米尔语 | Tamil | ta |
| 泰卢固语 | Telugu | te |
| 尼泊尔语 | Nepali | ne |
| 波斯语 | Persian | fa |
| 阿塞拜疆语 | Azerbaijani | az |
| 哈萨克语 | Kazakh | kk |
| 乌兹别克语 | Uzbek | uz |
| 蒙古语 | Mongolian | mn |
| 维吾尔语 | Uyghur | ug |
| 白俄罗斯语 | Belarusian | be |
| 保加利亚语 | Bulgarian | bg |
| 塞尔维亚语 | Serbian | sr |
| 克罗地亚语 | Croatian | hr |
| 波斯尼亚语 | Bosnian | bs |
| 斯洛文尼亚语 | Slovenian | sl |
| 斯洛伐克语 | Slovak | sk |
| 马其顿语 | Macedonian | mk |
| 拉脱维亚语 | Latvian | lv |
| 立陶宛语 | Lithuanian | lt |
| 爱尔兰语 | Irish | ga |
| 卢森堡语 | Luxembourgish | lb |
| 南非荷兰语 | Afrikaans | af |
| 拉丁语 | Latin | la |
| 车臣语 | Chechen | ce |
| 印古什语 | Ingush | inh |
| 马里语 | Mari | chm |
</Accordion>
## 扩展参数示例
使用领域提示和术语干预提高翻译质量：
```bash
curl -X POST https://maas.qianwenaiapi.com/api/v1/services/aigc/image2image/image-synthesis \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-mt-image-2.0",
"input": {
"image_url": "https://example.com/product-image.jpg",
"source_lang": "zh",
"target_lang": "en",
"ext": {
"domainHint": "These are product descriptions on a B2C ecommerce platform. Use clear and engaging marketing language.",
"sensitives": ["全场9折", "七天无理由退换"],
"terminologies": [
{"src": "应用程序接口", "tgt": "API"},
{"src": "机器学习", "tgt": "ML"}
],
"config": {
"imageSegment": true
}
}
}
}'
```
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-multimodal-embedding-dashscope-multimodal-embedding.md
+721
View File
@@ -0,0 +1,721 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# DashScope 多模态向量
> 多模态向量化 API
将文本、图像和视频转换为统一语义空间中的数值向量，用于跨模态检索、相似度搜索和内容分类。
<Note>
开始前：[获取 API Key](/api-reference/preparation/api-key)，[将其设置为环境变量](/api-reference/preparation/export-api-key-env)，如需使用 SDK 请先[安装 DashScope SDK](/api-reference/preparation/install-sdk)。
</Note>
## 请求地址
- HTTP：`POST https://maas.qianwenaiapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding`
- SDK `base_http_api_url`：`https://maas.qianwenaiapi.com/api/v1`
## 模型概览
| 模型 | 支持模态 | 向量维度 | 单张图片大小 |
| ---------------------------------------- | ----------- | ----------------------------------- | ---------------- |
| qwen3-vl-embedding | 文本、图像、视频 | 2560（默认）、2048、1536、1024、768、512、256 | 10 MB |
| qwen2.5-vl-embedding | 文本、图像、视频 | 2048、1024（默认）、768、512 | 5 MB |
| tongyi-embedding-vision-plus-2026-03-06 | 文本、图像、视频、多图 | 1152（默认）、1024、512、256、128、64 | 建议 5 MB，最大 10 MB |
| tongyi-embedding-vision-flash-2026-03-06 | 文本、图像、视频、多图 | 768（默认）、512、256、128、64 | 建议 5 MB，最大 10 MB |
| tongyi-embedding-vision-plus | 文本、图像、视频、多图 | 1152 | 3 MB |
| tongyi-embedding-vision-flash | 文本、图像、视频、多图 | 768 | 3 MB |
## 使用说明
- **图像输入**：公网 URL 或 Base64 数据 URI（`data:image/{format};base64,{data}`）。
- **多图输入**：使用 `multi_images` 字段，值为图像 URL 列表，最多 8 张。
- **视频输入**：必须为公网 URL。通过 `parameters` 中的 `fps` 参数控制采样帧率（取值范围 \[0, 1]，默认 1.0）。
## 错误码
本 API 常见的错误码及排查方向如下。完整错误码请参见[通用错误码](/api-reference/preparation/error-messages)。
| 错误码 | HTTP 状态码 | 触发条件 | 排查建议 |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `InvalidApiKey` | 401 | API Key 无效或已过期，返回 `Invalid API-key provided.` | 确认 `Authorization` 请求头为 `Bearer sk-xxx` 格式，且使用的是当前账号下有效的 API Key。 |
| `BadRequest.EmptyModel` | 400 | 请求中缺少 `model` 字段，返回 `Required parameter model missing from request.` | 在请求体中补充 `model` 字段，取值使用本文模型列表中的模型名称。 |
| `InvalidParameter` | 400 | `model` 取值不存在，返回 `Model not exist.` | 核对 `model` 拼写，确认使用了本文模型列表中的模型名称。 |
| `InvalidParameter` | 400 | `input.contents` 缺失或为空数组，返回 `input can not be empty: input.contents` 或 `contents input can not be empty: input.contents` | 确认 `input.contents` 存在且为非空数组，数组中每个元素包含有效的 `text`、`image` 或 `video` 键。 |
| `InvalidParameter` | 400 | `dimension` 取值不在所选模型支持的向量维度范围内。 | 按本文模型列表中该模型支持的向量维度取值；`multimodal-embedding-v1` 不支持 `dimension` 参数，固定为 1024 维。 |
| `InternalError.Algo` | 500 | 请求体结构不完整或 `input.contents` 元素格式异常，导致服务端处理失败。 | 检查请求体结构，确认 `input` 及 `input.contents` 字段存在且元素格式符合本文请求参数说明；结构无误仍持续报错时，携带 `request_id` 联系技术支持。 |
## OpenAPI
````yaml post /services/embeddings/multimodal-embedding/multimodal-embedding
openapi: 3.1.0
info:
title: 千问AI平台图像 API
description: DashScope 图像 API，涵盖图像生成、图像编辑、专项图像任务及多模态向量嵌入。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/embeddings/multimodal-embedding/multimodal-embedding:
post:
operationId: createMultimodalEmbedding
summary: 创建多模态向量嵌入
description: 将文本、图像和视频映射到统一向量空间。适用于跨模态检索、语义相似度计算、内容分类等场景。所有模态共享同一语义空间，可直接通过余弦相似度跨模态比较向量。
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MultimodalEmbeddingRequest"
responses:
"200":
description: 多模态向量嵌入结果
content:
application/json:
schema:
$ref: "#/components/schemas/MultimodalEmbeddingResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"401":
description: 认证失败——API Key 无效或未提供
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"429":
description: 请求频率超出限制
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (Independent Vectors)
source: |-
curl --location --request POST \
'https://maas.qianwenaiapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "tongyi-embedding-vision-plus",
"input": {
"contents": [
{"text": "Multimodal embedding model"},
{"image": "https://example.com/image.jpg"},
{"video": "https://example.com/video.mp4"}
]
}
}'
- lang: curl
label: cURL (Fused Vector)
source: |-
curl --location --request POST \
'https://maas.qianwenaiapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3-vl-embedding",
"input": {
"contents": [
{"text": "Test text for generating a fused multimodal vector"},
{"image": "https://example.com/image.png"},
{"video": "https://example.com/video.mp4"}
]
},
"parameters": {
"enable_fusion": true
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
SyncImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 模型名称。文生图使用 `wan2.6-t2i`，图像编辑与图文交替输出使用 `wan2.6-image`，轻量快速生成使用 `z-image-turbo`。
enum:
- wan2.6-t2i
- wan2.6-image
- z-image-turbo
example: wan2.6-t2i
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话，包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ImageMessage"
parameters:
$ref: "#/components/schemas/SyncImageParameters"
ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: 必须为 `user`。
content:
type: array
description: 内容项数组，必须包含且仅包含一个文本对象。使用图像编辑模式（`wan2.6-image`）时，还可包含 1-4 个图像对象（编辑模式）或 0-1 个图像对象（图文交替模式）。
items:
$ref: "#/components/schemas/ImageContentPart"
ImageContentPart:
type: object
description: 消息中的内容项。每个对象只能提供 `text` 或 `image` 其中之一，不可同时包含两者。
properties:
text:
type: string
description: 图像生成提示词。`wan2.6-t2i` 最多 2100 个字符，`wan2.6-image` 最多 2000 个字符，`z-image-turbo` 最多 800 个字符。每个内容数组中只允许包含一个文本对象。
maxLength: 2100
image:
type: string
description: 参考图像 URL（HTTP/HTTPS）或 Base64 数据 URI（`data:{MIME_type};base64,{data}`）。仅限图像编辑模式（`wan2.6-image` 且 `enable_interleave=false`）：需提供 1-4 张图像；图文交替模式：0-1 张图像。支持格式：JPEG、JPG、PNG、BMP、WEBP。分辨率：每边 [384, 5000] 像素，最大 10 MB。
SyncImageParameters:
type: object
description: 生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`。`wan2.6-t2i`：总像素范围 [1280x1280, 1440x1440]，宽高比 [1:4, 4:1]，默认值：`1280*1280`。`wan2.6-image`：总像素范围 [768x768, 1280x1280]，宽高比 [1:4, 4:1]，默认值：`1280*1280`。`z-image-turbo`：总像素范围 [512x512, 2048x2048]，默认值：`1024*1536`。
default: 1280*1280
example: 1280*1280
n:
type: integer
description: 生成图像数量，范围 1-4，默认值：4，按实际生成张数计费。图文交替模式下必须为 1。
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: 开启智能提示词扩写，会增加约 3-4 秒延迟。适用于 `wan2.6-t2i`、`wan2.6-image`（仅编辑模式）及 `z-image-turbo`。`z-image-turbo` 开启后费用更高（详见定价）。wan2.6 系列默认值：`true`，z-image-turbo 默认值：`false`。
default: true
watermark:
type: boolean
description: 在输出图像上添加 "AI 生成" 水印，默认值：`false`。
default: false
negative_prompt:
type: string
description: 生成图像时需排除的元素，仅适用于 `wan2.6-t2i`。
enable_interleave:
type: boolean
description: 仅适用于 `wan2.6-image`。`false`（默认）：图像编辑模式；`true`：图文交替输出模式（需开启流式输出）。
default: false
max_images:
type: integer
description: 仅适用于 `wan2.6-image` 图文交替模式，每次响应最多生成的图像数量，范围 1-5，默认值：5。实际数量由模型决定。
minimum: 1
maximum: 5
default: 5
stream:
type: boolean
description: 开启流式输出。图文交替模式（`enable_interleave=true`）时必须设置为 `true`，默认值：`false`。
default: false
AsyncImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 异步图像生成的模型名称。
enum:
- wan2.6-t2i
- wan2.5-t2i-preview
- wan2.2-t2i-flash
- wan2.2-t2i-plus
- wanx2.1-t2i-turbo
- wanx2.1-t2i-plus
- flux-schnell
- flux-dev
- flux-merged
example: wan2.6-t2i
input:
type: object
required:
- messages
description: 包含消息数组的输入数据。
properties:
messages:
type: array
description: 仅支持单轮对话，包含一条角色为 `user` 的消息。
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ImageMessage"
parameters:
$ref: "#/components/schemas/AsyncImageParameters"
AsyncImageParameters:
type: object
description: 异步图像生成的生成参数。
properties:
size:
type: string
description: 输出分辨率，格式为 `宽*高`，支持的值因模型而异。Wan 系列：参见各模型限制；FLUX 系列：`512*1024`、`768*512`、`768*1024`、`1024*576`、`576*1024`、`1024*1024`。默认值：`1280*1280`（Wan）或 `1024*1024`（FLUX）。
example: 1280*1280
n:
type: integer
description: 生成图像数量，范围 1-4，默认值：4（Wan 系列）或 1（FLUX 系列）。
minimum: 1
maximum: 4
prompt_extend:
type: boolean
description: 开启智能提示词扩写，会增加约 3-4 秒延迟，默认值：`true`。
default: true
watermark:
type: boolean
description: 在输出图像上添加 "AI 生成" 水印，默认值：`false`。
default: false
negative_prompt:
type: string
description: 生成图像时需排除的元素。
SpecializedImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 专项图像任务的模型名称。
enum:
- wanx-style-repaint-v1
- wanx-background-generation-v2
- image-expansion
- wanx-poster-generation-v1
- image-inpainting
- person-segmentation
- wanx-sketch-to-image-v1
- aitryon-v1
- aitryon-v2
- virtual-model
- shoe-model
- facechain-generation
example: aitryon-v2
input:
type: object
description: 特定于模型的输入数据，结构因模型而异。详见上方接口描述中各模型的参数说明。
properties:
person_image_url:
type: string
description: 人物图像 URL，适用于 `aitryon-v1` 和 `aitryon-v2`。
garment_image_url:
type: string
description: 服装图像 URL，适用于 `aitryon-v1` 和 `aitryon-v2`。
base_image_url:
type: string
description: 前景/产品图像 URL，适用于 `wanx-background-generation-v2`。
prompt:
type: string
description: 描述期望输出效果的文本提示词，适用于 `wanx-background-generation-v2` 及其他模型。
parameters:
$ref: "#/components/schemas/SpecializedImageParameters"
SpecializedImageParameters:
type: object
description: 专项图像任务的参数，可用参数因模型而异。
properties:
n:
type: integer
description: 生成图像数量，范围 1-4，默认值因模型而异。
minimum: 1
maximum: 4
resolution:
type: integer
description: 输出分辨率（短边像素数），适用于虚拟试穿模型，默认值：768。
default: 768
WordArtRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 艺术字生成的模型名称。
enum:
- wordart-texture
- wordart-deformation-v1
example: wordart-texture
input:
type: object
required:
- text
- prompt
description: 艺术字生成的输入数据。
properties:
text:
type: object
required:
- text_content
- font_name
description: 文字配置。
properties:
text_content:
type: string
description: 要渲染的文本内容，最多 6 个字符。
maxLength: 6
example: AI
font_name:
type: string
description: 基础文字的字体名称。
example: dongfangdakai
prompt:
type: string
description: 纹理效果的风格描述。
example: Flames and fire, burning effect
parameters:
type: object
description: 生成参数。
properties:
n:
type: integer
description: 生成图像数量，默认值：4。
default: 4
MultimodalEmbeddingRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 多模态向量嵌入的模型名称。
enum:
- qwen3-vl-embedding
- qwen2.5-vl-embedding
- tongyi-embedding-vision-plus
- tongyi-embedding-vision-flash
- tongyi-embedding-vision-plus-2026-03-06
- tongyi-embedding-vision-flash-2026-03-06
- multimodal-embedding-v1
example: tongyi-embedding-vision-plus
input:
type: object
required:
- contents
description: 包含内容项的输入数据。
properties:
contents:
type: array
description: 内容项列表，每项为包含一个或多个模态键（`text`、`image`、`video`、`multi_images`）的对象。生成独立向量时每个对象只使用一种模态；生成融合向量时将多种模态组合在同一对象中。
items:
$ref: "#/components/schemas/MultimodalContentItem"
parameters:
$ref: "#/components/schemas/MultimodalEmbeddingParameters"
MultimodalContentItem:
type: object
description: 多模态向量嵌入的内容项，可包含一个或多个模态键。生成独立向量时每个对象使用一个键；生成融合向量时在同一对象中组合多个键。
properties:
text:
type: string
description: 要嵌入的文本内容。
image:
type: string
description: 图像 URL（公开的 HTTP/HTTPS 链接）或 Base64 数据 URI（`data:image/{format};base64,{data}`）。
video:
type: string
description: 视频 URL（必须为公开链接）。
multi_images:
type: array
description: 用于多图嵌入的图像 URL 列表，最多 8 张图像，仅 `tongyi-embedding-vision-plus` 和 `tongyi-embedding-vision-flash` 支持。
items:
type: string
maxItems: 8
MultimodalEmbeddingParameters:
type: object
description: 多模态向量嵌入的参数。
properties:
output_type:
type: string
description: 输出格式，目前仅支持 `dense`。
enum:
- dense
default: dense
dimension:
type: integer
description: 输出向量维度，支持的值因模型而异，详见模型概览表中的默认值与可选项。
fps:
type: number
description: 视频帧采样率，范围 [0, 1]，默认值：1.0。
minimum: 0
maximum: 1
default: 1
instruct:
type: string
description: 自定义任务指令，建议使用英文，通常可使检索任务效果提升 1-5%。
enable_fusion:
type: boolean
description: 是否生成融合向量。仅 `qwen3-vl-embedding` 模型支持。设置为 `true` 时将 contents 中的所有多模态内容融合为 1 个向量；默认为 `false`，各模态独立生成向量。
default: false
res_level:
type: integer
description: 输入分辨率档位（0/1/2/3），对应单图 token 为 127/402/578/1026，默认值 1。仅 `tongyi-embedding-vision-plus-2026-03-06` 和 `tongyi-embedding-vision-flash-2026-03-06` 支持。
enum:
- 0
- 1
- 2
- 3
default: 1
max_video_frames:
type: integer
description: 视频最大采样帧数上限，最大不超过 64，默认值 8。仅 `tongyi-embedding-vision-plus-2026-03-06` 和 `tongyi-embedding-vision-flash-2026-03-06` 支持。
maximum: 64
default: 8
SyncImageResponse:
type: object
description: 同步图像生成或编辑的响应结果。
properties:
output:
type: object
properties:
choices:
type: array
description: 生成结果列表。
items:
$ref: "#/components/schemas/ImageChoice"
finished:
type: boolean
description: 任务是否已完成。
usage:
$ref: "#/components/schemas/ImageUsage"
request_id:
type: string
description: 唯一请求标识符。
example: 815505c6-7c3d-49d7-b197-xxxxx
ImageChoice:
type: object
properties:
finish_reason:
type: string
description: 正常完成时为 `stop`，流式输出过程中为 `null`。
example: stop
message:
type: object
properties:
role:
type: string
description: 始终为 `assistant`。
enum:
- assistant
content:
type: array
description: 内容项数组，每项包含图像 URL 或文本（图文交替模式下）。
items:
$ref: "#/components/schemas/ImageResponseContentPart"
ImageResponseContentPart:
type: object
description: 响应消息中的内容项。
properties:
type:
type: string
description: 内容类型：`image` 或 `text`（仅图文交替模式下包含文本）。
enum:
- image
- text
image:
type: string
description: 生成的图像 URL（PNG 格式），**有效期 24 小时**，当 `type` 为 `image` 时存在。
text:
type: string
description: 生成的文本内容，当 `type` 为 `text` 时存在（图文交替模式）。
ImageUsage:
type: object
description: 图像生成的用量统计。
properties:
image_count:
type: integer
description: 已生成的图像数量。
input_tokens:
type: integer
description: 消耗的输入 token 数，编辑模式下为 0，图文交替模式下为实际值。
output_tokens:
type: integer
description: 消耗的输出 token 数，编辑模式下为 0，图文交替模式下为实际值。
size:
type: string
description: 输出分辨率。
example: 1280*1280
total_tokens:
type: integer
description: 总 token 数（input_tokens + output_tokens）。
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交后的响应结果。
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 用于轮询状态的任务 ID，配合 `GET /tasks/{task_id}` 使用。
task_status:
type: string
description: 任务初始状态，通常为 `PENDING`。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
AsyncTaskStatusResponse:
type: object
description: 异步任务的状态与结果。
properties:
request_id:
type: string
description: 唯一请求标识符。
output:
type: object
properties:
task_id:
type: string
description: 任务 ID。
task_status:
type: string
description: 当前任务状态。
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
results:
type: array
description: 已生成的图像结果列表，当 `task_status` 为 `SUCCEEDED` 时存在。
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: 用量统计。
properties:
image_count:
type: integer
description: 成功生成的图像数量。
AsyncTaskResult:
type: object
description: 异步任务的单条结果。
properties:
url:
type: string
description: 生成图像的 URL，**有效期 24 小时**。
TaskMetrics:
type: object
description: 任务完成情况统计。
properties:
TOTAL:
type: integer
description: 请求生成的图像总数。
SUCCEEDED:
type: integer
description: 成功生成的图像数量。
FAILED:
type: integer
description: 生成失败的图像数量。
MultimodalEmbeddingResponse:
type: object
description: 多模态向量嵌入的响应结果。
properties:
output:
type: object
properties:
embeddings:
type: array
description: 向量嵌入结果列表。
items:
$ref: "#/components/schemas/MultimodalEmbeddingData"
usage:
type: object
description: Token 用量统计。不同模型返回的字段存在差异：`tongyi-embedding-vision-*` 系列返回 `input_tokens`（含文本和图片 Token 总和）、`input_tokens_details`、`output_tokens`、`total_tokens`；其他模型返回的字段可能不同，详见各字段说明。
properties:
input_tokens:
type: integer
description: 本次请求输入内容的 Token 数目。对于 `tongyi-embedding-vision-*` 系列模型，该值包含文本和图片/视频 Token 的总和。
input_tokens_details:
type: object
description: 输入 Token 的详细分类信息。仅 `tongyi-embedding-vision-*` 系列模型返回此字段。
properties:
image_tokens:
type: integer
description: 输入内容中图片或视频等视觉部分消耗的 Token 数量，不包含文本（文本部分见 `text_tokens`）。图片消耗的 Token 数量与输入图片的分辨率有关，分辨率越高消耗的 Token 越多；若输入为视频，系统会先对视频抽帧，再基于抽帧结果计算 Token。
text_tokens:
type: integer
description: 输入内容中文本部分消耗的 Token 数量（不包含图片或视频等视觉部分）。
output_tokens:
type: integer
description: 本次请求输出的 Token 数目。仅 `tongyi-embedding-vision-*` 系列模型返回此字段。
total_tokens:
type: integer
description: 输入与输出的 Token 总数。
image_tokens:
type: integer
description: 本次请求输入的图片或视频等视觉部分消耗的 Token 数量（不包含文本）。图片消耗的 Token 数量与输入图片的分辨率有关；系统会对输入视频进行抽帧处理，帧数上限受系统配置控制，随后基于处理结果计算 Token。仅 `qwen3-vl-embedding`、`qwen2.5-vl-embedding` 和 `multimodal-embedding-v1` 返回此字段（作为顶层字段），`tongyi-embedding-vision-*` 系列模型的图片 Token 包含在 `input_tokens_details.image_tokens` 中。
request_id:
type: string
description: 唯一请求标识符。
example: 1fff9502-a6c5-9472-9ee1-73930fdd04c5
MultimodalEmbeddingData:
type: object
description: 单条向量嵌入结果。
properties:
index:
type: integer
description: 在输入内容列表中的位置索引。
embedding:
type: array
description: 浮点数向量。
items:
type: number
type:
type: string
description: 本条嵌入结果的内容类型。
enum:
- text
- image
- video
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 唯一请求标识符。
code:
type: string
description: 错误码（如 `InvalidParameter`、`Throttling`、`Unauthorized`）。
example: InvalidParameter
message:
type: string
description: 可读的错误信息。
example: num_images_per_prompt must be 1
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-multimodal-translation-qwen-mt-uni-query-result.md
+459
View File
@@ -0,0 +1,459 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 查询任务结果
> 查询 qwen-mt-uni 全模态翻译任务状态和结果
## OpenAPI
````yaml get /tasks/{task_id}
openapi: 3.0.0
info:
title: 千问-全模态翻译 API 参考
description: |-
Qwen-MT-Uni 是一款面向图片、文本、音频及各类文档的全模态翻译模型，通过统一的格式识别、智能路由、内容抽取、跨模态翻译与原格式重构链路，实现多类型输入的一体化高保真翻译。
同一接口支持**同步**与**异步**两种调用模式，请求体参数完全一致，由请求头 `X-DashScope-Async` 控制返回形式。同步调用请求后等待并直接返回翻译结果，适合文本、图片、小文件等耗时较短的场景。
异步调用流程分两步：
1. **创建任务获取任务 ID**：发送 POST 请求创建任务，返回 task_id。
2. **根据任务 ID 查询结果**：使用 task_id 轮询任务状态，直到任务完成并获得译后文件 URL 或译文文本。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getUniTranslationTaskStatus
summary: 根据任务 ID 查询结果
description: |-
查询全模态翻译任务的状态和结果。
注意事项：
- `task_id` 有效期为 **24 小时**，若 ID 不存在或已过期，任务状态将返回 `UNKNOWN`。
- 任务成功后返回的 `TranslatedFileUrl` 有效期为 **24 小时**，请及时下载并保存文件。
- 此查询接口的默认 RPS 为 1。如需更高频次的查询或事件通知，请配置异步任务回调。
- `task_status` 为 `PENDING` / `RUNNING` 时，`TranslatedFileUrl`、`TranslatedTexts`、`usage`、`end_time` 均为空，调用方需继续轮询。
- 业务失败时 `task_status` 仍为 `SUCCEEDED`，需通过 `output.Success = false` 判断。
parameters:
- name: task_id
in: path
required: true
description: 任务标识。由创建接口返回的 task_id。
schema:
type: string
responses:
"200":
description: 成功获取任务状态和结果。
content:
application/json:
schema:
$ref: "#/components/schemas/UniTaskStatusResponse"
examples:
PENDING:
summary: 任务排队中
value:
request_id: 6e8d1dd6-9e02-9793-ad25-6e7fda5eeea0
output:
task_id: df8fc25e-b9ee-4e96-9aa2-24d69681299e
task_status: PENDING
RUNNING:
summary: 任务处理中
value:
request_id: 6e8d1dd6-9e02-9793-ad25-6e7fda5eeea0
output:
task_id: df8fc25e-b9ee-4e96-9aa2-24d69681299e
task_status: RUNNING
SUCCEEDED:
summary: 任务执行成功
value:
request_id: 47bb236e-4ecc-90a7-ac39-9ab3435d2cc8
output:
task_id: 9a7ccda6-4604-4541-a2f3-f9d412c0779b
task_status: SUCCEEDED
submit_time: 2026-09-15 13:35:06.883
scheduled_time: 2026-09-15 13:35:06.931
end_time: 2026-09-15 13:35:10.149
Message: Success
RequestId: 9a7ccda6-4604-4541-a2f3-f9d412c0779b
Data:
FileType: image
TranslatedFileUrl: http://dashscope-a717.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx
Code: 200
Success: true
usage:
input_tokens_details:
document_tokens: 0
audio_tokens: 0
character_tokens: 0
image_tokens: 1887
total_tokens: 3774
output_tokens: 1887
input_tokens: 1887
output_tokens_details:
document_tokens: 0
audio_tokens: 0
character_tokens: 0
image_tokens: 1887
FAILED:
summary: 业务失败（task_status 仍为 SUCCEEDED，需结合 Success 判断）
value:
request_id: <查询请求id>
output:
task_id: <task-id>
task_status: SUCCEEDED
submit_time: 2026-09-14 11:09:36.876
scheduled_time: 2026-09-14 11:09:36.926
end_time: 2026-09-14 11:09:37.050
Success: false
Code: 400
Message: "InvalidParameter: missing required field: input.target_lang"
RequestId: <task_id>
usage: {}
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 查询任务结果
source: |-
# 将 86ecf553-d340-4e21-xxxxxxxxx 替换为真实的 task_id
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
UniTranslationRequest:
type: object
description: 全模态翻译请求体。使用 qwen-mt-uni 模型进行图片、文本、音频及各类文档的翻译。
required:
- model
- input
properties:
model:
type: string
enum:
- qwen-mt-uni
description: 模型名称，必须设置为 `qwen-mt-uni`。
input:
type: object
description: 输入参数对象。`fileUrl` 与 `source_texts` 必须且只能提供一个。
required:
- target_lang
properties:
fileUrl:
type: string
description: |-
可访问的 HTTP(S) URL，服务端自动判断模态类型（文档 / 图片 / 音频）。与 `source_texts` **必须且只能提供一个**。
- **支持格式**：PDF、DOCX、PPTX、XLSX、TXT、HTML、Markdown、JPG、PNG、MP3、WAV。
- **大小限制**：单文件不超过 100 MB，文档不超过 200 页，音频时长需在 3 秒～60 分钟之间。
- URL 地址中不能包含中文字符。
source_texts:
type: string
description: 一条非空字符串或非空字符串数组（`string | array<string>`）。批量翻译保持输入顺序，响应保持标量/数组形状。与 `fileUrl` **必须且只能提供一个**。
source_lang:
type: string
description: 源语言代码，例如 `zh`。不填则自动识别。
target_lang:
type: string
description: 目标语言代码或项目支持的语言名称，例如 `ko`。详见[支持的语种](/api-reference/multimodal-translation/qwen-mt-uni/translate#支持的语种)。
ext:
type: object
description: 可选扩展参数。
properties:
domainHint:
type: string
description: |-
英文领域提示，最多 200 个英文单词。为使译文风格更贴合特定领域，可以使用英文描述使用场景、译文风格等需求。
领域提示语句当前**只支持英文**。
示例：`These sentences are from seller-buyer conversations on a B2C ecommerce platform. Translate them into clear, engaging customer service language.`
format_hint:
type: string
description: 格式提示。当 `fileUrl` 没有可识别后缀时，用它显式指定格式，如 `pdf`、`image`。
sensitives:
type: array
description: |-
敏感词列表，**区分大小写**，最多 50 个非空字符串。提取文本与某项完全相同时保留原文且不发送给模型。
示例：`["全场9折", "七天无理由退换"]`
items:
type: string
maxItems: 50
glossary:
type: array
description: |-
术语表，最多 100 组 `{"src": "源文本", "tgt": "目标文本"}`。当前作为 Prompt 术语表接入，支持保持原文、指定翻译和空目标词。
示例：`[{"src": "应用程序接口", "tgt": "API"}, {"src": "机器学习", "tgt": "ML"}]`
items:
type: object
required:
- src
- tgt
properties:
src:
type: string
description: 术语的源文本。
tgt:
type: string
description: 术语的目标文本。
maxItems: 100
config:
type: object
description: 额外配置选项。
properties:
imageSegment:
type: boolean
default: false
description: |-
**仅图像格式生效**。是否开启图像主体分割。开启后，将跳过对图像中主体（如人物、商品、Logo）上文字的翻译。
- `false`：（默认值）翻译图像中的所有文字
- `true`：不翻译图像主体的文字
SyncTranslationResponse:
type: object
description: 同步调用成功时的响应。顶层有 `output` 表示成功（结果在 `output.Data`，用量在 `usage`）。
properties:
request_id:
type: string
description: 顶层请求 ID，成功和失败均返回。
output:
type: object
description: 业务结果容器；成功时返回。
properties:
Success:
type: boolean
description: 是否成功，成功为 `true`。
Code:
type: integer
description: 业务结果码，成功为 `200`。
Message:
type: string
description: 结果说明，成功固定为 `Success`。
RequestId:
type: string
description: 本次调用的唯一 ID，便于问题排查。
Data:
type: object
description: 翻译结果。
properties:
FileType:
type: string
enum:
- strings
- document
- image
- audio
description: 结果类型：`strings`（文本）/ `document`（文档）/ `image`（图片）/ `audio`（音频）。
TranslatedTexts:
type: string
description: 文本翻译结果。**仅传 `source_texts` 时返回**，形状与入参一致（`string | array<string>`）。
TranslatedFileUrl:
type: string
description: 译后文件的下载地址（带签名，有有效期）。**仅传 `fileUrl` 时返回**。
usage:
type: object
description: Token 用量统计（在 output 之外的顶层），按 `input_tokens` 计费。
properties:
input_tokens:
type: integer
description: 输入 Token 总量。
output_tokens:
type: integer
description: 输出 Token 总量。
total_tokens:
type: integer
description: 输入与输出 Token 总量。
input_tokens_details:
type: object
description: 按内容类型划分的输入 Token 用量明细。
properties:
document_tokens:
type: integer
description: 文档类输入 Token 数。
audio_tokens:
type: integer
description: 音频类输入 Token 数。
character_tokens:
type: integer
description: 字符类输入 Token 数。
image_tokens:
type: integer
description: 图像类输入 Token 数。
output_tokens_details:
type: object
description: 按内容类型划分的输出 Token 用量明细，字段同 `input_tokens_details`。
properties:
document_tokens:
type: integer
description: 文档类输出 Token 数。
audio_tokens:
type: integer
description: 音频类输出 Token 数。
character_tokens:
type: integer
description: 字符类输出 Token 数。
image_tokens:
type: integer
description: 图像类输出 Token 数。
AsyncTaskSubmitResponse:
type: object
description: 异步任务成功创建时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
description: 任务状态。新创建的任务始终返回 `PENDING`。
UniTaskStatusResponse:
type: object
description: 查询全模态翻译任务状态和结果时的响应。
properties:
request_id:
type: string
description: 本次查询请求的唯一标识；三种状态均返回。
output:
type: object
description: 异步任务状态及执行结果。
properties:
task_id:
type: string
description: 异步任务的唯一标识；三种状态均返回。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: |-
异步任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行完成，需结合 `output.Success` 判断业务是否成功
- FAILED：任务执行失败
- UNKNOWN：任务不存在或状态未知
submit_time:
type: string
description: 任务提交时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始调度时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
end_time:
type: string
description: 任务结束时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
Success:
type: boolean
description: 业务执行是否成功。`true`：成功；`false`：失败。待处理示例不返回。
Code:
type: integer
description: 业务结果码。`200` 表示成功，`400` 表示请求参数错误。待处理示例不返回。
Message:
type: string
description: 业务执行结果说明。成功示例为 `Success`；失败时返回错误详情。
RequestId:
type: string
description: 业务执行请求标识。成功和失败示例均返回。
Data:
type: object
description: 翻译结果数据；**仅业务成功时返回**。
properties:
FileType:
type: string
enum:
- strings
- document
- image
- audio
description: 结果类型：`strings`（文本）/ `document`（文档）/ `image`（图片）/ `audio`（音频）。
TranslatedTexts:
type: string
description: 文本翻译结果。**仅传 `source_texts` 时返回**，形状与入参一致（`string | array<string>`）。
TranslatedFileUrl:
type: string
description: 译后文件的下载地址（带签名及有效期参数）。**仅传 `fileUrl` 时返回**。
usage:
type: object
description: Token 用量统计。成功示例返回详细统计；失败示例返回空对象 `{}`；待处理示例不返回。按 `input_tokens` 计费。
properties:
input_tokens:
type: integer
description: 输入 Token 总量。
output_tokens:
type: integer
description: 输出 Token 总量。
total_tokens:
type: integer
description: 输入与输出 Token 总量。
input_tokens_details:
type: object
description: 按内容类型划分的输入 Token 用量明细。
properties:
document_tokens:
type: integer
description: 文档类输入 Token 数。
audio_tokens:
type: integer
description: 音频类输入 Token 数。
character_tokens:
type: integer
description: 字符类输入 Token 数。
image_tokens:
type: integer
description: 图像类输入 Token 数。
output_tokens_details:
type: object
description: 按内容类型划分的输出 Token 用量明细，字段同 `input_tokens_details`。
properties:
document_tokens:
type: integer
description: 文档类输出 Token 数。
audio_tokens:
type: integer
description: 音频类输出 Token 数。
character_tokens:
type: integer
description: 字符类输出 Token 数。
image_tokens:
type: integer
description: 图像类输出 Token 数。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
code:
type: string
description: 错误码字符串（如 `InvalidParameter`、`InvalidApiKey`）。
message:
type: string
description: "错误详情，形如 `InvalidParameter: <原因>`。"
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-multimodal-translation-qwen-mt-uni-translate.md
+573
View File
@@ -0,0 +1,573 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen-MT-Uni — 全模态翻译
> 调用 qwen-mt-uni 全模态翻译模型，支持同步直接返回结果与异步提交任务两种模式
<Note>
[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
</Note>
Qwen-MT-Uni 是一款面向图片、文本、音频及各类文档的全模态翻译模型，通过统一的格式识别、智能路由、内容抽取、跨模态翻译与原格式重构链路，实现多类型输入的一体化高保真翻译。
## 同步与异步
同步与异步共用本页的同一个接口，请求体参数完全一致，仅由请求头 `X-DashScope-Async` 决定返回形式：
| 调用模式 | 请求头 | 响应 | 适用场景 |
| ------ | --------------------------- | ------------------------------ | ----------------- |
| 同步（默认） | 不设置 `X-DashScope-Async` | 等待处理完成，直接返回翻译结果（译文文本或译后文件 URL） | 文本、图片、小文件等耗时较短的场景 |
| 异步 | `X-DashScope-Async: enable` | 立即返回 `task_id`，不等待翻译完成 | 大文档、长音频等耗时较长的场景 |
上方响应示例中，`SYNC_SUCCESS` 对应同步返回的翻译结果，`ASYNC_PENDING` 对应异步返回的 `task_id`。
### 异步调用流程
1. **创建任务获取任务 ID**：带 `X-DashScope-Async: enable` 发送本页的 POST 请求，返回 `task_id`。创建成功后 `task_id` 有效期为 24 小时，**请勿重复创建任务**，轮询获取即可。
2. **根据任务 ID 查询结果**：使用 `task_id` 调用[查询任务结果](/api-reference/multimodal-translation/qwen-mt-uni/query-result)接口轮询任务状态，直到任务完成并获得译后文件 URL 或译文文本。
## 支持的输入格式
输入与输出保持相同的格式形状：
- **字符串**：输入 `str` 或 `list[str]`，输出保持相同的标量/数组形状。
- **PDF**：输入 `.pdf`，输出 `.pdf`。
- **Word**：输入 `.docx`，输出 `.docx`。
- **PowerPoint**：输入 `.pptx`，输出 `.pptx`。
- **Excel**：输入 `.xlsx`，输出 `.xlsx`。
- **TXT**：输入 `.txt`，输出 `.txt`。
- **HTML**：输入 `.html`、`.htm`，输出 `.html`。
- **Markdown**：输入 `.md`、`.markdown`、`.mdown`、`.mkd`，输出 `.md`。
- **图像**：输入 `.png`、`.jpg`、`.jpeg`，输出 `.jpg`。
- **音频**：输入 `.mp3`、`.wav`，输出 `.mp3`。
<Note>
* 单文件不超过 **100 MB**，文档不超过 **200 页**，音频时长需在 **3 秒～60 分钟** 之间。
* URL 地址中不能包含中文字符。
* 旧版二进制 Word（`.doc`）和 PowerPoint（`.ppt`）需要先转换为 OOXML 格式（`.docx`/`.pptx`）再传入。
</Note>
## 支持的语种
若不确定源语种，可将 `source_lang` 留空以自动识别。下表列出全部受支持的翻译方向：
| 源语种（中文名） | 源语种（编码） | 可选目标语种 |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 中文（简体） | `zh` | 中文（繁体）（`zh-tw`）、英语（`en`）、日语（`ja`）、韩语（`ko`）、哈萨克语（`kk`）、马来语（`ms`）、泰语（`th`） |
| 中文（繁体） | `zh-tw` | 中文（简体）（`zh`）、英语（`en`）、日语（`ja`）、韩语（`ko`）、哈萨克语（`kk`）、马来语（`ms`）、泰语（`th`） |
| 英语 | `en` | 阿拉伯语（`ar`）、阿塞拜疆语（`az`）、孟加拉语（`bn`）、波斯尼亚语（`bs`）、捷克语（`cs`）、丹麦语（`da`）、德语（`de`）、希腊语（`el`）、西班牙语（`es`）、爱沙尼亚语（`et`）、芬兰语（`fi`）、法语（`fr`）、希伯来语（`he`）、印地语（`hi`）、匈牙利语（`hu`）、印度尼西亚语（`id`）、意大利语（`it`）、日语（`ja`）、韩语（`ko`）、立陶宛语（`lt`）、拉脱维亚语（`lv`）、马来语（`ms`）、缅甸语（`my`）、尼泊尔语（`ne`）、荷兰语（`nl`）、挪威语（`no`）、波兰语（`pl`）、葡萄牙语-巴西（`pt`）、葡萄牙语-葡萄牙（`pt-pt`）、罗马尼亚语（`ro`）、罗马尼亚语-乌尔都（`ro_ur`）、俄语（`ru`）、僧伽罗语（`si`）、斯洛伐克语（`sk`）、斯洛文尼亚语（`sl`）、塞尔维亚语（`sr`）、瑞典语（`sv`）、泰语（`th`）、菲律宾语（`tl`）、土耳其语（`tr`）、乌克兰语（`uk`）、乌尔都语（`ur`）、越南语（`vi`）、中文（简体）（`zh`）、中文（繁体）（`zh-tw`） |
| 西班牙语 | `es` | 保加利亚语（`bg`）、捷克语（`cs`）、丹麦语（`da`）、德语（`de`）、希腊语（`el`）、英语（`en`）、爱沙尼亚语（`et`）、芬兰语（`fi`）、法语（`fr`）、克罗地亚语（`hr`）、匈牙利语（`hu`）、意大利语（`it`）、立陶宛语（`lt`）、拉脱维亚语（`lv`）、荷兰语（`nl`）、挪威语（`no`）、波兰语（`pl`）、葡萄牙语-巴西（`pt`）、葡萄牙语-葡萄牙（`pt-pt`）、罗马尼亚语（`ro`）、俄语（`ru`）、斯洛伐克语（`sk`）、瑞典语（`sv`） |
| 阿拉伯语 | `ar` | 英语（`en`）、土耳其语（`tr`） |
| 土耳其语 | `tr` | 阿拉伯语（`ar`）、捷克语（`cs`）、德语（`de`）、希腊语（`el`）、英语（`en`）、匈牙利语（`hu`）、罗马尼亚语（`ro`）、斯洛伐克语（`sk`） |
| 罗马尼亚语 | `ro` | 英语（`en`）、土耳其语（`tr`） |
| 阿塞拜疆语 | `az` | 英语（`en`） |
| 孟加拉语 | `bn` | 英语（`en`） |
| 捷克语 | `cs` | 英语（`en`） |
| 德语 | `de` | 英语（`en`） |
| 希腊语 | `el` | 英语（`en`） |
| 芬兰语 | `fi` | 英语（`en`） |
| 法语 | `fr` | 英语（`en`） |
| 希伯来语 | `he` | 英语（`en`） |
| 印地语 | `hi` | 英语（`en`） |
| 匈牙利语 | `hu` | 英语（`en`） |
| 印度尼西亚语 | `id` | 英语（`en`） |
| 意大利语 | `it` | 英语（`en`） |
| 日语 | `ja` | 英语（`en`） |
| 韩语 | `ko` | 英语（`en`） |
| 马来语 | `ms` | 英语（`en`） |
| 缅甸语 | `my` | 英语（`en`） |
| 尼泊尔语 | `ne` | 英语（`en`） |
| 荷兰语 | `nl` | 英语（`en`） |
| 波兰语 | `pl` | 英语（`en`） |
| 葡萄牙语（巴西） | `pt` | 英语（`en`） |
| 俄语 | `ru` | 英语（`en`） |
| 僧伽罗语 | `si` | 英语（`en`） |
| 瑞典语 | `sv` | 英语（`en`） |
| 泰语 | `th` | 英语（`en`） |
| 菲律宾语 | `tl` | 英语（`en`） |
| 乌克兰语 | `uk` | 英语（`en`） |
| 乌尔都语 | `ur` | 英语（`en`） |
| 越南语 | `vi` | 英语（`en`） |
| 保加利亚语 | `bg` | 英语（`en`） |
| 波斯尼亚语 | `bs` | 英语（`en`） |
| 丹麦语 | `da` | 英语（`en`） |
| 爱沙尼亚语 | `et` | 英语（`en`） |
| 克罗地亚语 | `hr` | 英语（`en`） |
| 立陶宛语 | `lt` | 英语（`en`） |
| 拉脱维亚语 | `lv` | 英语（`en`） |
| 挪威语 | `no` | 英语（`en`） |
| 葡萄牙语（葡萄牙） | `pt-pt` | 英语（`en`） |
| 罗马尼亚语（乌尔都） | `ro_ur` | 英语（`en`） |
| 斯洛伐克语 | `sk` | 英语（`en`） |
| 斯洛文尼亚语 | `sl` | 英语（`en`） |
| 塞尔维亚语 | `sr` | 英语（`en`） |
## 计费与限流
- 按 `input_tokens` 计费。同步与异步价格一致。
- 模型调用失败或处理错误不产生任何费用，也不消耗新人免费额度。
- 限流说明请参见[限流](/developer-guides/administration/rate-limits)。
## OpenAPI
````yaml post /services/aigc/multimodal-generation/generation
openapi: 3.0.0
info:
title: 千问-全模态翻译 API 参考
description: |-
Qwen-MT-Uni 是一款面向图片、文本、音频及各类文档的全模态翻译模型，通过统一的格式识别、智能路由、内容抽取、跨模态翻译与原格式重构链路，实现多类型输入的一体化高保真翻译。
同一接口支持**同步**与**异步**两种调用模式，请求体参数完全一致，由请求头 `X-DashScope-Async` 控制返回形式。同步调用请求后等待并直接返回翻译结果，适合文本、图片、小文件等耗时较短的场景。
异步调用流程分两步：
1. **创建任务获取任务 ID**：发送 POST 请求创建任务，返回 task_id。
2. **根据任务 ID 查询结果**：使用 task_id 轮询任务状态，直到任务完成并获得译后文件 URL 或译文文本。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createUniTranslation
summary: 全模态翻译（同步/异步）
description: |-
调用 qwen-mt-uni 全模态翻译模型，支持**同步**与**异步**两种模式，由请求头 `X-DashScope-Async` 控制：
- **同步**（默认）：不设置 `X-DashScope-Async`，请求等待处理完成后直接返回翻译结果（译文文本或译后文件 URL）。适合文本、图片、小文件等耗时较短的场景。
- **异步**：设置 `X-DashScope-Async: enable`，请求立即返回 `task_id`，再通过[查询接口](/api-reference/multimodal-translation/qwen-mt-uni/query-result)轮询结果。适合大文档、长音频等耗时较长的场景。`task_id` 有效期为 24 小时，请勿重复创建任务，轮询获取即可。
parameters:
- name: X-DashScope-Async
in: header
required: false
description: |-
异步处理配置参数。
- 不设置（默认）：同步模式，响应直接返回翻译结果。
- 设置为 `enable`：异步模式，响应返回 `task_id`，需轮询[查询接口](/api-reference/multimodal-translation/qwen-mt-uni/query-result)获取结果。
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UniTranslationRequest"
responses:
"200":
description: 同步模式直接返回翻译结果；异步模式返回 task_id 用于查询任务状态与结果。
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SyncTranslationResponse"
- $ref: "#/components/schemas/AsyncTaskSubmitResponse"
examples:
SYNC_SUCCESS:
summary: 同步调用成功（直接返回翻译结果）
value:
output:
Code: 200
Data:
FileType: image
TranslatedFileUrl: http://dashscope-a717.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx
Message: Success
RequestId: a20aa16a-2445-929f-9130-af70b4a0ade4
Success: true
usage:
input_tokens: 1887
input_tokens_details:
audio_tokens: 0
character_tokens: 0
document_tokens: 0
image_tokens: 1887
output_tokens: 1887
output_tokens_details:
audio_tokens: 0
character_tokens: 0
document_tokens: 0
image_tokens: 1887
total_tokens: 3774
request_id: a20aa16a-2445-929f-9130-af70b4a0ade4
ASYNC_PENDING:
summary: 异步任务创建成功（返回 task_id，排队中）
value:
output:
task_id: 5dfd1549-e956-4f26-8802-6c9e06f704c6
task_status: PENDING
request_id: fe9a9059-02dd-497c-a62c-8e27a0081c02
"400":
description: 请求参数无效。
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
examples:
InvalidParameter:
summary: 缺少必填字段
value:
code: InvalidParameter
message: "InvalidParameter: missing required field: input.target_lang"
request_id: a20aa16a-2445-929f-9130-af70b4a0ade4
x-codeSamples:
- lang: curl
label: cURL - 同步调用
source: |-
curl -X POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen-mt-uni",
"input": {
"fileUrl": "https://maas-infra-public.oss-cn-hangzhou.aliyuncs.com/lzhe/test/03bc3a6a-a02b-11f1-8874-00163e79676e.jpg",
"target_lang": "zh"
}
}'
- lang: curl
label: cURL - 异步调用
source: |-
curl -X POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen-mt-uni",
"input": {
"fileUrl": "https://maas-infra-public.oss-cn-hangzhou.aliyuncs.com/lzhe/test/03bc3a6a-a02b-11f1-8874-00163e79676e.jpg",
"target_lang": "zh"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
UniTranslationRequest:
type: object
description: 全模态翻译请求体。使用 qwen-mt-uni 模型进行图片、文本、音频及各类文档的翻译。
required:
- model
- input
properties:
model:
type: string
enum:
- qwen-mt-uni
description: 模型名称，必须设置为 `qwen-mt-uni`。
input:
type: object
description: 输入参数对象。`fileUrl` 与 `source_texts` 必须且只能提供一个。
required:
- target_lang
properties:
fileUrl:
type: string
description: |-
可访问的 HTTP(S) URL，服务端自动判断模态类型（文档 / 图片 / 音频）。与 `source_texts` **必须且只能提供一个**。
- **支持格式**：PDF、DOCX、PPTX、XLSX、TXT、HTML、Markdown、JPG、PNG、MP3、WAV。
- **大小限制**：单文件不超过 100 MB，文档不超过 200 页，音频时长需在 3 秒～60 分钟之间。
- URL 地址中不能包含中文字符。
source_texts:
type: string
description: 一条非空字符串或非空字符串数组（`string | array<string>`）。批量翻译保持输入顺序，响应保持标量/数组形状。与 `fileUrl` **必须且只能提供一个**。
source_lang:
type: string
description: 源语言代码，例如 `zh`。不填则自动识别。
target_lang:
type: string
description: 目标语言代码或项目支持的语言名称，例如 `ko`。详见[支持的语种](/api-reference/multimodal-translation/qwen-mt-uni/translate#支持的语种)。
ext:
type: object
description: 可选扩展参数。
properties:
domainHint:
type: string
description: |-
英文领域提示，最多 200 个英文单词。为使译文风格更贴合特定领域，可以使用英文描述使用场景、译文风格等需求。
领域提示语句当前**只支持英文**。
示例：`These sentences are from seller-buyer conversations on a B2C ecommerce platform. Translate them into clear, engaging customer service language.`
format_hint:
type: string
description: 格式提示。当 `fileUrl` 没有可识别后缀时，用它显式指定格式，如 `pdf`、`image`。
sensitives:
type: array
description: |-
敏感词列表，**区分大小写**，最多 50 个非空字符串。提取文本与某项完全相同时保留原文且不发送给模型。
示例：`["全场9折", "七天无理由退换"]`
items:
type: string
maxItems: 50
glossary:
type: array
description: |-
术语表，最多 100 组 `{"src": "源文本", "tgt": "目标文本"}`。当前作为 Prompt 术语表接入，支持保持原文、指定翻译和空目标词。
示例：`[{"src": "应用程序接口", "tgt": "API"}, {"src": "机器学习", "tgt": "ML"}]`
items:
type: object
required:
- src
- tgt
properties:
src:
type: string
description: 术语的源文本。
tgt:
type: string
description: 术语的目标文本。
maxItems: 100
config:
type: object
description: 额外配置选项。
properties:
imageSegment:
type: boolean
default: false
description: |-
**仅图像格式生效**。是否开启图像主体分割。开启后，将跳过对图像中主体（如人物、商品、Logo）上文字的翻译。
- `false`：（默认值）翻译图像中的所有文字
- `true`：不翻译图像主体的文字
SyncTranslationResponse:
type: object
description: 同步调用成功时的响应。顶层有 `output` 表示成功（结果在 `output.Data`，用量在 `usage`）。
properties:
request_id:
type: string
description: 顶层请求 ID，成功和失败均返回。
output:
type: object
description: 业务结果容器；成功时返回。
properties:
Success:
type: boolean
description: 是否成功，成功为 `true`。
Code:
type: integer
description: 业务结果码，成功为 `200`。
Message:
type: string
description: 结果说明，成功固定为 `Success`。
RequestId:
type: string
description: 本次调用的唯一 ID，便于问题排查。
Data:
type: object
description: 翻译结果。
properties:
FileType:
type: string
enum:
- strings
- document
- image
- audio
description: 结果类型：`strings`（文本）/ `document`（文档）/ `image`（图片）/ `audio`（音频）。
TranslatedTexts:
type: string
description: 文本翻译结果。**仅传 `source_texts` 时返回**，形状与入参一致（`string | array<string>`）。
TranslatedFileUrl:
type: string
description: 译后文件的下载地址（带签名，有有效期）。**仅传 `fileUrl` 时返回**。
usage:
type: object
description: Token 用量统计（在 output 之外的顶层），按 `input_tokens` 计费。
properties:
input_tokens:
type: integer
description: 输入 Token 总量。
output_tokens:
type: integer
description: 输出 Token 总量。
total_tokens:
type: integer
description: 输入与输出 Token 总量。
input_tokens_details:
type: object
description: 按内容类型划分的输入 Token 用量明细。
properties:
document_tokens:
type: integer
description: 文档类输入 Token 数。
audio_tokens:
type: integer
description: 音频类输入 Token 数。
character_tokens:
type: integer
description: 字符类输入 Token 数。
image_tokens:
type: integer
description: 图像类输入 Token 数。
output_tokens_details:
type: object
description: 按内容类型划分的输出 Token 用量明细，字段同 `input_tokens_details`。
properties:
document_tokens:
type: integer
description: 文档类输出 Token 数。
audio_tokens:
type: integer
description: 音频类输出 Token 数。
character_tokens:
type: integer
description: 字符类输出 Token 数。
image_tokens:
type: integer
description: 图像类输出 Token 数。
AsyncTaskSubmitResponse:
type: object
description: 异步任务成功创建时的响应。
properties:
request_id:
type: string
description: 请求唯一标识。可用于请求明细溯源和问题排查。
output:
type: object
description: 任务输出信息。
properties:
task_id:
type: string
description: 任务 ID。查询有效期 24 小时。
task_status:
type: string
enum:
- PENDING
description: 任务状态。新创建的任务始终返回 `PENDING`。
UniTaskStatusResponse:
type: object
description: 查询全模态翻译任务状态和结果时的响应。
properties:
request_id:
type: string
description: 本次查询请求的唯一标识；三种状态均返回。
output:
type: object
description: 异步任务状态及执行结果。
properties:
task_id:
type: string
description: 异步任务的唯一标识；三种状态均返回。
task_status:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
description: |-
异步任务状态。
- PENDING：任务排队中
- RUNNING：任务处理中
- SUCCEEDED：任务执行完成，需结合 `output.Success` 判断业务是否成功
- FAILED：任务执行失败
- UNKNOWN：任务不存在或状态未知
submit_time:
type: string
description: 任务提交时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
scheduled_time:
type: string
description: 任务开始调度时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
end_time:
type: string
description: 任务结束时间，格式为 `yyyy-MM-dd HH:mm:ss.SSS`。
Success:
type: boolean
description: 业务执行是否成功。`true`：成功；`false`：失败。待处理示例不返回。
Code:
type: integer
description: 业务结果码。`200` 表示成功，`400` 表示请求参数错误。待处理示例不返回。
Message:
type: string
description: 业务执行结果说明。成功示例为 `Success`；失败时返回错误详情。
RequestId:
type: string
description: 业务执行请求标识。成功和失败示例均返回。
Data:
type: object
description: 翻译结果数据；**仅业务成功时返回**。
properties:
FileType:
type: string
enum:
- strings
- document
- image
- audio
description: 结果类型：`strings`（文本）/ `document`（文档）/ `image`（图片）/ `audio`（音频）。
TranslatedTexts:
type: string
description: 文本翻译结果。**仅传 `source_texts` 时返回**，形状与入参一致（`string | array<string>`）。
TranslatedFileUrl:
type: string
description: 译后文件的下载地址（带签名及有效期参数）。**仅传 `fileUrl` 时返回**。
usage:
type: object
description: Token 用量统计。成功示例返回详细统计；失败示例返回空对象 `{}`；待处理示例不返回。按 `input_tokens` 计费。
properties:
input_tokens:
type: integer
description: 输入 Token 总量。
output_tokens:
type: integer
description: 输出 Token 总量。
total_tokens:
type: integer
description: 输入与输出 Token 总量。
input_tokens_details:
type: object
description: 按内容类型划分的输入 Token 用量明细。
properties:
document_tokens:
type: integer
description: 文档类输入 Token 数。
audio_tokens:
type: integer
description: 音频类输入 Token 数。
character_tokens:
type: integer
description: 字符类输入 Token 数。
image_tokens:
type: integer
description: 图像类输入 Token 数。
output_tokens_details:
type: object
description: 按内容类型划分的输出 Token 用量明细，字段同 `input_tokens_details`。
properties:
document_tokens:
type: integer
description: 文档类输出 Token 数。
audio_tokens:
type: integer
description: 音频类输出 Token 数。
character_tokens:
type: integer
description: 字符类输出 Token 数。
image_tokens:
type: integer
description: 图像类输出 Token 数。
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
code:
type: string
description: 错误码字符串（如 `InvalidParameter`、`InvalidApiKey`）。
message:
type: string
description: "错误详情，形如 `InvalidParameter: <原因>`。"
request_id:
type: string
description: 请求唯一标识。
````
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-client-events.md
+899
View File
@@ -0,0 +1,899 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 客户端事件
> Qwen-Omni-Realtime API的客户端事件参考。
## session.update
建立 WebSocket 连接后，发送此事件更新会话的默认配置。服务端收到 `session.update` 事件后校验参数，若参数不合法则返回错误，若参数合法则应用更改并返回会话配置。
<table style={{ display: "table", tableLayout: "fixed", width: "100%", overflowWrap: "anywhere" }}>
<colgroup>
<col style={{ width: "60%" }} />
<col style={{ width: "40%" }} />
</colgroup>
<tbody>
<tr>
<td style={{ verticalAlign: "top" }}>
**type**`string`**（必选）**
事件类型，固定为 `session.update`。
</td>
<td rowSpan={9} style={{ verticalAlign: "top" }}>
```json expandable
{
"event_id": "event_ToPZqeobitzUJnt3QqtWg",
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"model": "qwen3.5-omni-flash-realtime",
"voice": "Tina",
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000
}
},
"output": {
"format": {
"type": "wav",
"sample_rate": 24000
}
}
},
"instructions": "你是某五星级酒店的AI客服专员，请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应，杜绝提供未经证实或超出酒店服务范围的信息。",
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 800
},
"enable_search": false,
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "当你想查询指定城市的天气时非常有用。",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市或县区，比如北京市、杭州市、余杭区等。"
}
},
"required": ["location"]
}
}
}
],
"seed": 1314,
"max_tokens": 16384,
"repetition_penalty": 1.05,
"presence_penalty": 0.0,
"top_k": 50,
"top_p": 1.0,
"temperature": 0.9
}
}
```
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**session**`object`（可选）
会话配置。
Qwen3.8-Omni-Flash-Realtime 更新会话时必须提供 `session`。全部输入 Token 总数上限为 196608，输入长度计算规则与 Qwen3.5-Omni-Realtime 一致。
<Accordion title="属性" defaultOpen>
**modalities**`array`（可选）
模型输出模态设置，可选值：
- \["text"]
仅输出文本。
- \["text","audio"]（默认值）
同时输出文本和音频。
**voice**`string`（可选）
模型生成音频的音色，支持的音色参见[音色列表](/developer-guides/speech/omni-voice-list)。
默认音色：
- Qwen3.8-Omni-Flash-Realtime：`Tina`
- Qwen3.5-Omni-Realtime 系列模型：`Tina`
- Qwen3-Omni-Flash-Realtime：`Cherry`
- Qwen-Omni-Turbo-Realtime：`Chelsie`
**audio**`object`（可选）
<a id="session-audio" />
<a id="qwen38-client" />
输入和输出音频配置。未配置时沿用现有默认行为。
<Accordion title="属性" defaultOpen>
**input**`object`（可选）
用户输入音频配置。
<Accordion title="属性" defaultOpen>
**format**`object`（可选）
输入音频的格式和采样率。建议在会话 IDLE 阶段、发送首段音频前完成配置，音频输入开始后不可修改。
<Accordion title="属性" defaultOpen>
**type**`string`（可选）
`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime` 可选 `pcm`（默认值，单声道、16 bit 裸 PCM）或 `wav`（WAV 容器封装的单声道、16 bit PCM）。Qwen3.8-Omni-Flash-Realtime 的多通道输入只能使用 `pcm`，默认值为 `pcm`。
**sample\_rate**`integer`（可选）
`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime` 可选 8000、16000（默认值）、24000、48000 Hz。Qwen3.8-Omni-Flash-Realtime 的多通道输入只能使用 16000 Hz，默认值为 16000 Hz。
<a id="session-audio-multichannel" />以下四个字段适用于 Qwen3.8-Omni-Flash-Realtime 的 WebSocket 多通道输入：
**sample\_format**`string`（可选）
PCM 采样格式，只能为 `s16le`，默认值为 `s16le`。
**channels**`integer`（可选）
输入声道数，仅支持 1（默认值）、2、4。2、4 声道空间音频的输入 Token 数均为普通音频的 2 倍，详见[Token 计算](/developer-guides/getting-started/pricing#语音对话)。
**packing**`string`（可选）
多通道样本排列方式，只能为 `interleaved`，默认值为 `interleaved`。
**channel\_layout**`string`（可选）
按 `channels` 确定默认值：1 声道为 `mono`，2 声道为 `raw_mic_array`，4 声道为 `foa_ambix`。显式提供时必须与 `channels` 匹配。
多通道输入必须使用 PCM、16000 Hz、s16le 和 interleaved；字段省略时使用上述默认值，一旦提供则必须符合类型和值约束，不得以 `null` 代替省略。
</Accordion>
</Accordion>
**output**`object`（可选）
模型输出音频配置。
<Accordion title="属性" defaultOpen>
**format**`object`（可选）
模型输出音频的格式和采样率。建议在会话建立初期、尚未开始音频交互前完成配置。
<Accordion title="属性" defaultOpen>
**type**`string`（可选）
`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime` 可选 `pcm`（默认值，单声道、16 bit 裸 PCM）或 `wav`（WAV 容器封装的单声道、16 bit PCM）。
**sample\_rate**`integer`（可选）
`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime` 可选 8000、16000、24000（默认值）、48000 Hz。
</Accordion>
<a id="session-audio-voice" />**voice**`string`（可选）
Qwen3.8-Omni-Flash-Realtime 的输出音色，默认为 `Tina`。支持的音色及对应的 `voice` 参数值见[音色列表](/developer-guides/speech/omni-voice-list#qwen3-8-omni-flash-realtime)。`session.voice` 是兼容旧接入的字段，新接入建议使用 `session.audio.output.voice`。如果两个字段都设置，输出音频使用 `session.audio.output.voice` 指定的音色。
</Accordion>
</Accordion>
**input\_audio\_transcription**`object｜null`（可选）
<a id="session-input-audio-transcription" />
输入音频转录配置。设为 `null` 可关闭。
<Accordion title="属性" defaultOpen>
**model**`string`（必选）
固定为 `qwen3-asr-flash-realtime`；设置 `{"model":"qwen3-asr-flash-realtime"}` 可启用输入音频转录，不支持修改模型值。Python SDK 的 `enable_input_audio_transcription` 是 `update_session` 方法参数，不是 `session.update` 的顶层字段。
</Accordion>
**input\_audio\_format**`string`（可选）
历史兼容字段，新增接入建议使用 `audio.input.format` 同时配置输入格式和采样率。
**output\_audio\_format**`string`（可选）
历史兼容字段，新增接入建议使用 `audio.output.format` 同时配置输出格式和采样率。
**smooth\_output**`boolean｜null`（可选）
**仅在使用 Qwen3-Omni-Flash-Realtime 系列模型时生效。**
控制回复风格。可选值：
- `true`（默认值）：口语化风格。
- `false`：书面化、正式风格。
> 难以朗读的内容可能效果不好。
- `null`：模型自动选择口语化或书面化风格。
**instructions**`string`（可选）
系统消息，用于设定模型的目标或角色。
**turn\_detection**`object`（可选）
语音活动检测（VAD）配置。设为 `null` 可禁用 VAD，改为手动触发模型响应。若不提供此字段，系统将使用默认参数启用 VAD。
<Accordion title="属性">
**type**`string`（可选）
VAD 类型，可选值：
- `server_vad`（默认值）：基于声学特征检测语音结束。
- `semantic_vad`：基于语义有效性检测语音结束，可过滤回应语、背景音等无意义声音。Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型支持。
**threshold**`float`（可选）
VAD 灵敏度。值越低，VAD 越灵敏，越容易将微弱声音（包括背景噪音）识别为语音；值越高，越不灵敏，需要更清晰、音量更大的语音才能触发。
取值范围：`[-1.0, 1.0]`，默认值为 0.5。
**silence\_duration\_ms**`integer`（可选）
语音结束后需保持静音的最短时间（毫秒），超时即触发模型响应。值越低，响应越快，但可能在短暂停顿时误触发。
取值范围：\[200, 6000]，默认值为 800。
**idle\_timeout\_ms**`integer`（可选）
**仅在使用 `qwen3.5-omni-plus-realtime` 或 `qwen3.5-omni-flash-realtime` 模型且 VAD 类型为 `server_vad` 时生效。**
静默超时时间（毫秒）。服务端完成音频播报且用户持续静默超过该时间（未触发 `speech.started`）后，模型将主动触发一轮响应，基于当前上下文引导用户继续对话。超时计时从上一条模型响应的音频播放完毕后开始。
取值范围：\[5000, 30000]。
</Accordion>
**enable\_search**`boolean`（可选）
适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。
是否启用联网搜索。设为 `true` 启用，默认为 `false`。启用后，模型可自主判断是否需要联网搜索来回答用户问题。
> tools 和 enable\_search 不兼容，不可同时开启。
**search\_options**`object`（可选）
联网搜索选项配置，需先启用 `enable_search` 才生效。
<Accordion title="属性">
**enable\_source**`boolean`（可选）
是否在响应中返回搜索结果来源列表。设为 `true` 启用。
</Accordion>
**video**`object`（可选）
<a id="session-video" />
Qwen3.8-Omni-Flash-Realtime 的视频输入配置。
<Accordion title="属性" defaultOpen>
**input**`object`（可选）
视频输入参数。
<Accordion title="属性" defaultOpen>
**representation\_compact**`string`（可选）
视频输入表征聚合方式；会话初始默认 `none`，保留完整的细粒度视频输入表征。`normal` 聚合表征以降低计算开销，适用于对视觉细节要求不高的场景；相同视频输入的 Token 数为 `none` 模式的 1/4，详见[Token 计算](/developer-guides/getting-started/pricing#语音对话)。应在发送首段音频前设置，音频输入开始后不可修改。
</Accordion>
</Accordion>
**tools**`array`（可选）
<a id="session-tools" />
工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。Qwen3.8-Omni-Flash-Realtime 可在同一会话中同时配置 Function Calling 和 MCP 工具，数组元素按 `type` 区分；`tools` 与 `enable_search` 不可同时开启。
<Accordion title="Function Calling（type=function）" defaultOpen>
**type**`string`（必选）
固定为 `function`。
**function**`object`（必选）
自定义函数定义。
<Accordion title="属性" defaultOpen>
**name**`string`（必选）
工具函数名称，建议与函数名保持一致，例如 `get_current_weather` 或 `get_current_time`。
**description**`string`（可选）
对工具函数功能的描述，模型据此判断是否调用该工具。
**parameters**`object`（可选）
对工具函数入参的描述，模型据此提取所需入参。函数无需入参时可不指定。
<Accordion title="属性" defaultOpen>
**type**`string`（必选）
固定为 `object`。
**properties**`object`（可选）
按名称列出函数的入参定义。右侧示例中的 `location` 是自定义入参名称，其 `type` 和 `description` 分别描述数据类型和用途。
**required**`array`（可选）
指定哪些入参为必填项。
</Accordion>
</Accordion>
</Accordion>
<a id="session-tools-mcp" />
<Accordion title="MCP（type=mcp）" defaultOpen>
字段标为“必选”表示该 MCP 数组元素出现时必须提供。每次新增或更新 MCP 配置都必须同时提供 `server_label` 和 `server_url`，不能只传 `server_label` 复用已有配置；仅在没有活动 Response 时更新。MCP 连接、工具发现和调用受服务配额及超时限制，详见[MCP 调用限制](/api-reference/real-time-multimodal/interaction-process#使用限制)。
**type**`string`（必选）
固定为 `mcp`。
**server\_label**`string`（必选）
MCP Server 的会话内唯一标识，1～64 位，仅允许字母、数字、下划线和连字符。
**server\_url**`string`（必选）
MCP Streamable HTTP 地址，必须为公网 HTTPS 443 地址，最长 4096 字符；不得包含用户名、密码或 URL fragment，域名解析结果必须为公网地址。
**authorization**`string`（可选）
出站 Authorization 值，最长 8192 字符，仅允许可打印 ASCII 字符。
**headers**`object`（可选）
额外出站 HTTP Header，最多 16 个键值对。名称和值均为字符串。名称长 1～128 位，仅允许标准 HTTP Header 名称字符；值最长 8192 字符，仅允许可打印 ASCII 字符。
名称不得使用 `mcp-`、`proxy-`、`x-forwarded-` 前缀，也不得为 `host`、`authorization`、`connection`、`content-length`、`transfer-encoding`、`accept`、`content-type`、`forwarded`、`cookie`、`origin`、`upgrade`、`te`、`trailer`。
**allowed\_tools**`array[string]`（可选）
工具发现后的白名单过滤。省略表示允许全部，空数组表示不暴露任何工具。每个工具名 1～64 位，仅允许字母、数字、下划线、点和连字符。
**require\_approval**`string`（可选）
工具调用审批策略，可选 `always`（默认）或 `never`。
`server_url`、`authorization` 和 `headers` 仅用于服务端连接，不在 `session.updated` 中回显；客户端不应依赖该事件重建这些敏感配置。
</Accordion>
</Accordion>
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**temperature**`float`（可选）
采样温度，控制输出内容的多样性。值越高，输出越多样；值越低，输出越确定。
取值范围：\[0, 2)。
由于 temperature 和 top\_p 均可控制多样性，建议只设置其中一个。
默认值：
- `qwen3.8-omni-flash-realtime`：0.6
- Qwen3.5-Omni-Realtime 系列模型：0.7
- `qwen3-omni-flash-realtime` 系列：0.9
- `qwen-omni-turbo-realtime` 系列：1.0
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**top\_p**`float`（可选）
核采样概率阈值，控制输出内容的多样性。值越高，输出越多样；值越低，输出越确定。
取值范围：(0, 1.0]。
由于 temperature 和 top\_p 均可控制多样性，建议只设置其中一个。
默认值：
- `qwen3.8-omni-flash-realtime`：0.95
- Qwen3.5-Omni-Realtime 系列模型：0.8
- `qwen3-omni-flash-realtime` 系列：1.0
- `qwen-omni-turbo-realtime` 系列：0.01
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**top\_k**`integer`（可选）
采样候选集大小。例如设为 50 时，每步生成仅从得分最高的 50 个 Token 中采样。值越大，随机性越高；值越小，确定性越高。设为 `null` 或大于 100 时，禁用 top\_k 策略，仅 `top_p` 生效。
取值需大于或等于 0。
默认值：
- `qwen3.8-omni-flash-realtime`：20
- Qwen3.5-Omni-Realtime 系列模型：20
- `qwen3-omni-flash-realtime` 系列：50
- `qwen-omni-turbo-realtime` 系列：20
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**max\_tokens**`integer`（可选）
本次请求返回的最大 Token 数。
> `max_tokens` 不影响模型的生成过程。若模型生成的 Token 数超过 `max_tokens`，响应将被截断。
`qwen3.8-omni-flash-realtime` 的取值范围为 \[1, 65536]。其他模型的默认值和最大值均为模型的最大输出长度，各模型的最大输出长度参见[模型列表](/developer-guides/getting-started/model-selection)。
适用于需要限制输出长度的场景，如生成摘要或关键词、控制成本、缩短响应时间等。
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**repetition\_penalty**`float`（可选）
控制生成内容中连续序列的重复度。值越高，重复惩罚越强；1.0 表示不做惩罚。`qwen3.8-omni-flash-realtime` 支持取值 0；其他模型取值需大于 0，无严格上限。
默认值：
- `qwen3.8-omni-flash-realtime`：0
- Qwen3.5-Omni-Realtime 系列模型：1.0
- `qwen3-omni-flash-realtime` 系列：1.05
- `qwen-omni-turbo-realtime` 系列：1.05
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**presence\_penalty** `float`（可选）
控制生成内容的重复度。
取值范围：\[-2.0, 2.0]。正数降低重复度，负数增加重复度。
默认值：
- `qwen3.8-omni-flash-realtime`：1
- Qwen3.5-Omni-Realtime 系列模型：1.5
- `qwen3-omni-flash-realtime` 系列：0.0
- `qwen-omni-turbo-realtime` 系列：0.0
适用场景：
较高值适合创意写作、头脑风暴等需要多样性和创造性的场景。
较低值适合技术文档等需要一致性和专业术语的场景。
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**seed**`integer`（可选）
提高生成过程的确定性，常用于在相同参数下复现相同结果。
每次调用时传入相同的 seed 值并保持其他参数不变，模型将尽可能返回相同的结果。
取值范围：0 到 2<sup>31</sup>−1，默认值为 -1。
> `qwen-omni-turbo` 系列模型**不支持修改**。
</td>
</tr>
</tbody>
</table>
### 工具配置示例
配置 MCP 工具时，将地址与凭证替换为实际值；`allowed_tools` 使用 MCP Server 实际提供的工具名。
```json
{
"type": "session.update",
"session": {
"tools": [
{
"type": "mcp",
"server_label": "amap",
"server_url": "https://example.com/mcp",
"authorization": "Bearer ***",
"allowed_tools": ["maps_weather"],
"require_approval": "always"
}
]
}
}
```
### 音频配置示例
双通道示例：
```json
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000,
"sample_format": "s16le",
"channels": 2,
"packing": "interleaved",
"channel_layout": "raw_mic_array"
}
}
}
}
}
```
四通道示例：
```json
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000,
"sample_format": "s16le",
"channels": 4,
"packing": "interleaved",
"channel_layout": "foa_ambix"
}
}
}
}
}
```
单通道兼容示例：
```json
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000
}
}
}
}
}
```
`session.audio.output.voice` 配置示例（使用“龙安灵心”音色，其 `voice` 参数值为 `longanlingxin`）：
```json
{
"type": "session.update",
"session": {
"audio": {
"output": {
"voice": "longanlingxin"
}
}
}
}
```
### 视频配置示例
视频聚合示例：
```json
{
"type": "session.update",
"session": {
"video": {
"input": {
"representation_compact": "normal"
}
}
}
}
```
## response.create
`response.create` 事件用于指示服务端生成模型响应。VAD 模式下，服务端通常根据语音活动自动开始响应；工具调用后的续答仍按下述流程显式触发。Function Calling 场景中，客户端通过 `conversation.item.create` 回传工具结果后，发送此事件触发模型续答。Qwen3.8-Omni-Flash-Realtime 的 MCP 工具由服务端执行；如需基于 MCP 结果续答，应在本次 MCP 调用所在 Response 的 `response.done` 事件到达后发送一次 `response.create`，不附带 MCP 结果。
服务端以 `response.created` 事件开始响应，随后发送一个或多个项和内容事件（如 `conversation.item.created` 和 `response.content_part.added`），最后以 `response.done` 事件表示响应完成。
| **type**`string`（必选） 事件类型，固定为 `response.create`。 | 示例 1 请参见表格下方 |
| ------------------------------------------------ | ------------ |
**示例 1（示例 1 请参见表格下方）**：
```json
{
"type": "response.create",
"event_id": "event_1718624400000"
}
```
## response.cancel
客户端发送此事件取消正在进行的响应。若当前无响应可取消，服务端将返回错误事件。
| **type**`string`（必选） 事件类型，固定为 `response.cancel`。 | 示例 1 请参见表格下方 |
| ------------------------------------------------ | ------------ |
**示例 1（示例 1 请参见表格下方）**：
```json
{
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "response.cancel"
}
```
## input\_audio\_buffer.append
将音频字节追加到输入音频缓冲区。
<table style={{ display: "table", tableLayout: "fixed", width: "100%", overflowWrap: "anywhere" }}>
<colgroup>
<col style={{ width: "50%" }} />
<col style={{ width: "50%" }} />
</colgroup>
<tbody>
<tr>
<td style={{ verticalAlign: "top" }}>
**type**`string`（必选）
事件类型，固定为 `input_audio_buffer.append`。
</td>
<td rowSpan={2} style={{ verticalAlign: "top" }}>
```json
{
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_audio_buffer.append",
"audio": "UklGR..."
}
```
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**audio**`string`（必选）
Base64 编码的音频数据。
</td>
</tr>
</tbody>
</table>
## input\_audio\_buffer.commit
提交输入音频缓冲区，在对话中创建新的用户消息项。若音频缓冲区为空，服务端将返回错误事件。
- [VAD 模式](/api-reference/realtime-api/overview)：服务端自动提交音频缓冲区，客户端无需发送此事件。
- [Manual 模式](/api-reference/realtime-api/overview)：客户端必须提交音频缓冲区才能创建用户消息项。
提交音频缓冲区不会触发模型响应，服务端将以 `input_audio_buffer.committed` 事件响应。
> 若客户端已发送过 [input\_image\_buffer.append](/api-reference/real-time-multimodal/client-events#input-image-buffer-append) 事件，input\_audio\_buffer.commit 事件将同时提交图像缓冲区。
| **type**`string`（必选） 事件类型，固定为 `input_audio_buffer.commit`。 | 示例 1 请参见表格下方 |
| ---------------------------------------------------------- | ------------ |
**示例 1（示例 1 请参见表格下方）**：
```json
{
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_audio_buffer.commit"
}
```
## input\_audio\_buffer.clear
清除音频缓冲区中的字节。服务端以 `input_audio_buffer.cleared` 事件响应。
| **type**`string`（必选） 事件类型，固定为 `input_audio_buffer.clear`。 | 示例 1 请参见表格下方 |
| --------------------------------------------------------- | ------------ |
**示例 1（示例 1 请参见表格下方）**：
```json
{
"event_id": "event_xxx",
"type": "input_audio_buffer.clear"
}
```
## input\_image\_buffer.append
将图像数据添加到图像缓冲区。图像可来自本地文件，也可从视频流实时采集。
图片输入限制如下：
- 图像格式必须为 JPG 或 JPEG。建议分辨率为 480p 或 720p 以获得最佳性能，最高不超过 1080p。
- 单张图片经Base64编码后不得超过256KB，建议编码前原始图片大小不超过190KB。
- 图片数据需经过 Base64 编码。
- 建议以 1 张/秒的频率向服务端发送图像。
- 发送 input\_image\_buffer.append 事件前，至少已发送过一次 input\_audio\_buffer.append 事件。
> 图像缓冲区与音频缓冲区通过 [input\_audio\_buffer.commit](/api-reference/real-time-multimodal/client-events#input-audio-buffer-commit) 事件一起提交。
<table style={{ display: "table", tableLayout: "fixed", width: "100%", overflowWrap: "anywhere" }}>
<colgroup>
<col style={{ width: "50%" }} />
<col style={{ width: "50%" }} />
</colgroup>
<tbody>
<tr>
<td style={{ verticalAlign: "top" }}>
**type**`string`（必选）
事件类型，固定为 `input_image_buffer.append`。
</td>
<td rowSpan={2} style={{ verticalAlign: "top" }}>
```json
{
"event_id": "event_xxx",
"type": "input_image_buffer.append",
"image": "xxx"
}
```
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**image**`string`（必选）
Base64 编码的图像数据。
</td>
</tr>
</tbody>
</table>
## conversation.item.create
客户端发送此事件创建对话项，包括 Function Calling 的工具执行结果，以及 Qwen3.8-Omni-Flash-Realtime 的 MCP 审批回复。Function Calling 由客户端执行工具，再以 `function_call_output` 回传结果并发送 `response.create`；MCP 工具由服务端执行，审批回复使用 `mcp_approval_response`，续答时序见[审批回复](#mcp-审批回复-qwen3-8-omni-flash-realtime)。
<table style={{ display: "table", tableLayout: "fixed", width: "100%", overflowWrap: "anywhere" }}>
<colgroup>
<col style={{ width: "50%" }} />
<col style={{ width: "50%" }} />
</colgroup>
<tbody>
<tr>
<td style={{ verticalAlign: "top" }}>
**event\_id**`string`（可选）
客户端生成的事件 ID，用于日志追踪。
**type**`string`（必选）
事件类型，固定为 `conversation.item.create`。
</td>
<td rowSpan={2} style={{ verticalAlign: "top" }}>
```json
{
"event_id": "event_55099cddb51b4f208cb95d1a994eef80",
"type": "conversation.item.create",
"item": {
"id": "item_2a80d7682b4e473c9c2154da135041e9",
"type": "function_call_output",
"call_id": "call_62c24725afdb4c2680ac54",
"output": "北京今天天气为霾转晴，气温4/-4℃，微风"
}
}
```
</td>
</tr>
<tr>
<td style={{ verticalAlign: "top" }}>
**item**`object`（必选）
要创建的对话项，不能为空。
<Accordion title="属性" defaultOpen>
**id**`string`（可选）
对话项 ID。可预先指定以对齐本地状态；若未提供，由服务端生成。
**type**`string`（必选）
`function_call_output`（Function Calling 结果）或 `mcp_approval_response`（Qwen3.8-Omni-Flash-Realtime 的 MCP 审批回复）。
**call\_id**`string`（条件必选）
仅 `function_call_output` 必填；取 `response.function_call_arguments.done` 事件中返回的 `call_id`。
**output**`string`（条件必选）
仅 `function_call_output` 必填；工具函数的执行结果。
**approval\_request\_id**`string`（条件必选）
仅 `mcp_approval_response` 必填；必须精确匹配一个尚未处理的 `mcp_approval_request` 的 `item.id`。
**approve**`boolean`（条件必选）
仅 `mcp_approval_response` 必填；`true` 允许执行，`false` 拒绝且本次调用进入 `failed`。
</Accordion>
</td>
</tr>
</tbody>
</table>
### MCP 审批回复（Qwen3.8-Omni-Flash-Realtime）
当 MCP 配置的 `require_approval` 为 `always` 或省略时，服务端可能发送 `mcp_approval_request`。客户端以本节定义的 `conversation.item.create` 和 `item.type="mcp_approval_response"` 回复审批结果。服务端执行 MCP 工具；如需基于结果续答，等待本次 MCP 调用所在 Response 的 `response.done` 事件，再发送一次不附带 MCP 结果的 `response.create`。
服务端返回的审批请求 ID、对话项 ID 和事件 ID 均为不透明字符串，不应依赖其长度、前缀或生成规则。
示例：
```json
{
"event_id": "event_client_xxx",
"type": "conversation.item.create",
"item": {
"type": "mcp_approval_response",
"approval_request_id": "opaque_approval_id",
"approve": true
}
}
```
> 另请参见： [实时（Qwen-Omni-Realtime）](/api-reference/realtime-api/overview) 。
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-interaction-process.md
+136
View File
@@ -0,0 +1,136 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# WebSocket 接入指南
> 介绍 Qwen-Omni-Realtime 系列模型的 WebSocket 接入地址、交互流程及 SDK。
## 接入地址
适用模型：`qwen3.8-omni-flash-realtime`、`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`。
`wss://maas.qianwenaiapi.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime`
将 `model` 替换为要调用的模型名称。鉴权和连接前的准备工作请参见[接入概览](/api-reference/realtime-api/websocket-overview)。
## 接入流程
### VAD 模式
将[客户端事件](/api-reference/real-time-multimodal/client-events)事件的`session.turn_detection.type` 设为`"server_vad"`以启用 VAD 模式。在 VAD 模式下，服务端对传入的音频进行语音活动检测，并在检测到作出响应。此模式适用于客户端到服务器始终发送音频的情况，也是当前的默认模式。
![server\_vad](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0520773571/p991064.svg)
- 服务端在检测到语音开始时发送`input_audio_buffer.speech_started` 事件。
- 客户端随时可以选择通过发送 `input_audio_buffer.append` 事件将音频追加到缓冲区。
- 服务端在检测到语音结束时发送`input_audio_buffer.speech_stopped`事件。
- 服务端通过发送 `input_audio_buffer.committed` 事件来提交输入音频缓冲区。
- 服务端发送 `conversation.item.created` 事件，其中包含从音频缓冲区创建的用户消息项。
#### Function Calling 流程
在 VAD 模式下，当服务端生成的响应需要客户端执行 Function Calling 工具时，遵循以下交互流程：
![image.svg](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/3014236771/p1067613.svg)
- 服务端在检测到语音结束并生成响应时，识别到需要调用工具。
- 服务端发送 `response.function_call_arguments.delta` 事件，包含工具调用参数的增量数据。
- 服务端发送 `response.function_call_arguments.done` 事件，表示工具调用参数传递完成。
- 客户端执行工具调用并获取结果。
- 客户端通过 `conversation.item.create` 事件发送工具调用结果。
- 客户端发送 `response.create` 事件，触发服务端基于工具调用结果生成响应。
### Manual 模式
将[客户端事件](/api-reference/real-time-multimodal/client-events)事件的`session.turn_detection` 设为 null 以启用 Manual 模式。此模式下，客户端通过显式发送`input_audio_buffer.commit` 和`response.create`事件请求服务器响应。适用于按下即说场景，如聊天软件中的发送语音。
![manual](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0520773571/p991066.svg)
- 客户端可以通过发送 `input_audio_buffer.append` 事件将音频追加到缓冲区。
- 客户端通过发送 `input_audio_buffer.commit`事件来提交输入音频缓冲区。 该提交会在对话中创建一个新的用户消息项。
- 服务器通过发送 `input_audio_buffer.committed`事件进行响应。
- 客户端发送 `response.create` 事件，触发模型生成最终响应。
- 服务器通过发送 `conversation.item.created`事件进行响应。
#### Function Calling 流程
![image.svg](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/3014236771/p1067740.svg)
在 Manual 模式下，当服务端生成的响应需要客户端执行 Function Calling 工具时，遵循以下交互流程：
- 客户端发送 `response.create` 事件后，服务端生成响应并识别到需要调用工具。
- 服务端发送 `response.function_call_arguments.delta` 事件，包含工具调用参数的增量数据。
- 服务端发送 `response.function_call_arguments.done` 事件，表示工具调用参数传递完成。
- 客户端执行工具调用并获取结果。
- 客户端通过 `conversation.item.create` 事件发送工具调用结果。
- 客户端发送 `response.create` 事件，触发模型生成最终响应。
- 服务端基于工具调用结果生成响应，并通过 `response.audio.delta` 或 `response.text.delta` 事件返回给客户端。
## MCP 工具调用
以下流程适用于 Qwen3.8-Omni-Flash-Realtime，可与上述 VAD 或 Manual 模式配合使用。
Function Calling 与 MCP 可以在同一会话的 `session.tools` 中配置，不能同时启用联网搜索（`enable_search`）。千问AI平台不额外收取 MCP 工具调用费，模型推理仍按模型价格计费。
MCP 由服务端执行工具，前述 Function Calling 流程则由客户端执行工具，两者的结果回传方式不同。
### 工具发现
客户端通过 `session.update` 配置 MCP 服务后，由 Realtime 服务异步发现工具，交互流程如下：
<Image src="https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/images/6a4b3c2d1e0f92df.png" alt="MCP 工具发现时序图" width={558} />
本节时序图中，`opt` 表示满足条件时执行，`alt` 表示按条件选择不同分支，`par` 表示并行处理。
- `session.updated` 仅表示 MCP 配置已接受，不表示工具已经可用。
- `mcp_list_tools.in_progress` 可能早于 `session.updated` 到达。
- 客户端可以在工具发现完成前继续发送音频或 `response.create`；但只有发现完成后的 Response 才能使用对应 MCP 工具。
- 工具发现成功时，服务端先发送包含最终工具列表的 `conversation.item.created`，再发送 `mcp_list_tools.completed`。
- 工具发现失败时，服务端先发送包含 error 的 `conversation.item.created`，再发送 `mcp_list_tools.failed`。
### MCP 调用与续答
模型选择 MCP 工具后，由 Realtime 服务执行工具调用；需要审批时，客户端先回复审批结果。交互流程如下：
<Image src="https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/images/6a4b3c2d1e0f92de.png" alt="MCP 工具调用、审批与续答时序图" width={558} />
审批拒绝或超时会直接触发 `response.mcp_call.failed`，不执行工具，也不会经过 `response.mcp_call.in_progress`。无需审批或审批通过时，典型事件顺序如下：
```text
response.output_item.added（mcp_call）
→ response.mcp_call_arguments.delta
→ response.mcp_call_arguments.done
→ 可选：conversation.item.created（mcp_approval_request）
→ 可选：conversation.item.create（mcp_approval_response）
→ response.mcp_call.in_progress
→ response.mcp_call.completed 或 response.mcp_call.failed
→ response.output_item.done（最终 mcp_call）
→ response.done（父 Response）
```
服务端会在同一父 Response 的全部 MCP item 进入终态后发送 `response.done`。其中 `response.output` 已包含最终 mcp\_call 快照：成功项为 completed 并包含 output；失败项为 failed 并包含 error。
如果需要模型基于 MCP 结果继续生成回答，客户端应在收到父 `response.done` 后发送一次不附带 MCP 结果的 `response.create`。
参见[客户端 MCP 工具配置](/api-reference/real-time-multimodal/client-events#session-tools-mcp)、[审批回复](/api-reference/real-time-multimodal/client-events#mcp-审批回复-qwen3-8-omni-flash-realtime)、[MCP 服务端事件](/api-reference/real-time-multimodal/server-events#mcp-事件)和[MCP 对话项](/api-reference/real-time-multimodal/server-events#mcp-对话项)。
### 使用限制
以下为每个会话的 MCP 默认约束：
| 项目 | 默认值 |
| -------- | ---- |
| MCP 服务数 | 8 |
| MCP 工具数 | 128 |
| 工具发现超时 | 30 秒 |
| 审批超时 | 60 秒 |
| 工具执行超时 | 30 秒 |
| 单次上游响应大小 | 2 MB |
| 累计工具结果大小 | 8 MB |
| 累计工具调用数 | 256 |
## SDK
- [Python SDK](/api-reference/real-time-multimodal/realtime-python-sdk)
- [Java SDK](/api-reference/real-time-multimodal/realtime-java-sdk)
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-model-access.md
+39
View File
@@ -0,0 +1,39 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen-Omni-Realtime 模型接入方式
> 介绍 Qwen-Omni-Realtime 的接入入口、SDK 和事件参考。
## 接入方式
<Note>
Qwen3.8-Omni-Flash-Realtime、Qwen3.5-Omni-Plus-Realtime 和 Qwen3.5-Omni-Flash-Realtime 模型支持 AOQ（AI over QUIC）、WebRTC 和 WebSocket 三种传输协议，开发者可以根据业务场景灵活选择。详细接入流程请参见 [Realtime API](/api-reference/realtime-api/overview)。
</Note>
<Tabs>
<Tab title="AOQ">
- [AOQ 接入](/api-reference/realtime-api/aoq-access)
</Tab>
<Tab title="WebSocket">
通过 [WebSocket 接入指南](/api-reference/real-time-multimodal/interaction-process)了解连接地址及交互流程。
SDK 接入：
- [Python SDK](/api-reference/real-time-multimodal/realtime-python-sdk)
- [Java SDK](/api-reference/real-time-multimodal/realtime-java-sdk)
</Tab>
<Tab title="WebRTC">
- [WebRTC 接入](/api-reference/realtime-api/webrtc-access)
</Tab>
</Tabs>
## 事件参考
模型参数和事件字段的详细定义请参见：
- [客户端事件](/api-reference/real-time-multimodal/client-events)
- [服务端事件](/api-reference/real-time-multimodal/server-events)
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-realtime-java-sdk.md
+239
View File
@@ -0,0 +1,239 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Java SDK
> 本文介绍 DashScope Java SDK 调用 Qwen-Omni 实时模型 时的关键接口与请求参数。
## 前期准备
您的 Java SDK 版本需要不低于v2.22.15。请先阅读[实时多模态交互流程](/api-reference/real-time-multimodal/interaction-process)。
## 快速开始
使用 `qwen3.8-omni-flash-realtime` 时，将会话构造参数 `model` 设为该模型名，默认音色为 `Tina`。Java SDK 会话配置和视频聚合参数示例见[实时调用指南](/developer-guides/speech/realtime-multimodal-speech#2-配置会话)。
请访问[github](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni)下载示例代码。我们提供了三种调用方式的示例代码：
1. [音频对话示例](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java)：麦克风采集实时音频输入，开启[VAD 模式](/api-reference/realtime-api/overview)（自动检测语音起止），支持语音打断。
> enableTurnDetection 参数需设为 `true`。
> 推荐您使用耳机播放音频，避免回声触发语音打断。
2. [音视频对话示例](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java)：麦克风和摄像头采集实时音视频输入，开启[VAD 模式](/api-reference/realtime-api/overview)（自动检测语音起止），支持语音打断。
> enableTurnDetection 参数需设为 `true`。
> 推荐您使用耳机播放音频，避免回声触发语音打断。
3. [本地调用](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java)：本地音频和图片作为输入，开启[Manual 模式](/api-reference/realtime-api/overview)（手动控制发送节奏）。
> enableTurnDetection 参数需设为 `false`。
## 请求参数
下述请求参数可以通过`OmniRealtimeParam`对象的链式方法或setter配置、之后作为参数传入OmniRealtimeConversation的构造方法完成配置。
| **参数** | **类型** | **说明** |
| ------ | ------ | ----------------------------------------------------------------------------------- |
| model | String | Qwen-Omni 实时模型的名称。参见[模型列表](/developer-guides/getting-started/model-selection)。 |
| url | String | 调用地址：<br /><ul> <li>wss\://maas.qianwenaiapi.com/api-ws/v1/realtime<br /></li></ul> |
下述请求参数可以通过`OmniRealtimeConfig`对象的链式方法或setter配置、之后作为参数传入updateSession接口完成配置。
| **参数** | **类型** | **说明** |
| ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| modalities | List\<OmniRealtimeModality> | 模型输出模态设置，支持设置\[OmniRealtimeModality.TEXT]（仅输出文本）或\[OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO]（输出音频和文本）。 |
| voice | String | 模型生成音频的音色，支持的音色参见[音色列表](/developer-guides/speech/omni-voice-list)。 默认音色： <ul><li>Qwen3.5-Omni: "Tina"</li><li>Qwen3-Omni-Flash-Realtime：“Cherry”，</li><li>Qwen-Omni-Turbo-Realtime：“Chelsie”</li></ul> |
| inputAudioFormat | OmniRealtimeAudioFormat | 用户输入音频的格式，当前仅支持设为`PCM_16000HZ_MONO_16BIT`，表示16 kHz采样率的PCM音频流。 |
| outputAudioFormat | OmniRealtimeAudioFormat | 模型输出音频的格式，当前仅支持设为`PCM_24000HZ_MONO_16BIT`，表示24 kHz采样率的PCM音频流。当前不支持自定义输出采样率。 |
| instructions | String | 系统消息，用于设定模型的目标或角色。 例如：你是某五星级酒店的AI客服专员，请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应，杜绝提供未经证实或超出酒店服务范围的信息。 **说明：** `instructions`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置： 示例 1 请参见表格下方 |
| smooth\_output | Boolean | 仅Qwen3-Omni-Flash-Realtime系列版本支持设置。 <ul><li>true：获得口语化的回复</li><li>false：获得更书面化、正式的回复</li></ul> > 但可能会因为存在难以朗读的内容而导致效果不好。 <ul><li>null：默认值，模型自动选择口语化或书面化的回复风格</li></ul> > `smooth_output`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| enableInputAudioTranscription | Boolean | 是否开启输入音频的语音识别。 |
| InputAudioTranscription | String | 用于输入音频转录的语音识别模型，固定为qwen3-asr-flash-realtime，不支持修改 |
| enableTurnDetection | Boolean | 是否开启语音活动检测（VAD），如果关闭后，由用户手动提交音频创建omni回复。 |
| turnDetectionType | String | VAD类型，取值如下： <ul><li>`server&#95;vad`（默认值）：基于声学特征检测用户语音结束。</li><li>`semantic&#95;vad`：基于语义有效性检测用户语音结束，可过滤无意义语音（如回应语、背景音）。Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型支持。</li></ul> |
| turnDetectionThreshold | Float | VAD检测阈值。建议在嘈杂的环境中增加， 在安静的环境中降低。 <ul><li>取值越接近-1，噪音被判定为语音的概率越大。</li><li>取值越接近1，噪音被判定为语音的概率越小。</li></ul> 默认为 0.5, 参数范围：\[-1.0, 1.0]。 |
| turnDetectionSilenceDurationMs | Integer | 检测语音停止的静音持续时间，超过此值后会触发模型响应。默认值为800，参数范围\[200, 6000]。 |
| turnDetectionParam | Map | VAD 扩展参数，用于传入 `turn_detection` 的额外配置项。当前支持传入 `idle_timeout_ms`（Integer）：静默超时时间（毫秒）。**仅在使用**`qwen3.5-omni-plus-realtime`**或**`qwen3.5-omni-flash-realtime`**模型且 VAD 类型为**`server_vad`\*\*时生效。\*\*服务端完成音频播报且用户持续静默超过该时间（未触发 `speech.started`）后，模型将主动触发一轮响应，基于当前上下文引导用户继续对话。取值范围：\[5000, 30000]。 示例：`turnDetectionParam(Map.of("idle_timeout_ms", 5000))` |
| enable\_search | Boolean | 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。 是否启用联网搜索功能。设置为 `true` 启用，默认为 `false`。启用后，模型可自主判断是否需要搜索来回应用户的即时问题。 > `enable_search`和`search_options`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 > 工具调用（tools）和联网搜索（enable\_search）不兼容，不可同时开启。 |
| search\_options | Object | 联网搜索选项配置。需启用 `enable_search` 后才生效。目前支持设置 `enable_source`（Boolean），表示是否返回搜索结果来源列表，设置为 `true` 启用。 > `search_options`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| tools | List\<Map\<String, Object>> | 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。 工具定义列表。启用后，模型可自主判断是否需要调用外部工具来回应用户的问题。命中 Function Calling 时，模型不生成音频，仅返回工具调用参数。 Qwen3.8-Omni-Flash-Realtime 可在同一会话中配置 Function Calling 和 MCP 工具。MCP 配置字段见[客户端事件](/api-reference/real-time-multimodal/client-events#session-tools-mcp)，调用限制见[MCP 调用限制](/api-reference/real-time-multimodal/interaction-process#使用限制)。`tools` 与 `enable_search` 不可同时开启，该限制也适用于 MCP。 以下字段描述 Function Calling 工具。每个工具为一个 Map，包含以下字段： <ul><li>`type`（String，必选）：固定为 "function"。</li><li>`function`（Map，必选）：工具函数的定义，包含以下字段：</li></ul> <ul><li>`name`（String，必选）：自定义的工具函数名称，建议使用与函数相同的名称，如 get\_current\_weather 或 get\_current\_time。</li><li>`description`（String，可选）：对工具函数功能的描述，大模型会参考该字段来选择是否使用该工具函数。</li><li>`parameters`（Map，可选）：对工具函数入参的描述，大模型会参考该字段来进行入参的提取。如果工具函数不需要输入参数，则无需指定。包含以下字段：</li></ul> <ul><li>`type`（String，必选）：固定为 "object"。</li><li>`properties`（Map，可选）：描述各入参的名称、数据类型与描述。Key 值为入参的名称，Value 值为包含数据类型（type）与描述（description）的 Map。</li><li>`required`（List，可选）：指定哪些入参为必填项。</li></ul> > `search_options`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| temperature | Float | 采样温度，控制模型生成内容的多样性。 temperature越高，生成的内容更多样，反之，生成的内容更确定。 取值范围： \[0, 2) 由于temperature与top\_p均可以控制生成内容的多样性，因此建议您只设置其中一个值。 temperature默认值： <ul><li>`qwen3.8-omni-flash-realtime`：0.6</li><li>`qwen3.5-omni-realtime`系列：0.7</li><li>`qwen3-omni-flash-realtime`系列：0.9</li><li>`qwen-omni-turbo-realtime`系列：1.0</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 > `temperature`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| top\_p | Float | 核采样的概率阈值，控制模型生成内容的多样性。 top\_p越高，生成的内容更多样。反之，生成的内容更确定。 取值范围：（0,1.0] 由于temperature与top\_p均可以控制生成内容的多样性，因此建议您只设置其中一个值。 top\_p默认值： <ul><li>`qwen3.8-omni-flash-realtime`：0.95</li><li>`qwen3.5-omni-realtime`系列：0.8</li><li>`qwen3-omni-flash-realtime`系列：1.0</li><li>`qwen-omni-turbo-realtime`系列：0.01</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 > `top_p`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| top\_k | Integer | 生成过程中采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top\_k大于100时，表示不启用top\_k策略，此时仅有top\_p策略生效。 取值需要大于或等于0。 top\_k默认值： <ul><li>`qwen3.8-omni-flash-realtime`：20</li><li>`qwen3.5-omni-realtime`系列：20</li><li>`qwen3-omni-flash-realtime`系列：50</li><li>`qwen-omni-turbo-realtime`系列：20</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 > `top_k`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| max\_tokens | Integer | 本次请求返回的最大 Token 数。 > `max_tokens` 的设置不会影响大模型的生成过程，如果模型生成的 Token 数超过`max_tokens`，本次请求会返回截断后的内容。 `qwen3.8-omni-flash-realtime` 的取值范围为 \[1, 65536]。其他模型的默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度，请参见[模型列表](/developer-guides/getting-started/model-selection)。 max\_tokens参数适用于需要限制字数（如生成摘要、关键词）、控制成本或减少响应时间的场景。 > `qwen-omni-turbo` 系列模型**不支持修改**。 > `max_tokens`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| repetition\_penalty | Float | 模型生成时连续序列中的重复度。提高repetition\_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。`qwen3.8-omni-flash-realtime` 支持取值 0；其他模型没有严格的取值范围，只要大于0即可。 repetition\_penalty默认值： <ul><li>`qwen3.8-omni-flash-realtime`：0</li><li>`qwen3.5-omni-realtime`系列：1.0</li><li>其他模型：1.05</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 > `repetition_penalty`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| presence\_penalty | Float | 控制模型生成内容时的重复度。 取值范围：\[-2.0, 2.0]。正数会减少重复度，负数会增加重复度。 presence\_penalty默认值： <ul><li>`qwen3.8-omni-flash-realtime`：1</li><li>`qwen3.5-omni-realtime`系列：1.5</li><li>其他模型：0.0</li></ul> 适用场景： 较高的presence\_penalty适用于要求多样性、趣味性或创造性的场景，如创意写作或头脑风暴。 较低的presence\_penalty适用于要求一致性或专业术语的场景，如技术文档或其他正式文档。 > `qwen-omni-turbo` 系列模型**不支持修改**。 > `presence_penalty`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
| seed | Integer | 设置seed参数会使模型生成过程更具有确定性，通常用于使模型每次运行的结果一致。 在每次模型调用时传入相同的seed值（由您指定），并保持其他参数不变，模型将尽可能返回相同的结果。 取值范围：0到231−1，默认值-1。 > `qwen-omni-turbo` 系列模型**不支持修改**。 > `seed`需要通过`OmniRealtimeConfig`实例的`parameters`方法进行设置，用法与`instructions`一致。 |
**示例 1（说明）**：
```java
conversation.updateSession(OmniRealtimeConfig.builder()
.modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
.voice("Tina")
.enableTurnDetection(true)
.enableInputAudioTranscription(true)
.parameters(Map.of(
"instructions", "你是个人助理小云"
))
.build()
);
```
## 关键接口
### OmniRealtimeConversation类
OmniRealtimeConversation通过`import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;`方法引入。
| 方法签名 | 服务端响应事件（通过回调下发） | 说明 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 示例 1 请参见表格下方 | [服务端事件](/api-reference/real-time-multimodal/server-events) > 会话已创建 [session.updated](/api-reference/real-time-multimodal/server-events#session-updated) > 会话配置已更新 | 和服务端创建连接。 |
| 示例 2 请参见表格下方 | [session.updated](/api-reference/real-time-multimodal/server-events#session-updated) > 会话配置已更新 | 更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。 在您建立链接，服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置，我们也推荐您总是在建立链接后即刻调用此接口。 服务端在收到session.update事件后，会进行参数校验，如果参数不合法则返回错误，否则更新服务端侧的会话配置。 |
| 示例 3 请参见表格下方 | 无 | 将base64编码后的音频数据片段追加到云端输入音频缓冲区。 音频缓冲区是你可以写入并稍后提交的临时存储。 <ul><li>打开"turn\_detection"，音频缓冲区用于检测语音，服务器决定何时提交。</li><li>关闭"turn\_detection"，客户端可以选择每个事件中放置多少音频量，最多放置 15 MiB。 例如，从客户端流式处理较小的数据块可以让 VAD 响应更迅速。</li></ul> |
| 示例 4 请参见表格下方 | 无 | 将base64编码后的图片数据添加到云端视频缓冲区。图片数据可以是本地的图片，或从视频流实时采集的图片数据。 目前对图片输入有以下限制： <ul><li>图片格式需要为JPG或JPEG，建议传入的图片分辨率为480P或720P， 最大1080P；</li><li>单张图片经Base64编码后不得超过256KB，建议编码前原始图片大小不超过190KB；</li><li>图片数据需要经过Base64编码；</li><li>建议您以 1张/秒 的频率向服务端发送图片；</li></ul> |
| 示例 5 请参见表格下方 | [input\_audio\_buffer.cleared](/api-reference/real-time-multimodal/server-events#input-audio-buffer-cleared) > 清空服务端收到的音频 | 删除当前云端缓冲区的音频。 |
| 示例 6 请参见表格下方 | [input\_audio\_buffer.committed](/api-reference/real-time-multimodal/server-events#input-audio-buffer-committed) > 服务器收到提交的音频 | 提交之前通过append添加到云端缓冲区的音视频，如果输入的音频缓冲区为空将产生错误。 <ul><li>打开"turn\_detection"，客户端不需要发送此事件，服务器会自动提交音频缓冲区。</li><li>关闭"turn\_detection"，客户端必须提交音频缓冲区才能创建用户消息项。</li></ul> **注意**： 1. 如果 input\_audio\_transcription为会话配置了音频转录，系统会转录音频。 2. 提交输入音频缓冲区不会从模型创建响应。 |
| 示例 7 请参见表格下方 | [服务端事件](/api-reference/real-time-multimodal/server-events) > 服务端开始生成响应 [response.output\_item.added](/api-reference/real-time-multimodal/server-events#response-output-item-added) > 响应时有新的输出内容 [服务端事件](/api-reference/real-time-multimodal/server-events) > 对话项被创建 [response.content\_part.added](/api-reference/real-time-multimodal/server-events#response-content-part-added) > 新的输出内容添加到assistant message 项 [response.audio\_transcript.delta](/api-reference/real-time-multimodal/server-events#response-audio-transcript-delta) > 增量生成的转录文字 [response.audio.delta](/api-reference/real-time-multimodal/server-events#response-audio-delta) > 模型增量生成的音频 [response.audio\_transcript.done](/api-reference/real-time-multimodal/server-events#response-audio-transcript-done) > 完成文本转录 [response.audio.done](/api-reference/real-time-multimodal/server-events#response-audio-done) > 完成音频生成 [response.content\_part.done](/api-reference/real-time-multimodal/server-events#response-content-part-done) > Assistant mesasge 的文本或音频内容流式输出完成 [response.output\_item.done](/api-reference/real-time-multimodal/server-events#response-output-item-done) > Assistant mesasge 的整个输出项流式传输完成 [response.done](/api-reference/real-time-multimodal/server-events#response-done) > 响应完成 | 指示服务器创建模型响应。 打开"turn\_detection"模式下配置会话时，服务器会自动创建模型响应。 |
| 示例 8 请参见表格下方 | 无 | 取消正在进行的响应。如果没有任何响应可供取消，服务器将以一个错误进行响应。 |
| 示例 9 请参见表格下方 | 无 | 向服务端发送 `conversation.item.create` 事件。 回传 Function Calling 工具结果时，`item` 为 JsonObject，包含以下字段： <ul><li>`type`：固定为 `function&#95;call&#95;output`。</li><li>`call&#95;id`：对应 `response.function&#95;call&#95;arguments.done` 事件中的 call\_id。</li><li>`output`：工具执行结果的字符串。</li></ul> MCP 审批也使用此事件，但 `item.type` 为 `mcp_approval_response`；字段见[客户端事件中的 MCP 审批回复](/api-reference/real-time-multimodal/client-events#mcp-审批回复-qwen3-8-omni-flash-realtime)。 |
| 示例 10 请参见表格下方 | 无 | 终止任务，并关闭连接。 |
| 示例 11 请参见表格下方 | 无 | 获取当前任务的session\_id。 |
| 示例 12 请参见表格下方 | 无 | 获取最近一次response的response\_id。 |
**示例 1（方法签名）**：
```java
public void connect() throws NoApiKeyException, InterruptedException
```
**示例 2（方法签名）**：
```java
public void updateSession(OmniRealtimeConfig config)
```
**示例 3（方法签名）**：
```java
public void appendAudio(String audioBase64)
```
**示例 4（方法签名）**：
```java
public void appendVideo(String videoBase64)
```
**示例 5（方法签名）**：
```java
public void clearAppendedAudio()
```
**示例 6（方法签名）**：
```java
public void commit()
```
**示例 7（方法签名）**：
```java
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
```
**示例 8（方法签名）**：
```java
public void cancelResponse()
```
**示例 9（方法签名）**：
```java
public void createItem(JsonObject item)
```
**示例 10（方法签名）**：
```java
public void close()
```
**示例 11（方法签名）**：
```java
public String getSessionId()
```
**示例 12（方法签名）**：
```java
public String getResponseId()
```
### 回调接口（OmniRealtimeCallback）
服务端会通过回调的方式，将服务端响应事件和数据返回给客户端。您需要实现回调方法，处理服务端返回的信息或者数据。
通过`import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;`引入。
| 方法 | 参数 | 返回值 | 描述 |
| ------------ | ---------------------------------------------- | --- | ----------------------------------------------------------------------------------------- |
| 示例 1 请参见表格下方 | 无 | 无 | 当和服务端建立连接完成后，该方法立刻被回调。 |
| 示例 2 请参见表格下方 | message：服务端响应事件。 | 无 | 包括对接口调用的回复响应和模型生成的文本和音频。具体可以参考：[服务端事件](/api-reference/real-time-multimodal/server-events) |
| 示例 3 请参见表格下方 | code：关闭websokcet的状态码。 reason：关闭websocket的关闭信息。 | 无 | 当服务已经关闭连接后进行回调。 |
**示例 1（方法）**：
```java
public void onOpen()
```
**示例 2（方法）**：
```java
public abstract void onEvent(JsonObject message)
```
**示例 3（方法）**：
```java
public abstract void onClose(int code, String reason)
```
## 常见问题
### Q：输入的音频和图片要如何对齐？
omni-realtime模型的输入将音频作为时间轴，图片会按照发送的时间，插入到音频中。您可以在音频时间轴的任意时刻添加图片。
在实时交互场景下，您可以在任意时刻打开或关闭视频输入。
### Q：输入图片和音频的推荐频率？
在实时交互场景，推荐按照1 fps或2 fps的帧率发送图片，按照100ms一包的音频发送音频。
### Q：turn\_detection开关两种模式的区别？
turn\_detection打开后支持server\_vad和semantic\_vad两种模式：
- 打开"turn\_detection"：
- 输入状态：云端的VAD（语音事件监测）会根据输入音频判断输入的一句话结束，并且立刻自动调用omni的推理下发回复文本和语音。
- 回复状态：在此状态下，音视频可以继续输入，不需要在模型回复阶段中断。回复结束后会回到输入状态等待语音。
- 打断：如果在模型回复期间，如果检测到用户开始说话则会触发打断，服务会立刻停止这一次的回复并且转换到输入状态。
- 关闭"turn\_detection"：
- 用户需要自己判断一轮音视频输入的结束，并且手动通过commit和create\_response触发omni的推理，获得回复。
- 在模型回复状态，需要停止音视频的输入。在模型回复结束后才可以继续输入下一轮音视频。
- 需要通过response\_cancel接口打断模型回复。
注意，在打开"turn\_detection"时，依旧可以通过commit和create\_response主动触发回复，通过response\_cancel主动打断。
### Q：input\_audio\_transcription为何要选择其他模型？
omni是端到端的多模态大模型，文本输出是对输入的回答，因此不会直接产生输入音频的转录。需要接入其他ASR模型转录。目前由内置模型决定，不支持修改。
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-realtime-python-sdk.md
+277
View File
@@ -0,0 +1,277 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK
> 本文介绍 DashScope Python SDK 调用 Qwen-Omni 实时模型 时的关键接口与请求参数。
## 前期准备
SDK 版本需要不低于 1.26.5。请先阅读[实时多模态交互流程](/api-reference/real-time-multimodal/interaction-process)。
## 快速开始
使用 `qwen3.8-omni-flash-realtime` 时，将会话构造参数 `model` 设为该模型名，默认音色为 `Tina`。Python SDK 会话配置和视频聚合参数示例见[实时调用指南](/developer-guides/speech/realtime-multimodal-speech#2-配置会话)。
请访问[GitHub](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni)下载示例代码。我们提供了三种调用方式的示例代码：
1. [音频对话示例](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/python)：麦克风采集实时音频输入，开启[VAD 模式](/api-reference/realtime-api/overview)（自动检测语音起止），支持语音打断。
> `enable_turn_detection`参数需设为 True。
> 推荐使用耳机播放音频，避免回声触发语音打断。
2. [音视频对话示例](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/python)：麦克风和摄像头采集实时音视频输入，开启[VAD 模式](/api-reference/realtime-api/overview)（自动检测语音起止），支持语音打断。
> `enable_turn_detection`参数需设为 True。
> 推荐使用耳机播放音频，避免回声触发语音打断。
3. [本地调用](https://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/python)：本地音频和图片作为输入，开启[Manual 模式](/api-reference/realtime-api/overview)（手动控制发送节奏）。
> `enable_turn_detection`参数需设为 False。
## 请求参数
下述请求参数可以通过OmniRealtimeConversation的构造方法（**init**）进行设置。
| **参数** | **类型** | **说明** |
| -------- | ---------------------- | ----------------------------------------------------------------------------------- |
| model | str | Qwen-Omni系列模型名称。参见模型列表。 |
| callback | `OmniRealtimeCallback` | 用于处理服务端事件的回调对象实例。 |
| url | str | 调用地址：<br /><ul> <li>wss\://maas.qianwenaiapi.com/api-ws/v1/realtime<br /></li></ul> |
下述请求参数可以通过update\_session接口配置。
| **参数** | **类型** | **说明** |
| -------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| output\_modalities | list\[MultiModality] | 模型输出模态设置，支持设置\[MultiModality.TEXT]（仅输出文本）或\[MultiModality.TEXT, MultiModality.AUDIO]（输出音频和文本）。 |
| voice | str | 模型生成音频的音色，支持的音色参见[音色列表](/developer-guides/speech/omni-voice-list)。 默认音色： <ul><li>Qwen3.5-Omni-Realtime系列模型: `"Tina"`</li><li>Qwen3-Omni-Flash-Realtime: `"Cherry"`</li><li>Qwen-Omni-Turbo-Realtime: `"Chelsie"`</li></ul> |
| input\_audio\_config | AudioFormatConfig | 用户输入音频格式配置。通过 `AudioFormatConfig` 同时设置格式（`type`：`pcm`/`wav`）和采样率（`sample_rate`：`8000`/`16000`/`24000`/`48000`，默认 16000 Hz）。 **适用模型：`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`。** |
| output\_audio\_config | AudioFormatConfig | 模型输出音频格式配置。通过 `AudioFormatConfig` 同时设置格式（`type`：`pcm`/`wav`）和采样率（`sample_rate`：`8000`/`16000`/`24000`/`48000`）。`AudioFormatConfig` 未指定采样率时默认 16000 Hz；配置输出音频时请显式设置所需采样率，如 24000 Hz。 **适用模型：`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`。** |
| input\_audio\_format | AudioFormat | 历史兼容字段，新增接入建议使用 `input_audio_config` 同时配置输入格式和采样率。 |
| output\_audio\_format | AudioFormat | 历史兼容字段，新增接入建议使用 `output_audio_config` 同时配置输出格式和采样率。 |
| smooth\_output | bool | 仅Qwen3-Omni-Flash-Realtime系列模型支持设置。 <ul><li>True：获得口语化的回复</li><li>False：获得更书面化、正式的回复</li></ul> > 但可能会因为存在难以朗读的内容而导致效果不好。 <ul><li>None：模型自动选择口语化或书面化的回复风格</li></ul> |
| instructions | str | 系统消息，用于设定模型的目标或角色。 例如：你是某五星级酒店的AI客服专员，请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应，杜绝提供未经证实或超出酒店服务范围的信息。 |
| enable\_input\_audio\_transcription | bool | 是否开启输入音频的语音识别。 |
| input\_audio\_transcription\_model | str | 用于输入音频转录的语音识别模型，固定为qwen3-asr-flash-realtime，不支持修改。 |
| turn\_detection\_type | str | VAD类型，取值如下： <ul><li>`server&#95;vad`（默认值）：基于声学特征检测用户语音结束。</li><li>`semantic&#95;vad`：基于语义有效性检测用户语音结束，可过滤无意义语音（如回应语、背景音）。Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型支持。</li></ul> |
| turn\_detection\_threshold | float | VAD检测阈值。建议在嘈杂的环境中增加， 在安静的环境中降低。 <ul><li>取值越接近-1，噪音被判定为语音的概率越大。</li><li>取值越接近1，噪音被判定为语音的概率越小。</li></ul> 默认为 0.5，参数范围：\[-1.0, 1.0]。 |
| turn\_detection\_silence\_duration\_ms | int | 检测语音停止的静音持续时间，超过此值后会触发模型响应。默认值为800，参数范围\[200, 6000]。 |
| turn\_detection\_param | dict | VAD 扩展参数字典，用于传入 `turn_detection` 的额外配置项。当前支持传入 `idle_timeout_ms`（int）：静默超时时间（毫秒）。**仅在使用**`qwen3.5-omni-plus-realtime`**或**`qwen3.5-omni-flash-realtime`**模型且 VAD 类型为**`server_vad`\*\*时生效。\*\*服务端完成音频播报且用户持续静默超过该时间（未触发 `speech.started`）后，模型将主动触发一轮响应，基于当前上下文引导用户继续对话。取值范围：\[5000, 30000]。 示例：`turn_detection_param={'idle_timeout_ms': 5000}` |
| enable\_search | bool | 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。 是否启用联网搜索功能。设置为 `true` 启用，默认为 `false`。启用后，模型可自主判断是否需要搜索来回应用户的即时问题。 > 工具调用（tools）和联网搜索（enable\_search）不兼容，不可同时开启。 |
| search\_options | object | 联网搜索选项配置。需启用 `enable_search` 后才生效。 目前仅支持设置 `enable_source`（Boolean），表示是否返回搜索结果来源列表，设置为 `true` 启用。示例：`search_options={'enable_source': True}`。 |
| tools | list\[dict] | 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。 工具定义列表。启用后，模型可自主判断是否需要调用外部工具来回应用户的问题。命中 Function Calling 时，模型不生成音频，仅返回工具调用参数。 Qwen3.8-Omni-Flash-Realtime 可在同一会话中配置 Function Calling 和 MCP 工具。MCP 配置字段见[客户端事件](/api-reference/real-time-multimodal/client-events#session-tools-mcp)，调用限制见[MCP 调用限制](/api-reference/real-time-multimodal/interaction-process#使用限制)。`tools` 与 `enable_search` 不可同时开启，该限制也适用于 MCP。 以下字段描述 Function Calling 工具。每个工具为一个字典，包含以下字段： <ul><li>`type`（`string`，必选）：固定为 `"function"`。</li><li>`function`（`dict`，必选）：工具函数的定义，包含以下字段：</li></ul> <ul><li>`name`（`string`，必选）：自定义的工具函数名称，建议使用与函数相同的名称，如 `get&#95;current&#95;weather` 或 `get&#95;current&#95;time`。</li><li>`description`（`string`，可选）：对工具函数功能的描述，大模型会参考该字段来选择是否使用该工具函数。</li><li>`parameters`（`dict`，可选）：对工具函数入参的描述，大模型会参考该字段来进行入参的提取。如果工具函数不需要输入参数，则无需指定。包含以下字段：</li></ul> <ul><li>`type`（`string`，必选）：固定为 `"object"`。</li><li>`properties`（`dict`，可选）：描述各入参的名称、数据类型与描述。Key 值为入参的名称，Value 值为包含数据类型（`type`）与描述（`description`）的字典。</li><li>`required`（`list`，可选）：指定哪些入参为必填项。</li></ul> |
| temperature | float | 采样温度，控制模型生成内容的多样性。 temperature越高，生成的内容更多样，反之，生成的内容更确定。 取值范围： \[0, 2) 由于temperature与top\_p均可以控制生成内容的多样性，因此建议只设置其中一个值。 <ul><li>`qwen3.8-omni-flash-realtime`：0.6</li><li>Qwen3.5-Omni-Realtime系列模型：0.7</li><li>Qwen3-Omni-Flash-Realtime系列模型：0.9</li><li>Qwen-Omni-Turbo-Realtime系列模型：1.0</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| top\_p | float | 核采样的概率阈值，控制模型生成内容的多样性。 top\_p越高，生成的内容更多样。反之，生成的内容更确定。 取值范围：（0,1.0] 由于temperature与top\_p均可以控制生成内容的多样性，因此建议只设置其中一个值。 top\_p默认值： <ul><li>`qwen3.8-omni-flash-realtime`：0.95</li><li>Qwen3.5-Omni-Realtime系列模型：0.8</li><li>Qwen3-Omni-Flash-Realtime系列模型：1.0</li><li>Qwen-Omni-Turbo-Realtime系列模型：0.01</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| top\_k | integer | 生成过程中采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top\_k大于100时，表示不启用top\_k策略，此时仅有top\_p策略生效。 取值需要大于或等于0。 top\_k默认值： <ul><li>`qwen3.8-omni-flash-realtime`：20</li><li>Qwen3.5-Omni-Realtime系列模型：20</li><li>Qwen3-Omni-Flash-Realtime系列模型：50</li><li>Qwen-Omni-Turbo-Realtime系列模型：20</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| max\_tokens | integer | 本次请求返回的最大 Token 数。 > `max_tokens` 的设置不会影响大模型的生成过程，如果模型生成的 Token 数超过`max_tokens`，本次请求会返回截断后的内容。 `qwen3.8-omni-flash-realtime` 的取值范围为 \[1, 65536]。其他模型的默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度，请参见千问AI平台控制台。 max\_tokens参数适用于需要限制字数（如生成摘要、关键词）、控制成本或减少响应时间的场景。 > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| repetition\_penalty | float | 模型生成时连续序列中的重复度。提高repetition\_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。`qwen3.8-omni-flash-realtime` 支持取值 0；其他模型没有严格的取值范围，只要大于0即可。 repetition\_penalty默认值： <ul><li>`qwen3.8-omni-flash-realtime`：0</li><li>Qwen3.5-Omni-Realtime系列模型：1.0</li><li>其他模型：1.05</li></ul> > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| presence\_penalty | float | 控制模型生成内容的重复度。 取值范围：\[-2.0, 2.0]。正数会减少重复度，负数会增加重复度。 presence\_penalty默认值： <ul><li>`qwen3.8-omni-flash-realtime`：1</li><li>Qwen3.5-Omni-Realtime系列模型：1.5</li><li>其他模型：0.0</li></ul> 适用场景： 较高的presence\_penalty适用于要求多样性、趣味性或创造性的场景，如创意写作或头脑风暴。 较低的presence\_penalty适用于要求一致性或专业术语的场景，如技术文档或其他正式文档。 > `qwen-omni-turbo` 系列模型**不支持修改**。 |
| seed | integer | 设置seed参数会使模型生成过程更具有确定性，通常用于使模型每次运行的结果一致。 在每次模型调用时传入相同的seed值（自行指定），并保持其他参数不变，模型将尽可能返回相同的结果。 取值范围：0到231−1，默认值-1。 > `qwen-omni-turbo` 系列模型**不支持修改**。 |
## 关键接口
### OmniRealtimeConversation类
OmniRealtimeConversation通过`from dashscope.audio.qwen_omni import OmniRealtimeConversation`方法引入。
| 方法签名 | 服务端响应事件（通过回调下发） | 说明 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 示例 1 请参见表格下方 | [服务端事件](/api-reference/real-time-multimodal/server-events) > 会话已创建 [session.updated](/api-reference/real-time-multimodal/server-events#session-updated) > 会话配置已更新 | 和服务端创建连接。 |
| 示例 2 请参见表格下方 | [session.updated](/api-reference/real-time-multimodal/server-events#session-updated) > 会话配置已更新 | 更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。 在建立链接后，服务端会及时返回用于此会话的默认输出输入配置。如果需要更新默认会话配置，推荐总是在建立链接后即刻调用此接口。 服务端在收到session.update事件后，会进行参数校验，如果参数不合法则返回错误，否则更新服务端侧的会话配置。 |
| 示例 3 请参见表格下方 | 无 | 将base64编码后的音频数据片段追加到云端输入音频缓冲区。 音频缓冲区是可以写入并稍后提交的临时存储。 <ul><li>打开"turn\_detection"，音频缓冲区用于检测语音，服务端决定何时提交。</li><li>关闭"turn\_detection"，客户端可以选择每个事件中放置多少音频量，最多放置 15 MiB。 例如，从客户端流式处理较小的数据块可以让 VAD 响应更迅速。</li></ul> |
| 示例 4 请参见表格下方 | 无 | 将base64编码后的图片数据添加到云端视频缓冲区。图片数据可以是本地的图片，或从视频流实时采集的图片数据。 目前对图片输入有以下限制： <ul><li>图片格式需要为JPG或JPEG，建议传入的图片分辨率为480P或720P， 最大1080P；</li><li>单张图片经Base64编码后不得超过256KB，建议编码前原始图片大小不超过190KB；</li><li>图片数据需要经过Base64编码；</li><li>建议以 1张/秒 的频率向服务端发送图片；</li></ul> |
| 示例 5 请参见表格下方 | [input\_audio\_buffer.cleared](/api-reference/real-time-multimodal/server-events#input-audio-buffer-cleared) > 清空服务端收到的音频 | 删除当前云端缓冲区的音频。 |
| 示例 6 请参见表格下方 | [input\_audio\_buffer.committed](/api-reference/real-time-multimodal/server-events#input-audio-buffer-committed) > 服务端收到提交的音频 | 提交之前通过append添加到云端缓冲区的音视频，如果输入的音频缓冲区为空将产生错误。 <ul><li>打开"turn\_detection"，客户端不需要发送此事件，服务端会自动提交音频缓冲区。</li><li>关闭"turn\_detection"，客户端必须提交音频缓冲区才能创建用户消息项。</li></ul> **注意**： 1. 如果 input\_audio\_transcription为会话配置了音频转录，系统会转录音频。 2. 提交输入音频缓冲区不会从模型创建响应。 |
| 示例 7 请参见表格下方 | [服务端事件](/api-reference/real-time-multimodal/server-events) > 服务端开始生成响应 [response.output\_item.added](/api-reference/real-time-multimodal/server-events#response-output-item-added) > 响应时有新的输出内容 [服务端事件](/api-reference/real-time-multimodal/server-events) > 对话项被创建 [response.content\_part.added](/api-reference/real-time-multimodal/server-events#response-content-part-added) > 新的输出内容添加到assistant message 项 [response.audio\_transcript.delta](/api-reference/real-time-multimodal/server-events#response-audio-transcript-delta) > 增量生成的转录文字 [response.audio.delta](/api-reference/real-time-multimodal/server-events#response-audio-delta) > 模型增量生成的音频 [response.audio\_transcript.done](/api-reference/real-time-multimodal/server-events#response-audio-transcript-done) > 完成文本转录 [response.audio.done](/api-reference/real-time-multimodal/server-events#response-audio-done) > 完成音频生成 [response.content\_part.done](/api-reference/real-time-multimodal/server-events#response-content-part-done) > Assistant message 的文本或音频内容流式输出完成 [response.output\_item.done](/api-reference/real-time-multimodal/server-events#response-output-item-done) > Assistant message 的整个输出项流式传输完成 [response.done](/api-reference/real-time-multimodal/server-events#response-done) > 响应完成 | 指示服务端创建模型响应。 打开"turn\_detection"模式下配置会话时，服务端会自动创建模型响应。 |
| 示例 8 请参见表格下方 | 无 | 取消正在进行的响应。如果没有任何响应可供取消，服务端将以一个错误进行响应。 |
| 示例 9 请参见表格下方 | 无 | 向服务端发送 `conversation.item.create` 事件。 回传 Function Calling 工具结果时，`item` 为 dict，包含以下字段： <ul><li>`type`：固定为 `function&#95;call&#95;output`。</li><li>`call&#95;id`：对应 `response.function&#95;call&#95;arguments.done` 事件中的 call\_id。</li><li>`output`：工具执行结果的字符串。</li></ul> MCP 审批也使用此事件，但 `item.type` 为 `mcp_approval_response`；字段见[客户端事件中的 MCP 审批回复](/api-reference/real-time-multimodal/client-events#mcp-审批回复-qwen3-8-omni-flash-realtime)。 |
| 示例 10 请参见表格下方 | 无 | 终止任务，并关闭连接。 |
| 示例 11 请参见表格下方 | 无 | 获取当前任务的session\_id。 |
| 示例 12 请参见表格下方 | 无 | 获取最近一次response的response\_id。 |
**示例 1（方法签名）**：
```python
def connect(self,) -> None
```
**示例 2（方法签名）**：
```python
def update_session(self,
output_modalities: List[MultiModality],
voice: str = None,
input_audio_format: AudioFormat = AudioFormat.PCM_16000HZ_MONO_16BIT,
output_audio_format: AudioFormat = AudioFormat.PCM_24000HZ_MONO_16BIT,
enable_input_audio_transcription: bool = True,
input_audio_transcription_model: str = None,
enable_turn_detection: bool = True,
turn_detection_type: str = "server_vad",
prefix_padding_ms: int = 300,
turn_detection_threshold: float = 0.2,
turn_detection_silence_duration_ms: int = 800,
turn_detection_param: dict = None,
input_audio_config: AudioFormatConfig = None,
output_audio_config: AudioFormatConfig = None,
**kwargs) -> None
```
**示例 3（方法签名）**：
```python
def append_audio(self, audio_b64: str) -> None
```
**示例 4（方法签名）**：
```python
def append_video(self, video_b64: str) -> None
```
**示例 5（方法签名）**：
```python
def clear_appended_audio(self, ) -> None
```
**示例 6（方法签名）**：
```python
def commit(self, ) -> None
```
**示例 7（方法签名）**：
```python
def create_response(self,
instructions: str = None,
output_modalities: list[MultiModality] = None) -> None
```
**示例 8（方法签名）**：
```python
def cancel_response(self, ) -> None
```
**示例 9（方法签名）**：
```python
def create_item(self, item: dict) -> None
```
**示例 10（方法签名）**：
```python
def close(self, ) -> None
```
**示例 11（方法签名）**：
```python
def get_session_id(self) -> str
```
**示例 12（方法签名）**：
```python
def get_last_response_id(self) -> str
```
### AudioFormatConfig 配置类
通过 `from dashscope.audio.qwen_omni import AudioFormatConfig, AudioFormatType, AudioSampleRate` 引入。用于同时配置音频格式和采样率。
**适用模型：`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`。**
```python
from dashscope.audio.qwen_omni import (
AudioFormatConfig, AudioFormatType, AudioSampleRate,
)
# 方式一：使用枚举
conversation.update_session(
output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
voice=voice,
input_audio_config=AudioFormatConfig(
type=AudioFormatType.PCM,
sample_rate=AudioSampleRate.SAMPLE_RATE_16K
),
output_audio_config=AudioFormatConfig(
type=AudioFormatType.WAV,
sample_rate=AudioSampleRate.SAMPLE_RATE_24K
),
)
# 方式二：自由传值
conversation.update_session(
output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
voice=voice,
input_audio_config=AudioFormatConfig(type="pcm", sample_rate=16000),
output_audio_config=AudioFormatConfig(type="wav", sample_rate=24000),
)
```
### 回调接口（OmniRealtimeCallback）
服务端会通过回调的方式，将服务端响应事件和数据返回给客户端。需要实现回调方法，处理服务端返回的信息或者数据。
通过`from dashscope.audio.qwen_omni import OmniRealtimeCallback`引入。
| 方法 | 参数 | 返回值 | 描述 |
| ------------ | ----------------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------- |
| 示例 1 请参见表格下方 | 无 | 无 | 当和服务端建立连接完成后，该方法立刻被回调。 |
| 示例 2 请参见表格下方 | message：服务端响应事件。 | 无 | 包括对接口调用的回复响应和模型生成的文本和音频。具体可以参考：[服务端事件](/api-reference/real-time-multimodal/server-events) |
| 示例 3 请参见表格下方 | close\_status\_code：关闭websocket的状态码。 close\_msg：关闭websocket的关闭信息。 | 无 | 当服务已经关闭连接后进行回调。 |
**示例 1（方法）**：
```python
def on_open(self) -> None
```
**示例 2（方法）**：
```python
def on_event(self, message: str) -> None
```
**示例 3（方法）**：
```python
def on_close(self, close_status_code, close_msg) -> None
```
## 常见问题
### Q：输入的音频和图片要如何对齐？
Qwen-Omni实时模型的输入将音频作为时间轴，图片会按照发送的时间，插入到音频中。可以在音频时间轴的任意时刻添加图片。
在实时交互场景下，可以在任意时刻打开或关闭视频输入。
### Q：输入图片和音频的推荐频率？
在实时交互场景，推荐按照1 fps或2 fps的帧率发送图片，按照100ms一包的音频发送音频。
### Q：turn\_detection开关两种模式的区别？
turn\_detection打开后支持server\_vad和semantic\_vad两种模式：
- 打开"turn\_detection"：
- 输入状态：云端的VAD（语音事件监测）会根据输入音频判断输入的一句话结束，并且立刻自动调用Qwen-Omni的推理下发回复文本和语音。
- 回复状态：在此状态下，音视频可以继续输入，不需要在模型回复阶段中断。回复结束后会回到输入状态等待语音。
- 打断：如果在模型回复期间，如果检测到用户开始说话则会触发打断，服务会立刻停止这一次的回复并且转换到输入状态。
- 关闭"turn\_detection"：
- 需要自行判断一轮音视频输入的结束，并手动通过commit和create\_response触发Qwen-Omni的推理，获得回复。
- 在模型回复状态，需要停止音视频的输入。在模型回复结束后才可以继续输入下一轮音视频。
- 需要通过cancel\_response接口打断模型回复。
注意，在打开"turn\_detection"时，依旧可以通过commit和create\_response主动触发回复，通过cancel\_response主动打断。
### Q：input\_audio\_transcription为何要选择其他模型？
Qwen-Omni实时是端到端的多模态大模型，文本输出是对输入的回答，因此不会直接产生输入音频的转录。需要接入其他ASR模型转录。目前由内置模型决定，不支持修改。
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-server-events.md
+1375
View File
File diff suppressed because it is too large Load Diff
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-real-time-multimodal-voice-cloning.md
+1469
View File
File diff suppressed because it is too large Load Diff
mac-agent-os-main/05_tools/09_ave/docs/api/raw/qwen/api-reference-video-generation-animate-anyone-create-task.md
+302
View File
@@ -0,0 +1,302 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://platform.qianwenai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AnimateAnyone — 创建任务
> 提交舞动人像视频生成任务
根据人物图片和动作模板，生成角色动作视频。适用于舞蹈视频、肢体动作等场景。
## 前置准备
1. [获取 API Key](/api-reference/preparation/api-key)。
2. 使用 [AnimateAnyone 动作模板生成 API](/api-reference/video-generation/animate-anyone-template-gen/create-task) 生成动作模板，获取 `template_id`。
3. 使用 [AnimateAnyone 图像检测 API](/api-reference/video-generation/animate-anyone/wan-aa-detect) 验证人物图片是否符合要求，并按目标宽高比裁剪图片。
## 背景模式
通过 `use_ref_img_bg` 参数控制视频背景：
| 模式 | `use_ref_img_bg` | 说明 |
| ------ | ---------------- | ------------------------------------- |
| 视频背景模式 | `false`（默认） | 使用模板视频的原始背景。 |
| 图片背景模式 | `true` | 使用输入图片作为视频背景，可通过 `video_ratio` 设置宽高比。 |
## 输入要求
**人物图片（`image_url`）**：
- 格式：JPG、PNG、JPEG 或 BMP
- 文件大小：不超过 5 MB
- 宽高比：不超过 2:1
- 最大边长：4096 像素
**图片类型兼容性**：
| 图片类型 | 图片背景模式 | 视频背景模式 |
| ---- | ------ | ---------------------- |
| 全身照 | 支持 | 支持 |
| 半身照 | 支持 | 不推荐（模型会随机生成缺失部分，效果不可控） |
<Note>
使用视频背景模式时，建议使用全身照。半身照在视频背景模式下，模型会随机生成腿部等缺失区域，可能产生不可预期的效果。
</Note>
## OpenAPI
````yaml post /services/aigc/image2video/video-synthesis/
openapi: 3.1.0
info:
title: 舞动人像 AnimateAnyone 视频生成 API
description: AnimateAnyone模型，可基于AnimateAnyone-template模型生成的动作模板，以及通过AnimateAnyone-detect模型检测的人物图像生成人物动作视频。本文档介绍了该模型提供的视频生成能力的API调用方法。
version: 1.0.0
servers:
- url: https://maas.qianwenaiapi.com/api/v1
description: DashScope API
security:
- BearerAuth: []
paths:
/services/aigc/image2video/video-synthesis/:
post:
operationId: createAnimateAnyoneTask
summary: 创建任务获取任务ID
description: 用于生成人物动作视频。因该算法调用耗时较长，故采用异步调用的方式提交任务。任务提交之后，系统会返回对应的任务ID，后续可通过'根据任务ID查询结果接口'获取任务状态及对应结果。
parameters:
- name: Content-Type
in: header
required: true
description: 请求类型：application/json。
schema:
type: string
example: application/json
- name: Authorization
in: header
required: true
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schema:
type: string
example: Bearer $DASHSCOPE_API_KEY
- name: X-DashScope-Async
in: header
required: true
description: 使用 enable，表明使用异步方式提交任务。
schema:
type: string
enum:
- enable
example: enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AnimateAnyoneRequest"
responses:
"200":
description: 任务提交成功
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: 请求参数无效
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - 创建视频生成任务
source: |-
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2video/video-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "animate-anyone-gen2",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251224/pkswoc/p883941.png",
"template_id": "AACT.xxx.xxx-xxx.xxx"
},
"parameters": {
"use_ref_img_bg": false,
"video_ratio": "9:16"
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
schemas:
AnimateAnyoneRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: 指明需要调用的模型。
enum:
- animate-anyone-gen2
example: animate-anyone-gen2
input:
type: object
required:
- image_url
- template_id
description: 输入数据，包含人物图片和动作模板。
properties:
image_url:
type: string
description: |-
用户上传的图片 URL，该图应先通过AnimateAnyone 图像检测API，并结合所需生成的画幅进行适当裁剪。
**图像要求：**
- 格式：JPG、PNG、JPEG 或 BMP
- 文件大小：＜5M
- 宽高比：≤2
- 最大边长：≤4096像素
**说明：**上传文件支持HTTP或HTTPS链接方式，不支持本地链接方式。您也可在此获取临时公网URL。
example: http://aaa/bbb.jpg
template_id:
type: string
description: |-
动作模板ID，用于指明所需使用的动作模板。应输入AnimateAnyone 动作模板生成API生成的template_id。
**说明：**动作模板ID会进行权限校验，请确保所使用的template_id是由当前的云账号创建得到的。
**使用建议：**提高模板视频的分辨率和帧率，可有效提升生成视频的画质效果。
example: AACT.xxx.xxx-xxx.xxx
parameters:
$ref: "#/components/schemas/AnimateAnyoneParameters"
AnimateAnyoneParameters:
type: object
description: 视频生成参数配置。
properties:
use_ref_img_bg:
type: boolean
description: |-
生成视频的背景控制，可设值为true或false。
- 设true时将以输入图片的画面为背景生成视频（按图片背景生成）。
- 设false时将以模板文件的原视频画面为背景生成视频（按视频背景生成）。默认值为false。
**说明：**按视频背景生成时，需将图片中人像匹配到视频中人像的对应位置。对于半身人像图中未出现的区域（如腿部），模型将随机生成补全，有较大不确定性，故不推荐在该条件下做视频生成。
default: false
example: false
video_ratio:
type: string
description: |-
选择按图片背景生成视频时，可选画幅为 "9:16"或"3:4"，默认为"9:16"。
**说明：**选择按视频背景生成时，即use_ref_img_bg设false时，该参数不生效。将按模板视频的比例生成新视频。
**说明：**应确保输入图像的画幅与所选画幅一致，以避免生成视频的画面变形。
enum:
- 9:16
- 3:4
default: 9:16
example: 9:16
AsyncTaskSubmitResponse:
type: object
description: 异步任务提交响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
type: object
properties:
task_id:
type: string
description: 提交异步任务的任务ID，实际任务结果需要通过异步任务查询接口获取。
example: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status:
type: string
description: 提交异步任务后的任务状态。
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
example: PENDING
TaskStatusResponse:
type: object
description: 异步任务查询响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
example: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
output:
type: object
properties:
task_id:
type: string
description: 查询任务的 task_id。
example: a8532587-fa8c-4ef8-82be-0c46b17950d1
task_status:
type: string
description: 被查询任务的任务状态。
enum:
- PENDING
- PRE-PROCESSING
- RUNNING
- POST-PROCESSING
- SUCCEEDED
- FAILED
- UNKNOWN
x-enumDescriptions:
PENDING: 排队中
PRE-PROCESSING: 前置处理中
RUNNING: 处理中
POST-PROCESSING: 后置处理中
SUCCEEDED: 成功
FAILED: 失败
UNKNOWN: 任务不存在或状态未知
video_url:
type: string
description: 平台输出的视频结果，**video_url有效期为任务完成后24小时**。
example: https://xxx/1.mp4
code:
type: string
description: 错误码。仅在任务失败时返回。
message:
type: string
description: 错误详情。仅在任务失败时返回。
usage:
type: object
description: 输出统计信息。仅在任务成功时返回。
properties:
video_duration:
type: number
description: 本次请求生成视频时长计量，单位：秒。
example: 10.23
video_ratio:
type: string
description: 本次请求生成视频的画幅类型，该值为standard。
example: standard
DashScopeErrorResponse:
type: object
description: DashScope API 错误响应。
properties:
request_id:
type: string
description: 本次请求的系统唯一码。
code:
type: string
description: 错误码（如 InvalidApiKey、InvalidParameter、Throttling）。
example: InvalidApiKey
message:
type: string
description: 人类可读的错误描述。
example: No API-key provided.
````

Some files were not shown because too many files have changed in this diff Show More