千问（Qwen）绘画 - 数字先锋API文档

# 通义千问（Qwen）绘画模型 API 文档

## 1. 接口概述

本接口用于通过文本生成图片（Text-to-Image），支持通义千问绘画模型调用。

- **Base URL**: `https://api.cxsee.com/v1`
- **Endpoint**: `POST /images/generations`
- **模型示例**: `qwen-image`
- **返回形式**: 图片 URL

---

## 2. 认证方式

请求头携带 API Key：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

---

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，固定示例：`qwen-image` |
| messages | array | 是 | 对话格式输入（与聊天接口一致） |
| stream | boolean | 否 | 是否流式返回，默认 `false`（当前建议传 `false`） |

### `messages` 格式

```json
[
  {
    "role": "user",
    "content": "画一只猫"
  }
]
```

> 建议在 `content` 中写清楚风格、构图、光线、分辨率倾向等提示词，以获得更可控结果。

---

## 4. 请求示例（cURL）

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "画一只猫"
      }
    ]
  }'
```

---

## 5. 成功响应示例

```json
{
  "created": 1774103730,
  "data": [
    {
      "url": "https://xxx.png?Expires=...&OSSAccessKeyId=...&Signature=..."
    }
  ]
}
```

---

## 6. 响应字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| created | integer | 生成时间戳（Unix） |
| data | array | 图片结果数组 |
| data[].url | string | 图片下载地址（通常为时效性签名 URL） |

---

## 7. 错误响应（通用格式）

```json
{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "code": "error_code"
  }
}
```

常见错误：
- `401 Unauthorized`：API Key 无效
- `429 Too Many Requests`：请求频率超限
- `400 Bad Request`：参数缺失或格式错误
- `402/余额相关`：账户额度不足

---

## 8. Python 调用示例（requests）

```python
import requests

url = "https://api.cxsee.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "model": "qwen-image",
    "stream": False,
    "messages": [
        {"role": "user", "content": "画一只猫"}
    ]
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()

print("created:", data.get("created"))
print("image_url:", data["data"][0]["url"])
```

---

## 9. 提示词最佳实践

建议采用结构化描述：

```text
主体 + 风格 + 场景 + 光线 + 构图 + 细节约束
```

示例：

- “一只橘猫坐在窗边，日落暖光，写实风格，浅景深，4k细节”
- “赛博朋克风格的黑猫，霓虹雨夜，低机位广角，电影感”

---

## 10. 使用注意事项

1. **URL 有时效**：返回的 `data[].url` 通常是签名链接，请尽快下载或转存。
2. **内容合规**：请遵守法律法规与平台内容安全规范。
3. **重试机制**：建议对 `429/5xx` 使用指数退避重试。
4. **日志追踪**：保存请求参数与返回时间，便于排障与计费核对。

---
qwen-images模型生成效果
![](https://img.cxhao.com/2026032123085385418?imageMogr2/thumbnail/1024x/format/jpg/blur/1x0/quality/95|imageslim)

上一篇：Gemini 对话（OpenAI 兼容）下一篇：Gemini 绘画（OpenAI 兼容）