> ## 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.

# 创建视频生成任务

> 创建异步视频生成任务。受理后立即返回任务 ID，视频生成结果通过查询接口获取。
支持文生视频、图生视频、首尾帧、多模态参考、使用素材库等输入组合。


提交异步视频生成任务。平台受理后立即返回任务 ID，视频生成结果通过 [查询视频生成任务](/api/videos/query-task) 接口获取。

```
POST /v1/videos/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

***

## 请求参数

| 参数                        | 类型        | 必填    | 说明                                                                                    |
| ------------------------- | --------- | ----- | ------------------------------------------------------------------------------------- |
| `model`                   | string    | **是** | 平台开通的视频模型名称，例如 `seedance-2.0`、`seedance-2.0-fast`。实际可用名称以 `/v1/models` 返回为准。          |
| `content`                 | object\[] | **是** | 输入内容数组，至少包含一项。支持 `text`、`image_url`、`video_url`、`audio_url` 混合，详见下方说明。                |
| `generate_audio`          | boolean   | 否     | 是否生成与画面同步的声音。`true`：有声视频；`false`：无声视频。**未传时平台按 `true` 预估计费。**                         |
| `resolution`              | string    | 否     | 视频分辨率：`480p`、`720p`、`1080p`。`seedance-2.0-fast` 不支持 `1080p`。未传按 `720p` 预估。            |
| `ratio`                   | string    | 否     | 视频宽高比，例如 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`（模型自动选择）。未传按 `adaptive` 预估。 |
| `duration`                | integer   | 否     | 视频时长（秒），`[4, 15]` 或 `-1`（模型自主选择）。未传按 `5` 秒预估。                                         |
| `watermark`               | boolean   | 否     | 是否添加水印。`false` 不含水印（默认），`true` 含右下角 AI 水印。                                            |
| `seed`                    | integer   | 否     | 随机种子，`[-1, 2^32-1]`。相同种子+相同请求会生成类似结果，`-1` 表示随机。                                       |
| `safety_identifier`       | string    | 否     | 终端用户唯一标识，建议传用户 ID 或邮箱的哈希值，不超过 64 个字符，用于内容安全检测。                                        |
| `execution_expires_after` | integer   | 否     | 任务超时阈值（秒），默认 `172800`（48 小时），范围 `[3600, 259200]`。                                     |
| `service_tier`            | string    | 否     | 服务等级，当前仅支持 `default`。传 `flex` 会返回 400。                                                |
| `callback_url`            | string    | 否     | 任务状态回调地址，任务状态变化时平台推送 POST 请求。建议以查询接口为主要结果获取方式。                                        |
| `return_last_frame`       | boolean   | 否     | 是否返回生成视频的尾帧图像（PNG，无水印）。可用于首尾帧连续视频场景。                                                  |

<Warning>
  以下字段当前不支持，传入返回 400：`frames`、`service_tier=flex`、`seedance-2.0-fast + resolution=1080p`。

  请求体只需要传入文档列出的公开字段；额外字段可能会被忽略或返回参数错误。
</Warning>

***

## content 输入对象

### 文本 `type: text`

```json theme={null}
{
  "type": "text",
  "text": "生成一段城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上"
}
```

| 字段     | 类型     | 必填    | 说明                 |
| ------ | ------ | ----- | ------------------ |
| `type` | string | **是** | 固定为 `text`。        |
| `text` | string | **是** | 文本提示词，描述期望生成的视频内容。 |

### 图片 `type: image_url`

```json theme={null}
{
  "type": "image_url",
  "image_url": { "url": "https://example.com/product.png" },
  "role": "first_frame"
}
```

| 字段              | 类型     | 必填    | 说明                                                              |
| --------------- | ------ | ----- | --------------------------------------------------------------- |
| `type`          | string | **是** | 固定为 `image_url`。                                                |
| `image_url.url` | string | **是** | 图片公网 HTTPS URL、Base64，或素材 URI（`asset://asset_xxx`）。             |
| `role`          | string | 建议填   | 图片用途：`first_frame`（首帧）、`last_frame`（尾帧）、`reference_image`（参考图）。 |

