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

# Wan 2.5 Video Generation

> Alibaba Wan 2.5 text-to-video and image-to-video

## Introduction

Wan 2.5 is Alibaba Cloud Bailian's video generation family, consisting of text-to-video (`wan2.5-t2v-preview`) and image-to-video (`wan2.5-i2v-preview`). It supports **480P**, **720P**, and **1080P** output.

Use GravitexAI's unified video API: [submit a task](/en/api-reference/endpoint/submit-video-task) to get a task `id`, then [query the task](/en/api-reference/endpoint/query-video-task) to poll status and get the video URL.

<Note>
  Wan 2.5 recommends passing underlying DashScope parameters via `metadata.input` and `metadata.parameters`. Top-level fields like `prompt` and `duration` are for compatibility; **`metadata.parameters` takes precedence**.
</Note>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer Token, e.g. `Bearer sk-xxxxxxxxxx`
</ParamField>

## Supported models

| Model ID             | Description    | Resolution        | Highlights                          |
| -------------------- | -------------- | ----------------- | ----------------------------------- |
| `wan2.5-t2v-preview` | Text-to-video  | 480P, 720P, 1080P | Generate video from text prompts    |
| `wan2.5-i2v-preview` | Image-to-video | 480P, 720P, 1080P | First-frame image driven generation |

## Call flow

1. **Submit**: `POST /v1/video/generations` with `model`, `prompt`, and Wan parameters in `metadata`.
2. **Poll**: `GET /llm-api/v1/video/generations/{id}` (host `maas.gravitex.ai`) every 3–15 seconds until `data.status` is `completed` or `failed`.
3. **Result**: On success, get the video URL from `data.url`, `data.video_url`, or `data.metadata.output.video_url` (typically a temporary link—download promptly).

## Request structure

| Field                 | Type    | Required    | Description                                                                                |
| --------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------ |
| `model`               | string  | Yes         | Model ID (see table above)                                                                 |
| `prompt`              | string  | Recommended | Video prompt; keep in sync with `metadata.input.prompt`                                    |
| `duration`            | integer | No          | Top-level duration; if it differs from `metadata.parameters.duration`, the latter wins     |
| `metadata.input`      | object  | Yes         | Input: `prompt`, `img_url` (image-to-video), etc.                                          |
| `metadata.parameters` | object  | Recommended | Processing params: `resolution`, `ratio`, `duration`, `prompt_extend`, `watermark`, `seed` |

### Submit response

The submit endpoint returns an OpenAI Video-style object; use `id` as the task ID for subsequent queries:

```json theme={null}
{
  "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
  "object": "video",
  "model": "wan2.5-i2v-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1781767983,
  "metadata": {
    "output": {
      "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
      "task_status": "PENDING"
    },
    "request_id": "2a17a551-0db2-910d-988b-7d5abed99d2d"
  }
}
```

### Query response

The query endpoint returns a wrapped structure; `data.status` of `completed` indicates success:

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
    "object": "video",
    "model": "wan2.5-i2v-preview",
    "status": "completed",
    "progress": 100,
    "seconds": "3",
    "url": "https://xxx.mp4",
    "video_url": "https://xxx.mp4",
    "created_at": 1781767983,
    "completed_at": 1781768013,
    "metadata": {
      "output": {
        "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
        "task_status": "SUCCEEDED",
        "orig_prompt": "A lamb grazing on grass\n",
        "video_url": "https://xxx.mp4",
        "submit_time": "2026-06-18 15:33:03.266",
        "scheduled_time": "2026-06-18 15:33:03.285",
        "end_time": "2026-06-18 15:33:32.407"
      },
      "usage": {
        "SR": 480,
        "duration": 3,
        "video_count": 1
      },
      "url": "https://xxx.mp4",
      "video_url": "https://xxx.mp4"
    }
  }
}
```

## Use cases

<Tabs>
  <Tab title="Text-to-video (T2V)">
    Generate video from text prompts with smart prompt rewriting and custom resolution/aspect ratio.

    <ParamField body="metadata.input.prompt" type="string" required>
      Text prompt; keep in sync with top-level `prompt`
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`, `720P`, or `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      Aspect ratio: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      Video duration in seconds; common values: 3, 5, 10
    </ParamField>

    <ParamField body="metadata.parameters.prompt_extend" type="boolean" default="true">
      Enable smart prompt rewriting
    </ParamField>

    <ParamField body="metadata.parameters.watermark" type="boolean" default="false">
      Add watermark
    </ParamField>

    <ParamField body="metadata.parameters.seed" type="integer">
      Random seed, range `[0, 2147483647]`
    </ParamField>

    **Text-to-video example:**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-t2v-preview",
        "prompt": "A kitten slowly opens its eyes, ears twitch gently, camera slowly pushes in",
        "metadata": {
          "input": {
            "prompt": "A kitten slowly opens its eyes, ears twitch gently, camera slowly pushes in"
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Image-to-video (I2V)">
    Generate video from a first-frame image via `metadata.input.img_url`.

    <ParamField body="metadata.input.img_url" type="string" required>
      First-frame image URL
    </ParamField>

    <ParamField body="metadata.input.prompt" type="string" required>
      Text prompt; keep in sync with top-level `prompt`
    </ParamField>

    <ParamField body="metadata.input.media" type="array">
      Optional; describes input media type, e.g. `[{"type": "reference_image"}]`
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`, `720P`, or `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      Aspect ratio: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      Video duration in seconds; common values: 3, 5, 10
    </ParamField>

    <ParamField body="metadata.parameters.prompt_extend" type="boolean" default="true">
      Enable smart prompt rewriting
    </ParamField>

    <ParamField body="metadata.parameters.watermark" type="boolean" default="false">
      Add watermark
    </ParamField>

    **Image-to-video example:**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-i2v-preview",
        "prompt": "A lamb grazing on grass",
        "metadata": {
          "input": {
            "img_url": "https://example.com/first_frame.png",
            "prompt": "A lamb grazing on grass",
            "media": [
              {"type": "reference_image"}
            ]
          },
          "parameters": {
            "resolution": "480P",
            "ratio": "16:9",
            "duration": 3,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Parameter reference

### metadata.parameters

| Parameter       | Type    | Description                            |
| --------------- | ------- | -------------------------------------- |
| `duration`      | integer | Effective video duration in seconds    |
| `resolution`    | string  | `480P`, `720P`, or `1080P`             |
| `ratio`         | string  | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`    |
| `prompt_extend` | boolean | Smart prompt rewriting, default `true` |
| `watermark`     | boolean | Add watermark, default `false`         |
| `seed`          | integer | Random seed, range `[0, 2147483647]`   |

