Name: Cinematic Text-to-Video Generator API (Wan 3.0)
Brand: magicapi
SKU: api-magicapi-text-to-video-generator-alibaba-wan-3
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Cinematic Text-to-Video Generator API (Wan 3.0)

## Overview
This API generates video with Wan 3.0 from Alibaba. Send a text `prompt` to create a video from scratch, or add a starting `image` to animate it into a video guided by the prompt. Wan 3.0 produces cinematic motion at 480p, 720p or 1080p, with clips from 2 to 30 seconds long. The response is a URL to the generated video.

## Features
- **Text-to-video**: `prompt` is the only required field.
- **Image-to-video**: pass an optional first-frame `image` (jpg, png, bmp or webp, up to 10 MB) and the video is generated from that image, guided by the prompt.
- **Three resolutions**: `480p`, `720p` or `1080p` (default `1080p`).
- **Duration from 2 to 30 seconds**: set `duration` in whole seconds (default 5).
- **Aspect ratio**: `adaptive` (default, the model picks the best ratio for the prompt), `16:9`, `9:16`, `1:1`, `4:3` or `3:4`. When you send an image, its own aspect ratio is used instead.
- **Negative prompt**: describe content that should not appear in the video.
- **Prompt expansion**: `enable_prompt_expansion` (default `true`) expands and optimizes your prompt. It improves quality for short prompts but increases latency.
- **Reproducible output**: set `seed` (0 to 2147483647).

## Use Cases
1. **Marketing and social video**: Create short clips for ads, product launches and social posts from a written brief.
2. **Animating stills**: Turn a product shot, illustration or photo into a moving scene with the `image` field.
3. **Storyboards and previs**: Draft camera moves and scene ideas before a shoot.
4. **B-roll and backgrounds**: Generate establishing shots and ambient footage for edits and presentations.

## Visual Examples
### Example Input
**Prompt:**
`A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise`

**Settings:** `resolution` set to `720p`; all other fields at their defaults (5 second duration, adaptive aspect ratio, prompt expansion on). No input image was used.

### Example Output
[Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/wan-3-output-api-market.mp4)

## Pricing
- **Pay As You Go (PAYG)**: you only pay for what you use.
- **Price**: $0.032 per API unit.
- **Billing unit**: per second of output video. The number of seconds is rounded up to a whole second and multiplied by the resolution tier:
  - **480p**: 1 unit per second = **$0.032 per second**
  - **720p**: 2 units per second = **$0.064 per second**
  - **1080p** (default): 4 units per second = **$0.128 per second**
- Examples: a default request (5 seconds at 1080p) is 20 units = $0.64. The example on this page (5 seconds at 720p) was 10 units = $0.32. The longest video (30 seconds at 1080p) is 120 units = $3.84.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status are free and don't count toward API unit usage.
- No monthly subscription fee.

## API Documentation

### Base URL
All API requests should be made to:
`https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3`

### Authentication
Include your api.market API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. Follow these steps:
1. Send a POST request to `/predictions` with the `version` and your `input`.
2. The API answers **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. A 201 response means the job was accepted; it is not an error.
3. Poll GET `/predictions/{id}` with that ID.
4. Stop when `status` is `succeeded`, `failed` or `canceled`. On `succeeded`, `output` holds the URL of the generated video.

Video generation is not instant. The code samples below poll once per second and give up after 600 seconds (10 minutes); raise the timeout if your requests take longer.

### Endpoints

#### POST /api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions
Create a prediction. This is the request used for the example on this page:

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b",
    "input": {
      "prompt": "A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise",
      "resolution": "720p"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b",
  "status": "starting",
  "created_at": "2026-10-11T19:15:11.521Z"
}
```

#### GET /api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions/{id}
Check the status of a prediction and get its output. Status checks are free.

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b",
  "status": "succeeded",
  "input": {
    "prompt": "A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise",
    "resolution": "720p"
  },
  "output": "https://blog.api.market/wp-content/uploads/2026/10/wan-3-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-11T19:15:11.521Z",
  "started_at": "2026-10-11T19:15:12.104Z",
  "completed_at": "2026-10-11T19:16:20.733Z"
}
```

