通义千问(qwen) 视频模型格式

# 通义千问图像生成 / 万相视频生成 API 对接文档

图片生成接口： /v1/images/generations 
视频提交任务： /v1/videos/generations
视频任务查询： /v1/videos/generations/{task_id}

---

## 1. 快速开始

### 1.1 生成一张图片（同步，秒级返回）

```bash
curl https://api.cxsee.com/v1/images/generations \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0",
    "prompt": "一只橘猫坐在窗台上，阳光洒进来，高清写实",
    "size": "1024x1024"
  }'
```

### 1.2 生成一段视频（异步，3~10 分钟）

```bash
# ① 提交任务（立即返回 task_id）
curl -X POST https://api.cxsee.com/v1/videos/generations \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.2-t2v-plus",
    "prompt": "一只小狗在草地上奔跑，镜头跟随，电影质感",
    "size": "1920*1080",
    "duration": 5
  }'

# ② 用返回的 task_id 轮询任务状态（每 10~20 秒一次）
curl https://api.cxsee.com/v1/videos/generations/<task_id> \
  -H "Authorization: Bearer <你的API令牌>"
```

---

## 2. 鉴权方式

所有接口使用 **API 令牌**（Bearer Token）鉴权：

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 兼容 Header | `x-api-key: <API 令牌>` / `api-key: <API 令牌>` |
| 令牌获取 | 登录控制台 →「令牌」页面创建；或注册 / OAuth / 微信登录后自动生成的默认密钥 |
| 内容类型 | `Content-Type: application/json` |

> 令牌以 `sk-` 开头。未认证或令牌失效返回 `401`。

**Base URL：`https://api.cxsee.com`**

---

## 3. 接口总览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/v1/images/generations` | 图片生成（**同步**返回结果） |
| POST | `/v1/videos/generations` | 视频生成（**异步**提交，返回 task_id） |
| GET | `/v1/videos/generations/:task_id` | 视频任务查询（轮询状态与结果） |
| GET | `/v1/videos/:task_id` | 视频任务查询（兼容路径） |
| GET | `/v1/tasks/:task_id` | 视频任务查询（通用路径） |
| GET | `/v1/videos/:task_id/content` | 获取视频文件内容（代理下载） |

---

## 4. 图片生成（同步）

### 4.1 请求

```
POST /v1/images/generations
```

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | 模型名：`qwen-image-3.0`、`qwen-image-3.0-pro` |
| `prompt` | string | ✅ | 提示词（中文 / 英文均可） |
| `size` | string | 否 | `1024x1024`（默认）、`768x1024`、`1024x768` 等，用 `x` 分隔 |
| `n` | int | 否 | 生成张数，**当前固定按 1 张计费，建议传 1** |

### 4.2 响应

```json
{
  "created": 1755660000,
  "data": [
    {
      "url": "https://xxx.oss-cn-xxx.aliyuncs.com/xxx.png"
    }
  ],
  "metadata": { "...上游原始返回..." }
}
```

`data[].url` 为生成图片的公开可访问地址（阿里云 OSS，有效期请以实际为准，建议下载保存）。

### 4.3 示例

**Python**

```python
import requests

API = "https://api.cxsee.com/v1/images/generations"
HEADERS = {"Authorization": "Bearer <你的API令牌>"}

resp = requests.post(API, headers=HEADERS, json={
    "model": "qwen-image-3.0",
    "prompt": "赛博朋克风格的未来城市夜景",
    "size": "1024x1024",
}).json()

print(resp["data"][0]["url"])
```

---

## 5. 视频生成（异步）

> 视频为异步任务：**提交 → 返回 task_id → 轮询状态 → status=completed 后取结果**。

### 5.1 提交任务

```
POST /v1/videos/generations
```

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | 见下方「模型与价格表」 |
| `prompt` | string | ✅ | 提示词 |
| `size` | string | 否 | 文生视频(t2v)用 `宽*高`，如 `1920*1080`、`1280*720`；图生视频(i2v)用分辨率 `720P`、`1080P` |
| `duration` | int | 否 | 时长（秒），默认 5，范围 3~10（视模型支持） |
| `image` | string | i2v 必填 | 参考图 URL（图生视频首帧） |
| `input_reference` | string | i2v 必填 | 参考图 URL（等价于 `image`） |
| `metadata` | object | 否 | 额外参数透传（见 5.4） |