### metadata.input

| Parameter | Type   | Use case  | Description                          |
| --------- | ------ | --------- | ------------------------------------ |
| `prompt`  | string | T2V / I2V | Prompt used by upstream              |
| `img_url` | string | I2V       | First-frame image URL                |
| `media`   | array  | I2V       | Optional; describes input media type |

### Query response key fields

| Field                              | Description                                                         |
| ---------------------------------- | ------------------------------------------------------------------- |
| `data.status`                      | Unified task status: `queued`, `in_progress`, `completed`, `failed` |
| `data.seconds`                     | Final video duration (string)                                       |
| `data.url` / `data.video_url`      | Video download URL                                                  |
| `data.metadata.output.task_status` | Upstream status, e.g. `SUCCEEDED`                                   |
| `data.metadata.usage.SR`           | Resolution tier, e.g. `480`, `720`                                  |
| `data.metadata.usage.duration`     | Final billing/output duration                                       |

## Status mapping

| Upstream status                   | Query `data.status` |
| --------------------------------- | ------------------- |
| `PENDING`                         | `queued`            |
| `RUNNING`                         | `in_progress`       |
| `SUCCEEDED`                       | `completed`         |
| `FAILED` / `CANCELED` / `UNKNOWN` | `failed`            |

## Error handling

| HTTP status | Meaning         | Suggestion                                  |
| ----------- | --------------- | ------------------------------------------- |
| 400         | Invalid request | Check `metadata` structure and media limits |
| 401         | Unauthorized    | Check API key                               |
| 429         | Rate limited    | Retry with lower frequency                  |
| 502         | Upstream error  | Retry later                                 |

On failure, `data.status` is `failed`; check `data.metadata.output.task_status` for details.

## FAQ

<AccordionGroup>
  <Accordion title="Top-level duration vs metadata.parameters.duration?">
    **`metadata.parameters.duration` wins**. For production, either omit top-level `duration` or keep both values identical.
  </Accordion>

  <Accordion title="How many times should I send prompt?">
    Keep top-level `prompt` and `metadata.input.prompt` **in sync** so `orig_prompt` in query results matches your request.
  </Accordion>

  <Accordion title="How long is the video URL valid?">
    `video_url` is typically a temporary OSS link. Download and store it promptly after success.
  </Accordion>

  <Accordion title="How do I know the task succeeded?">
    Check in this order:

    1. `data.status == "completed"`
    2. `data.video_url` or `data.url` is non-empty
    3. `data.metadata.output.task_status == "SUCCEEDED"`
  </Accordion>

  <Accordion title="How is Wan 2.5 different from Wan 2.7?">
    Wan 2.5 supports text-to-video and first-frame image-to-video only, using `metadata.input.img_url` instead of 2.7's `media` array. Wan 2.7 adds reference-to-video, continuation, first+last frame, and more. See [Wan 2.7](/en/api-reference/endpoint/wan2.7).
  </Accordion>
</AccordionGroup>

## Related APIs

<Columns cols={2}>
  <Card title="Submit video task" icon="upload" href="/en/api-reference/endpoint/submit-video-task">
    Unified video task submission and multi-model parameters
  </Card>

  <Card title="Query video task" icon="search" href="/en/api-reference/endpoint/query-video-task">
    Poll task status and get video URL
  </Card>
</Columns>