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

# Create a video

> Create an asynchronous video generation task.

Creates a video task and returns the provider-neutral task envelope. Poll [`GET /v2/videos/{id}`](/api-reference/video/get) until the task completes.

See [supported models and billing](/guides/video#supported-v2-models) for Mini, standard 2.0, Fast and 2.5 limits and a full poll loop.

<ParamField body="model" type="string" required>
  Use `doubao-seedance-2-0-mini-260615`, `seedance-2.0`, `doubao-seedance-2-0-fast-260128`, or `doubao-seedance-2-5-260628`. Mini also accepts `seedance-2-0-mini` and `seedance-2.0-mini`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the video to generate.
</ParamField>

<ParamField body="inputs" type="array">
  Optional media inputs. Each item needs `type` and `url`. Mini allows at most 9 images, 3 videos, and 3 audios. Combined reference-video duration must be ≤ 15s. Standard, Fast and 2.5 accept up to 9 images only.

  <Expandable title="inputs[]">
    <ParamField body="type" type="string" required>
      `image_url`, `video_url`, or `audio_url`.
    </ParamField>

    <ParamField body="url" type="string" required>
      HTTPS URL of the media.
    </ParamField>

    <ParamField body="role" type="string">
      Protocol values: `first_frame`, `last_frame`, `reference_image`, `reference_video`, `reference_audio`. Mini images require `reference_image`. Mini videos/audio use `reference_video` / `reference_audio` or omit `role`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="duration" type="integer">
  Output seconds: 4–15 for Mini, standard and Fast; 4–30 for 2.5. Default `5`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  `adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, or `21:9`. Mini defaults to `16:9`.
</ParamField>

<ParamField body="resolution" type="string">
  `480p`, `720p`, or `1080p`. Only 2.5 also accepts `1080p`; the other models accept `480p` and `720p`. Default `480p`.
</ParamField>

<ParamField body="audio" type="boolean">
  Whether to generate audio. Mini defaults to `false`.
</ParamField>

<ParamField body="provider_options" type="object">
  Provider-keyed native options. Not supported on these four model profiles.
</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": "A cat walking across a sunlit kitchen floor",
      "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": "A cat walking across a sunlit kitchen floor",
          "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>

Unknown fields are rejected. Duration lives on `outputs[]` after completion, not on the task top level.

<ResponseField name="id" type="string">
  Public task ID (`gen-...`). Use this on GET and DELETE. Upstream IDs stay internal.
</ResponseField>

<ResponseField name="object" type="string">
  Always `video`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name from the request.
</ResponseField>

<ResponseField name="provider" type="string">
  Upstream provider that accepted the task, for example `volcengine`.
</ResponseField>

<ResponseField name="status" type="string">
  `queued`, `in_progress`, `completed`, `failed`, `cancelled`, or `expired`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Optional 0–100 progress.
</ResponseField>

<ResponseField name="outputs" type="array">
  Present after `completed`. Duration is on each output, not the task.

  <Expandable title="outputs[]">
    <ResponseField name="type" type="string">
      `video`, `image`, or `audio`.
    </ResponseField>

    <ResponseField name="role" type="string">
      `result`, `last_frame`, `cover`, or `watermarked`.
    </ResponseField>

    <ResponseField name="url" type="string">
      Download URL for the artifact.
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      For example `video/mp4`.
    </ResponseField>

    <ResponseField name="duration" type="number">
      Length of this video or audio output, in seconds.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Present when `status` is `failed`. Contains `code` and `message`.
</ResponseField>

## Errors

Mini and standard 2.0 are billed after acceptance. Fast and 2.5 settle on completion from actual video tokens. Validation failures return `400` and are not billed. Same envelope as [Errors](/api-reference/errors). Unknown JSON fields are rejected.

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    Missing `model` / `prompt`, unsupported Mini duration or resolution, wrong input `role`, too many references, or `provider_options` on Mini.

    ```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">
    Quote is taken at create time. Insufficient balance rejects the request before a task is created.

    ```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">
    See [Rate Limits](/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.