### 视频 `type: video_url`

```json theme={null}
{
  "type": "video_url",
  "video_url": { "url": "https://example.com/reference.mp4" },
  "role": "reference_video"
}
```

| 字段              | 类型     | 必填    | 说明                                           |
| --------------- | ------ | ----- | -------------------------------------------- |
| `type`          | string | **是** | 固定为 `video_url`。                             |
| `video_url.url` | string | **是** | 视频公网 HTTPS URL 或素材 URI（`asset://asset_xxx`）。 |
| `role`          | string | 建议填   | 固定为 `reference_video`。                       |

### 音频 `type: audio_url`

```json theme={null}
{
  "type": "audio_url",
  "audio_url": { "url": "https://example.com/bgm.mp3" },
  "role": "reference_audio"
}
```

| 字段              | 类型     | 必填    | 说明                                                  |
| --------------- | ------ | ----- | --------------------------------------------------- |
| `type`          | string | **是** | 固定为 `audio_url`。                                    |
| `audio_url.url` | string | **是** | 音频公网 HTTPS URL、Base64，或素材 URI（`asset://asset_xxx`）。 |
| `role`          | string | 建议填   | 固定为 `reference_audio`。                              |

***

## 提示词中如何引用多个素材

当 `content` 中含有多个同类型素材时，用"**图片 1、图片 2、视频 1、音频 1**"这类顺序编号指代。编号按请求体中同类型素材出现的顺序计算，文本对象不参与编号。

**示例**（5 张参考图 + 1 段参考音频）：

> 0-2 秒：图片 1 中的霸总不小心撞到穿着图片 2 的衣服的图片 3 中的女主；2-6 秒：两人在雨夜共撑一把黑伞，雨天背景参考图片 4，台词参考音频 1；6-8 秒：右下角出现图片 5 的文字部分。

***

## 示例

<CodeGroup>
  ```bash 文生视频 theme={null}
  curl -X POST "https://{your-domain}/v1/videos/generations" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2.0",
      "content": [
        {
          "type": "text",
          "text": "生成一段 5 秒的城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上"
        }
      ],
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }'
  ```

  ```bash 图生视频（首帧） theme={null}
  curl -X POST "https://{your-domain}/v1/videos/generations" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2.0-fast",
      "content": [
        {
          "type": "text",
          "text": "让画面中的产品在干净的工作台上缓慢旋转，镜头轻微推进"
        },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/product.png" },
          "role": "first_frame"
        }
      ],
      "duration": 5,
      "resolution": "720p",
      "ratio": "1:1",
      "watermark": false
    }'
  ```

  ```bash 多模态参考 theme={null}
  curl -X POST "https://{your-domain}/v1/videos/generations" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2.0",
      "content": [
        {
          "type": "text",
          "text": "参考视频的镜头运动，生成一段新品宣传短片"
        },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/product.png" },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": { "url": "https://example.com/reference.mp4" },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": { "url": "https://example.com/bgm.mp3" },
          "role": "reference_audio"
        }
      ],
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }'
  ```

  ```bash 使用素材库 theme={null}
  curl -X POST "https://{your-domain}/v1/videos/generations" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2.0",
      "content": [
        {
          "type": "text",
          "text": "参考图片中的人物站在城市街道上，镜头缓慢推进，电影感"
        },
        {
          "type": "image_url",
          "image_url": { "url": "asset://asset_6f9a4c2b8d1e3a90" },
          "role": "reference_image"
        }
      ],
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "watermark": false
    }'
  ```
</CodeGroup>

***

## 成功响应

HTTP 状态码：`202 Accepted`

```json theme={null}
{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "model": "seedance-2.0",
  "status": "queued",
  "expires_at": 1779955200
}
```

| 字段           | 类型      | 说明                           |
| ------------ | ------- | ---------------------------- |
| `id`         | string  | 平台任务 ID，用于查询任务。              |
| `object`     | string  | 固定为 `video.generation.task`。 |
| `created`    | integer | 任务创建时间，Unix 秒。               |
| `model`      | string  | 请求中的平台模型名称。                  |
| `status`     | string  | 初始状态，通常为 `queued`。           |
| `expires_at` | integer | 任务过期时间估算，Unix 秒。             |

