> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wengaocloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 阿里百炼万相 2.7 生图

> 使用 `/v1/images/aliwan` 调用阿里云百炼万相 2.7（wan2.7-image-pro）进行同步图片生成，按张计费。

`/v1/images/aliwan` 是专用于阿里云百炼万相 2.7 模型的同步图片生成接口。
每次请求生成 1 张图片，直接返回结果，无需轮询任务状态。

<Info>
  * 公网路径：`POST /v1/images/aliwan`
  * 请求体：JSON
  * 返回模式：同步 JSON
  * 计费单位：按张计费（每次请求 1 张）
</Info>

## 当前接入模型

| 模型                 | 典型用途      | 备注            |
| ------------------ | --------- | ------------- |
| `wan2.7-image-pro` | 文生图、参考图生成 | 平台按模型配置完成实际调用 |

## 请求示例

### 文生图

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v1/images/aliwan" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-pro",
    "prompt": "一朵七色花，通透花瓣，纯色背景，质感细腻",
    "size": "2K"
  }'
```

### 参考图生成

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v1/images/aliwan" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-pro",
    "prompt": "保留主体，将背景替换为星空场景",
    "size": "2K",
    "image": [
      "https://example.com/subject.png"
    ]
  }'
```

### 指定像素尺寸

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v1/images/aliwan" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-pro",
    "prompt": "产品宣传海报，商务风格",
    "size": "1920*1080",
    "watermark": true
  }'
```

## 请求参数

| 参数          | 类型                 | 必填 | 说明                                         |
| ----------- | ------------------ | -- | ------------------------------------------ |
| `model`     | string             | 是  | 模型调用 ID，平台会按当前模型配置完成实际调用                   |
| `prompt`    | string             | 是  | 图片生成提示词，不能为空                               |
| `n`         | integer            | 否  | 生成图片数量；当前只允许 1，不传时默认为 1                    |
| `size`      | string             | 否  | 见下方尺寸说明，默认 `2K`                            |
| `seed`      | integer            | 否  | 随机种子；如需复现效果可传整数                            |
| `watermark` | boolean            | 否  | 是否添加水印；不传时使用官方默认 false                     |
| `image`     | string / string\[] | 否  | 参考图片 URL 或图片 Data URI；数组最多 9 张；图片大小由官方接口校验 |

### size 尺寸说明

| 类型 | 示例                      | 说明                                              |
| -- | ----------------------- | ----------------------------------------------- |
| 档位 | `1K`、`2K`（默认）、`4K`      | 档位仅文生图可用，参考图生成建议使用像素格式                          |
| 像素 | `1920*1080`、`1920x1080` | 总像素在 \[768×768, 4096×4096] 之间，宽高比范围 \[1:8, 8:1] |

当前各规格同价。

## 响应结构

```json theme={null}
{
  "created": 1784125568,
  "data": [
    {
      "url": "https://dashscope-7c2c.oss-accelerate.aliyuncs.com/example.png"
    }
  ]
}
```

### 响应字段说明

| 字段                | 说明                                 |
| ----------------- | ---------------------------------- |
| `created`         | 响应创建时间戳（Unix 秒）                    |
| `data[]`          | 生成图片结果列表，单次请求最多 1 张                |
| `data[].url`      | 图片 URL（OSS 临时链接，官方保留约 24 小时，请及时下载） |
| `data[].b64_json` | 当官方返回 Base64 图片时返回该字段              |
| `error`           | 请求失败时返回错误对象；官方接口返回的参数错误会返回给调用方     |

<Warning>
  `data[].url` 为官方 OSS 临时链接，官方保留约 24 小时后将失效。
  如需长期保存，请在收到响应后及时自行下载转存。
</Warning>

## 计费说明

* 按成功返回的实际图片数计费，单次请求最多 1 张。
* 请求前检查余额和价格配置；余额不足直接返回 `402`。
* 上游返回非 2xx 时，平台全额退还本次冻结金额，不计入计费。

<Tip>
  `image` 字段仅用于参考图。
  不传 `watermark` 时，官方接口默认不添加水印；需要水印时显式传 `true`。
</Tip>