Name: Vidu Q3 Pro Text and Image to Video API
Brand: magicapi
SKU: api-magicapi-high-fidelity-video-generation-api-vidu-q3-pro
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 Text and Image to Video Generator API with Audio (Vidu Q3 Pro)

## Overview
Vidu Q3 Pro is a video generation model from Vidu. Its developer describes it as high-fidelity video generation with synchronized audio, up to 16 seconds at 1080p.

It works in three modes, picked by the images you send:
- **Text-to-video**: send only a `prompt`.
- **Image-to-video**: send a `prompt` and a `start_image`. The video starts from that frame.
- **Start-end-to-video**: send a `prompt`, a `start_image` and an `end_image`. The video moves from the first frame to the last.

Choose the length with `duration` (1 to 16 seconds) and the resolution with `resolution` (`540p`, `720p` or `1080p`). Audio (dialogue and sound effects) is generated by default. Each request returns the URL of one MP4 video.

## Features
- **Three generation modes**: text-to-video, image-to-video and start-end-to-video.
- **Duration**: 1 to 16 seconds, default 5.
- **Resolution**: `540p`, `720p` (default) or `1080p`.
- **Synchronized audio**: `audio` (default `true`) generates dialogue and sound effects with the video. Set it to `false` for a silent video.
- **Aspect ratios** (text-to-video only): `16:9` (default), `9:16`, `3:4`, `4:3`, `1:1`. Ignored when you send images.
- **Long prompts**: up to 5000 characters.
- **Seed**: set a seed to reproduce a result.

## Use Cases
1. **Short scenes from a script**: generate a clip with ambient sound or dialogue from a written description.
2. **Animating a still**: turn a product photo, illustration or key frame into a moving shot with `start_image`.
3. **Transitions between two frames**: set the first and last frame with `start_image` and `end_image` and let the model fill the motion in between.
4. **Social video**: vertical `9:16` clips for stories and reels from a text prompt.

## Visual Examples
### Example Input
- **Prompt**: "A cozy mountain cabin at dawn, steam rising from a mug of coffee on the wooden porch railing while pine trees sway in a soft breeze and birds chirp in the distance, slow cinematic dolly-in."
- **duration**: `4`
- **resolution**: `540p`

All other fields were left at their defaults (text-to-video, `aspect_ratio` `16:9`, `audio` `true`).

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

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  | Up to 5000 characters | Text prompt for video generation |
| `start_image` | string (URL) | No | none |  | Start frame image for the video. When provided without an `end_image`, the model runs in image-to-video mode. Supported formats: png, jpeg, jpg, webp. |
| `end_image` | string (URL) | No | none |  | End frame image for the video. Must be used together with `start_image` for start-end-to-video mode. The aspect ratios of the start and end images must be similar (ratio between 0.8 and 1.25). Supported formats: png, jpeg, jpg, webp. |
| `duration` | integer | No | `5` | 1 to 16 | Duration of the video in seconds |
| `aspect_ratio` | string | No | `16:9` | `16:9`, `9:16`, `3:4`, `4:3`, `1:1` | Aspect ratio of the output video. Only used in text-to-video mode (ignored when images are provided). |
| `resolution` | string | No | `720p` | `540p`, `720p`, `1080p` | Resolution of the output video |
| `audio` | boolean | No | `true` |  | Whether to generate audio synchronized with the video (dialogue and sound effects) |
| `seed` | integer | No | none |  | Random seed. Set for reproducible generation. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.088 per API unit.
- **1 API unit = 1 second of 540p video.** Requests are billed on the requested `duration`, times the factor for the chosen `resolution`:

| `resolution` | Units per second | Price per second |
| --- | --- | --- |
| `540p` | 1 | $0.088 |
| `720p` (default) | 2.143 | about $0.1886 |
| `1080p` | 2.286 | about $0.2012 |

- **No resolution set**: the default `720p` applies, at 2.143 units per second.
- **Rounding**: the total for a request (`duration` x units per second) is rounded up to a whole unit.
- **Worked examples**: the default request (5 seconds at 720p) is 10.715, rounded up to 11 units = $0.968. 5 seconds at 1080p is 11.43, rounded up to 12 units = $1.056. 16 seconds at 1080p is 36.576, rounded up to 37 units = $3.256.
- **The example request above** (4 seconds at 540p) used 4 units and cost $0.352.
- Mode (text, image or start-end), `audio`, `aspect_ratio` and `seed` do not change the price.
- **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 go to: `https://prod.api.market/api/v1/magicapi/high-fidelity-video-generation-api-vidu-q3-pro`

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

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/high-fidelity-video-generation-api-vidu-q3-pro/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "1a8e2767ffcf46d64a4d97727f187ccc2cadc59db844db7167327e01a2a79390",
    "input": {
      "prompt": "A cozy mountain cabin at dawn, steam rising from a mug of coffee on the wooden porch railing while pine trees sway in a soft breeze and birds chirp in the distance, slow cinematic dolly-in.",
      "duration": 4,
      "resolution": "540p"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ge5yygxw11rmw0d17fvs20ane0",
  "version": "1a8e2767ffcf46d64a4d97727f187ccc2cadc59db844db7167327e01a2a79390",
  "status": "starting",
  "created_at": "2026-10-14T19:50:53.818Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/high-fidelity-video-generation-api-vidu-q3-pro/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ge5yygxw11rmw0d17fvs20ane0",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/q3-pro-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-14T19:50:53.818Z",
  "started_at": "2026-10-14T19:50:54.818Z",
  "completed_at": "2026-10-14T19:52:23.818Z"
}
```

`output` is a single URL string pointing to the generated MP4 video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt`, a `duration` outside 1 to 16 or a `resolution` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry 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.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/high-fidelity-video-generation-api-vidu-q3-pro";

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

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

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

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    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(pollInterval);
  }

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

createAndWaitForPrediction({
  "prompt": "A cozy mountain cabin at dawn, steam rising from a mug of coffee on the wooden porch railing while pine trees sway in a soft breeze and birds chirp in the distance, slow cinematic dolly-in.",
  "duration": 4,
  "resolution": "540p"
}).then((output) => console.log(output));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/high-fidelity-video-generation-api-vidu-q3-pro"

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": "1a8e2767ffcf46d64a4d97727f187ccc2cadc59db844db7167327e01a2a79390", "input": input_data},
    )

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

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

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    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"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

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

print(create_and_wait_for_prediction({
    "prompt": "A cozy mountain cabin at dawn, steam rising from a mug of coffee on the wooden porch railing while pine trees sway in a soft breeze and birds chirp in the distance, slow cinematic dolly-in.",
    "duration": 4,
    "resolution": "540p"
}))
```

## FAQ
- **How do I choose between text-to-video, image-to-video and start-end-to-video?**
  - By the images you send. No image gives text-to-video, `start_image` alone gives image-to-video, and `start_image` plus `end_image` gives start-end-to-video. `end_image` without `start_image` is not a valid combination.
- **Why is my `aspect_ratio` ignored?**
  - `aspect_ratio` only applies in text-to-video mode. When you send `start_image`, the video follows the image instead.
- **Can I get a video without sound?**
  - Yes. Set `audio` to `false`. The price is the same with or without audio.
- **How is the price calculated?**
  - Requested `duration` in seconds, times 1 unit at 540p, 2.143 at 720p or 2.286 at 1080p, rounded up to a whole unit, at $0.088 per unit. A default 5 second 720p video costs $0.968.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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 1 to 16 second videos with dialogue and sound from text or start and end frames with Vidu Q3 Pro, 540p to 1080p. From $0.088 per second.