***

## 错误码

| HTTP 状态码 | `error.type`              | 场景                                                                          |
| -------- | ------------------------- | --------------------------------------------------------------------------- |
| 400      | `invalid_request_error`   | 缺少 `model` 或 `content`、`duration` 超范围、传入 `frames`、传入 `service_tier=flex` 等。 |
| 400      | `endpoint_not_configured` | 模型视频生成能力未启用。                                                                |
| 400      | `model_endpoint_mismatch` | 模型不能通过视频生成接口调用。                                                             |
| 402      | `insufficient_balance`    | 余额不足，无法创建任务。                                                                |
| 403      | `model_not_allowed`       | API Key 白名单未包含该模型。                                                          |
| 403      | `model_not_visible`       | 当前域名不可见或未开通该模型。                                                             |
| 404      | `model_not_found`         | 模型不存在或未启用。                                                                  |
| 429      | `quota_exceeded`          | API Key 配额不足。                                                               |


## OpenAPI

````yaml POST /v1/videos/generations
openapi: 3.1.0
info:
  title: WengaoCloud AI Gateway API
  version: 0.1.0
  description: WengaoCloud AI 聚合平台公开 API 契约草案，覆盖 OpenAI 兼容接口、Anthropic 原生接口和平台扩展接口。
servers:
  - url: https://xxx.wengaocloud.com
    description: 问高云 API 网关根域名。OpenAI SDK 的 base_url 使用 https://xxx.wengaocloud.com/v1。
  - url: https://{tenant}.wengaocloud.com
    description: 控制台展示的租户或 OEM API 网关根域名。
    variables:
      tenant:
        default: xxx
security:
  - bearerAuth: []
tags:
  - name: models
    x-group: 模型
  - name: openai-compatible
    x-group: OpenAI 兼容接口
  - name: anthropic-native
    x-group: Anthropic 原生接口
  - name: images-v3
    x-group: 图片（V3 同步）
  - name: volcengine-images
    x-group: 图片（火山直连）
  - name: images
    x-group: 图片（V1 兼容）
  - name: async-images
    x-group: 图片异步任务
  - name: aliwan-images
    x-group: 图片（百炼万相）
  - name: videos
    x-group: 视频
