> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vidu Q3
> Vidu video generation API for text-to-video, Standard and Turbo image-to-video, and first-and-last-frame workflows
## Overview
Vidu Q3 is a per-second video generation model for text-to-video, image-to-video, and Turbo image-to-video workflows. Use this page when you are ready to call the API after trying the model in the APIXO playground.
| Capability | Value |
| ----------------------- | --------------------------------------------------------- |
| Model ID | `vidu-q3` |
| Modes | `text-to-video`, `image-to-video`, `turbo-image-to-video` |
| Prompt length | 1-5000 characters |
| Duration | Any integer from `1` through `16` seconds |
| Resolutions | `540p`, `720p`, `1080p` |
| Text-mode aspect ratios | `16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
| Text-mode styles | `general`, `anime` |
| Reference images | 1-2 URLs for image modes |
| Output | MP4 video URL array in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/vidu-q3` | Submit a generation task |
| `GET` | `/statusTask/vidu-q3?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a Standard text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/vidu-q3" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic flyover of a futuristic city at sunrise",
"resolution": "720p",
"duration": 8,
"style": "general",
"aspect_ratio": "16:9",
"sound": true,
"bgm": true
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final video.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/vidu-q3?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965730929,
"costTime": 120000
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "PromptInvalid",
"failMsg": "Prompt is invalid or rejected by upstream service",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a polished app launch teaser with a glowing phone rotating above a reflective surface",
"resolution": "720p",
"duration": 8,
"style": "general",
"aspect_ratio": "16:9",
"movement": "auto",
"sound": true,
"bgm": true,
"seed": 1234
}
}
```
### Single-image animation
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "make this product photo come alive with subtle camera motion",
"resolution": "1080p",
"duration": 4,
"image_urls": [
"https://example.com/start.jpg"
],
"sound": true,
"bgm": true
}
}
```
### First-and-last-frame transition
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "transition smoothly from the first frame to the last frame",
"resolution": "720p",
"duration": 8,
"image_urls": [
"https://example.com/start.jpg",
"https://example.com/end.jpg"
],
"sound": true,
"bgm": true
}
}
```
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
Vidu Q3 input parameters.
Generation mode. Supported values: `text-to-video`, `image-to-video`, `turbo-image-to-video`.
Text prompt describing the desired video. Must be non-empty after trimming and must not exceed 5000 characters.
Output resolution. Supported values: `540p`, `720p`, `1080p`.
Output duration in seconds. Supports any integer from `1` through `16`.
Text-mode style preset. Supported values: `general`, `anime`. Applies only to `text-to-video`.
Text-mode output aspect ratio. Supported values: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`. Applies only to `text-to-video`.
Required for `image-to-video` and `turbo-image-to-video`. Supports 1-2 image URLs. One image creates single-image animation; two images create a first-and-last-frame transition where the first URL is the start frame and the second URL is the end frame.
Motion amplitude. Supported values: `auto`, `small`, `medium`, `large`.
Whether to generate sound effects with the video.
Whether to generate background music with the video.
Random seed. Supports integers from `-1` through `2147483647`.
| Mode | Required media | Text controls | Billing tier |
| ---------------------- | ---------------------------- | ----------------------- | ------------ |
| `text-to-video` | None | `style`, `aspect_ratio` | Standard |
| `image-to-video` | `image_urls` with 1-2 images | Not used | Standard |
| `turbo-image-to-video` | `image_urls` with 1-2 images | Not used | Turbo |
Use public, directly accessible image URLs for image modes. The task is rejected if an image URL cannot be accessed or processed.
## Response format
### Submit task response
`POST /generateTask/vidu-q3` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds. Present after completion when timing data is available.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/vidu-q3" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "turbo-image-to-video",
"prompt": "animate the reference image with a smooth handheld camera move",
"resolution": "720p",
"duration": 4,
"image_urls": [
"https://example.com/reference-image.jpg"
],
"sound": true,
"bgm": true
}
}'
```
The callback payload uses the same top-level shape as status polling with `code`, `message`, and `data`. Successful callbacks include the final `state` and `resultJson`. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Vidu Q3 is billed per second. The selected `mode` determines whether the task uses the Standard or Turbo rate, and `resolution` determines the per-second unit price.
```text theme={null}
total cost = unit price x duration
```
| Mode group | Resolution | APIXO price |
| ------------------------------------------- | ---------- | ---------------- |
| Standard: `text-to-video`, `image-to-video` | `540p` | `$0.07 / second` |
| Standard: `text-to-video`, `image-to-video` | `720p` | `$0.15 / second` |
| Standard: `text-to-video`, `image-to-video` | `1080p` | `$0.16 / second` |
| Turbo: `turbo-image-to-video` | `540p` | `$0.04 / second` |
| Turbo: `turbo-image-to-video` | `720p` | `$0.06 / second` |
| Turbo: `turbo-image-to-video` | `1080p` | `$0.08 / second` |
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Video generation is long-running. Typical Vidu Q3 processing time is about 60-120 seconds, but actual latency may vary by mode, duration, resolution, prompt complexity, reference image accessibility, route queue load, and storage transfer time.
| Workload | Typical generation time | Recommended first poll | Poll interval |
| ---------------------------------------- | ----------------------- | --------------------------- | ------------- |
| Short Turbo previews | 60s-120s | 60s after task creation | 5s-10s |
| Standard text-to-video or image-to-video | 60s-180s | 60s-90s after task creation | 5s-10s |
| Longer or 1080p jobs | 2-4 minutes or longer | 90s after task creation | 10s |
For production workloads, use callback mode to avoid frequent polling while video tasks run.
Result URLs are temporary. Download and store important outputs promptly after task completion.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, missing `input`, unsupported `mode`, empty or too-long `prompt`, invalid `resolution`, invalid `duration`, invalid `style`, invalid `aspect_ratio`, invalid `movement`, or invalid `image_urls` | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model, or content was rejected | Check permissions and revise the prompt or input |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error or unknown task failure | Retry with backoff |
| `502` | Upstream service error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode for long-running jobs |
### Validation notes
| Condition | Backend behavior |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Missing `input` | Request fails before task creation. |
| Missing `mode` | Request fails before task creation. |
| Unsupported `mode` | Request fails before task creation. Supported values are `text-to-video`, `image-to-video`, and `turbo-image-to-video`. |
| Missing, non-string, or empty `prompt` | Request fails before task creation. |
| `prompt` longer than 5000 characters | Request fails before task creation. |
| Missing or unsupported `resolution` | Request fails before task creation. Supported values are `540p`, `720p`, and `1080p`. |
| Missing `duration` | Request fails before task creation. |
| `duration` outside `1` through `16` | Request fails before task creation. |
| Unsupported `style` in text modes | Request fails before task creation. Supported values are `general` and `anime`. |
| Unsupported `aspect_ratio` in text modes | Request fails before task creation. Supported values are `16:9`, `9:16`, `4:3`, `3:4`, and `1:1`. |
| Unsupported `movement` | Request fails before task creation. Supported values are `auto`, `small`, `medium`, and `large`. |
| Image mode without `image_urls` | Request fails before task creation. |
| Image mode with zero or more than two images | Request fails before task creation. |
| `image_urls` contains non-string items | Request fails before task creation. |
| `seed` outside `-1` through `2147483647` | Request fails before task creation. |
### Task failure codes
`failCode` is generated from APIXO's mapped upstream error. Common values include:
| Fail code | Meaning | What to do |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| `PromptInvalid` | Prompt was invalid or rejected by the upstream service | Rewrite the prompt and retry |
| `SensitiveContent` | Prompt or input/output content was rejected by safety checks | Change the prompt or reference image |
| `ImageFormatIncorrect` | Reference image format could not be processed | Use a public, direct image URL in a common image format |
| `RateLimited` | Upstream rate limit was reached | Retry with exponential backoff |
| `Timeout` | Upstream timeout | Retry later or use callback mode |
| `StreamError` | Upstream returned a `500`-class generation error | Retry with backoff |
| `Unknown error` | Upstream returned an unmapped failure | Retry with backoff or contact support with the `taskId` |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)