**返回**（立即返回，任务后台执行）：

```json
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "object": "video",
  "model": "wan2.2-t2v-plus",
  "status": "in_progress",
  "progress": 0,
  "created_at": 1755660000
}
```

`id` / `task_id` 即后续查询用的任务 ID。

### 5.2 查询任务

```
GET /v1/videos/generations/:task_id
```

| 状态值 | 含义 |
|---|---|
| `queued` | 排队中 |
| `in_progress` | 生成中 |
| `completed` | 完成（可从 `data[].url` 取视频） |
| `failed` | 失败（`error` 字段含原因） |

**完成时响应**：

```json
{
  "id": "xxxxx",
  "task_id": "xxxxx",
  "model": "wan2.2-t2v-plus",
  "status": "completed",
  "progress": "100%",
  "created_at": 1755660000,
  "updated_at": 1755661000,
  "object": "video",
  "data": [
    {
      "url": "https://xxx.aliyuncs.com/xxx.mp4"
    }
  ]
}
```

建议轮询间隔 10~20 秒；生成一般需 3~10 分钟，请勿过于频繁请求。

### 5.3 获取视频文件

可用 `data[].url` 直接下载；或通过代理路径：

```
GET /v1/videos/:task_id/content
```

### 5.4 metadata 透传（高级参数）

除上述标准参数外，可通过 `metadata` 透传官方支持的高级参数，例如：

```json
{
  "model": "wan2.2-i2v-plus",
  "prompt": "人物转身微笑",
  "image": "https://xxx.com/first-frame.png",
  "size": "1080P",
  "metadata": {
    "negative_prompt": "模糊, 变形",
    "watermark": false,
    "prompt_extend": true,
    "seed": 42
  }
}
```

常用高级参数（阿里 DashScope 万相通用）：

| 参数 | 类型 | 说明 |
|---|---|---|
| `negative_prompt` | string | 反向提示词 |
| `resolution` | string | 分辨率（i2v），如 `720P`、`1080P` |
| `duration` | int | 时长（秒） |
| `prompt_extend` | bool | 是否开启提示词智能改写 |
| `watermark` | bool | 是否添加水印 |
| `seed` | int | 随机种子（固定可复现） |
| `audio_url` | string | 音频 URL（支持音频的模型） |

---

## 6. 模型与价格表

> 价格为**固定价**，按「张 / 次」计费；图片 1K / 2K 分辨率同价。
> 预扣即终价，成功后不多退少补（失败自动退款）。

### 6.1 图片模型（$/张）

| 模型 | 价格（$） | 说明 |
|---|---|---|
| `qwen-image-3.0` | $0.20 | 通义千问图像 3.0（1K / 2K 同价） |
| `qwen-image-3.0-pro` | $0.26 | 千问图像 3.0 Pro |

### 6.2 视频模型（$/次 或 $/秒）

| 模型 | 类型 | 价格 |
|---|---|---|
| `wan2.7-t2v` | 文生视频（按秒×分辨率阶梯计费） | 720P **$0.6/秒**、1080P **$1/秒** |
| `wan2.6-t2v` | 文生视频 | $4.00 / 次 |
| `wan2.6-i2v` | 图生视频 | $4.00 / 次 |
| `wan2.6-r2v` | 参考视频 | $4.00 / 次 |
| `wan2.2-t2v-plus` | 文生视频 | $3.50 / 次 |
| `wan2.2-i2v-plus` | 图生视频 | $3.50 / 次 |
| `wan2.2-i2v-flash` | 图生视频（极速） | $2.00 / 次 |
| `wanx2.1-t2v-plus` | 文生视频 | $2.85 / 次 |
| `wanx2.1-i2v-turbo` | 图生视频（极速） | $1.20 / 次 |
| `wanx2.1-kf2v-plus` | 首尾帧 / 关键帧 | $2.90 / 次 |
| `wanx2.1-vace-plus` | 视频编辑 / 风格迁移 | $0.70 / 次 |
| `wan2.2-kf2v-flash` | 首尾帧（极速） | $1.00 / 次 |
| `wan2.2-animate-mix` | 动作迁移 | $0.60 / 次 |
| `wan2.2-s2v` | 音频生成视频 | $0.50 / 次 |
| `wan2.2-s2v-detect` | 音频检测 | $0.005 / 次 |

