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

# 创建视频

> 创建异步视频生成任务。

创建视频任务，返回平台无关的任务信封。用 [`GET /v2/videos/{id}`](/zh/api-reference/video/get) 轮询直到完成。

Mini、标准版 2.0、Fast 和 2.5 的支持范围、计费规则及轮询示例见 [视频生成](/zh/guides/video)。

<ParamField body="model" type="string" required>
  使用 `doubao-seedance-2-0-mini-260615`、`seedance-2.0`、`doubao-seedance-2-0-fast-260128` 或 `doubao-seedance-2-5-260628`。Mini 也接受 `seedance-2-0-mini`、`seedance-2.0-mini`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频生成提示词。
</ParamField>

<ParamField body="inputs" type="array">
  可选媒体输入。每项需要 `type` 和 `url`。Mini 最多 9 张图、3 个视频、3 个音频。参考视频合计时长必须 ≤ 15 秒。标准版、Fast 和 2.5 仅接受最多 9 张图片。

  <Expandable title="inputs[]">
    <ParamField body="type" type="string" required>
      `image_url`、`video_url` 或 `audio_url`。
    </ParamField>

    <ParamField body="url" type="string" required>
      媒体的 HTTPS URL。
    </ParamField>

    <ParamField body="role" type="string">
      协议取值：`first_frame`、`last_frame`、`reference_image`、`reference_video`、`reference_audio`。Mini 的图片必须是 `reference_image`。Mini 的视频/音频用 `reference_video` / `reference_audio`，或不填 `role`。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="duration" type="integer">
  输出秒数：Mini、标准版和 Fast 为 4–15；2.5 为 4–30。默认 `5`。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  `adaptive`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4` 或 `21:9`。Mini 默认 `16:9`。
</ParamField>

<ParamField body="resolution" type="string">
  `480p`、`720p` 或 `1080p`。仅 2.5 额外接受 `1080p`；其他模型接受 `480p` 和 `720p`。默认 `480p`。
</ParamField>

<ParamField body="audio" type="boolean">
  是否生成音频。Mini 默认 `false`。
</ParamField>

<ParamField body="provider_options" type="object">
  按 Provider 隔离的原生参数。这四款模型均不支持。
</ParamField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.pipellm.ai/v2/videos \
    -H "Authorization: Bearer $PIPELLM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2-0-mini",
      "prompt": "一只猫走过洒满阳光的厨房地板",
      "duration": 4,
      "aspect_ratio": "16:9",
      "resolution": "480p",
      "audio": false
    }'
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  response = requests.post(
      "https://api.pipellm.ai/v2/videos",
      headers={
          "Authorization": f"Bearer {os.environ['PIPELLM_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "seedance-2-0-mini",
          "prompt": "一只猫走过洒满阳光的厨房地板",
          "duration": 4,
          "aspect_ratio": "16:9",
          "resolution": "480p",
          "audio": False,
      },
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"dark"}
  {
    "id": "gen-xxxxxxxx",
    "object": "video",
    "model": "seedance-2-0-mini",
    "provider": "volcengine",
    "status": "queued",
    "progress": 0,
    "created_at": 1726400000,
    "updated_at": 1726400000
  }
  ```
</ResponseExample>

未知字段会被拒绝。时长在完成后出现在 `outputs[]` 上，不在任务顶层。

<ResponseField name="id" type="string">
  公开任务 ID（`gen-...`）。GET 和 DELETE 使用这个值。上游 ID 只在网关内部使用。
</ResponseField>

<ResponseField name="object" type="string">
  固定为 `video`。
</ResponseField>

<ResponseField name="model" type="string">
  请求中的模型名。
</ResponseField>

<ResponseField name="provider" type="string">
  接受该任务的上游，例如 `volcengine`。
</ResponseField>

<ResponseField name="status" type="string">
  `queued`、`in_progress`、`completed`、`failed`、`cancelled` 或 `expired`。
</ResponseField>

<ResponseField name="progress" type="integer">
  可选的 0–100 进度。
</ResponseField>

<ResponseField name="outputs" type="array">
  `completed` 之后出现。时长在每个产物上，不在任务顶层。

  <Expandable title="outputs[]">
    <ResponseField name="type" type="string">
      `video`、`image` 或 `audio`。
    </ResponseField>

    <ResponseField name="role" type="string">
      `result`、`last_frame`、`cover` 或 `watermarked`。
    </ResponseField>

    <ResponseField name="url" type="string">
      产物下载 URL。
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      例如 `video/mp4`。
    </ResponseField>

    <ResponseField name="duration" type="number">
      该视频或音频产物的时长，单位秒。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  `status` 为 `failed` 时出现，包含 `code` 和 `message`。
</ResponseField>

## 错误

Mini 和标准版 2.0 在成功接受任务后计费；Fast 和 2.5 完成后按实际视频 Token 结算。校验失败返回 `400`，不计费。错误信封与 [错误](/zh/api-reference/errors) 相同。未知 JSON 字段会被拒绝。

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    缺少 `model` / `prompt`、Mini 不支持的时长或分辨率、错误的 input `role`、参考素材过多，或 Mini 上传了 `provider_options`。

    ```json theme={"dark"}
    {
      "error": {
        "type": "invalid_request_error",
        "code": "400",
        "message": "Mini image inputs require role=reference_image"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 authentication_error">
    ```json theme={"dark"}
    {
      "error": {
        "type": "authentication_error",
        "code": "401",
        "message": "Incorrect API key provided. Please visit https://console.pipellm.ai/account/api-keys to find your API key."
      }
    }
    ```
  </Accordion>

  <Accordion title="402 insufficient_balance">
    报价在创建时确定。余额不足会在创建任务前拒绝请求。

    ```json theme={"dark"}
    {
      "error": {
        "type": "insufficient_balance",
        "code": "402",
        "message": "Insufficient balance. Please recharge your account at https://console.pipellm.ai/billing."
      }
    }
    ```
  </Accordion>

  <Accordion title="429 rate_limit_error">
    见 [速率限制](/zh/api-reference/rate-limits)。

    ```json theme={"dark"}
    {
      "error": {
        "type": "rate_limit_error",
        "code": "429",
        "message": "Rate limit exceeded. Your current limit is 120 requests per minute (approximately 2.00 requests per second). Please visit https://console.pipellm.ai/billing to upgrade your plan for higher limits."
      }
    }
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.