### Input Parameters
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
| `prompt` | string | - | yes | Text prompt for video generation. |
| `image` | string | - | no | Optional first-frame image to animate into a video (jpg/png/bmp/webp, up to 10MB). When provided, the video is generated from this image guided by the prompt. |
| `negative_prompt` | string | `""` | no | Negative prompt: describes content that should not appear in the video. |
| `resolution` | string | `1080p` | no | Output video resolution. One of: `480p`, `720p`, `1080p`. |
| `aspect_ratio` | string | `adaptive` | no | Aspect ratio of the generated video. 'adaptive' lets the model choose the best ratio for the prompt. Ignored when an image is provided (the input image's aspect ratio is used). One of: `adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. |
| `duration` | integer | `5` | no | Duration of the generated video in seconds. Range: 2 to 30. |
| `enable_prompt_expansion` | boolean | `true` | no | Automatically expand and optimize the prompt for better results. Improves quality for short prompts but increases latency. |
| `seed` | integer | - | no | Random seed for reproducible generation. Range: 0-2147483647. |

### Status Codes
- **201 Created**: The POST request was accepted and the prediction was created (success). Poll the GET endpoint for the result.
- **200 OK**: The GET request succeeded. Check the `status` field to see whether the prediction has finished.
- **400 Bad Request**: Invalid input parameters or malformed request
- **401 Unauthorized**: Missing or invalid API key
- **404 Not Found**: Prediction not found
- **429 Too Many Requests**: Rate limit exceeded
- **500 Internal Server Error**: Server-side error

### Error Handling
1. **HTTP errors**: Read the response body for the error message. Fix the request for `400` and `401`; retry `429` and `5xx` with exponential backoff.
2. **Failed predictions**: If GET returns `status: "failed"`, the `error` field explains why. Failed and cancelled predictions are not billed.
3. **Timeouts**: If a prediction is still `starting` or `processing` when your timeout runs out, you can keep polling the same ID later.

### Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide
### Example Code
#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3";

async function createAndWaitForPrediction(inputData) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b", input: inputData })
  });

  // 201 Created means the prediction was accepted
  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return await pollForResults(prediction.id);
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "prompt": "A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise",
  "resolution": "720p"
}).then(output => console.log(output));
```

#### Python
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }

    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b", "input": input_data}
    )

    # 201 Created means the prediction was accepted
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    return poll_for_results(prediction["id"])

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks

    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers=headers
        )

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            error_msg = prediction.get("error") or "Unknown error"
            raise Exception(f"Prediction {prediction['status']}: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")

output = create_and_wait_for_prediction({
  "prompt": "A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise",
  "resolution": "720p"
})
print(output)
```

#### cURL
```bash
# Step 1: Create a prediction (returns 201 Created)
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "78e877ac6841ba1fe938f4886243cdac82b2e40e4c29c2cfc977d671aeb0d15b",
    "input": {
      "prompt": "A smooth drone shot flying low over a turquoise lagoon toward a small palm-covered island at sunrise",
      "resolution": "720p"
    }
  }'

# The response contains a prediction ID, for example:
# {"id": "ufawqhfynnddngldkgtslldrkq", "status": "starting", ...}

# Step 2: Check the prediction status (replace the ID with yours)
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generator-alibaba-wan-3/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Repeat step 2 until status is "succeeded", "failed" or "canceled"
```

### Performance Optimization
- Draft prompts at `480p` with a short `duration`, then render the final version at `720p` or `1080p`; price per second doubles with each step up in resolution.
- Turn off `enable_prompt_expansion` when your prompt is already detailed, to avoid the extra latency.
- Use a fixed `seed` when comparing prompt changes.

## FAQ
1. **Can I generate a video from an image?**
   - Yes. Pass a URL in `image` (jpg, png, bmp or webp, up to 10 MB). The video starts from that image and follows your prompt. `aspect_ratio` is ignored in that case.

2. **How long can a video be?**
   - Between 2 and 30 seconds, set with `duration`. The default is 5 seconds.

3. **What resolution do I get if I do not choose one?**
   - `1080p`, which is also the most expensive tier ($0.128 per second). Set `resolution` to `480p` or `720p` to pay less.

4. **What does prompt expansion do?**
   - When `enable_prompt_expansion` is `true` (the default), the prompt is automatically expanded and optimized. This helps short prompts but adds latency.

5. **How do I handle failures?**
   - Check the `status` field. If it is `failed` or `canceled`, read the `error` field. Failed and cancelled predictions are not billed.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Generate 2 to 30 second videos from text or a first-frame image at 480p, 720p or 1080p with the Wan 3.0 API. Pay per second of video.