feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP
移植自 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:
@@ -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
|
||||
```
|
||||
|
||||
看板「⚙️ 能力配置」页据此显示「📖 查看官方文档 →」链接，跳到本文档中心对应页。
|
||||
File diff suppressed because it is too large
Load Diff
+391
@@ -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。
|
||||
````
|
||||
+251
@@ -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。
|
||||
````
|
||||
+209
@@ -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)。
|
||||
````
|
||||
+260
@@ -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)。
|
||||
````
|
||||
+215
@@ -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)。
|
||||
````
|
||||
+496
@@ -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.
|
||||
````
|
||||
+354
@@ -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.
|
||||
````
|
||||
+337
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+348
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+408
@@ -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.
|
||||
````
|
||||
+392
@@ -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.
|
||||
````
|
||||
+452
@@ -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
|
||||
````
|
||||
+231
@@ -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.
|
||||
````
|
||||
+343
@@ -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
|
||||
````
|
||||
+235
@@ -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)。
|
||||
````
|
||||
+226
@@ -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)。
|
||||
````
|
||||
+435
@@ -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: 请求唯一标识，用于排查问题。
|
||||
````
|
||||
+332
@@ -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: 请求唯一标识，用于排查问题。
|
||||
````
|
||||
+349
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+308
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+169
@@ -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>
|
||||
+311
@@ -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
|
||||
````
|
||||
+264
@@ -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
|
||||
````
|
||||
+660
@@ -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.
|
||||
````
|
||||
+662
@@ -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
|
||||
````
|
||||
+649
@@ -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
|
||||
````
|
||||
+332
@@ -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)。
|
||||
````
|
||||
+600
@@ -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
|
||||
````
|
||||
+666
@@ -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
|
||||
````
|
||||
+266
@@ -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)。
|
||||
````
|
||||
+285
@@ -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)。
|
||||
````
|
||||
+400
@@ -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.
|
||||
````
|
||||
+362
@@ -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.
|
||||
````
|
||||
+467
@@ -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.
|
||||
````
|
||||
+429
@@ -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.
|
||||
````
|
||||
+940
@@ -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，用于问题排查。
|
||||
````
|
||||
+536
@@ -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，用于问题排查。
|
||||
````
|
||||
+561
@@ -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，用于问题排查。
|
||||
````
|
||||
+788
@@ -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: 请求的唯一标识符，用于问题排查。
|
||||
````
|
||||
+371
@@ -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: 请求的唯一标识符，用于问题排查。
|
||||
````
|
||||
+694
@@ -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: 用于问题排查的唯一请求标识符。
|
||||
````
|
||||
+334
@@ -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: 用于问题排查的唯一请求标识符。
|
||||
````
|
||||
+795
@@ -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
|
||||
````
|
||||
+492
@@ -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
|
||||
````
|
||||
+702
@@ -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
|
||||
````
|
||||
+863
@@ -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
|
||||
````
|
||||
+477
@@ -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
|
||||
````
|
||||
+814
@@ -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
|
||||
````
|
||||
+482
@@ -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)。
|
||||
````
|
||||
+338
@@ -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)。
|
||||
````
|
||||
+365
@@ -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: 请求唯一标识，用于排查问题。
|
||||
````
|
||||
+384
@@ -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: 请求唯一标识，用于排查问题。
|
||||
````
|
||||
+816
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+320
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+548
@@ -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: 用于排查问题的请求唯一标识。
|
||||
````
|
||||
+369
@@ -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: 用于排查问题的请求唯一标识。
|
||||
````
|
||||
+276
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+287
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+376
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+328
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+308
@@ -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
|
||||
````
|
||||
+282
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+316
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+250
@@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
+721
@@ -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
|
||||
````
|
||||
+459
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+573
@@ -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: 请求唯一标识。
|
||||
````
|
||||
+899
@@ -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) 。
|
||||
+136
@@ -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 模式下，服务端对传入的音频进行语音活动检测，并在检测到作出响应。此模式适用于客户端到服务器始终发送音频的情况，也是当前的默认模式。
|
||||
|
||||
|
||||
|
||||
- 服务端在检测到语音开始时发送`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 工具时，遵循以下交互流程：
|
||||
|
||||
|
||||
|
||||
- 服务端在检测到语音结束并生成响应时，识别到需要调用工具。
|
||||
- 服务端发送 `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`事件请求服务器响应。适用于按下即说场景，如聊天软件中的发送语音。
|
||||
|
||||
|
||||
|
||||
- 客户端可以通过发送 `input_audio_buffer.append` 事件将音频追加到缓冲区。
|
||||
- 客户端通过发送 `input_audio_buffer.commit`事件来提交输入音频缓冲区。 该提交会在对话中创建一个新的用户消息项。
|
||||
- 服务器通过发送 `input_audio_buffer.committed`事件进行响应。
|
||||
- 客户端发送 `response.create` 事件，触发模型生成最终响应。
|
||||
- 服务器通过发送 `conversation.item.created`事件进行响应。
|
||||
|
||||
#### Function Calling 流程
|
||||
|
||||
|
||||
|
||||
在 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)
|
||||
+39
@@ -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)
|
||||
+239
@@ -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_vad`（默认值）：基于声学特征检测用户语音结束。</li><li>`semantic_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_call_output`。</li><li>`call_id`：对应 `response.function_call_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模型转录。目前由内置模型决定，不支持修改。
|
||||
+277
@@ -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_vad`（默认值）：基于声学特征检测用户语音结束。</li><li>`semantic_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_current_weather` 或 `get_current_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_call_output`。</li><li>`call_id`：对应 `response.function_call_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模型转录。目前由内置模型决定，不支持修改。
|
||||
+1375
File diff suppressed because it is too large
Load Diff
+1469
File diff suppressed because it is too large
Load Diff
+302
@@ -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.
|
||||
````
|
||||
+279
@@ -0,0 +1,279 @@
|
||||
> ## 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-reference/video-generation/animate-anyone/create-task)接口获取 `task_id`。
|
||||
2. 每 **15 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 任务成功后，从 `output.video_url` 获取视频。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **URL 有效期**：视频 URL 在 **24 小时**后过期，请及时下载。
|
||||
- **状态流转**：`PENDING` → `PRE-PROCESSING` → `RUNNING` → `POST-PROCESSING` → `SUCCEEDED` 或 `FAILED`。`UNKNOWN` 表示任务不存在或已过期。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
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:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getAnimateAnyoneTaskStatus
|
||||
summary: 根据任务ID查询结果
|
||||
description: 查询异步任务的状态及结果。异步任务查询接口提供 20 QPS 的访问流量限制。若有更高频次的查询需求，可通过EventBridge配置事件转发。已提交的异步任务列表查询和异步任务的取消管理，详见管理异步任务接口。
|
||||
parameters:
|
||||
- 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: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 需要查询任务的task_id。
|
||||
schema:
|
||||
type: string
|
||||
example: a8532587-fa8c-4ef8-82be-0c46b17950d1
|
||||
responses:
|
||||
"200":
|
||||
description: 获取任务状态成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/TaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务成功
|
||||
value:
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
video_url: https://xxx/1.mp4
|
||||
usage:
|
||||
video_duration: 10.23
|
||||
video_ratio: standard
|
||||
FAILED:
|
||||
summary: 任务失败
|
||||
value:
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: FAILED
|
||||
code: xxx
|
||||
message: xxxxxx
|
||||
RUNNING:
|
||||
summary: 任务处理中
|
||||
value:
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: RUNNING
|
||||
"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:
|
||||
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.
|
||||
````
|
||||
+230
@@ -0,0 +1,230 @@
|
||||
> ## 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 动作模板生成 — 创建任务
|
||||
|
||||
> 提交 AnimateAnyone 动作模板生成任务
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
## 模型信息
|
||||
|
||||
| 模型名 | 模型简介 |
|
||||
| ------------------------------ | ------------------------------- |
|
||||
| `animate-anyone-template-gen2` | 人物动作模板生成模型，可基于人物运动视频提取人物动作并制作模板 |
|
||||
|
||||
## 输入视频要求
|
||||
|
||||
上传的视频中人物应全身入镜、身体无遮挡、保持人脸清晰。人物应从画面首帧开始出现，动作连贯，一镜到底（有场景切换的视频建议拆分成多段）。建议画面首帧人物正面朝向镜头；避免人物运动中出现大幅弯腰、下蹲、身体蜷缩等动作。
|
||||
|
||||
<Warning>
|
||||
为保障模板制作效果，应避免上传视频中的任一帧画面出现以下情况：身体蜷缩或遮挡、画面有多人、人物模糊、人物过小（人脸不清晰）、人物过大（人物不完整）。当视频首帧画面出现上述错误情形时，当次提交的任务可能报错并中止。
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
请确保上传的视频文件来源符合相关法律法规。生成的动作模板的音频与上传的视频文件中的音频一致。若不希望使用该音频，或尚未取得该音频（如音乐等）的使用许可，请在上传视频文件前消除其中的音频信息。
|
||||
</Warning>
|
||||
|
||||
## 输入限制
|
||||
|
||||
- 视频格式：支持 MP4、AVI、MOV。
|
||||
- 视频文件不大于 200 MB。
|
||||
- 视频边长不低于 200，不大于 2048 像素；长宽比介于 1:3 到 3:1。
|
||||
- 视频帧率 ≥ 24 fps，视频编码采用 H.264 或 H.265。
|
||||
- 视频时长不小于 2s 且不大于 60s。
|
||||
- 上传的视频文件支持 HTTP/HTTPS 链接，不支持本地路径。也可使用[文件上传 API](/api-reference/platform-api/file/upload-file) 上传本地文件并创建链接。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/aa-template-generation/
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: AnimateAnyone 动作模板生成 API
|
||||
description: AnimateAnyone动作模板生成模型，可基于人物运动视频提取人物动作，并生成可供AnimateAnyone视频生成模型使用的人物动作模板。本文档介绍了该模型提供的动作模板生成能力的API调用方法。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/aa-template-generation/:
|
||||
post:
|
||||
operationId: createAnimateAnyoneTemplateGenTask
|
||||
summary: 创建动作模板生成任务
|
||||
description: 用于生成人物动作模板，该模板可作为AnimateAnyone视频生成API的输入物，以生成人物动作视频。因该算法调用耗时较长，采用异步调用的方式提交任务。任务提交之后，系统会返回对应的任务ID，后续可通过根据任务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/TemplateGenRequest"
|
||||
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/aa-template-generation/' \
|
||||
--header 'X-DashScope-Async: enable' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "animate-anyone-template-gen2",
|
||||
"input": {
|
||||
"video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241210/cwjmsz/1.mp4"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
TemplateGenRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 指明需要调用的模型，此处用 animate-anyone-template-gen2。
|
||||
enum:
|
||||
- animate-anyone-template-gen2
|
||||
example: animate-anyone-template-gen2
|
||||
input:
|
||||
type: object
|
||||
description: 输入数据，包含用于动作模板提取的参考视频。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: |-
|
||||
用户上传的视频 URL，用于生成基于指定视频的动作模板。
|
||||
|
||||
**视频约束：**
|
||||
- 格式：支持 MP4、AVI、MOV。
|
||||
- 时长：不小于 2s 且不大于 60s。
|
||||
- 边长：不低于 200，不大于 2048；长宽比介于 1:3 到 3:1。
|
||||
- 帧率：≥ 24fps，视频编码采用 H.264 或 H.265。
|
||||
- 文件大小：不大于 200MB。
|
||||
- 内容：人物应全身入镜、身体无遮挡、保持人脸清晰。人物应从画面首帧开始出现，动作连贯，一镜到底。
|
||||
|
||||
上传文件支持HTTP或HTTPS链接方式，不支持本地链接方式。也可使用平台提供的文件存储API上传本地文件并创建链接。
|
||||
example: https://example.com/video.mp4
|
||||
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
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- 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
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
example: SUCCEEDED
|
||||
template_id:
|
||||
type: string
|
||||
description: 平台输出的动作模板ID，可作为"Animate-Anyone 视频生成接口"的入参。动作模板ID会进行权限校验，请确保使用template_id的云账号与当前生产该动作模板的云账号一致。
|
||||
example: AACT.xxx.xxx-xxx.xxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码，任务失败时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误详情，任务失败时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 本次请求的用量统计，仅任务成功时返回。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
format: float
|
||||
description: 本次请求生成模板时长计量，单位：秒。
|
||||
example: 10.23
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 本次请求生成视频模板的画幅类型，该值为 standard。
|
||||
enum:
|
||||
- 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.
|
||||
````
|
||||
+235
@@ -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.
|
||||
|
||||
# AnimateAnyone 动作模板生成 — 查询结果
|
||||
|
||||
> 根据任务 ID 查询 AnimateAnyone 动作模板生成任务的状态和结果
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[设置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
异步任务查询接口提供 20 QPS 的访问流量限制。
|
||||
</Note>
|
||||
|
||||
## 状态说明
|
||||
|
||||
| 状态 | 说明 |
|
||||
| ----------- | ---------- |
|
||||
| `PENDING` | 排队中 |
|
||||
| `RUNNING` | 处理中 |
|
||||
| `SUCCEEDED` | 成功 |
|
||||
| `FAILED` | 失败 |
|
||||
| `CANCELED` | 已取消 |
|
||||
| `UNKNOWN` | 任务不存在或状态未知 |
|
||||
|
||||
## 状态码
|
||||
|
||||
通用状态码请参阅[错误信息](/api-reference/preparation/error-messages)。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: AnimateAnyone 动作模板生成 API
|
||||
description: AnimateAnyone动作模板生成模型，可基于人物运动视频提取人物动作，并生成可供AnimateAnyone视频生成模型使用的人物动作模板。本文档介绍了该模型提供的动作模板生成能力的API调用方法。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getAnimateAnyoneTemplateGenTaskStatus
|
||||
summary: 根据任务ID查询结果
|
||||
description: 查询动作模板生成任务的状态及结果。异步任务查询接口提供 20 QPS 的访问流量限制。若有更高频次的查询需求，可通过EventBridge配置事件转发。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 需要查询任务的task_id。
|
||||
schema:
|
||||
type: string
|
||||
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
|
||||
template_id: AACT.xxx.xxx-xxx.xxx
|
||||
usage:
|
||||
video_duration: 10.23
|
||||
video_ratio: standard
|
||||
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: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
|
||||
task_status: RUNNING
|
||||
"400":
|
||||
description: 请求无效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL - 查询任务结果
|
||||
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:
|
||||
TemplateGenRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 指明需要调用的模型，此处用 animate-anyone-template-gen2。
|
||||
enum:
|
||||
- animate-anyone-template-gen2
|
||||
example: animate-anyone-template-gen2
|
||||
input:
|
||||
type: object
|
||||
description: 输入数据，包含用于动作模板提取的参考视频。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: |-
|
||||
用户上传的视频 URL，用于生成基于指定视频的动作模板。
|
||||
|
||||
**视频约束：**
|
||||
- 格式：支持 MP4、AVI、MOV。
|
||||
- 时长：不小于 2s 且不大于 60s。
|
||||
- 边长：不低于 200，不大于 2048；长宽比介于 1:3 到 3:1。
|
||||
- 帧率：≥ 24fps，视频编码采用 H.264 或 H.265。
|
||||
- 文件大小：不大于 200MB。
|
||||
- 内容：人物应全身入镜、身体无遮挡、保持人脸清晰。人物应从画面首帧开始出现，动作连贯，一镜到底。
|
||||
|
||||
上传文件支持HTTP或HTTPS链接方式，不支持本地链接方式。也可使用平台提供的文件存储API上传本地文件并创建链接。
|
||||
example: https://example.com/video.mp4
|
||||
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
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- 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
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
example: SUCCEEDED
|
||||
template_id:
|
||||
type: string
|
||||
description: 平台输出的动作模板ID，可作为"Animate-Anyone 视频生成接口"的入参。动作模板ID会进行权限校验，请确保使用template_id的云账号与当前生产该动作模板的云账号一致。
|
||||
example: AACT.xxx.xxx-xxx.xxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码，任务失败时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误详情，任务失败时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 本次请求的用量统计，仅任务成功时返回。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
format: float
|
||||
description: 本次请求生成模板时长计量，单位：秒。
|
||||
example: 10.23
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 本次请求生成视频模板的画幅类型，该值为 standard。
|
||||
enum:
|
||||
- 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.
|
||||
````
|
||||
+202
@@ -0,0 +1,202 @@
|
||||
> ## 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 — 图像检测
|
||||
|
||||
> 检测图像是否符合 AnimateAnyone 视频生成模型的人物图像规格要求
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
AnimateAnyone 图像检测用于判断输入图像是否符合 AnimateAnyone 视频生成模型的人物图像规格要求，通常在舞蹈视频生成前作为图像筛选步骤使用。返回图像是否通过检测以及人物体型（半身/全身）。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/aa-detect
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: AnimateAnyone Image Detection API
|
||||
description: AnimateAnyone 图像检测 API。检测输入图像是否符合 AnimateAnyone 视频生成模型的人物图像规格要求。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/aa-detect:
|
||||
post:
|
||||
operationId: detectAnimateAnyonePortrait
|
||||
summary: 检测人物图像
|
||||
description: 检测输入图像是否符合 AnimateAnyone 视频生成模型的人物图像规格要求。返回图像是否通过检测以及人物体型（半身/全身）。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/AADetectRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 检测成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/AADetectResponse"
|
||||
examples:
|
||||
pass:
|
||||
summary: 检测通过
|
||||
value:
|
||||
output:
|
||||
check_pass: true
|
||||
bodystyle: full
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: 76df937d-6eb6-40aa-9ccf-xxxxxx
|
||||
fail:
|
||||
summary: 检测未通过
|
||||
value:
|
||||
output:
|
||||
check_pass: false
|
||||
reason: The input image has no human body. Please upload other image with single person.
|
||||
bodystyle: ""
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: c56f62df-724e-9c19-96bd-xxxxxx
|
||||
"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: No API-key provided.
|
||||
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
|
||||
"429":
|
||||
description: 超出速率限制
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
"500":
|
||||
description: 服务端内部错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL
|
||||
source: |-
|
||||
curl --location --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2video/aa-detect' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"model": "animate-anyone-detect-gen2",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251224/pkswoc/p883941.png"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
AADetectRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称，固定为 `animate-anyone-detect-gen2`。
|
||||
enum:
|
||||
- animate-anyone-detect-gen2
|
||||
example: animate-anyone-detect-gen2
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
description: 输入图像参数。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
待检测图像的公网可访问 URL。必须为 HTTP 或 HTTPS 协议的公网可访问地址。
|
||||
|
||||
<Tip>如需将本地图像上传获取临时 URL，请参考[上传文件获取临时URL](/api-reference/platform-api/file/upload-file)。</Tip>
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251224/pkswoc/p883941.png
|
||||
AADetectResponse:
|
||||
type: object
|
||||
description: AnimateAnyone 人物图像检测响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符，用于链路追踪和问题排查。
|
||||
example: 76df937d-6eb6-40aa-9ccf-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 检测结果。
|
||||
properties:
|
||||
check_pass:
|
||||
type: boolean
|
||||
description: 图像是否通过检测。`true` 表示图像符合 AnimateAnyone 视频生成模型的人物图像规格要求，`false` 表示不符合。
|
||||
example: true
|
||||
bodystyle:
|
||||
type: string
|
||||
description: 人物体型类别。`half` 表示半身图，`full` 表示全身图。检测未通过时返回空字符串。
|
||||
enum:
|
||||
- half
|
||||
- full
|
||||
- ""
|
||||
example: full
|
||||
reason:
|
||||
type: string
|
||||
description: 检测未通过时的原因说明。仅当 `check_pass` 为 `false` 时返回此字段。
|
||||
usage:
|
||||
type: object
|
||||
description: 使用量统计。
|
||||
properties:
|
||||
image_count:
|
||||
type: integer
|
||||
description: 本次检测的图像数量，固定为 `1`。用于计费。
|
||||
example: 1
|
||||
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.
|
||||
````
|
||||
+269
@@ -0,0 +1,269 @@
|
||||
> ## 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.
|
||||
|
||||
# 悦动人像 EMO — 创建任务
|
||||
|
||||
> 提交悦动人像 EMO 唱演视频生成异步任务
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
## 模型概览
|
||||
|
||||
**模型简介**
|
||||
|
||||
| 模型名 | 模型简介 |
|
||||
| ------ | ----------------------------------------------------------- |
|
||||
| emo-v1 | 悦动人像 EMO，基于人物肖像图片和音频，生成口型与音频同步的唱演视频。适用于数字人播报、音乐 MV、虚拟主播等场景。 |
|
||||
|
||||
## 前置条件
|
||||
|
||||
在调用本接口前，需先调用 [EMO 图像检测](/api-reference/video-generation/emo-video/emo-detect) 接口对人物图片进行检测，获取 `face_bbox`（人脸边界框）和 `ext_bbox`（扩展边界框），再将其传入本接口。
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. 调用 [EMO 图像检测](/api-reference/video-generation/emo-video/emo-detect) 接口，传入人物图片，获取 `face_bbox` 和 `ext_bbox`。
|
||||
2. 调用本接口，将图片 URL、音频 URL 及上一步获取的 bbox 信息一并提交，获取 `task_id`。
|
||||
3. 调用[查询视频生成结果](/api-reference/video-generation/emo-video/query-result)接口，使用 `task_id` 轮询任务状态，直到获取生成的视频 URL。
|
||||
|
||||
## 错误码
|
||||
|
||||
大模型服务通用状态码请查阅[错误信息](/api-reference/preparation/error-messages)。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 悦动人像 EMO 视频生成 API
|
||||
version: 1.0.0
|
||||
description: 基于人物肖像图片和音频，生成口型与音频同步的唱演视频。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/video-synthesis:
|
||||
post:
|
||||
summary: 提交视频生成任务
|
||||
operationId: createEmoVideoTask
|
||||
description: 提交悦动人像 EMO 视频生成异步任务。需要先调用 [EMO 图像检测](/api-reference/video-generation/emo-detect) 接口获取 `face_bbox` 和 `ext_bbox`。
|
||||
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/EmoVideoRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 任务提交成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmoVideoSubmitResponse"
|
||||
example:
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: PENDING
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
|
||||
"400":
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: InvalidParameter
|
||||
message: The request parameter is invalid.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
"401":
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: InvalidApiKey
|
||||
message: No API-key provided.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
"429":
|
||||
description: 请求频率超限
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: Throttling
|
||||
message: Requests throttling triggered.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
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": "emo-v1",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png",
|
||||
"audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
|
||||
"face_bbox": [302, 286, 610, 593],
|
||||
"ext_bbox": [71, 9, 840, 778]
|
||||
},
|
||||
"parameters": {
|
||||
"style_level": "normal"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
schemas:
|
||||
EmoVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- emo-v1
|
||||
description: 模型名称，固定为 `emo-v1`。
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- audio_url
|
||||
- face_bbox
|
||||
- ext_bbox
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: 人物肖像图片公网 URL。模型将根据 EMO 图像检测 API 返回的 `ext_bbox` 参数对原始图片进行裁剪，裁剪后区域的宽高比决定输出视频的画幅比例与分辨率。支持 jpg、png、jpeg、bmp 格式；图像最小边长 >= 400 像素，最大边长 <= 7000 像素。仅支持 HTTP/HTTPS 链接。
|
||||
audio_url:
|
||||
type: string
|
||||
description: 驱动视频的音频公网 URL。支持 wav、mp3 格式；文件大小不超过 15MB；音频时长不超过 60 秒。仅支持 HTTP/HTTPS 链接。
|
||||
face_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
minItems: 4
|
||||
maxItems: 4
|
||||
description: 人脸边界框，格式为 `[x1, y1, x2, y2]`，代表人脸区域的左上角和右下角坐标。可通过 [EMO 图像检测](/api-reference/video-generation/emo-detect) 接口获取。
|
||||
ext_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
minItems: 4
|
||||
maxItems: 4
|
||||
description: 图片中动态区域 bbox 的像素坐标，应输入 EMO 图像检测 API 出参中同名字段的值。该区域的宽高比为 1:1 或 3:4。坐标格式 `[x1, y1, x2, y2]`，分别对应左上角和右下角两个点的坐标。可通过 [EMO 图像检测](/api-reference/video-generation/emo-detect) 接口获取。
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
style_level:
|
||||
type: string
|
||||
enum:
|
||||
- normal
|
||||
- calm
|
||||
- active
|
||||
default: normal
|
||||
description: 生成视频的动态程度。`normal`：正常动态幅度；`calm`：较平静，动态幅度更小；`active`：较活跃，动态幅度更大。默认为 `normal`。
|
||||
EmoVideoSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 异步任务 ID，用于查询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，值为 `PENDING`。
|
||||
EmoVideoQueryResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
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`：任务不存在或已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（成功或失败时返回）。
|
||||
results:
|
||||
type: object
|
||||
description: 任务成功时返回。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: 生成视频的 URL，有效期 24 小时，请及时下载保存。
|
||||
code:
|
||||
type: string
|
||||
description: 任务失败时的错误码。
|
||||
message:
|
||||
type: string
|
||||
description: 任务失败时的错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 任务成功时返回的用量信息。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
description: 生成视频的时长，单位为秒。
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比，例如 `1:1`、`3:4`。
|
||||
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)。
|
||||
````
|
||||
+259
@@ -0,0 +1,259 @@
|
||||
> ## 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.
|
||||
|
||||
# EMO — 图像检测
|
||||
|
||||
> 检测图像是否符合 EMO 视频生成模型的人物肖像图片规范
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
EMO 图像检测用于判断输入图像是否符合 EMO 视频生成模型的人物肖像图片规范，通常在生成唱演视频前作为图像筛选步骤使用。检测通过后会返回人脸区域坐标和动态区域坐标，可直接作为 EMO 视频生成 API 的入参。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/face-detect
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: EMO Portrait Image Detection API
|
||||
description: EMO 图像检测 API。检测输入图像是否符合 EMO 视频生成模型的人物肖像图片规范。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/face-detect:
|
||||
post:
|
||||
operationId: detectEmoPortrait
|
||||
summary: EMO 图像检测
|
||||
description: 检测输入图像是否符合 EMO 视频生成模型的人物肖像图片规范。返回图像是否通过检测、人脸区域坐标和动态区域坐标。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmoDetectRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 检测成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmoDetectResponse"
|
||||
examples:
|
||||
pass:
|
||||
summary: 图像检测通过
|
||||
value:
|
||||
output:
|
||||
check_pass: true
|
||||
face_bbox:
|
||||
- 302
|
||||
- 286
|
||||
- 610
|
||||
- 593
|
||||
ext_bbox:
|
||||
- 71
|
||||
- 9
|
||||
- 840
|
||||
- 778
|
||||
humanoid: true
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: c56f62df-724e-9c19-96bd-xxxxxx
|
||||
fail:
|
||||
summary: 图像检测不通过
|
||||
value:
|
||||
output:
|
||||
check_pass: false
|
||||
humanoid: false
|
||||
code: ""
|
||||
message: ""
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: c56f62df-724e-9c19-96bd-xxxxxx
|
||||
"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: No API-key provided.
|
||||
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
|
||||
"429":
|
||||
description: 超出速率限制
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
"500":
|
||||
description: 服务端内部错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL
|
||||
source: |-
|
||||
curl 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2video/face-detect' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "emo-detect-v1",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png"
|
||||
},
|
||||
"parameters": {
|
||||
"ratio": "1:1"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
EmoDetectRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
- parameters
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称，固定为 `emo-detect-v1`。
|
||||
enum:
|
||||
- emo-detect-v1
|
||||
example: emo-detect-v1
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
description: 输入图像参数。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
待检测图像的公网可访问 URL。
|
||||
|
||||
**图像要求**：
|
||||
- **格式**：JPG、JPEG、PNG、BMP、WEBP
|
||||
- **分辨率**：宽和高必须在 400 到 7000 像素之间
|
||||
- **URL**：必须为 HTTP 或 HTTPS 协议的公网可访问地址
|
||||
|
||||
<Tip>如需将本地图像上传获取临时 URL，请参考[上传文件获取临时URL](/api-reference/platform-api/file/upload-file)。</Tip>
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png
|
||||
parameters:
|
||||
type: object
|
||||
required:
|
||||
- ratio
|
||||
description: 检测参数。
|
||||
properties:
|
||||
ratio:
|
||||
type: string
|
||||
description: |-
|
||||
希望检测确认的画幅比例。
|
||||
|
||||
- `1:1`：适用于头像图片（默认值）
|
||||
- `3:4`：适用于半身像图片
|
||||
enum:
|
||||
- 1:1
|
||||
- 3:4
|
||||
default: 1:1
|
||||
example: 1:1
|
||||
EmoDetectResponse:
|
||||
type: object
|
||||
description: EMO 图像检测响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符，用于链路追踪和问题排查。
|
||||
example: c56f62df-724e-9c19-96bd-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 检测结果。
|
||||
properties:
|
||||
check_pass:
|
||||
type: boolean
|
||||
description: 图像是否通过检测。`true` 表示图像符合 EMO 视频生成模型的人物肖像图片规范，`false` 表示不符合。
|
||||
example: true
|
||||
face_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 算法检测到的人脸区域坐标 `[x1, y1, x2, y2]`，对应左上和右下两个点的坐标。可将该值作为 EMO 视频生成 API 的入参。检测通过时返回。
|
||||
example:
|
||||
- 302
|
||||
- 286
|
||||
- 610
|
||||
- 593
|
||||
ext_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 算法预测的动态区域坐标 `[x1, y1, x2, y2]`，对应左上和右下两个点的坐标。该区域的宽高比与入参画幅一致。可将该值作为 EMO 视频生成 API 的入参。检测通过时返回。
|
||||
example:
|
||||
- 71
|
||||
- 9
|
||||
- 840
|
||||
- 778
|
||||
humanoid:
|
||||
type: boolean
|
||||
description: 检测到的对象是否为人像。`true` 表示检测到人像，`false` 表示未检测到人像。
|
||||
example: true
|
||||
code:
|
||||
type: string
|
||||
description: 检测未通过或请求失败时的错误码。检测通过时不返回此字段。
|
||||
message:
|
||||
type: string
|
||||
description: 检测未通过或请求失败时的错误描述。检测通过时不返回此字段。
|
||||
usage:
|
||||
type: object
|
||||
description: 使用量统计。
|
||||
properties:
|
||||
image_count:
|
||||
type: integer
|
||||
description: 本次检测的图像数量，固定为 `1`。用于计费。
|
||||
example: 1
|
||||
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.
|
||||
````
|
||||
+239
@@ -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.
|
||||
|
||||
# 悦动人像 EMO — 查询视频生成结果
|
||||
|
||||
> 查询悦动人像 EMO 视频生成任务状态，获取生成的视频
|
||||
|
||||
查询任务状态并获取生成的视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 调用[提交视频生成任务](/api-reference/video-generation/emo-video/create-task)接口获取 `task_id`。
|
||||
2. 每 **15 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 任务成功后，从 `output.results.video_url` 获取视频。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **URL 有效期**：视频 URL 在 **24 小时**后过期，请及时下载保存。
|
||||
- **状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。`UNKNOWN` 表示任务不存在或已过期。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 悦动人像 EMO 视频生成 API
|
||||
version: 1.0.0
|
||||
description: 基于人物肖像图片和音频，生成口型与音频同步的唱演视频。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
summary: 查询视频生成结果
|
||||
operationId: getEmoVideoTask
|
||||
description: 查询悦动人像 EMO 视频生成任务状态，并在任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: 提交任务时返回的 `task_id`。
|
||||
responses:
|
||||
"200":
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmoVideoQueryResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务成功
|
||||
value:
|
||||
request_id: 8190395f-ca1b-4703-9656-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2025-09-11 14:33:38.716
|
||||
scheduled_time: 2025-09-11 14:33:53.089
|
||||
end_time: 2025-09-11 14:35:51.541
|
||||
results:
|
||||
video_url: https://xxx/output.mp4
|
||||
usage:
|
||||
video_duration: 13.93
|
||||
video_ratio: 1:1
|
||||
FAILED:
|
||||
summary: 任务失败
|
||||
value:
|
||||
request_id: 4d687387-580a-4b49-a1f8-4691289e09a3
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: FAILED
|
||||
code: InvalidURL
|
||||
message: Required URL is missing or invalid, please check the request URL.
|
||||
RUNNING:
|
||||
summary: 任务处理中
|
||||
value:
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2025-09-11 14:33:38.716
|
||||
scheduled_time: 2025-09-11 14:33:53.089
|
||||
"401":
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
||||
components:
|
||||
schemas:
|
||||
EmoVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- emo-v1
|
||||
description: 模型名称，固定为 `emo-v1`。
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- audio_url
|
||||
- face_bbox
|
||||
- ext_bbox
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: 人物肖像图片公网 URL。模型将根据 EMO 图像检测 API 返回的 `ext_bbox` 参数对原始图片进行裁剪，裁剪后区域的宽高比决定输出视频的画幅比例与分辨率。支持 jpg、png、jpeg、bmp 格式；图像最小边长 >= 400 像素，最大边长 <= 7000 像素。仅支持 HTTP/HTTPS 链接。
|
||||
audio_url:
|
||||
type: string
|
||||
description: 驱动视频的音频公网 URL。支持 wav、mp3 格式；文件大小不超过 15MB；音频时长不超过 60 秒。仅支持 HTTP/HTTPS 链接。
|
||||
face_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
minItems: 4
|
||||
maxItems: 4
|
||||
description: 人脸边界框，格式为 `[x1, y1, x2, y2]`，代表人脸区域的左上角和右下角坐标。可通过 [EMO 图像检测](/api-reference/video-generation/emo-detect) 接口获取。
|
||||
ext_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
minItems: 4
|
||||
maxItems: 4
|
||||
description: 图片中动态区域 bbox 的像素坐标，应输入 EMO 图像检测 API 出参中同名字段的值。该区域的宽高比为 1:1 或 3:4。坐标格式 `[x1, y1, x2, y2]`，分别对应左上角和右下角两个点的坐标。可通过 [EMO 图像检测](/api-reference/video-generation/emo-detect) 接口获取。
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
style_level:
|
||||
type: string
|
||||
enum:
|
||||
- normal
|
||||
- calm
|
||||
- active
|
||||
default: normal
|
||||
description: 生成视频的动态程度。`normal`：正常动态幅度；`calm`：较平静，动态幅度更小；`active`：较活跃，动态幅度更大。默认为 `normal`。
|
||||
EmoVideoSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 异步任务 ID，用于查询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，值为 `PENDING`。
|
||||
EmoVideoQueryResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
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`：任务不存在或已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（成功或失败时返回）。
|
||||
results:
|
||||
type: object
|
||||
description: 任务成功时返回。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: 生成视频的 URL，有效期 24 小时，请及时下载保存。
|
||||
code:
|
||||
type: string
|
||||
description: 任务失败时的错误码。
|
||||
message:
|
||||
type: string
|
||||
description: 任务失败时的错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 任务成功时返回的用量信息。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
description: 生成视频的时长，单位为秒。
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比，例如 `1:1`、`3:4`。
|
||||
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)。
|
||||
````
|
||||
+330
@@ -0,0 +1,330 @@
|
||||
> ## 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.
|
||||
|
||||
# 表情包视频 Emoji — 创建任务
|
||||
|
||||
> 提交表情包视频生成任务
|
||||
|
||||
根据人物肖像图片和预设表情模板，生成表情包视频。适用于社交媒体表情包、趣味短视频等场景。
|
||||
|
||||
## 前置准备
|
||||
|
||||
1. [获取 API Key](/api-reference/preparation/api-key)。
|
||||
2. 使用 [Emoji 图像检测 API](/api-reference/video-generation/emoji-video/emoji-detect) 检测人脸，获取 `bbox_face`（人脸框坐标）和 `ext_bbox_face`（表情框坐标）。
|
||||
|
||||
## 输入要求
|
||||
|
||||
**人物图片（`image_url`）**：
|
||||
|
||||
- 格式：JPEG、JPG、PNG、BMP 或 WEBP
|
||||
- 分辨率：宽高均在 400～7000 像素之间
|
||||
- 文件大小：不超过 10 MB
|
||||
|
||||
**坐标参数**：
|
||||
|
||||
- `face_bbox`：人脸区域坐标 `[x1, y1, x2, y2]`，取自 Emoji 图像检测 API 返回的 `output.bbox_face`。
|
||||
- `ext_bbox`：表情区域坐标 `[x1, y1, x2, y2]`，取自 Emoji 图像检测 API 返回的 `output.ext_bbox_face`。表情区域略大于人脸区域，包含部分背景和肩部，宽高比约为 1:1。
|
||||
|
||||
## 表情模板
|
||||
|
||||
通过 `driven_id` 指定预设表情模板：
|
||||
|
||||
| 分类 | 模板 ID |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| 萌娃系列 | `mengwa_kaixin`、`mengwa_dengyan`、`mengwa_gandong`、`mengwa_renzhen_1`、`mengwa_jidong`、`mengwa_kun_1`、`mengwa_jiaoxie` |
|
||||
| 打工系列 | `dagong_kaixin`、`dagong_yangwang`、`dagong_kunhuo`、`dagong_zhuakuang`、`dagong_wunai`、`dagong_weixiao`、`dagong_ganji` |
|
||||
| 经典系列 | `jingdian_tiaopi`、`jingdian_deyi_1`、`jingdian_qidai`、`jingdian_landuo_1`、`jingdian_xianqi`、`jingdian_lei` |
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/video-synthesis
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: 表情包视频生成 API
|
||||
description: 表情包emoji-v1模型可基于人物肖像图片和预设模板ID，生成人脸表情包视频。
|
||||
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: createEmojiVideoTask
|
||||
summary: 创建表情包视频生成任务
|
||||
description: "输入通过检测的人物肖像图片、对应的人脸区域、动态表情区域坐标以及表情包模板ID，生成人脸表情包视频。由于视频生成任务耗时较长（通常为1-5分钟），API采用异步调用，需通过 X-DashScope-Async: enable 请求头开启异步处理。"
|
||||
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: 异步处理配置参数。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/EmojiVideoRequest"
|
||||
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"
|
||||
example:
|
||||
code: InvalidApiKey
|
||||
message: Invalid API-key provided.
|
||||
request_id: fb53c4ec-1c12-4fc4-a580-xxxxxx
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/image2video/video-synthesis' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'X-DashScope-Async: enable' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "emoji-v1",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png",
|
||||
"driven_id": "mengwa_kaixin",
|
||||
"face_bbox": [212,194,460,441],
|
||||
"ext_bbox": [63,30,609,575]
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
EmojiVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。固定为 emoji-v1。
|
||||
enum:
|
||||
- emoji-v1
|
||||
example: emoji-v1
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- face_bbox
|
||||
- ext_bbox
|
||||
- driven_id
|
||||
description: 输入的基本信息，如人脸图像、人脸区域、表情包区域等。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: |-
|
||||
人脸正面肖像图像的公网 URL。支持 HTTP 或 HTTPS 协议。本地文件可通过上传文件接口获取临时URL。
|
||||
|
||||
图像限制：
|
||||
- 图像格式：JPEG、JPG、PNG、BMP、WEBP。
|
||||
- 图像分辨率：图像的宽度和高度均在[400, 7000]像素之间。
|
||||
- 文件大小：不超过10MB。
|
||||
- 此图像必须通过 Emoji 图像检测接口进行检测。
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png
|
||||
face_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 图片中人脸区域坐标，格式为 [x1, y1, x2, y2]，单位为像素，对应左上和右下两个点的坐标。此参数需填入 Emoji 图像检测接口响应中的 output.bbox_face 字段的值。
|
||||
example:
|
||||
- 212
|
||||
- 194
|
||||
- 460
|
||||
- 441
|
||||
ext_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: |-
|
||||
动态表情区域坐标，该区域的宽高比约为1:1，格式为 [x1, y1, x2, y2]，单位为像素，对应左上和右下两个点的坐标。此参数需填入 Emoji 图像检测接口响应中的 output.ext_bbox_face 字段的值。
|
||||
|
||||
说明：动态表情区域指的是模型进行视频生成时实际关注的正方形图像区域，它通常比人脸区域稍大，以包含部分背景和肩膀，确保动画效果自然。
|
||||
example:
|
||||
- 63
|
||||
- 30
|
||||
- 609
|
||||
- 575
|
||||
driven_id:
|
||||
type: string
|
||||
description: 预设模板ID，可选值参见附录表情包模板ID列表。
|
||||
enum:
|
||||
- mengwa_kaixin
|
||||
- mengwa_dengyan
|
||||
- mengwa_gandong
|
||||
- mengwa_renzhen_1
|
||||
- mengwa_jidong
|
||||
- mengwa_kun_1
|
||||
- mengwa_jiaoxie
|
||||
- dagong_kaixin
|
||||
- dagong_yangwang
|
||||
- dagong_kunhuo
|
||||
- dagong_zhuakuang
|
||||
- dagong_wunai
|
||||
- dagong_weixiao
|
||||
- dagong_ganji
|
||||
- jingdian_tiaopi
|
||||
- jingdian_deyi_1
|
||||
- jingdian_qidai
|
||||
- jingdian_landuo_1
|
||||
- jingdian_xianqi
|
||||
- jingdian_lei
|
||||
example: mengwa_kaixin
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。请保存 task_id，用于查询任务状态与结果。
|
||||
properties:
|
||||
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
|
||||
example: PENDING
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。可用于请求明细溯源和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
TaskStatusResponse:
|
||||
type: object
|
||||
description: 查询任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。可用于请求明细溯源和问题排查。
|
||||
example: ad225054-6c94-47e5-9356-xxxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 任务输出信息。
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务ID。查询有效期24小时。
|
||||
example: b56f509a-3ea9-4cfe-848d-xxxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: |-
|
||||
任务状态。
|
||||
|
||||
枚举值：
|
||||
- PENDING：任务排队中
|
||||
- RUNNING：任务处理中
|
||||
- SUCCEEDED：任务执行成功
|
||||
- FAILED：任务执行失败
|
||||
- CANCELED：任务已取消
|
||||
- UNKNOWN：任务不存在或状态未知
|
||||
|
||||
轮询过程中的状态流转：
|
||||
- PENDING（排队中） → RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
|
||||
- 初次查询状态通常为 PENDING（排队中）或 RUNNING（处理中）。
|
||||
- 当状态变为 SUCCEEDED 时，响应中将包含生成的视频URL。
|
||||
- 若状态为 FAILED，请检查错误信息并重试。
|
||||
enum:
|
||||
- PENDING
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:28:04.372
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:28:04.400
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:29:03.924
|
||||
video_url:
|
||||
type: string
|
||||
description: 视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时，可通过此URL下载视频。视频格式为MP4（H.264 编码）。
|
||||
example: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx
|
||||
code:
|
||||
type: string
|
||||
description: 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。
|
||||
message:
|
||||
type: string
|
||||
description: 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 输出信息统计，只对成功的结果计数。
|
||||
properties:
|
||||
video_duration:
|
||||
type: integer
|
||||
description: 生成视频的时长，单位为秒。计费公式：费用 = 视频秒数 × 单价。
|
||||
example: 2
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的画幅，固定为standard，表示生成1:1画幅的视频。
|
||||
example: standard
|
||||
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.
|
||||
````
|
||||
+281
@@ -0,0 +1,281 @@
|
||||
> ## 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.
|
||||
|
||||
# Emoji — 图像检测
|
||||
|
||||
> 检测图像中的人物形象是否满足表情包 Emoji 视频生成模型的要求
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
`emoji-detect-v1` 是一个图像合规性检测模型，用于判断输入图像中的人物形象是否满足表情包 Emoji 模型的要求。检测通过后，模型输出人脸区域及扩展后的动态表情区域坐标，供后续 Emoji 视频生成使用。
|
||||
|
||||
## 模型概览
|
||||
|
||||
| 模型名称 | 模型简介 |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| emoji-detect-v1 | 检测输入的图像是否符合 Emoji 视频生成所需要的图像规范。检测通过后，输出人脸区域（bbox\_face）和扩展后的动态表情区域（ext\_bbox\_face）坐标，供视频生成使用。 |
|
||||
|
||||
## 输入图像要求
|
||||
|
||||
**合规图像（检测通过）需满足**：
|
||||
|
||||
- **单人正面肖像**
|
||||
- **面部无遮挡**（如手、头发、饰品等）
|
||||
- **表情自然**，无夸张表情
|
||||
- **头部姿态端正**，无大幅度倾斜
|
||||
|
||||
**不合规图像示例（检测失败）**：
|
||||
|
||||
| 脸部区域附近露出手部 | 存在面部遮挡 | 存在夸张表情 | 头部倾斜角度过大 |
|
||||
| ---------- | ------ | ------ | -------- |
|
||||
| 手部遮挡 | 面部被遮挡 | 夸张表情 | 头部倾斜 |
|
||||
|
||||
## 计费与限流
|
||||
|
||||
- 模型免费额度和计费单价请参见[模型价格](/developer-guides/getting-started/pricing)。
|
||||
- 模型限流请参见[限流](/developer-guides/administration/rate-limits)。
|
||||
|
||||
<Note>
|
||||
当图像因不合规而导致检测不通过时，本次 API 调用仍会正常计费，因为模型已经执行了完整的检测流程。
|
||||
</Note>
|
||||
|
||||
## 错误码
|
||||
|
||||
如果模型调用失败并返回报错信息，请参见[错误信息](/api-reference/preparation/error-messages)进行解决。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/face-detect
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Emoji 图像检测 API
|
||||
description: 检测输入图像中的人物形象是否满足表情包 Emoji 模型的要求。检测通过后返回人脸区域及扩展后的动态表情区域坐标，供后续 Emoji 视频生成使用。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/face-detect:
|
||||
post:
|
||||
operationId: detectEmojiPortrait
|
||||
summary: Emoji 图像检测
|
||||
description: 检测输入图像中的人物形象是否满足表情包 Emoji 模型（emoji-detect-v1）的要求。检测通过后，返回人脸区域坐标（bbox_face）和扩展后的动态表情区域坐标（ext_bbox_face），可直接作为 Emoji 视频生成 API 的入参。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmojiDetectRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 请求成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/EmojiDetectResponse"
|
||||
examples:
|
||||
pass:
|
||||
summary: 检测通过
|
||||
value:
|
||||
output:
|
||||
bbox_face:
|
||||
- 212
|
||||
- 194
|
||||
- 460
|
||||
- 441
|
||||
ext_bbox_face:
|
||||
- 63
|
||||
- 30
|
||||
- 609
|
||||
- 575
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: 78becbc4-f7f7-41ea-9e38-xxxxxx
|
||||
fail_detection:
|
||||
summary: 检测不通过
|
||||
value:
|
||||
output:
|
||||
code: InvalidFile.FacePose
|
||||
message: The pose of the detected face is invalid, please upload other image with the expected oriention.
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: ed0d0d8f-e55a-4144-b855-xxxxxx
|
||||
fail_request:
|
||||
summary: 请求失败
|
||||
value:
|
||||
request_id: 5e1fefbd-fa7a-4e59-82a0-xxxxxx
|
||||
code: InvalidParameter
|
||||
message: Required body invalid, please check the request body format.
|
||||
"400":
|
||||
description: 请求参数无效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
examples:
|
||||
InvalidParameter:
|
||||
summary: 参数缺失或无效
|
||||
value:
|
||||
code: InvalidParameter
|
||||
message: Required body invalid, please check the request body format.
|
||||
request_id: 5e1fefbd-fa7a-4e59-82a0-xxxxxx
|
||||
"401":
|
||||
description: 认证失败 — API Key 无效或缺失
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
examples:
|
||||
InvalidApiKey:
|
||||
summary: API Key 无效
|
||||
value:
|
||||
code: InvalidApiKey
|
||||
message: No API-key provided.
|
||||
request_id: 7438d53d-6eb8-4596-8835-xxxxxx
|
||||
"429":
|
||||
description: 超出速率限制
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
"500":
|
||||
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/face-detect' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "emoji-detect-v1",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png"
|
||||
},
|
||||
"parameters": {
|
||||
"ratio": "1:1"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
EmojiDetectRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
- parameters
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称，固定为 `emoji-detect-v1`。
|
||||
enum:
|
||||
- emoji-detect-v1
|
||||
example: emoji-detect-v1
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
description: 输入的基本信息，如待检测图像。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
待检测图像的公网 URL。支持 HTTP 或 HTTPS 协议。
|
||||
|
||||
**图像限制**：
|
||||
- **格式**：JPEG、JPG、PNG、BMP、WEBP
|
||||
- **分辨率**：宽度和高度均在 400 到 7000 像素之间
|
||||
- **文件大小**：不超过 10 MB
|
||||
|
||||
本地文件可通过[上传文件获取临时 URL](/api-reference/platform-api/file/upload-file)。
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png
|
||||
parameters:
|
||||
type: object
|
||||
required:
|
||||
- ratio
|
||||
description: 图像处理参数。
|
||||
properties:
|
||||
ratio:
|
||||
type: string
|
||||
description: 待检测区域的长宽比。对于 Emoji 视频生成，此值固定为 `1:1`。
|
||||
enum:
|
||||
- 1:1
|
||||
example: 1:1
|
||||
EmojiDetectResponse:
|
||||
type: object
|
||||
description: Emoji 图像检测响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，可用于请求明细溯源和问题排查。
|
||||
example: 78becbc4-f7f7-41ea-9e38-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 任务输出信息。
|
||||
properties:
|
||||
bbox_face:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 检测到的人脸区域坐标，格式为 `[x1, y1, x2, y2]`，单位为像素，对应左上和右下两个点的坐标。仅在检测通过时返回。此值应作为 Emoji 视频生成接口 `input.face_bbox` 参数的值。
|
||||
example:
|
||||
- 212
|
||||
- 194
|
||||
- 460
|
||||
- 441
|
||||
ext_bbox_face:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 扩展后的动态表情区域坐标，格式为 `[x1, y1, x2, y2]`，单位为像素，对应左上和右下两个点的坐标。仅在检测通过时返回。此值应作为 Emoji 视频生成接口 `input.ext_bbox` 参数的值。
|
||||
example:
|
||||
- 63
|
||||
- 30
|
||||
- 609
|
||||
- 575
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在检测不通过时返回，详情请参见[错误信息](/api-reference/preparation/error-messages)。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在检测不通过时返回，详情请参见[错误信息](/api-reference/preparation/error-messages)。
|
||||
usage:
|
||||
type: object
|
||||
description: 输出信息统计。
|
||||
properties:
|
||||
image_count:
|
||||
type: integer
|
||||
description: 本次请求检测图像数量，固定为 1 张，用于计费。无论检测是否通过，只要请求成功就计费；请求失败不计费。
|
||||
example: 1
|
||||
DashScopeErrorResponse:
|
||||
type: object
|
||||
description: DashScope API 错误响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符。
|
||||
example: 5e1fefbd-fa7a-4e59-82a0-xxxxxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。
|
||||
example: InvalidParameter
|
||||
message:
|
||||
type: string
|
||||
description: 错误描述信息。
|
||||
example: Required body invalid, please check the request body format.
|
||||
````
|
||||
+320
@@ -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.
|
||||
|
||||
# 表情包视频 Emoji — 查询结果
|
||||
|
||||
> 查询表情包视频生成状态
|
||||
|
||||
查询任务状态并获取生成的表情包视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 调用[创建任务](/api-reference/video-generation/emoji-video/create-task)接口获取 `task_id`。
|
||||
2. 每 **15 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 任务成功后，从 `output.video_url` 获取视频。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **URL 有效期**：视频 URL 在 **24 小时**后过期，请及时下载。
|
||||
- **状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。`UNKNOWN` 表示任务不存在或已过期。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: 表情包视频生成 API
|
||||
description: 表情包emoji-v1模型可基于人物肖像图片和预设模板ID，生成人脸表情包视频。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: DashScope API
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getEmojiVideoTaskStatus
|
||||
summary: 根据任务ID查询结果
|
||||
description: 根据任务ID查询视频生成任务的状态和结果。视频生成过程约需数分钟，建议采用轮询机制，并设置合理的查询间隔（如15秒）来获取结果。task_id 有效期为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
|
||||
responses:
|
||||
"200":
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/TaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务执行成功
|
||||
description: 视频URL仅保留24小时，超时后会被自动清除，请及时保存生成的视频。
|
||||
value:
|
||||
request_id: ad225054-6c94-47e5-9356-xxxxxxx
|
||||
output:
|
||||
task_id: b56f509a-3ea9-4cfe-848d-xxxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2025-10-14 11:28:04.372
|
||||
scheduled_time: 2025-10-14 11:28:04.400
|
||||
end_time: 2025-10-14 11:29:03.924
|
||||
video_url: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx
|
||||
usage:
|
||||
video_duration: 2
|
||||
video_ratio: standard
|
||||
FAILED:
|
||||
summary: 任务执行失败
|
||||
description: 若任务执行失败，task_status将置为 FAILED，并提供错误码和信息。请参见错误信息进行解决。
|
||||
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 xxxxxx
|
||||
RUNNING:
|
||||
summary: 任务处理中
|
||||
value:
|
||||
request_id: ad225054-6c94-47e5-9356-xxxxxxx
|
||||
output:
|
||||
task_id: b56f509a-3ea9-4cfe-848d-xxxxxxx
|
||||
task_status: RUNNING
|
||||
UNKNOWN:
|
||||
summary: 任务查询过期
|
||||
description: task_id查询有效期为24小时，超时后将无法查询，返回以下报错信息。
|
||||
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: |-
|
||||
# 请将 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:
|
||||
EmojiVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。固定为 emoji-v1。
|
||||
enum:
|
||||
- emoji-v1
|
||||
example: emoji-v1
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- face_bbox
|
||||
- ext_bbox
|
||||
- driven_id
|
||||
description: 输入的基本信息，如人脸图像、人脸区域、表情包区域等。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: |-
|
||||
人脸正面肖像图像的公网 URL。支持 HTTP 或 HTTPS 协议。本地文件可通过上传文件接口获取临时URL。
|
||||
|
||||
图像限制：
|
||||
- 图像格式：JPEG、JPG、PNG、BMP、WEBP。
|
||||
- 图像分辨率：图像的宽度和高度均在[400, 7000]像素之间。
|
||||
- 文件大小：不超过10MB。
|
||||
- 此图像必须通过 Emoji 图像检测接口进行检测。
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png
|
||||
face_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: 图片中人脸区域坐标，格式为 [x1, y1, x2, y2]，单位为像素，对应左上和右下两个点的坐标。此参数需填入 Emoji 图像检测接口响应中的 output.bbox_face 字段的值。
|
||||
example:
|
||||
- 212
|
||||
- 194
|
||||
- 460
|
||||
- 441
|
||||
ext_bbox:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: |-
|
||||
动态表情区域坐标，该区域的宽高比约为1:1，格式为 [x1, y1, x2, y2]，单位为像素，对应左上和右下两个点的坐标。此参数需填入 Emoji 图像检测接口响应中的 output.ext_bbox_face 字段的值。
|
||||
|
||||
说明：动态表情区域指的是模型进行视频生成时实际关注的正方形图像区域，它通常比人脸区域稍大，以包含部分背景和肩膀，确保动画效果自然。
|
||||
example:
|
||||
- 63
|
||||
- 30
|
||||
- 609
|
||||
- 575
|
||||
driven_id:
|
||||
type: string
|
||||
description: 预设模板ID，可选值参见附录表情包模板ID列表。
|
||||
enum:
|
||||
- mengwa_kaixin
|
||||
- mengwa_dengyan
|
||||
- mengwa_gandong
|
||||
- mengwa_renzhen_1
|
||||
- mengwa_jidong
|
||||
- mengwa_kun_1
|
||||
- mengwa_jiaoxie
|
||||
- dagong_kaixin
|
||||
- dagong_yangwang
|
||||
- dagong_kunhuo
|
||||
- dagong_zhuakuang
|
||||
- dagong_wunai
|
||||
- dagong_weixiao
|
||||
- dagong_ganji
|
||||
- jingdian_tiaopi
|
||||
- jingdian_deyi_1
|
||||
- jingdian_qidai
|
||||
- jingdian_landuo_1
|
||||
- jingdian_xianqi
|
||||
- jingdian_lei
|
||||
example: mengwa_kaixin
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。请保存 task_id，用于查询任务状态与结果。
|
||||
properties:
|
||||
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
|
||||
example: PENDING
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。可用于请求明细溯源和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
TaskStatusResponse:
|
||||
type: object
|
||||
description: 查询任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。可用于请求明细溯源和问题排查。
|
||||
example: ad225054-6c94-47e5-9356-xxxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 任务输出信息。
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务ID。查询有效期24小时。
|
||||
example: b56f509a-3ea9-4cfe-848d-xxxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: |-
|
||||
任务状态。
|
||||
|
||||
枚举值：
|
||||
- PENDING：任务排队中
|
||||
- RUNNING：任务处理中
|
||||
- SUCCEEDED：任务执行成功
|
||||
- FAILED：任务执行失败
|
||||
- CANCELED：任务已取消
|
||||
- UNKNOWN：任务不存在或状态未知
|
||||
|
||||
轮询过程中的状态流转：
|
||||
- PENDING（排队中） → RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
|
||||
- 初次查询状态通常为 PENDING（排队中）或 RUNNING（处理中）。
|
||||
- 当状态变为 SUCCEEDED 时，响应中将包含生成的视频URL。
|
||||
- 若状态为 FAILED，请检查错误信息并重试。
|
||||
enum:
|
||||
- PENDING
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:28:04.372
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:28:04.400
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。
|
||||
example: 2025-10-14 11:29:03.924
|
||||
video_url:
|
||||
type: string
|
||||
description: 视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时，可通过此URL下载视频。视频格式为MP4（H.264 编码）。
|
||||
example: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx
|
||||
code:
|
||||
type: string
|
||||
description: 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。
|
||||
message:
|
||||
type: string
|
||||
description: 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 输出信息统计，只对成功的结果计数。
|
||||
properties:
|
||||
video_duration:
|
||||
type: integer
|
||||
description: 生成视频的时长，单位为秒。计费公式：费用 = 视频秒数 × 单价。
|
||||
example: 2
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的画幅，固定为standard，表示生成1:1画幅的视频。
|
||||
example: standard
|
||||
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.
|
||||
````
|
||||
+270
@@ -0,0 +1,270 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 图生视频（首帧）
|
||||
|
||||
> 提交 HappyHorse 图生视频任务（基于首帧）
|
||||
|
||||
以首帧图片为基础，支持通过文本描述进行引导，生成物理真实、运动流畅的视频，最长 15 秒，支持 1080P 分辨率。输出视频宽高比自动跟随输入首帧图像。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/video-generation/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 图生视频 API
|
||||
description: 使用 HappyHorse 模型以首帧图片为基础生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/video-generation/video-synthesis:
|
||||
post:
|
||||
operationId: createHappyHorseImageToVideo
|
||||
summary: 提交图生视频任务
|
||||
description: 提交图生视频任务，返回 `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/HappyHorseImageToVideoRequest"
|
||||
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/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "happyhorse-1.1-i2v",
|
||||
"input": {
|
||||
"prompt": "一只猫在草地上奔跑",
|
||||
"media": [
|
||||
{
|
||||
"type": "first_frame",
|
||||
"url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
|
||||
}
|
||||
]
|
||||
},
|
||||
"parameters": {
|
||||
"resolution": "720P",
|
||||
"duration": 5
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
HappyHorseImageToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-i2v`、`happyhorse-1.0-i2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-i2v
|
||||
- happyhorse-1.0-i2v
|
||||
example: happyhorse-1.1-i2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- media
|
||||
description: 输入的基本信息，如提示词等。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用于描述期望生成的视频内容。可选 -- 不传时模型根据图像自行推断运动。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分将自动截断。
|
||||
example: 一只猫在草地上奔跑
|
||||
media:
|
||||
type: array
|
||||
description: 输入媒体列表。有且仅有1张首帧图像。生成视频的宽高比自动跟随输入首帧图像。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型。固定值：`first_frame`（首帧）。
|
||||
enum:
|
||||
- first_frame
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
首帧图像 URL 或 Base64 编码数据。
|
||||
|
||||
**图像限制**：格式：JPEG、JPG、PNG、WEBP。分辨率：宽和高不小于 300 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 20 MB。
|
||||
|
||||
**支持的输入格式**：
|
||||
- 公网 URL：支持 HTTP 或 HTTPS 协议。
|
||||
- Base64 编码：格式为 `data:{MIME_type};base64,{base64_data}`。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseImageToVideoParameters"
|
||||
HappyHorseImageToVideoParameters:
|
||||
type: object
|
||||
description: 视频处理参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 指定生成视频的分辨率档位。模型根据选择的分辨率档位，自动缩放至相近总像素。输出的视频宽高比与输入首帧近似一致。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
duration:
|
||||
type: integer
|
||||
description: 指定生成视频的时长，单位为秒。取值为 [3, 15] 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseI2VTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 图生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
example: 8ae698ba-df2d-966c-abcf-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID。提交后 24 小时内可查询。
|
||||
example: e56d806f-76f9-4037-aefa-xxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务状态流转：`PENDING` -> `RUNNING` -> `SUCCEEDED` 或 `FAILED`。手动取消为 `CANCELED`，过期为 `UNKNOWN`。
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码，24fps）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。图生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 查询图生视频结果
|
||||
|
||||
> 查询 HappyHorse 图生视频任务状态
|
||||
|
||||
轮询任务状态，任务成功后下载视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 保存[提交任务](/api-reference/video-generation/happyhorse-image-to-video/create-task)响应中的 `task_id`。
|
||||
2. 每 **15 秒**轮询本接口，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 在 **24 小时**内通过 `video_url` 下载视频 -- 链接过期后将无法访问。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 图生视频 API
|
||||
description: 使用 HappyHorse 模型以首帧图片为基础生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getHappyHorseImageToVideoTaskStatus
|
||||
summary: 查询图生视频任务结果
|
||||
description: 轮询任务状态，任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 提交任务时返回的任务 ID。
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: 任务状态查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HappyHorseI2VTaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务执行成功
|
||||
value:
|
||||
request_id: 8ae698ba-df2d-966c-abcf-xxxxxx
|
||||
output:
|
||||
task_id: e56d806f-76f9-4037-aefa-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2026-04-20 19:33:50.425
|
||||
scheduled_time: 2026-04-20 19:33:50.463
|
||||
end_time: 2026-04-20 19:35:34.216
|
||||
orig_prompt: 一只猫在草地上奔跑
|
||||
video_url: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx
|
||||
usage:
|
||||
duration: 5
|
||||
input_video_duration: 0
|
||||
output_video_duration: 5
|
||||
video_count: 1
|
||||
SR: 720
|
||||
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 parameter is invalid.
|
||||
RUNNING:
|
||||
summary: 任务执行中
|
||||
value:
|
||||
request_id: c1209113-8437-424f-a386-xxxxxx
|
||||
output:
|
||||
task_id: e56d806f-76f9-4037-aefa-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2026-04-20 19:33:50.425
|
||||
scheduled_time: 2026-04-20 19:33:50.463
|
||||
UNKNOWN:
|
||||
summary: 任务查询过期
|
||||
value:
|
||||
request_id: a4de7c32-7057-9f82-8581-xxxxxx
|
||||
output:
|
||||
task_id: e56d806f-76f9-4037-aefa-xxxxxx
|
||||
task_status: UNKNOWN
|
||||
"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:
|
||||
HappyHorseImageToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-i2v`、`happyhorse-1.0-i2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-i2v
|
||||
- happyhorse-1.0-i2v
|
||||
example: happyhorse-1.1-i2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- media
|
||||
description: 输入的基本信息，如提示词等。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用于描述期望生成的视频内容。可选 -- 不传时模型根据图像自行推断运动。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分将自动截断。
|
||||
example: 一只猫在草地上奔跑
|
||||
media:
|
||||
type: array
|
||||
description: 输入媒体列表。有且仅有1张首帧图像。生成视频的宽高比自动跟随输入首帧图像。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型。固定值：`first_frame`（首帧）。
|
||||
enum:
|
||||
- first_frame
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
首帧图像 URL 或 Base64 编码数据。
|
||||
|
||||
**图像限制**：格式：JPEG、JPG、PNG、WEBP。分辨率：宽和高不小于 300 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 20 MB。
|
||||
|
||||
**支持的输入格式**：
|
||||
- 公网 URL：支持 HTTP 或 HTTPS 协议。
|
||||
- Base64 编码：格式为 `data:{MIME_type};base64,{base64_data}`。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseImageToVideoParameters"
|
||||
HappyHorseImageToVideoParameters:
|
||||
type: object
|
||||
description: 视频处理参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 指定生成视频的分辨率档位。模型根据选择的分辨率档位，自动缩放至相近总像素。输出的视频宽高比与输入首帧近似一致。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
duration:
|
||||
type: integer
|
||||
description: 指定生成视频的时长，单位为秒。取值为 [3, 15] 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseI2VTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 图生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
example: 8ae698ba-df2d-966c-abcf-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID。提交后 24 小时内可查询。
|
||||
example: e56d806f-76f9-4037-aefa-xxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务状态流转：`PENDING` -> `RUNNING` -> `SUCCEEDED` 或 `FAILED`。手动取消为 `CANCELED`，过期为 `UNKNOWN`。
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码，24fps）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。图生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+297
@@ -0,0 +1,297 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 参考生视频
|
||||
|
||||
> 提交 HappyHorse 参考生视频任务
|
||||
|
||||
传入多张参考图像，通过文本提示词描述场景，将图像中的主体角色融合生成一段流畅的视频，最长 15 秒，支持 1080P 分辨率。在 prompt 中使用 `[Image 1]`、`[Image 2]` 等标识指代 `media` 数组中对应位置的参考图像，顺序与 `media` 数组顺序一致。使用时需要指明参考图中的具体对象，例如"\[Image 1]中身着红色旗袍的女性"。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/video-generation/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 参考生视频 API
|
||||
description: 使用 HappyHorse 模型传入多张参考图像生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/video-generation/video-synthesis:
|
||||
post:
|
||||
operationId: createHappyHorseRefToVideo
|
||||
summary: 提交参考生视频任务
|
||||
description: 提交参考生视频任务，返回 `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/HappyHorseRefToVideoRequest"
|
||||
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/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "happyhorse-1.1-r2v",
|
||||
"input": {
|
||||
"prompt": "[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。",
|
||||
"media": [
|
||||
{
|
||||
"type": "reference_image",
|
||||
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
|
||||
},
|
||||
{
|
||||
"type": "reference_image",
|
||||
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
|
||||
},
|
||||
{
|
||||
"type": "reference_image",
|
||||
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
|
||||
}
|
||||
]
|
||||
},
|
||||
"parameters": {
|
||||
"resolution": "720P",
|
||||
"ratio": "16:9",
|
||||
"duration": 5
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
HappyHorseRefToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-r2v`、`happyhorse-1.0-r2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-r2v
|
||||
- happyhorse-1.0-r2v
|
||||
example: happyhorse-1.1-r2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
- media
|
||||
description: 输入的基本信息，包括参考图像和提示词。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用来描述生成视频中期望包含的元素和视觉特点。在 prompt 中通过 `[Image 1]`、`[Image 2]` 等标识指代 `media` 数组中对应位置的参考图像，顺序与 `media` 数组顺序一致。使用时需要指明参考图中的具体对象，例如"[Image 1]中身着红色旗袍的女性"。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分会自动截断。
|
||||
example: "[Image 1]中身着红色旗袍的女性，优雅站立。"
|
||||
media:
|
||||
type: array
|
||||
description: 媒体素材列表（1-9张参考图像）。数组中的第 1 个 `reference_image` 对应 `[Image 1]`，第 2 个对应 `[Image 2]`，以此类推。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型。固定值：`reference_image`（参考图像）。
|
||||
enum:
|
||||
- reference_image
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
参考图像 URL 或 Base64 编码数据。
|
||||
|
||||
**图像限制**：格式：JPEG、JPG、PNG、WEBP。分辨率：短边不低于 400 像素，推荐 720P 以上清晰图。文件大小：不超过 20 MB。
|
||||
|
||||
**支持的输入格式**：
|
||||
- 公网 URL：支持 HTTP 或 HTTPS 协议。
|
||||
- Base64 编码：格式为 `data:{MIME_type};base64,{base64_data}`。
|
||||
minItems: 1
|
||||
maxItems: 9
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseRefToVideoParameters"
|
||||
HappyHorseRefToVideoParameters:
|
||||
type: object
|
||||
description: 视频生成参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 生成视频的分辨率档位。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比。
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
- 4:3
|
||||
- 3:4
|
||||
- 4:5
|
||||
- 5:4
|
||||
- 9:21
|
||||
- 21:9
|
||||
default: 16:9
|
||||
duration:
|
||||
type: integer
|
||||
description: 生成视频的时长，单位为秒。取值范围：3~15 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseR2VTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 参考生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
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
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。参考生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+314
@@ -0,0 +1,314 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 查询参考生视频结果
|
||||
|
||||
> 查询 HappyHorse 参考生视频任务状态
|
||||
|
||||
轮询任务状态，任务成功后下载视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 保存[提交任务](/api-reference/video-generation/happyhorse-reference-to-video/create-task)响应中的 `task_id`。
|
||||
2. 每 **15 秒**轮询本接口，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 在 **24 小时**内通过 `video_url` 下载视频 -- 链接过期后将无法访问。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 参考生视频 API
|
||||
description: 使用 HappyHorse 模型传入多张参考图像生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getHappyHorseRefToVideoTaskStatus
|
||||
summary: 查询参考生视频任务结果
|
||||
description: 轮询任务状态，任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 提交任务时返回的任务 ID。
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: 任务状态查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HappyHorseR2VTaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务执行成功
|
||||
value:
|
||||
request_id: 35137489-2862-96cb-b6f2-xxxxxx
|
||||
output:
|
||||
task_id: 1469cfc3-3004-4d9e-ab10-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2026-04-25 15:03:25.848
|
||||
scheduled_time: 2026-04-25 15:03:25.884
|
||||
end_time: 2026-04-25 15:04:05.882
|
||||
orig_prompt: "[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。"
|
||||
video_url: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4
|
||||
usage:
|
||||
duration: 5
|
||||
input_video_duration: 0
|
||||
output_video_duration: 5
|
||||
video_count: 1
|
||||
SR: 720
|
||||
ratio: 16:9
|
||||
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 resolution is not valid xxxxxx
|
||||
RUNNING:
|
||||
summary: 任务执行中
|
||||
value:
|
||||
request_id: c1209113-8437-424f-a386-xxxxxx
|
||||
output:
|
||||
task_id: 1469cfc3-3004-4d9e-ab10-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2026-04-25 15:03:25.848
|
||||
scheduled_time: 2026-04-25 15:03:25.884
|
||||
UNKNOWN:
|
||||
summary: 任务查询过期
|
||||
value:
|
||||
request_id: a4de7c32-7057-9f82-8581-xxxxxx
|
||||
output:
|
||||
task_id: 1469cfc3-3004-4d9e-ab10-xxxxxx
|
||||
task_status: UNKNOWN
|
||||
"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:
|
||||
HappyHorseRefToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-r2v`、`happyhorse-1.0-r2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-r2v
|
||||
- happyhorse-1.0-r2v
|
||||
example: happyhorse-1.1-r2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
- media
|
||||
description: 输入的基本信息，包括参考图像和提示词。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用来描述生成视频中期望包含的元素和视觉特点。在 prompt 中通过 `[Image 1]`、`[Image 2]` 等标识指代 `media` 数组中对应位置的参考图像，顺序与 `media` 数组顺序一致。使用时需要指明参考图中的具体对象，例如"[Image 1]中身着红色旗袍的女性"。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分会自动截断。
|
||||
example: "[Image 1]中身着红色旗袍的女性，优雅站立。"
|
||||
media:
|
||||
type: array
|
||||
description: 媒体素材列表（1-9张参考图像）。数组中的第 1 个 `reference_image` 对应 `[Image 1]`，第 2 个对应 `[Image 2]`，以此类推。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型。固定值：`reference_image`（参考图像）。
|
||||
enum:
|
||||
- reference_image
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
参考图像 URL 或 Base64 编码数据。
|
||||
|
||||
**图像限制**：格式：JPEG、JPG、PNG、WEBP。分辨率：短边不低于 400 像素，推荐 720P 以上清晰图。文件大小：不超过 20 MB。
|
||||
|
||||
**支持的输入格式**：
|
||||
- 公网 URL：支持 HTTP 或 HTTPS 协议。
|
||||
- Base64 编码：格式为 `data:{MIME_type};base64,{base64_data}`。
|
||||
minItems: 1
|
||||
maxItems: 9
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseRefToVideoParameters"
|
||||
HappyHorseRefToVideoParameters:
|
||||
type: object
|
||||
description: 视频生成参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 生成视频的分辨率档位。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比。
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
- 4:3
|
||||
- 3:4
|
||||
- 4:5
|
||||
- 5:4
|
||||
- 9:21
|
||||
- 21:9
|
||||
default: 16:9
|
||||
duration:
|
||||
type: integer
|
||||
description: 生成视频的时长，单位为秒。取值范围：3~15 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseR2VTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 参考生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
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
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。参考生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
ratio:
|
||||
type: string
|
||||
description: 生成视频的宽高比。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+261
@@ -0,0 +1,261 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 文生视频
|
||||
|
||||
> 提交 HappyHorse 文生视频任务
|
||||
|
||||
输入文本提示词生成物理真实、运动流畅的视频，最长 15 秒，支持 1080P 分辨率。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/video-generation/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 文生视频 API
|
||||
description: 使用 HappyHorse 模型通过文本提示词生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/video-generation/video-synthesis:
|
||||
post:
|
||||
operationId: createHappyHorseTextToVideo
|
||||
summary: 提交文生视频任务
|
||||
description: 提交文生视频任务，返回 `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/HappyHorseTextToVideoRequest"
|
||||
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/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "happyhorse-1.1-t2v",
|
||||
"input": {
|
||||
"prompt": "一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。一列硬纸板火车缓缓驶过，小灯点缀其间，照亮前路。"
|
||||
},
|
||||
"parameters": {
|
||||
"resolution": "720P",
|
||||
"ratio": "16:9",
|
||||
"duration": 5
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
HappyHorseTextToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-t2v`、`happyhorse-1.0-t2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-t2v
|
||||
- happyhorse-1.0-t2v
|
||||
example: happyhorse-1.1-t2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
description: 模型的输入信息。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用于描述期望生成的视频内容。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分将自动截断。
|
||||
example: 一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseTextToVideoParameters"
|
||||
HappyHorseTextToVideoParameters:
|
||||
type: object
|
||||
description: 视频处理参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 指定生成视频的分辨率档位。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
ratio:
|
||||
type: string
|
||||
description: 指定生成视频的宽高比。
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
- 4:3
|
||||
- 3:4
|
||||
- 4:5
|
||||
- 5:4
|
||||
- 9:21
|
||||
- 21:9
|
||||
default: 16:9
|
||||
duration:
|
||||
type: integer
|
||||
description: 指定生成视频的时长，单位为秒。取值为 [3, 15] 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 文生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
example: 99243b47-ec5f-9413-9993-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID。提交后 24 小时内可查询。
|
||||
example: 4673458e-28be-4a05-bf2a-xxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务状态流转：`PENDING` -> `RUNNING` -> `SUCCEEDED` 或 `FAILED`。手动取消为 `CANCELED`，过期为 `UNKNOWN`。
|
||||
enum:
|
||||
- PENDING
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间（UTC+8，`YYYY-MM-DD HH:mm:ss.SSS`）。
|
||||
example: 2026-04-20 17:55:17.075
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始执行时间（UTC+8，`YYYY-MM-DD HH:mm:ss.SSS`）。
|
||||
example: 2026-04-20 17:55:17.129
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（UTC+8）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
example: 2026-04-20 17:56:36.658
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
example: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。文生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
ratio:
|
||||
type: string
|
||||
description: 输出视频的宽高比。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+292
@@ -0,0 +1,292 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 查询文生视频结果
|
||||
|
||||
> 查询 HappyHorse 文生视频任务状态
|
||||
|
||||
轮询任务状态，任务成功后下载视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 保存[提交任务](/api-reference/video-generation/happyhorse-text-to-video/create-task)响应中的 `task_id`。
|
||||
2. 每 **15 秒**轮询本接口，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 在 **24 小时**内通过 `video_url` 下载视频 -- 链接过期后将无法访问。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 文生视频 API
|
||||
description: 使用 HappyHorse 模型通过文本提示词生成视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getHappyHorseTextToVideoTaskStatus
|
||||
summary: 查询文生视频任务结果
|
||||
description: 轮询任务状态，任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 提交任务时返回的任务 ID。
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: 任务状态查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HappyHorseTaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务执行成功
|
||||
value:
|
||||
request_id: 99243b47-ec5f-9413-9993-xxxxxx
|
||||
output:
|
||||
task_id: 4673458e-28be-4a05-bf2a-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2026-04-20 17:55:17.075
|
||||
scheduled_time: 2026-04-20 17:55:17.129
|
||||
end_time: 2026-04-20 17:56:36.658
|
||||
orig_prompt: 一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。一列硬纸板火车缓缓驶过，小灯点缀其间，照亮前路。
|
||||
video_url: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx
|
||||
usage:
|
||||
duration: 5
|
||||
input_video_duration: 0
|
||||
output_video_duration: 5
|
||||
video_count: 1
|
||||
SR: 720
|
||||
ratio: 16:9
|
||||
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 parameter is invalid.
|
||||
RUNNING:
|
||||
summary: 任务执行中
|
||||
value:
|
||||
request_id: c1209113-8437-424f-a386-xxxxxx
|
||||
output:
|
||||
task_id: 4673458e-28be-4a05-bf2a-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2026-04-20 17:55:17.075
|
||||
scheduled_time: 2026-04-20 17:55:17.129
|
||||
UNKNOWN:
|
||||
summary: 任务查询过期
|
||||
value:
|
||||
request_id: a4de7c32-7057-9f82-8581-xxxxxx
|
||||
output:
|
||||
task_id: 4673458e-28be-4a05-bf2a-xxxxxx
|
||||
task_status: UNKNOWN
|
||||
"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:
|
||||
HappyHorseTextToVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。可选值：`happyhorse-1.1-t2v`、`happyhorse-1.0-t2v`。
|
||||
enum:
|
||||
- happyhorse-1.1-t2v
|
||||
- happyhorse-1.0-t2v
|
||||
example: happyhorse-1.1-t2v
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
description: 模型的输入信息。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用于描述期望生成的视频内容。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分将自动截断。
|
||||
example: 一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseTextToVideoParameters"
|
||||
HappyHorseTextToVideoParameters:
|
||||
type: object
|
||||
description: 视频处理参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 指定生成视频的分辨率档位。
|
||||
enum:
|
||||
- 480P
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
ratio:
|
||||
type: string
|
||||
description: 指定生成视频的宽高比。
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
- 4:3
|
||||
- 3:4
|
||||
- 4:5
|
||||
- 5:4
|
||||
- 9:21
|
||||
- 21:9
|
||||
default: 16:9
|
||||
duration:
|
||||
type: integer
|
||||
description: 指定生成视频的时长，单位为秒。取值为 [3, 15] 之间的整数。
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 文生视频任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
example: 99243b47-ec5f-9413-9993-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID。提交后 24 小时内可查询。
|
||||
example: 4673458e-28be-4a05-bf2a-xxxxxx
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务状态流转：`PENDING` -> `RUNNING` -> `SUCCEEDED` 或 `FAILED`。手动取消为 `CANCELED`，过期为 `UNKNOWN`。
|
||||
enum:
|
||||
- PENDING
|
||||
- RUNNING
|
||||
- SUCCEEDED
|
||||
- FAILED
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间（UTC+8，`YYYY-MM-DD HH:mm:ss.SSS`）。
|
||||
example: 2026-04-20 17:55:17.075
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始执行时间（UTC+8，`YYYY-MM-DD HH:mm:ss.SSS`）。
|
||||
example: 2026-04-20 17:55:17.129
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（UTC+8）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
example: 2026-04-20 17:56:36.658
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
example: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: integer
|
||||
description: 输入视频时长，单位秒。文生视频固定为 0。
|
||||
output_video_duration:
|
||||
type: integer
|
||||
description: 输出视频时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
ratio:
|
||||
type: string
|
||||
description: 输出视频的宽高比。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+273
@@ -0,0 +1,273 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 视频编辑
|
||||
|
||||
> 提交 HappyHorse 视频编辑任务
|
||||
|
||||
输入视频与参考图，结合文本指令完成风格变换、局部替换等编辑任务。支持 720P/1080P 分辨率，输入视频时长 3\~60 秒，输出视频上限 15 秒。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/video-generation/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 视频编辑 API
|
||||
description: 使用 HappyHorse 模型通过文本指令和参考图片编辑视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/video-generation/video-synthesis:
|
||||
post:
|
||||
operationId: createHappyHorseVideoEditing
|
||||
summary: 提交视频编辑任务
|
||||
description: 提交视频编辑任务，返回 `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/HappyHorseVideoEditingRequest"
|
||||
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/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "happyhorse-1.0-video-edit",
|
||||
"input": {
|
||||
"prompt": "让视频中的马头人身角色穿上图片中的条纹毛衣",
|
||||
"media": [
|
||||
{
|
||||
"type": "video",
|
||||
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
|
||||
},
|
||||
{
|
||||
"type": "reference_image",
|
||||
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
|
||||
}
|
||||
]
|
||||
},
|
||||
"parameters": {
|
||||
"resolution": "720P"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
HappyHorseVideoEditingRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。固定值：`happyhorse-1.0-video-edit`。
|
||||
enum:
|
||||
- happyhorse-1.0-video-edit
|
||||
example: happyhorse-1.0-video-edit
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
- media
|
||||
description: 输入的基本信息，包括待编辑的视频、参考图片和提示词。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用来描述对视频的编辑意图，如风格转换、局部替换等。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分会自动截断。
|
||||
example: 让视频中的马头人身角色穿上图片中的条纹毛衣
|
||||
media:
|
||||
type: array
|
||||
description: 媒体素材列表。必须包含1个 `video` 类型元素；可选包含 0~5 个 `reference_image` 类型元素。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型：`video`（必传，待编辑的视频）或 `reference_image`（可选，参考图像）。
|
||||
enum:
|
||||
- video
|
||||
- reference_image
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
媒体素材的 URL 地址或 Base64 编码数据。
|
||||
|
||||
**视频**（`type=video`）：MP4、MOV（建议 H.264 编码）。时长：3~60 秒。分辨率：长边不超过 4096 像素，短边不小于 360 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 100 MB。帧率：8~60 fps（若输入可变帧率视频，需保证帧率变化均在此范围内）。输出视频时长上限 15 秒（超出部分从头自动截取）。
|
||||
|
||||
**图像**（`type=reference_image`）：JPEG、JPG、PNG、WEBP。分辨率：宽高不小于 300 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 20 MB。支持公网 URL（HTTP/HTTPS）或 Base64 编码（格式：`data:{MIME_type};base64,{base64_data}`）。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseVideoEditingParameters"
|
||||
HappyHorseVideoEditingParameters:
|
||||
type: object
|
||||
description: 视频编辑参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 生成视频的分辨率档位。
|
||||
enum:
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
audio_setting:
|
||||
type: string
|
||||
description: 声音控制。
|
||||
enum:
|
||||
- auto
|
||||
- origin
|
||||
default: auto
|
||||
x-enumDescriptions:
|
||||
auto: 由模型自行控制。
|
||||
origin: 保留输入视频的原始声音。
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseVideoEditTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 视频编辑任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
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
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: number
|
||||
description: 输入视频的时长，单位秒。
|
||||
output_video_duration:
|
||||
type: number
|
||||
description: 输出视频的时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
> ## 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.
|
||||
|
||||
# HappyHorse -- 查询视频编辑结果
|
||||
|
||||
> 查询 HappyHorse 视频编辑任务状态
|
||||
|
||||
轮询任务状态，任务成功后下载视频。
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 保存[提交任务](/api-reference/video-generation/happyhorse-video-editing/create-task)响应中的 `task_id`。
|
||||
2. 每 **15 秒**轮询本接口，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 在 **24 小时**内通过 `video_url` 下载视频 -- 链接过期后将无法访问。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HappyHorse 视频编辑 API
|
||||
description: 使用 HappyHorse 模型通过文本指令和参考图片编辑视频。异步提交任务后，通过 `GET /tasks/{task_id}` 轮询获取结果。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 华北2（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getHappyHorseVideoEditingTaskStatus
|
||||
summary: 查询视频编辑任务结果
|
||||
description: 轮询任务状态，任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
description: 提交任务时返回的任务 ID。
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: 任务状态查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HappyHorseVideoEditTaskStatusResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务执行成功
|
||||
value:
|
||||
request_id: c11018a8-3f83-9591-a636-xxxxxx
|
||||
output:
|
||||
task_id: 051c7b40-b2c5-4341-aee4-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2026-04-26 14:13:14.373
|
||||
scheduled_time: 2026-04-26 14:13:14.419
|
||||
end_time: 2026-04-26 14:14:13.679
|
||||
orig_prompt: 让视频中的马头人身角色穿上图片中的条纹毛衣
|
||||
video_url: https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4
|
||||
usage:
|
||||
duration: 13.24
|
||||
input_video_duration: 6.62
|
||||
output_video_duration: 6.62
|
||||
video_count: 1
|
||||
SR: 720
|
||||
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 resolution is not valid xxxxxx
|
||||
RUNNING:
|
||||
summary: 任务执行中
|
||||
value:
|
||||
request_id: c1209113-8437-424f-a386-xxxxxx
|
||||
output:
|
||||
task_id: 051c7b40-b2c5-4341-aee4-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2026-04-26 14:13:14.373
|
||||
scheduled_time: 2026-04-26 14:13:14.419
|
||||
UNKNOWN:
|
||||
summary: 任务查询过期
|
||||
value:
|
||||
request_id: a4de7c32-7057-9f82-8581-xxxxxx
|
||||
output:
|
||||
task_id: 051c7b40-b2c5-4341-aee4-xxxxxx
|
||||
task_status: UNKNOWN
|
||||
"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:
|
||||
HappyHorseVideoEditingRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。固定值：`happyhorse-1.0-video-edit`。
|
||||
enum:
|
||||
- happyhorse-1.0-video-edit
|
||||
example: happyhorse-1.0-video-edit
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- prompt
|
||||
- media
|
||||
description: 输入的基本信息，包括待编辑的视频、参考图片和提示词。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
description: 文本提示词，用来描述对视频的编辑意图，如风格转换、局部替换等。支持任何语言输入，长度不超过5000个非中文字符或2500个中文字符，超过部分会自动截断。
|
||||
example: 让视频中的马头人身角色穿上图片中的条纹毛衣
|
||||
media:
|
||||
type: array
|
||||
description: 媒体素材列表。必须包含1个 `video` 类型元素；可选包含 0~5 个 `reference_image` 类型元素。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: 媒体素材类型：`video`（必传，待编辑的视频）或 `reference_image`（可选，参考图像）。
|
||||
enum:
|
||||
- video
|
||||
- reference_image
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
媒体素材的 URL 地址或 Base64 编码数据。
|
||||
|
||||
**视频**（`type=video`）：MP4、MOV（建议 H.264 编码）。时长：3~60 秒。分辨率：长边不超过 4096 像素，短边不小于 360 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 100 MB。帧率：8~60 fps（若输入可变帧率视频，需保证帧率变化均在此范围内）。输出视频时长上限 15 秒（超出部分从头自动截取）。
|
||||
|
||||
**图像**（`type=reference_image`）：JPEG、JPG、PNG、WEBP。分辨率：宽高不小于 300 像素。宽高比：1:2.5 ~ 2.5:1。文件大小：不超过 20 MB。支持公网 URL（HTTP/HTTPS）或 Base64 编码（格式：`data:{MIME_type};base64,{base64_data}`）。
|
||||
parameters:
|
||||
$ref: "#/components/schemas/HappyHorseVideoEditingParameters"
|
||||
HappyHorseVideoEditingParameters:
|
||||
type: object
|
||||
description: 视频编辑参数。
|
||||
properties:
|
||||
resolution:
|
||||
type: string
|
||||
description: 生成视频的分辨率档位。
|
||||
enum:
|
||||
- 720P
|
||||
- 1080P
|
||||
default: 1080P
|
||||
watermark:
|
||||
type: boolean
|
||||
description: 是否在生成的视频上添加水印标识。水印位于视频右下角，文案固定为"Happy Horse"。`true`（默认）：添加水印。`false`：不添加水印。
|
||||
default: true
|
||||
audio_setting:
|
||||
type: string
|
||||
description: 声音控制。
|
||||
enum:
|
||||
- auto
|
||||
- origin
|
||||
default: auto
|
||||
x-enumDescriptions:
|
||||
auto: 由模型自行控制。
|
||||
origin: 保留输入视频的原始声音。
|
||||
seed:
|
||||
type: integer
|
||||
description: 随机数种子。相同的种子和参数会生成相似（但不完全相同）的结果。
|
||||
minimum: 0
|
||||
maximum: 2147483647
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
description: 异步任务提交响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识，用于链路追踪和问题排查。
|
||||
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
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
|
||||
HappyHorseVideoEditTaskStatusResponse:
|
||||
type: object
|
||||
description: HappyHorse 视频编辑任务状态响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识。联系技术支持时请提供此 ID。
|
||||
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
|
||||
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）。仅在 `SUCCEEDED` 或 `FAILED` 时返回。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 原始提示词文本。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成视频的 URL（MP4，H.264 编码）。仅在 `task_status` 为 `SUCCEEDED` 时返回。**链接有效期 24 小时**，请及时下载。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息。仅在 `task_status` 为 `FAILED` 时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 资源消耗统计。仅在 `task_status` 为 `SUCCEEDED` 时返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 总的视频时长，用于计费，单位为秒。
|
||||
input_video_duration:
|
||||
type: number
|
||||
description: 输入视频的时长，单位秒。
|
||||
output_video_duration:
|
||||
type: number
|
||||
description: 输出视频的时长，单位秒。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 输出视频数量。固定为 1。
|
||||
SR:
|
||||
type: integer
|
||||
description: 输出视频的分辨率档位（如 720 表示 720P，1080 表示 1080P）。
|
||||
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: Invalid model name
|
||||
````
|
||||
+498
@@ -0,0 +1,498 @@
|
||||
> ## 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.
|
||||
|
||||
# 可灵视频生成 — 创建任务
|
||||
|
||||
> 提交可灵视频生成异步任务
|
||||
|
||||
可灵视频生成模型支持文本、图片和视频素材输入，可生成最长 15 秒、最高 1080P 分辨率的视频。
|
||||
|
||||
- **文生视频**：输入文字提示词生成视频，支持智能分镜（由模型自动规划多镜头叙事）和自定义分镜。
|
||||
- **图生视频（首帧）**：以图片作为视频首帧驱动视频生成。
|
||||
- **图生视频（首尾帧）**：同时指定首帧和尾帧，模型生成中间过渡内容。
|
||||
- **参考生视频**：以参考图像、视频素材为主体，结合提示词生成新视频，支持多主体组合。
|
||||
- **视频编辑**：基于输入视频进行编辑。
|
||||
|
||||
## 模型概览
|
||||
|
||||
| 模型名称 | 能力支持 | 输入模态 | 输出视频规格 |
|
||||
| ------------------------------------- | ---------------------------- | -------- | ------------------------------------------------------ |
|
||||
| kling/kling-v3-turbo-video-generation | 文生视频、图生视频（首帧） | 文本、图像 | 分辨率：std（720P）、pro（1080P）；宽高比：16:9、9:16、1:1；时长：3-15秒 |
|
||||
| kling/kling-v3-video-generation | 文生视频、图生视频（首帧/首尾帧） | 文本、图像 | 分辨率：std（720P）、pro（1080P）、4k；宽高比：16:9、9:16、1:1；时长：3-15秒 |
|
||||
| kling/kling-v3-omni-video-generation | 文生视频、图生视频（首帧/首尾帧）、参考生视频、视频编辑 | 文本、图像、视频 | 分辨率：std（720P）、pro（1080P）、4k；宽高比：16:9、9:16、1:1；时长：3-15秒 |
|
||||
|
||||
<Note>
|
||||
所有视频生成接口均为异步接口。提交任务后，使用返回的 `task_id` 轮询[查询接口](/api-reference/video-generation/kling-video-generation/query-result)获取结果。
|
||||
</Note>
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Python SDK">
|
||||
```python expandable
|
||||
from http import HTTPStatus
|
||||
from dashscope import VideoSynthesis
|
||||
import dashscope
|
||||
import os
|
||||
|
||||
# 若没有配置环境变量，请用千问AI平台API Key将下行替换为：api_key="sk-xxx"
|
||||
# 获取API Key：https://platform.qianwenai.com/home/api-keys
|
||||
api_key = os.getenv("DASHSCOPE_API_KEY")
|
||||
|
||||
def sample_async_call():
|
||||
# 异步提交视频生成任务
|
||||
rsp = VideoSynthesis.async_call(api_key=api_key,
|
||||
model='kling/kling-v3-turbo-video-generation',
|
||||
prompt='一只小猫在月光下奔跑',
|
||||
mode='std',
|
||||
aspect_ratio='16:9',
|
||||
duration=5,
|
||||
audio=False,
|
||||
watermark=True)
|
||||
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 = VideoSynthesis.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 = VideoSynthesis.wait(task=rsp, api_key=api_key)
|
||||
print(rsp)
|
||||
if rsp.status_code == HTTPStatus.OK:
|
||||
print(rsp.output.video_url)
|
||||
else:
|
||||
print('Failed, status_code: %s, code: %s, message: %s' %
|
||||
(rsp.status_code, rsp.code, rsp.message))
|
||||
|
||||
if __name__ == '__main__':
|
||||
sample_async_call()
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/video-generation/video-synthesis
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 可灵视频生成 API
|
||||
version: 1.0.0
|
||||
description: 可灵（Kling）视频生成异步 API，支持文生视频、图生视频（首帧/首尾帧）、参考生视频等多种模式。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/video-generation/video-synthesis:
|
||||
post:
|
||||
operationId: createKlingVideoTask
|
||||
summary: 提交可灵视频生成任务
|
||||
description: 提交可灵视频生成异步任务。任务提交后返回 `task_id`，通过查询接口轮询任务状态。
|
||||
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/KlingVideoRequest"
|
||||
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
|
||||
4XX:
|
||||
description: 请求错误
|
||||
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: bash
|
||||
label: 文生视频
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "kling/kling-v3-video-generation",
|
||||
"input": {
|
||||
"prompt": "一只小猫在月光下奔跑"
|
||||
},
|
||||
"parameters": {
|
||||
"mode": "std",
|
||||
"aspect_ratio": "16:9",
|
||||
"duration": 5,
|
||||
"audio": false,
|
||||
"watermark": true
|
||||
}
|
||||
}'
|
||||
- lang: bash
|
||||
label: 文生视频（智能分镜）
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "kling/kling-v3-video-generation",
|
||||
"input": {
|
||||
"prompt": "",
|
||||
"multi_shot": true,
|
||||
"shot_type": "customize",
|
||||
"multi_prompt": [
|
||||
{"index": 1, "prompt": "雾岭镇比地图上更小，山雾像棉絮一样堵在街口。邮局背后果然有三棵槐树，第三棵树根旁的泥土被人动过。", "duration": 5},
|
||||
{"index": 2, "prompt": "林澈蹲下挖出一个铁盒，里面除了一把生锈的钥匙，还有一盘老旧的录音带。录音机是邮局借的，按下播放键时，父亲的声音从沙沙杂音里爬出来："如果你听到这段话，说明你已经走到我走过的路上了。"", "duration": 5}
|
||||
],
|
||||
"media": [],
|
||||
"element_list": []
|
||||
},
|
||||
"parameters": {
|
||||
"mode": "pro",
|
||||
"duration": 10,
|
||||
"audio": true,
|
||||
"aspect_ratio": "9:16",
|
||||
"watermark": true
|
||||
}
|
||||
}'
|
||||
- lang: bash
|
||||
label: 图生视频（首帧）
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "kling/kling-v3-omni-video-generation",
|
||||
"input": {
|
||||
"prompt": "让图片中的人物动起来，头发被微风吹动",
|
||||
"media": [{"type": "first_frame", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"}]
|
||||
},
|
||||
"parameters": {
|
||||
"mode": "std",
|
||||
"duration": 5,
|
||||
"audio": false,
|
||||
"watermark": true
|
||||
}
|
||||
}'
|
||||
- lang: bash
|
||||
label: 图生视频（首尾帧）
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "kling/kling-v3-omni-video-generation",
|
||||
"input": {
|
||||
"prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
|
||||
"media": [
|
||||
{"type": "first_frame", "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"},
|
||||
{"type": "last_frame", "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"}
|
||||
]
|
||||
},
|
||||
"parameters": {
|
||||
"mode": "std",
|
||||
"duration": 5,
|
||||
"audio": false,
|
||||
"watermark": true
|
||||
}
|
||||
}'
|
||||
- lang: bash
|
||||
label: 参考生视频（视频+图像）
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
|
||||
-H 'X-DashScope-Async: enable' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "kling/kling-v3-omni-video-generation",
|
||||
"input": {
|
||||
"prompt": "<<<element_1>>>背景，<<<image_2>>>和<<<image_1>>>握手交谈，<<<video_1>>>人物穿着黑色风衣的侦探站在公寓楼顶，手持望远镜观察街道",
|
||||
"multi_shot": false,
|
||||
"shot_type": "intelligence",
|
||||
"multi_prompt": [],
|
||||
"media": [
|
||||
{"url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/lip_sync_5s.mp4", "type": "base", "keep_original_sound": "yes"},
|
||||
{"type": "refer", "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/zem_test/yangmi01.jpg"},
|
||||
{"type": "refer", "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/human_2.JPG"}
|
||||
],
|
||||
"element_list": [{"element_id": 171}]
|
||||
},
|
||||
"parameters": {
|
||||
"mode": "pro",
|
||||
"duration": 10,
|
||||
"audio": false,
|
||||
"aspect_ratio": "1:1",
|
||||
"watermark": true
|
||||
}
|
||||
}'
|
||||
components:
|
||||
schemas:
|
||||
KlingVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- kling/kling-v3-turbo-video-generation
|
||||
- kling/kling-v3-video-generation
|
||||
- kling/kling-v3-omni-video-generation
|
||||
description: 模型 ID。`kling/kling-v3-turbo-video-generation` 支持文生视频和图生视频（首帧）；`kling/kling-v3-video-generation` 支持文生视频、图生视频（首帧/首尾帧）和多镜头叙事；`kling/kling-v3-omni-video-generation` 支持所有模式，包括参考生视频和视频编辑。
|
||||
input:
|
||||
type: object
|
||||
required: []
|
||||
description: 任务输入参数。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
maxLength: 2500
|
||||
description: 视频描述提示词，最多 2500 个字符。使用 omni 模型的参考生视频模式时，可通过 `<<<element_1>>>`、`<<<image_1>>>`、`<<<video_1>>>` 语法引用 `element_list` 和 `media` 中的素材。`shot_type=intelligence` 时必填；`shot_type=customize` 时不使用本字段。
|
||||
negative_prompt:
|
||||
type: string
|
||||
maxLength: 2500
|
||||
description: 负向提示词，用于描述不希望在结果中出现的内容，不超过 2500 个字符。`kling/kling-v3-turbo-video-generation` 不支持该字段（负向描述可写入 `prompt`）；支持模型：`kling/kling-v3-video-generation`、`kling/kling-v3-omni-video-generation`。
|
||||
media:
|
||||
type: array
|
||||
description: 输入媒体列表。kling-v3-turbo-video-generation 仅支持 `first_frame`；kling-v3-video-generation 支持 `first_frame`、`last_frame`；kling-v3-omni-video-generation 额外支持 `refer`、`base`、`feature`。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- first_frame
|
||||
- last_frame
|
||||
- refer
|
||||
- base
|
||||
- feature
|
||||
description: 媒体类型。`first_frame`：图生视频首帧；`last_frame`：图生视频尾帧；`refer`：参考图像；`base`：参考视频（omni 模型）；`feature`：特征参考视频（omni 模型）。
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 媒体文件的公网 URL。
|
||||
keep_original_sound:
|
||||
type: string
|
||||
enum:
|
||||
- yes
|
||||
- no
|
||||
default: no
|
||||
description: 是否保留原视频音频，仅 omni 模型且 `type` 为 `base` 或 `feature` 时有效。`yes`：保留；`no`（默认）：不保留。
|
||||
multi_shot:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否启用多镜头模式。启用时须指定 `shot_type`。
|
||||
shot_type:
|
||||
type: string
|
||||
enum:
|
||||
- intelligence
|
||||
- customize
|
||||
description: 多镜头分镜策略，`multi_shot=true` 时必填。`intelligence`：由模型自动规划分镜；`customize`：按 `multi_prompt` 自定义分镜。
|
||||
multi_prompt:
|
||||
type: array
|
||||
description: 自定义多镜头提示词列表，`shot_type=customize` 时必填。最多 6 个镜头，index 从 1 开始。
|
||||
maxItems: 6
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- index
|
||||
- prompt
|
||||
- duration
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 6
|
||||
description: 镜头编号，从 1 开始。
|
||||
prompt:
|
||||
type: string
|
||||
maxLength: 512
|
||||
description: 该镜头的描述提示词，最多 512 个字符。
|
||||
duration:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: 该镜头时长（秒），须 ≥ 1 且 ≤ `parameters.duration`。
|
||||
element_list:
|
||||
type: array
|
||||
description: 元素列表，用于参考生视频模式。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- element_id
|
||||
properties:
|
||||
element_id:
|
||||
type: integer
|
||||
description: 元素 ID。
|
||||
parameters:
|
||||
type: object
|
||||
description: 生成参数。
|
||||
properties:
|
||||
mode:
|
||||
type: string
|
||||
enum:
|
||||
- pro
|
||||
- std
|
||||
- 4k
|
||||
default: pro
|
||||
description: 生成模式。`pro`（默认）：专业模式，输出 1080P；`std`：标准模式，输出 720P；`4k`：4K模式，输出视频分辨率为4K。
|
||||
aspect_ratio:
|
||||
type: string
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
default: 16:9
|
||||
description: 视频宽高比。文生视频和参考生视频（refer/feature）模式必填；图生视频（首帧/首尾帧）模式自动继承输入图像比例。
|
||||
duration:
|
||||
type: integer
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
description: 视频时长（秒），默认 5 秒，范围 3–15。使用 omni 模型且传入视频时：`type=feature`：取值为[3, 10]之间的整数，默认值为5。`type=base`：输出视频时长与传入视频时长相同，此时当前参数无效。按输入视频时长四舍五入取整计量计费。
|
||||
audio:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否自动生成配音，默认 false。注意：当传入视频（`type` 为 `base` 或 `feature`）时，`audio` 只能设置为 `false`。
|
||||
watermark:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否同时生成含水印的视频。水印位于视频右下角，文案固定为"可灵AI"。设置为 true 时，响应中将额外返回 `watermark_video_url` 字段。默认 false。
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID，用于轮询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，固定为 `PENDING`。
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符。
|
||||
KlingTaskQueryResponse:
|
||||
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
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
description: 任务状态。`PENDING`：等待中；`RUNNING`：生成中；`SUCCEEDED`：成功；`FAILED`：失败；`CANCELED`：任务已取消；`UNKNOWN`：task_id 查询有效期（24 小时）已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成的视频 URL，任务成功后返回，有效期 **30 天**。
|
||||
watermark_video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 带水印视频 URL，任务成功且 `watermark=true` 时返回，有效期 **30 天**。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 实际使用的提示词（经模型改写后）。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码，任务失败时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息，任务失败时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 用量统计，任务成功后返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 视频时长（秒）。
|
||||
size:
|
||||
type: string
|
||||
description: 视频分辨率，格式如 `1280*720`。
|
||||
fps:
|
||||
type: integer
|
||||
description: 帧率（FPS）。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 生成的视频数量。
|
||||
audio:
|
||||
type: boolean
|
||||
description: 是否包含音频。
|
||||
SR:
|
||||
type: string
|
||||
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)。
|
||||
````
|
||||
+353
@@ -0,0 +1,353 @@
|
||||
> ## 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/video-generation/kling-video-generation/create-task)接口提交任务，保存返回的 `task_id`。
|
||||
2. 每 **15 秒**轮询一次，直到 `task_status` 变为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 任务成功后，从 `video_url` 下载视频。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **视频 URL 有效期**：`video_url` 和 `watermark_video_url` 在 **30 天**后过期，请及时下载。
|
||||
- **task\_id 查询有效期**：`task_id` 仅在提交后 **24 小时**内有效。超出后查询返回 `task_status: UNKNOWN`。
|
||||
- **查询频率限制**：接口 RPS 限制为 20，建议以 15 秒为间隔轮询。
|
||||
- **状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 可灵视频生成 API
|
||||
version: 1.0.0
|
||||
description: 可灵（Kling）视频生成异步 API，支持文生视频、图生视频（首帧/首尾帧）、参考生视频等多种模式。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
operationId: getKlingVideoTask
|
||||
summary: 查询可灵视频生成任务状态
|
||||
description: 查询视频生成任务状态，任务成功后返回视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: 任务 ID，由提交任务接口返回。
|
||||
responses:
|
||||
"200":
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/KlingTaskQueryResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务成功
|
||||
value:
|
||||
request_id: 340f0d7d-bf7e-4c8f-9c03-xxxxxx
|
||||
output:
|
||||
task_id: 24f5c51e-d67b-44dc-9acb-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2026-03-27 21:30:32.575
|
||||
scheduled_time: 2026-03-27 21:30:32.603
|
||||
end_time: 2026-03-27 21:31:09.177
|
||||
video_url: https://v4-fdl.kechuangai.com/ksc2/xxx.mp4?xxxx
|
||||
watermark_video_url: https://v2-fdl.kechuangai.com/ksc2/xxx.mp4?xxxx
|
||||
usage:
|
||||
duration: 5
|
||||
size: 1280*720
|
||||
fps: 24
|
||||
video_count: 1
|
||||
audio: false
|
||||
SR: "720"
|
||||
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 parameter is invalid xxxxxx
|
||||
RUNNING:
|
||||
summary: 任务处理中
|
||||
value:
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: RUNNING
|
||||
CANCELED:
|
||||
summary: 任务已取消
|
||||
value:
|
||||
request_id: b3c4d5e6-f7a8-9b0c-1d2e-xxxxxx
|
||||
output:
|
||||
task_id: c4d5e6f7-a8b9-0c1d-2e3f-xxxxxx
|
||||
task_status: CANCELED
|
||||
UNKNOWN:
|
||||
summary: task_id 已超过24小时查询期
|
||||
value:
|
||||
request_id: a4de7c32-7057-9f82-8581-xxxxxx
|
||||
output:
|
||||
task_id: 502a00b1-19d9-4839-a82f-xxxxxx
|
||||
task_status: UNKNOWN
|
||||
x-codeSamples:
|
||||
- lang: bash
|
||||
label: 查询任务状态
|
||||
source: |-
|
||||
curl -X GET https://maas.qianwenaiapi.com/api/v1/tasks/{task_id} \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
||||
components:
|
||||
schemas:
|
||||
KlingVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- kling/kling-v3-turbo-video-generation
|
||||
- kling/kling-v3-video-generation
|
||||
- kling/kling-v3-omni-video-generation
|
||||
description: 模型 ID。`kling/kling-v3-turbo-video-generation` 支持文生视频和图生视频（首帧）；`kling/kling-v3-video-generation` 支持文生视频、图生视频（首帧/首尾帧）和多镜头叙事；`kling/kling-v3-omni-video-generation` 支持所有模式，包括参考生视频和视频编辑。
|
||||
input:
|
||||
type: object
|
||||
required: []
|
||||
description: 任务输入参数。
|
||||
properties:
|
||||
prompt:
|
||||
type: string
|
||||
maxLength: 2500
|
||||
description: 视频描述提示词，最多 2500 个字符。使用 omni 模型的参考生视频模式时，可通过 `<<<element_1>>>`、`<<<image_1>>>`、`<<<video_1>>>` 语法引用 `element_list` 和 `media` 中的素材。`shot_type=intelligence` 时必填；`shot_type=customize` 时不使用本字段。
|
||||
negative_prompt:
|
||||
type: string
|
||||
maxLength: 2500
|
||||
description: 负向提示词，用于描述不希望在结果中出现的内容，不超过 2500 个字符。`kling/kling-v3-turbo-video-generation` 不支持该字段（负向描述可写入 `prompt`）；支持模型：`kling/kling-v3-video-generation`、`kling/kling-v3-omni-video-generation`。
|
||||
media:
|
||||
type: array
|
||||
description: 输入媒体列表。kling-v3-turbo-video-generation 仅支持 `first_frame`；kling-v3-video-generation 支持 `first_frame`、`last_frame`；kling-v3-omni-video-generation 额外支持 `refer`、`base`、`feature`。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- url
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- first_frame
|
||||
- last_frame
|
||||
- refer
|
||||
- base
|
||||
- feature
|
||||
description: 媒体类型。`first_frame`：图生视频首帧；`last_frame`：图生视频尾帧；`refer`：参考图像；`base`：参考视频（omni 模型）；`feature`：特征参考视频（omni 模型）。
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 媒体文件的公网 URL。
|
||||
keep_original_sound:
|
||||
type: string
|
||||
enum:
|
||||
- yes
|
||||
- no
|
||||
default: no
|
||||
description: 是否保留原视频音频，仅 omni 模型且 `type` 为 `base` 或 `feature` 时有效。`yes`：保留；`no`（默认）：不保留。
|
||||
multi_shot:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否启用多镜头模式。启用时须指定 `shot_type`。
|
||||
shot_type:
|
||||
type: string
|
||||
enum:
|
||||
- intelligence
|
||||
- customize
|
||||
description: 多镜头分镜策略，`multi_shot=true` 时必填。`intelligence`：由模型自动规划分镜；`customize`：按 `multi_prompt` 自定义分镜。
|
||||
multi_prompt:
|
||||
type: array
|
||||
description: 自定义多镜头提示词列表，`shot_type=customize` 时必填。最多 6 个镜头，index 从 1 开始。
|
||||
maxItems: 6
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- index
|
||||
- prompt
|
||||
- duration
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 6
|
||||
description: 镜头编号，从 1 开始。
|
||||
prompt:
|
||||
type: string
|
||||
maxLength: 512
|
||||
description: 该镜头的描述提示词，最多 512 个字符。
|
||||
duration:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: 该镜头时长（秒），须 ≥ 1 且 ≤ `parameters.duration`。
|
||||
element_list:
|
||||
type: array
|
||||
description: 元素列表，用于参考生视频模式。
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- element_id
|
||||
properties:
|
||||
element_id:
|
||||
type: integer
|
||||
description: 元素 ID。
|
||||
parameters:
|
||||
type: object
|
||||
description: 生成参数。
|
||||
properties:
|
||||
mode:
|
||||
type: string
|
||||
enum:
|
||||
- pro
|
||||
- std
|
||||
- 4k
|
||||
default: pro
|
||||
description: 生成模式。`pro`（默认）：专业模式，输出 1080P；`std`：标准模式，输出 720P；`4k`：4K模式，输出视频分辨率为4K。
|
||||
aspect_ratio:
|
||||
type: string
|
||||
enum:
|
||||
- 16:9
|
||||
- 9:16
|
||||
- 1:1
|
||||
default: 16:9
|
||||
description: 视频宽高比。文生视频和参考生视频（refer/feature）模式必填；图生视频（首帧/首尾帧）模式自动继承输入图像比例。
|
||||
duration:
|
||||
type: integer
|
||||
minimum: 3
|
||||
maximum: 15
|
||||
default: 5
|
||||
description: 视频时长（秒），默认 5 秒，范围 3–15。使用 omni 模型且传入视频时：`type=feature`：取值为[3, 10]之间的整数，默认值为5。`type=base`：输出视频时长与传入视频时长相同，此时当前参数无效。按输入视频时长四舍五入取整计量计费。
|
||||
audio:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否自动生成配音，默认 false。注意：当传入视频（`type` 为 `base` 或 `feature`）时，`audio` 只能设置为 `false`。
|
||||
watermark:
|
||||
type: boolean
|
||||
default: false
|
||||
description: 是否同时生成含水印的视频。水印位于视频右下角，文案固定为"可灵AI"。设置为 true 时，响应中将额外返回 `watermark_video_url` 字段。默认 false。
|
||||
AsyncTaskSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 任务 ID，用于轮询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，固定为 `PENDING`。
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符。
|
||||
KlingTaskQueryResponse:
|
||||
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
|
||||
- CANCELED
|
||||
- UNKNOWN
|
||||
description: 任务状态。`PENDING`：等待中；`RUNNING`：生成中；`SUCCEEDED`：成功；`FAILED`：失败；`CANCELED`：任务已取消；`UNKNOWN`：task_id 查询有效期（24 小时）已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间。
|
||||
video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 生成的视频 URL，任务成功后返回，有效期 **30 天**。
|
||||
watermark_video_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: 带水印视频 URL，任务成功且 `watermark=true` 时返回，有效期 **30 天**。
|
||||
orig_prompt:
|
||||
type: string
|
||||
description: 实际使用的提示词（经模型改写后）。
|
||||
code:
|
||||
type: string
|
||||
description: 错误码，任务失败时返回。
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息，任务失败时返回。
|
||||
usage:
|
||||
type: object
|
||||
description: 用量统计，任务成功后返回。
|
||||
properties:
|
||||
duration:
|
||||
type: number
|
||||
description: 视频时长（秒）。
|
||||
size:
|
||||
type: string
|
||||
description: 视频分辨率，格式如 `1280*720`。
|
||||
fps:
|
||||
type: integer
|
||||
description: 帧率（FPS）。
|
||||
video_count:
|
||||
type: integer
|
||||
description: 生成的视频数量。
|
||||
audio:
|
||||
type: boolean
|
||||
description: 是否包含音频。
|
||||
SR:
|
||||
type: string
|
||||
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)。
|
||||
````
|
||||
+309
@@ -0,0 +1,309 @@
|
||||
> ## 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.
|
||||
|
||||
# 灵动人像 LivePortrait — 创建任务
|
||||
|
||||
> 提交灵动人像 LivePortrait 播报视频生成异步任务
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
## 模型概览
|
||||
|
||||
**模型简介**
|
||||
|
||||
| 模型名 | 模型简介 |
|
||||
| ------------ | ---------------------------------------------------------------- |
|
||||
| liveportrait | 灵动人像 LivePortrait，基于人物肖像图片和语音音频，生成口型与音频同步的播报视频。适用于数字人播报、虚拟主播等场景。 |
|
||||
|
||||
## 前置条件
|
||||
|
||||
在调用本接口前，建议先调用 [LivePortrait 图像检测](/api-reference/video-generation/liveportrait-video/liveportrait-detect) 接口对人物图片进行检测，确认图片符合模型输入规范。
|
||||
|
||||
## 头部运动模板
|
||||
|
||||
| 模板名 | 说明 |
|
||||
| ------ | -------------------- |
|
||||
| normal | 默认，中等幅度头部运动，适用于多种场景。 |
|
||||
| calm | 平静，小幅度头部运动，推荐用于播报场景。 |
|
||||
| active | 活跃，大幅度头部运动，推荐用于演唱场景。 |
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. 调用 [LivePortrait 图像检测](/api-reference/video-generation/liveportrait-video/liveportrait-detect) 接口，传入人物图片，确认通过检测。
|
||||
2. 调用本接口，将图片 URL、音频 URL 及可选参数一并提交，获取 `task_id`。
|
||||
3. 调用[查询视频生成结果](/api-reference/video-generation/liveportrait-video/query-result)接口，使用 `task_id` 轮询任务状态，直到获取生成的视频 URL。
|
||||
|
||||
## 错误码
|
||||
|
||||
大模型服务通用状态码请查阅[错误信息](/api-reference/preparation/error-messages)。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/video-synthesis/
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 灵动人像 LivePortrait 视频生成 API
|
||||
version: 1.0.0
|
||||
description: 基于人物肖像图片和语音音频，生成口型与音频同步的播报视频。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/video-synthesis/:
|
||||
post:
|
||||
summary: 提交视频生成任务
|
||||
operationId: createLivePortraitVideoTask
|
||||
description: 提交灵动人像 LivePortrait 视频生成异步任务。需要先调用 [LivePortrait 图像检测](/api-reference/video-generation/liveportrait-detect) 接口确认输入图片符合规范。
|
||||
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/LivePortraitVideoRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 任务提交成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/LivePortraitVideoSubmitResponse"
|
||||
example:
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-0c46b17950d1
|
||||
task_status: PENDING
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-11c33ab46e51
|
||||
"400":
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: InvalidParameter
|
||||
message: The request parameter is invalid.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
"401":
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: InvalidApiKey
|
||||
message: No API-key provided.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
"429":
|
||||
description: 请求频率超限
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
example:
|
||||
code: Throttling
|
||||
message: Requests throttling triggered.
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
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": "liveportrait",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png",
|
||||
"audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251226/fwnqyq/liveportrait_boy.mp3"
|
||||
},
|
||||
"parameters": {
|
||||
"template_id": "normal",
|
||||
"eye_move_freq": 0.5,
|
||||
"video_fps": 30,
|
||||
"mouth_move_strength": 1,
|
||||
"paste_back": true,
|
||||
"head_move_strength": 0.7
|
||||
}
|
||||
}'
|
||||
components:
|
||||
schemas:
|
||||
LivePortraitVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- liveportrait
|
||||
description: 模型名称，固定为 `liveportrait`。
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- audio_url
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: |-
|
||||
人物肖像图片公网 URL。建议先通过 [LivePortrait 图像检测](/api-reference/video-generation/liveportrait-detect) 接口验证图片是否符合规范。
|
||||
|
||||
**图片要求**：
|
||||
- **格式**：jpeg、jpg、png、bmp、webp
|
||||
- **文件大小**：小于 10 MB
|
||||
- **宽高比**：不超过 2
|
||||
- **最大边长**：不超过 4096 像素
|
||||
- **URL**：HTTP/HTTPS 公网可访问地址
|
||||
audio_url:
|
||||
type: string
|
||||
description: |-
|
||||
驱动视频的语音音频公网 URL。
|
||||
|
||||
**音频要求**：
|
||||
- **格式**：wav、mp3
|
||||
- **文件大小**：小于 15 MB
|
||||
- **时长**：1 秒到 3 分钟之间
|
||||
- **内容**：必须包含清晰的人声
|
||||
- **URL**：HTTP/HTTPS 公网可访问地址
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
template_id:
|
||||
type: string
|
||||
enum:
|
||||
- normal
|
||||
- calm
|
||||
- active
|
||||
default: normal
|
||||
description: 头部运动模板，控制头部运动风格。`normal`：默认，中等幅度头部运动，适用于多种场景；`calm`：平静，小幅度头部运动，推荐用于播报场景；`active`：活跃，大幅度头部运动，推荐用于演唱场景。默认为 `normal`。
|
||||
eye_move_freq:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
default: 0.5
|
||||
description: 眨眼频率，取值范围 0～1。值越大眨眼次数越多。默认为 `0.5`。
|
||||
video_fps:
|
||||
type: integer
|
||||
minimum: 15
|
||||
maximum: 30
|
||||
default: 24
|
||||
description: 生成视频的帧率，取值范围 15～30（整数）。默认为 `24`。
|
||||
mouth_move_strength:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1.5
|
||||
default: 1
|
||||
description: 嘴部运动幅度，取值范围 0～1.5。`0` 表示嘴部不动。默认为 `1`。
|
||||
paste_back:
|
||||
type: boolean
|
||||
default: true
|
||||
description: 是否将面部粘贴回原始图像身体上。`true`：输出完整人物图像；`false`：仅输出面部区域。默认为 `true`。
|
||||
head_move_strength:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
default: 0.7
|
||||
description: 头部运动幅度，取值范围 0～1。默认为 `0.7`。
|
||||
LivePortraitVideoSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 异步任务 ID，用于查询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，值为 `PENDING`。
|
||||
LivePortraitVideoQueryResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
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`：任务不存在或已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（成功或失败时返回）。
|
||||
results:
|
||||
type: object
|
||||
description: 任务成功时返回。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: 生成视频的 URL，有效期 24 小时，请及时下载保存。
|
||||
code:
|
||||
type: string
|
||||
description: 任务失败时的错误码。
|
||||
message:
|
||||
type: string
|
||||
description: 任务失败时的错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 任务成功时返回的用量信息。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
description: 生成视频的时长，单位为秒。
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的规格，值为 `standard`。
|
||||
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)。
|
||||
````
|
||||
+227
@@ -0,0 +1,227 @@
|
||||
> ## 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.
|
||||
|
||||
# LivePortrait 图像检测
|
||||
|
||||
> 检测人物肖像图片是否符合 LivePortrait 视频生成模型的输入规范
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
LivePortrait-detect 模型用于检测输入的图片是否满足 [LivePortrait 视频生成](/api-reference/video-generation/liveportrait-video/create-task)所需的人物肖像图片规范，通常在生成数字人播报视频前作为图像筛选步骤使用。
|
||||
|
||||
## 模型概览
|
||||
|
||||
| 模型名 | 模型简介 |
|
||||
| ------------------- | --------------------------------------------------- |
|
||||
| liveportrait-detect | 特定的图像检测模型，用于检测输入的图片是否满足 LivePortrait 模型所需的人物肖像图片规范。 |
|
||||
|
||||
## 输入限制
|
||||
|
||||
- 图像格式：JPEG、JPG、PNG、BMP、WEBP
|
||||
- 文件大小：小于 10 MB
|
||||
- 宽高比：不超过 2
|
||||
- 最大边长：不超过 4096 像素
|
||||
- 仅支持 HTTP 或 HTTPS 公网链接，不支持本地路径
|
||||
|
||||
<Note>
|
||||
如需将本地图像上传获取临时公网 URL，请参考[上传文件获取临时 URL](/api-reference/platform-api/file/upload-file)。
|
||||
</Note>
|
||||
|
||||
## 检测不通过原因
|
||||
|
||||
| output.message | 原因说明 |
|
||||
| ----------------------- | ----------------------- |
|
||||
| No human face detected. | 未检测到人脸（包括人脸过小、侧脸、遮挡等情况） |
|
||||
|
||||
## 状态码说明
|
||||
|
||||
通用错误码请参阅[错误信息](/api-reference/preparation/error-messages)。
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml post /services/aigc/image2video/face-detect
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: LivePortrait 图像检测 API
|
||||
description: LivePortrait-detect 模型，用于确认输入的人物肖像图片是否符合 LivePortrait 模型的输入规范。
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 中国内地（北京）
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/services/aigc/image2video/face-detect:
|
||||
post:
|
||||
operationId: detectLivePortraitImage
|
||||
summary: 检测人物肖像图像
|
||||
description: 检测输入的图片是否满足 LivePortrait 视频生成模型所需的人物肖像图片规范。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/LivePortraitDetectRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: 检测成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/LivePortraitDetectResponse"
|
||||
examples:
|
||||
pass:
|
||||
summary: 检测通过
|
||||
value:
|
||||
output:
|
||||
pass: true
|
||||
message: ""
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: a92e2ffd-9263-44ba-92c5-xxxxxx
|
||||
fail:
|
||||
summary: 检测不通过
|
||||
value:
|
||||
output:
|
||||
pass: false
|
||||
message: No human face detected.
|
||||
usage:
|
||||
image_count: 1
|
||||
request_id: c56f62df-724e-9c19-96bd-xxxxxx
|
||||
error:
|
||||
summary: 请求错误
|
||||
value:
|
||||
code: InvalidParameter.UnsupportedFileFormat
|
||||
message: Input files format not supported.
|
||||
request_id: 788b30fe-05f6-999f-a0b1-xxxxxx
|
||||
"400":
|
||||
description: 请求参数无效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
examples:
|
||||
UnsupportedFileFormat:
|
||||
summary: 文件格式不支持
|
||||
value:
|
||||
code: InvalidParameter.UnsupportedFileFormat
|
||||
message: Input files format not supported.
|
||||
request_id: 788b30fe-05f6-999f-a0b1-xxxxxx
|
||||
"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
|
||||
"500":
|
||||
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/face-detect' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "liveportrait-detect",
|
||||
"input": {
|
||||
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png"
|
||||
}
|
||||
}'
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: 千问AI平台 API Key。详见[获取 API Key](/api-reference/preparation/api-key)。
|
||||
schemas:
|
||||
LivePortraitDetectRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称，固定为 `liveportrait-detect`。
|
||||
enum:
|
||||
- liveportrait-detect
|
||||
example: liveportrait-detect
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
description: 输入图像参数。
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
待检测图像的公网可访问 URL。
|
||||
|
||||
**图像要求**：
|
||||
- **格式**：JPEG、JPG、PNG、BMP、WEBP
|
||||
- **文件大小**：小于 10 MB
|
||||
- **宽高比**：不超过 2
|
||||
- **最大边长**：不超过 4096 像素
|
||||
- **URL**：必须为 HTTP 或 HTTPS 协议的公网可访问地址，不支持本地路径
|
||||
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png
|
||||
LivePortraitDetectResponse:
|
||||
type: object
|
||||
description: 人物肖像图像检测响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的系统唯一码，用于链路追踪和问题排查。
|
||||
example: a92e2ffd-9263-44ba-92c5-xxxxxx
|
||||
output:
|
||||
type: object
|
||||
description: 检测结果。
|
||||
properties:
|
||||
pass:
|
||||
type: boolean
|
||||
description: 图像是否通过检测。`true` 表示图像符合 LivePortrait 模型的人物肖像规范，`false` 表示不符合。
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
description: 检测结果信息。检测通过时为空字符串；检测不通过时返回原因，例如 `No human face detected.`（未检测到人脸，包括人脸过小、侧脸、遮挡等情况）。
|
||||
example: ""
|
||||
usage:
|
||||
type: object
|
||||
description: 使用量统计。
|
||||
properties:
|
||||
image_count:
|
||||
type: integer
|
||||
description: 本次检测的图像数量，固定为 `1`。用于计费。
|
||||
example: 1
|
||||
DashScopeErrorResponse:
|
||||
type: object
|
||||
description: DashScope API 错误响应。
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 请求唯一标识符。
|
||||
example: 788b30fe-05f6-999f-a0b1-xxxxxx
|
||||
code:
|
||||
type: string
|
||||
description: 错误码。
|
||||
example: InvalidParameter.UnsupportedFileFormat
|
||||
message:
|
||||
type: string
|
||||
description: 错误描述信息。
|
||||
example: Input files format not supported.
|
||||
````
|
||||
+280
@@ -0,0 +1,280 @@
|
||||
> ## 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.
|
||||
|
||||
# 灵动人像 LivePortrait — 查询视频生成结果
|
||||
|
||||
> 查询灵动人像 LivePortrait 视频生成任务状态，获取生成的视频
|
||||
|
||||
<Note>
|
||||
请先[获取 API Key](/api-reference/preparation/api-key) 并[配置为环境变量](/api-reference/preparation/export-api-key-env)。
|
||||
</Note>
|
||||
|
||||
## 轮询策略
|
||||
|
||||
1. 调用[提交视频生成任务](/api-reference/video-generation/liveportrait-video/create-task)接口获取 `task_id`。
|
||||
2. 每 **15 秒**轮询一次，直到 `task_status` 为 `SUCCEEDED` 或 `FAILED`。
|
||||
3. 任务成功后，从 `output.results.video_url` 获取视频。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **URL 有效期**：视频 URL 在 **24 小时**后过期，请及时下载保存。
|
||||
- **状态流转**：`PENDING` → `RUNNING` → `SUCCEEDED` 或 `FAILED`。`UNKNOWN` 表示任务不存在或已过期。
|
||||
|
||||
**任务状态说明**：
|
||||
|
||||
| task\_status | 说明 |
|
||||
| ------------ | ------ |
|
||||
| PENDING | 任务排队中 |
|
||||
| RUNNING | 任务处理中 |
|
||||
| SUCCEEDED | 任务成功完成 |
|
||||
| FAILED | 任务失败 |
|
||||
| UNKNOWN | 任务状态未知 |
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml get /tasks/{task_id}
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: 灵动人像 LivePortrait 视频生成 API
|
||||
version: 1.0.0
|
||||
description: 基于人物肖像图片和语音音频，生成口型与音频同步的播报视频。
|
||||
servers:
|
||||
- url: https://maas.qianwenaiapi.com/api/v1
|
||||
description: 千问AI平台
|
||||
security:
|
||||
- BearerAuth: []
|
||||
paths:
|
||||
/tasks/{task_id}:
|
||||
get:
|
||||
summary: 查询视频生成结果
|
||||
operationId: getLivePortraitVideoTask
|
||||
description: 查询灵动人像 LivePortrait 视频生成任务状态，并在任务成功后获取视频 URL。
|
||||
parameters:
|
||||
- name: task_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: 提交任务时返回的 `task_id`。
|
||||
responses:
|
||||
"200":
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/LivePortraitVideoQueryResponse"
|
||||
examples:
|
||||
SUCCEEDED:
|
||||
summary: 任务成功
|
||||
value:
|
||||
request_id: b64e9c68-3923-462d-b25a-xxxxxx
|
||||
output:
|
||||
task_id: a1c69ca5-810b-49ae-8b20-xxxxxx
|
||||
task_status: SUCCEEDED
|
||||
submit_time: 2025-12-26 11:33:03.146
|
||||
scheduled_time: 2025-12-26 11:33:13.312
|
||||
end_time: 2025-12-26 11:33:22.455
|
||||
results:
|
||||
video_url: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx
|
||||
usage:
|
||||
video_duration: 2.79
|
||||
video_ratio: standard
|
||||
FAILED:
|
||||
summary: 任务失败
|
||||
value:
|
||||
request_id: 7574ee8f-38a3-4b1e-9280-xxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: FAILED
|
||||
code: InvalidURL
|
||||
message: Required URL is missing or invalid, please check the request URL.
|
||||
RUNNING:
|
||||
summary: 任务处理中
|
||||
value:
|
||||
request_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
output:
|
||||
task_id: a8532587-fa8c-4ef8-82be-xxxxxx
|
||||
task_status: RUNNING
|
||||
submit_time: 2025-12-26 11:33:03.146
|
||||
scheduled_time: 2025-12-26 11:33:13.312
|
||||
"401":
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DashScopeErrorResponse"
|
||||
x-codeSamples:
|
||||
- lang: curl
|
||||
label: cURL
|
||||
source: |-
|
||||
curl --location 'https://maas.qianwenaiapi.com/api/v1/tasks/{task_id}' \
|
||||
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
||||
components:
|
||||
schemas:
|
||||
LivePortraitVideoRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- input
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
enum:
|
||||
- liveportrait
|
||||
description: 模型名称，固定为 `liveportrait`。
|
||||
input:
|
||||
type: object
|
||||
required:
|
||||
- image_url
|
||||
- audio_url
|
||||
properties:
|
||||
image_url:
|
||||
type: string
|
||||
description: |-
|
||||
人物肖像图片公网 URL。建议先通过 [LivePortrait 图像检测](/api-reference/video-generation/liveportrait-detect) 接口验证图片是否符合规范。
|
||||
|
||||
**图片要求**：
|
||||
- **格式**：jpeg、jpg、png、bmp、webp
|
||||
- **文件大小**：小于 10 MB
|
||||
- **宽高比**：不超过 2
|
||||
- **最大边长**：不超过 4096 像素
|
||||
- **URL**：HTTP/HTTPS 公网可访问地址
|
||||
audio_url:
|
||||
type: string
|
||||
description: |-
|
||||
驱动视频的语音音频公网 URL。
|
||||
|
||||
**音频要求**：
|
||||
- **格式**：wav、mp3
|
||||
- **文件大小**：小于 15 MB
|
||||
- **时长**：1 秒到 3 分钟之间
|
||||
- **内容**：必须包含清晰的人声
|
||||
- **URL**：HTTP/HTTPS 公网可访问地址
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
template_id:
|
||||
type: string
|
||||
enum:
|
||||
- normal
|
||||
- calm
|
||||
- active
|
||||
default: normal
|
||||
description: 头部运动模板，控制头部运动风格。`normal`：默认，中等幅度头部运动，适用于多种场景；`calm`：平静，小幅度头部运动，推荐用于播报场景；`active`：活跃，大幅度头部运动，推荐用于演唱场景。默认为 `normal`。
|
||||
eye_move_freq:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
default: 0.5
|
||||
description: 眨眼频率，取值范围 0～1。值越大眨眼次数越多。默认为 `0.5`。
|
||||
video_fps:
|
||||
type: integer
|
||||
minimum: 15
|
||||
maximum: 30
|
||||
default: 24
|
||||
description: 生成视频的帧率，取值范围 15～30（整数）。默认为 `24`。
|
||||
mouth_move_strength:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1.5
|
||||
default: 1
|
||||
description: 嘴部运动幅度，取值范围 0～1.5。`0` 表示嘴部不动。默认为 `1`。
|
||||
paste_back:
|
||||
type: boolean
|
||||
default: true
|
||||
description: 是否将面部粘贴回原始图像身体上。`true`：输出完整人物图像；`false`：仅输出面部区域。默认为 `true`。
|
||||
head_move_strength:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
default: 0.7
|
||||
description: 头部运动幅度，取值范围 0～1。默认为 `0.7`。
|
||||
LivePortraitVideoSubmitResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
output:
|
||||
type: object
|
||||
properties:
|
||||
task_id:
|
||||
type: string
|
||||
description: 异步任务 ID，用于查询任务状态。
|
||||
task_status:
|
||||
type: string
|
||||
enum:
|
||||
- PENDING
|
||||
description: 任务初始状态，值为 `PENDING`。
|
||||
LivePortraitVideoQueryResponse:
|
||||
type: object
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
description: 本次请求的唯一 ID。
|
||||
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`：任务不存在或已过期。
|
||||
submit_time:
|
||||
type: string
|
||||
description: 任务提交时间。
|
||||
scheduled_time:
|
||||
type: string
|
||||
description: 任务开始调度时间。
|
||||
end_time:
|
||||
type: string
|
||||
description: 任务结束时间（成功或失败时返回）。
|
||||
results:
|
||||
type: object
|
||||
description: 任务成功时返回。
|
||||
properties:
|
||||
video_url:
|
||||
type: string
|
||||
description: 生成视频的 URL，有效期 24 小时，请及时下载保存。
|
||||
code:
|
||||
type: string
|
||||
description: 任务失败时的错误码。
|
||||
message:
|
||||
type: string
|
||||
description: 任务失败时的错误信息。
|
||||
usage:
|
||||
type: object
|
||||
description: 任务成功时返回的用量信息。
|
||||
properties:
|
||||
video_duration:
|
||||
type: number
|
||||
description: 生成视频的时长，单位为秒。
|
||||
video_ratio:
|
||||
type: string
|
||||
description: 生成视频的规格，值为 `standard`。
|
||||
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)。
|
||||
````
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user