千问（Qwen）图像编辑 - 数字先锋API文档

# Qwen 图像编辑 API 文档

## 1. 接口说明

使用自然语言编辑输入图片，返回编辑后图片 URL。

- **Method**: `POST`
- **URL**: `https://api.cxsee.com/v1/images/edits`
- **Content-Type**: `multipart/form-data`
- **Auth**: `Authorization: Bearer {API_KEY}`

---

## 2. 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| model | string | 是 | 模型名称，固定填 `qwen-image-edit` |
| prompt | string | 是 | 编辑指令（中文/英文均可） |
| image | file | 是 | 待编辑图片文件（png/jpg/jpeg/webp 建议） |

> 建议：图片尽量小于 2MB，最长边不超过 2048，以提升成功率和速度。

---

## 3. 请求示例（cURL）

```bash
curl -X POST "https://api.cxsee.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=qwen-image-edit" \
  -F "prompt=把未来主义生态住宅这张图里背景改为草原，保持写实风格" \
  -F "image=@/path/to/input.png"
```
### 一次提交 3 张参考图”的 cURL 示例

curl -X POST "https://api.cxsee.com/v1/images/edits" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "model=qwen-image-edit" \
      -F "prompt=参考前两张图的建筑风格与配色，并结合第三张图的景观氛围，生成一张写实的未来生态住宅效果图，统一为黄昏光线" \
      -F "image=@/path/to/ref1.png" \
      -F "image=@/path/to/ref2.jpg" \
      -F "image=@/path/to/ref3.webp"
---

## 4. 成功响应示例

```json
{
  "data": [
    {
      "url": "https://.../result.png?...",
      "b64_json": "",
      "revised_prompt": ""
    }
  ],
  "created": 1774105966,
  "metadata": {
    "usage": {
      "width": 1152,
      "height": 896,
      "image_count": 1
    },
    "request_id": "2892ada6-c155-4434-9c06-468ab115507e"
  }
}
```

### 字段说明
- `data[0].url`: 生成图片地址（通常为临时签名 URL，需及时下载保存）
- `metadata.request_id`: 请求追踪 ID（排障用）
- `metadata.usage.width/height`: 输出图尺寸

---

## 5. 错误码与常见问题

### 5.1 `For image editing ... Got 0 image items`
原因：调用了不兼容格式（如 `messages` JSON）
解决：使用 `/v1/images/edits` + `multipart/form-data` + `image=@文件`

### 5.2 `Failed to download image ... No address associated with hostname`
原因：服务端无法访问你传的图片 URL（DNS/网络限制）
解决：改用文件上传，不要传公网 URL

### 5.3 上传后长时间无响应
可能原因：图片过大、网络慢、超时设置过短
建议：
- 压缩到 <2MB
- 使用 jpg 并适当降分辨率
- 客户端设置 `--max-time 180`

---

## 6. 最佳实践

1. **优先文件上传**（稳定性最高）
2. **结果 URL 及时落盘**（签名链接会过期）
3. **记录 request_id**（便于客服排障）
4. **敏感 Key 不上日志/前端**
5. **建议重试策略**：5xx 或网络错误时指数退避重试 1~2 次

---
效果展示
源图
![](https://img.cxhao.com/images/5/2026/02/iq15oKI8M7mSQZFZUv7iYmSi5KuM7D.png)

编辑后
![](https://img.cxhao.com/2026032123214272056?imageMogr2/thumbnail/800x/format/jpg/blur/1x0/quality/95|imageslim)

上一篇：Chat（思考Thinking）下一篇：Flux 绘画（OpenAI 兼容）