paths:
  /v1/videos/generations:
    post:
      tags:
        - videos
      summary: 创建视频生成任务
      description: |
        创建异步视频生成任务。受理后立即返回任务 ID，视频生成结果通过查询接口获取。
        支持文生视频、图生视频、首尾帧、多模态参考、使用素材库等输入组合。
      operationId: createVideoGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
            examples:
              textToVideo:
                summary: 文生视频
                value:
                  model: seedance-2.0
                  content:
                    - type: text
                      text: 生成一段 5 秒的城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上
                  duration: 5
                  resolution: 720p
                  ratio: '16:9'
                  generate_audio: true
                  watermark: false
              imageToVideo:
                summary: 图生视频（首帧）
                value:
                  model: seedance-2.0-fast
                  content:
                    - type: text
                      text: 让画面中的产品在干净的工作台上缓慢旋转
                    - type: image_url
                      image_url:
                        url: https://example.com/product.png
                      role: first_frame
                  duration: 5
                  resolution: 720p
                  ratio: '1:1'
                  watermark: false
              multiModal:
                summary: 多模态参考
                value:
                  model: seedance-2.0
                  content:
                    - type: text
                      text: 参考视频的镜头运动，生成一段新品宣传短片
                    - type: image_url
                      image_url:
                        url: https://example.com/reference-image.png
                      role: reference_image
                    - type: video_url
                      video_url:
                        url: https://example.com/reference.mp4
                      role: reference_video
                    - type: audio_url
                      audio_url:
                        url: https://example.com/bgm.mp3
                      role: reference_audio
                  duration: 8
                  resolution: 720p
                  ratio: '16:9'
                  generate_audio: true
                  watermark: false
      responses:
        '202':
          description: 任务已受理并进入队列。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationCreateResponse'
              examples:
                queued:
                  value:
                    id: vidtask_3cb6299b32d24f93a82e8a74b3e06161
                    object: video.generation.task
                    created: 1779782400
                    model: seedance-2.0
                    status: queued
                    expires_at: 1779955200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientQuota'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    VideoGenerationRequest:
      type: object
      required:
        - model
        - content
      properties:
        model:
          type: string
          description: >-
            平台开通的视频模型名称，例如 `seedance-2.0`、`seedance-2.0-fast`。实际可用名称以
            `/v1/models` 返回为准。
          example: seedance-2.0
        content:
          type: array
          description: 输入内容数组，至少包含一项。支持文本、图片、视频、音频的组合。
          items:
            $ref: '#/components/schemas/VideoContentItem'
        generate_audio:
          type: boolean
          description: 是否生成与画面同步的声音。`true` 为有声视频，`false` 为无声视频。未传时按 `true` 预估计费。
        resolution:
          type: string
          enum:
            - 480p
            - 720p
            - 1080p
          description: 视频分辨率。`seedance-2.0-fast` 不支持 `1080p`。未传时按 `720p` 预估计费。
        ratio:
          type: string
          description: >-
            视频宽高比。建议值：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。未传时按
            `adaptive` 预估计费。
          example: '16:9'
        duration:
          type: integer
          description: >-
            视频时长（秒）。`seedance-2.0`、`seedance-2.0-fast` 支持 `[4,15]` 或 `-1`（最长 15
            秒）。未传时按 `5` 秒预估计费。
          example: 5
        watermark:
          type: boolean
          description: 是否生成带水印视频。`false` 表示不含水印。
          default: false
        seed:
          type: integer
          description: 随机种子，取值建议 `[-1, 2^32-1]`。
        safety_identifier:
          type: string
          description: 终端用户唯一标识，建议使用用户 ID、用户名或邮箱的哈希值，不超过 64 个字符。
        execution_expires_after:
          type: integer
          description: 任务超时时间（秒），默认 172800，建议范围 [3600, 259200]。
        service_tier:
          type: string
          enum:
            - default
          description: 服务等级，当前仅支持 `default`。
        callback_url:
          type: string
          description: 任务状态回调地址。建议以查询接口为主要结果获取方式。
      additionalProperties: true
    VideoGenerationCreateResponse:
      type: object
      required:
        - id
        - object
        - created
        - model
        - status
      properties:
        id:
          type: string
          description: 平台任务 ID，用于查询任务。
          example: vidtask_3cb6299b32d24f93a82e8a74b3e06161
        object:
          type: string
          enum:
            - video.generation.task
        created:
          type: integer
          description: 任务创建时间，Unix 秒。
        model:
          type: string
          description: 请求中的平台模型名称。
        status:
          type: string
          enum:
            - queued
          description: 初始状态，通常为 `queued`。
        expires_at:
          type: integer
          description: 任务过期时间估算，Unix 秒。
    VideoContentItem:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - video_url
            - audio_url
          description: 输入类型。
        text:
          type: string
          description: 文本提示词，`type=text` 时必填。
        image_url:
          type: object
          properties:
            url:
              type: string
              description: 图片公网 URL、Base64，或素材 URI（格式 `asset://asset_xxx`）。
        video_url:
          type: object
          properties:
            url:
              type: string
              description: 视频公网 URL 或素材 URI（格式 `asset://asset_xxx`）。
        audio_url:
          type: object
          properties:
            url:
              type: string
              description: 音频公网 URL、Base64，或素材 URI（格式 `asset://asset_xxx`）。
        role:
          type: string
          description: |
            素材用途。图片建议值：`first_frame`、`last_frame`、`reference_image`；
            视频建议值：`reference_video`；音频建议值：`reference_audio`。
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_endpoint_mismatch
            message:
              type: string
              example: 该模型不支持当前 endpoint。
  responses:
    BadRequest:
      description: 请求参数无效。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API Key 缺失或无效。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientQuota:
      description: 余额或额度不足。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 模型不可见、API Key 无权限或档位不可用。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      x-default: sk-your-api-key

````