> **wan2.7-t2v 阶梯计费**：720P 档按 `$0.6 × 时长(秒)` 计费（向上取整），1080P 档按 `$1 × 时长(秒)`。示例：`size=1920*1080`、`duration=5` → `$1 × 5 = $5.00`。预扣即终价，成功不额外扣费。
> 美元与账户额度换算：`1 $ = 500000 quota`。后台「模型定价」可随时调整以上价格。

---

## 7. 常见错误

| HTTP | code / message | 说明与处理 |
|---|---|---|
| 401 | 未认证 / 令牌无效 | 检查令牌是否正确、是否过期、余额是否充足 |
| 400 | `invalid_request` | 参数缺失或非法（如 i2v 模型未传 `image`、t2v 的 size 未用 `*` 分隔） |
| 400 | `invalid size: xxx` | 视频 size 不在支持列表（见 5.1） |
| 500 | `ali_api_error: InternalError.Algo` | 阿里官方偶发算法错误，**重试一次即可** |
| 500 | 上游 4xx | 提示词触发内容安全 / 额度限制，调整提示词或稍后重试 |
| 视频 | `status=failed` | 在查询响应 `error` 字段查看官方返回原因 |

---

## 8. 注意事项

1. **图片为同步接口**，请求会一直等到图片生成完成（约 10~60 秒），客户端请设置足够长的超时（建议 120 秒）。
2. **视频为异步接口**，提交后立即返回 `task_id`，需轮询查询接口（建议 10~20 秒间隔，最长等 15 分钟）。
3. **计费**：图片按张、视频按次固定价。失败任务自动退款，可到「消费记录」查看明细。
4. **图片 n 参数**：当前按 1 张计费，多张请分多次请求或先确认平台定价。
5. **图生视频（i2v）**必须传 `image` / `input_reference` 参考图 URL，否则报错。
6. **文生视频（t2v）**的 `size` 使用 `宽*高`（乘号 `*`），图生视频使用分辨率 `720P` / `1080P`。
7. 视频生成耗时较长，建议业务侧做任务持久化 + 异步轮询，避免服务重启丢任务。
8. 如需在控制台页面直接体验：平台「体验中心」已接入图像 / 视频生成能力。

---

## 9. 附录：完整调用流程示例（Python）

```python
import requests, time

BASE = "https://api.cxsee.com"
HEADERS = {"Authorization": "Bearer <你的API令牌>"}

# ---- 图片（同步）----
r = requests.post(f"{BASE}/v1/images/generations", headers=HEADERS, json={
    "model": "qwen-image-3.0",
    "prompt": "水墨风格的江南小镇，清晨薄雾",
}).json()
print("图片URL:", r["data"][0]["url"])

# ---- 视频（异步）----
r = requests.post(f"{BASE}/v1/videos/generations", headers=HEADERS, json={
    "model": "wan2.2-t2v-plus",
    "prompt": "海浪拍打礁石，航拍视角",
    "size": "1920*1080",
    "duration": 5,
}).json()
task_id = r["id"]
print("task_id:", task_id)

while True:
    time.sleep(15)
    q = requests.get(f"{BASE}/v1/videos/generations/{task_id}", headers=HEADERS).json()
    st = q["status"]
    print("状态:", st, q.get("progress"))
    if st == "completed":
        print("视频URL:", q["data"][0]["url"])
        break
    if st == "failed":
        print("失败:", q.get("error"))
        break
```

上一篇：Seedance 私域素材库下一篇：Gemini 对话（OpenAI 兼容）