World Video Generation

W Pricing Update

November Black Friday pricing is now live, together with:

Video reference support
Improved visual quality
Vivix W1 Auto

The November rates below include our limited-time Black Friday discounts.

Purchase W credit packs

November Black Friday Pricing

Base generation is billed per second of generated video.

Model	USD / sec	Credits / sec
Vivix W1 Auto	$0.0090	3.0
Vivix W1	$0.0050	≈ 1.7
Vivix W1 Fast	$0.0160	≈ 5.3
Vivix W1 Ultra Fast	$0.0280	≈ 9.3

1 Credit = $0.0030. Credit rates are rounded to one decimal place for display; billing uses the unrounded rates.

Reference Fees

Reference fees are additional to base generation and are listed below.

Reference	USD	Credits
Images: 1–5 images	$0.0150 total per request	5.0
Images: each image after the fifth	+$0.0150 per image	+5.0
Audio: every 5 seconds of total reference audio	$0.0030	1.0
Video: per second of total reference video	$0.0600	20.0

Audio durations are combined across clips, then rounded up to the next 5-second block. Video reference fees use the combined duration of the reference videos.

API Overview

Generate a finished world video asynchronously with Vivix-W1. One request carries a prompt, the requested duration and aspect ratio, and optionally reference images, audio and video. Submit one job to receive a job_id, poll the job until it reaches a terminal state, and play the result from video_url. Reference material is uploaded first, so a job that uses references touches four endpoints:

POST /v1/files/images / POST /v1/files/audios / POST /v1/files/videos — upload reference material and keep the returned url (skip this for text-to-video);
POST /v1/videos/jobs — submit a generation job;
GET /v1/videos/jobs/{job_id} — query one job;
POST /v1/videos/jobs/batch-get — query several jobs at once.

Model Selection

Set the request model field to one of the following W1 models. The models differ in generation speed and price.

The examples below use vivix-w1-ultrafast, the fastest model. You can also choose vivix-w1-auto, vivix-w1-fast or vivix-w1 to suit your needs; vivix-w1 is the most affordable.

Current November Black Friday rates and reference fees are listed in the pricing update above.

model	Description
`vivix-w1-auto`	Automatically selects the fastest available W1 mode; the Auto base rate applies at every speed.
`vivix-w1-ultrafast`	Fastest generation; highest price.
`vivix-w1-fast`	Faster generation than `vivix-w1`.
`vivix-w1`	Standard generation speed; lowest price.

Vivix W1 Auto

vivix-w1-auto automatically selects the fastest available W1 generation mode based on current throughput.

Behavior	Details
Automatic selection	Selects the fastest W1 mode available when your request runs.
Speed range	From Normal (`vivix-w1`) up to Ultra Fast (`vivix-w1-ultrafast`).
Base generation price	Always the Auto rate. Routing to Fast or Ultra Fast does not add an acceleration surcharge.

Reference image, audio and video fees are added to the base generation cost. See Reference Fees above.

Charges are deducted from your W credits balance. W credits and A credits are separate and cannot be used interchangeably. For the complete Vivix model lineup, see Models.

Reference Material

Upload every reference file to your workspace first, then pass the url from the upload response in ref_images / ref_audios / ref_videos. The examples use our CDN URL format (static.vivi-x.ai); replace sample URLs with the URLs returned by your own uploads. Reference URLs must be publicly reachable over HTTP(S); the file_id is used by other endpoints and is not accepted here. Each generation job supports up to 8 reference images, 4 reference audio files and 4 reference videos.

Images: use a width-to-height ratio between 1:4 and 4:1.
Audio: each file must be 15 seconds or shorter; the combined duration of all reference audio must be 20 seconds or less.
Video: each file must be 15 seconds or shorter; the combined duration of all reference videos must be 20 seconds or less.

Audio and video duration totals are calculated separately.

Endpoint	Accepted types	Max files per job	Max file size
`POST /v1/files/images`	jpg, png, webp, heic	8	10MB
`POST /v1/files/audios`	wav, mp3, m4a, ogg, webm (mp3 and wav recommended)	4	10MB
`POST /v1/files/videos`	mp4, mov, webm	4	20MB

File type is detected from the file content, not from the file name. The server sniffs the leading bytes and compares the detected type with the declared Content-Type; it must be one of the accepted types above and must match the declared value, or the upload returns 20008. Declare the real media type in your multipart Content-Type.

Upload an image

curl -X POST https://api.vivix.ai/v1/files/images \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -F "file=@traveler.png"

Upload response

{
  "code": 0,
  "message": "success",
  "data": {
    "file_id": "file_img_xxxxxxxx-xxx",
    "file_type": "image",
    "mime_type": "image/png",
    "size_bytes": 412876,
    "url": "https://static.vivi-x.ai/images/2026/09/15/xxxxxxxxxxxxxxxx.png",
    "created_at": "2026-09-15T08:00:00.000000000Z"
  }
}

Upload audio

curl -X POST https://api.vivix.ai/v1/files/audios \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -F "file=@market.mp3"

{
  "code": 0,
  "message": "success",
  "data": {
    "file_id": "file_aud_xxxxxxxx-xxx",
    "file_type": "audio",
    "mime_type": "audio/mpeg",
    "size_bytes": 335822,
    "url": "https://static.vivi-x.ai/audios/2026/09/15/xxxxxxxxxxxxxxxx.mp3",
    "created_at": "2026-09-15T08:00:12.000000000Z"
  }
}

Upload video

curl -X POST https://api.vivix.ai/v1/files/videos \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -F "file=@movement.mp4;type=video/mp4"

Use data.url from the upload response as the url in each ref_videos item.

First and Last Frame

To pin exactly how the video opens or ends, pass first_frame_image / last_frame_image. Both take an uploaded url, exactly like reference material.

Fields	Result
`first_frame_image` only	Generation starts from this image.
`last_frame_image` only	Generation converges onto this image.
Both	Starts at the first and lands on the last; the same image twice gives a seamless loop.

Keyframes and reference material are two different modes, so first_frame_image / last_frame_image cannot be combined with ref_images / ref_audios / ref_videos; mixing them returns 20004.

Task Types

The task type is derived from the material you send — there is no mode field. prompt, duration and aspect_ratio apply to every type.

Task type	Material	What it does
Text to video	`prompt` only	Builds the whole scene from your description.
Image reference to video	`prompt` + `ref_images`	Keeps characters, objects or style consistent with the reference images.
Audio reference to video	`prompt` + `ref_audios`	Generates the video together with a soundtrack guided by the reference audio.
Video reference to video	`prompt` + `ref_videos`	Uses the reference video to guide motion, camera movement or visual style.
Image and audio reference to video	`prompt` + `ref_images` + `ref_audios`	Combines both kinds of reference material in one job.
Mixed references to video	`prompt` + `ref_images` + `ref_audios` + `ref_videos`	Combines visual, audio and motion references in one job.
First frame to video	`prompt` + `first_frame_image`	Opens on the given image and moves forward from it.
Last frame to video	`prompt` + `last_frame_image`	Ends on the given image, converging toward it.
First and last frame to video	`prompt` + `first_frame_image` + `last_frame_image`	Travels from the first image to the last one.

Text to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "A traveler crosses a windswept salt flat at sunset as the camera slowly pulls back.",
      "aspect_ratio": "16:9",
      "duration": 8
    }
  ]
}'

How to write the prompt Describe who is in the scene, what happens and how it ends, then add the style, camera and sound details you care about. State appearance, blocking, action order and the final shot plainly when they matter, and use observable wording instead of vague mood words.

Write in natural language or in labelled fields — there is no fixed length or order.
Add “one continuous shot” when you do not want cuts, and advance with first / then / finally.
Speech, lyrics and on-screen text go in the finished language, in quotes, with the speaker named.

Image reference to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "The traveler from the reference image walks across a windswept salt flat at sunset.",
      "aspect_ratio": "16:9",
      "duration": 8,
      "ref_images": [
        { "url": "https://static.vivi-x.ai/images/2026/09/15/xxxxxxxxxxxxxxxx.png" }
      ]
    }
  ]
}'

How to write the prompt Say which aspect each reference image provides and which subject it applies to. Use the number or name the upload shows, and spell out anything you want changed or left out.

For a character: “Image 1 defines the character’s look, move the scene to a rainy street.”
With several images, name the pairing: “Image 1 for the character, image 2 only for the bold line work and palette.”
You do not have to list everything you are not referencing; only say so when it is easy to confuse.

Audio reference to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "A night market comes alive, matching the mood of the reference audio.",
      "aspect_ratio": "9:16",
      "duration": 10,
      "ref_audios": [
        { "url": "https://static.vivi-x.ai/audios/2026/09/15/xxxxxxxxxxxxxxxx.mp3" }
      ]
    }
  ]
}'

How to write the prompt Say what the audio is for — voice timbre, music style or ambience — and which subject or segment it binds to. With several people, bind each track explicitly instead of relying on upload order.

Borrowing a voice: “Audio 1 is the girl’s timbre for image 2; deliver the lines below verbatim.”
Using the original track: name the purpose and entry point, for example “the first 8 seconds of audio 1 as the backing track”.
Style only: write “reference the style, do not use the original track”.

Video reference to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "A traveler crosses a salt flat, following the slow camera movement in video 1.",
      "aspect_ratio": "16:9",
      "duration": 8,
      "ref_videos": [
        { "url": "https://static.vivi-x.ai/videos/2026/09/15/xxxxxxxxxxxxxxxx.mp4" }
      ]
    }
  ]
}'

How to write the prompt Describe what to borrow from each video, such as movement, camera work or visual style, and what should change in the generated scene. When combining reference types, name the role of each image, audio clip and video explicitly.

Image and audio reference to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "The traveler and the vehicle from the reference images cross the salt flat while the reference music plays.",
      "aspect_ratio": "16:9",
      "duration": 12,
      "ref_images": [
        { "url": "https://static.vivi-x.ai/images/2026/09/15/xxxxxxxxxxxxxxxx.png" },
        { "url": "https://static.vivi-x.ai/images/2026/09/15/yyyyyyyyyyyyyyyy.png" }
      ],
      "ref_audios": [
        { "url": "https://static.vivi-x.ai/audios/2026/09/15/yyyyyyyyyyyyyyyy.mp3" }
      ]
    }
  ]
}'

How to write the prompt Say which aspect each reference image provides and which subject it applies to, then describe the soundtrack the audio should guide. Bind every track to its subject explicitly when several are in play.

Name the pairing: “Image 1 and image 2 are the traveler and the vehicle; audio 1 sets the pacing and mood.”
State what changes and what stays: “keep the vehicle design from image 2 unchanged.”
Add the camera and sound you want, and call out anything that must be excluded.

First and last frame to video

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "jobs": [
    {
      "prompt": "The traveler walks from the dawn dunes toward the salt flat as the light turns golden.",
      "aspect_ratio": "16:9",
      "duration": 8,
      "first_frame_image": "https://static.vivi-x.ai/images/2026/09/15/3a9c7f14b2e85d60.png",
      "last_frame_image": "https://static.vivi-x.ai/images/2026/09/15/c05d8e37a9f16b42.png"
    }
  ]
}'

How to write the prompt Write how the motion leaves the first frame and how it arrives at the last one. You do not need to restate either image — add only the key change and the details that are easy to misread.

Both frames: describe the path between them, for example “the character opens the umbrella and settles into the final pose and framing”.
First frame only: write the action that follows. Last frame only: write the process that leads up to it.
Say whether the camera slows, holds or stays in one continuous shot, and keep people and clothing consistent.

Generation Inputs

Field	Accepted value	Purpose
`prompt`	non-empty string	Required. Natural-language description of the video.
`duration`	integer, 5–15	Required. Requested video duration in seconds.
`aspect_ratio`	`"16:9"` / `"9:16"` / `"1:1"` / `"4:3"` / `"3:4"`	Optional. Defaults to `"16:9"`.
`ref_images`	`{ url }[]`, at most 8	Optional. Reference images for subjects, objects or visual style. Each item contains only an uploaded image `url`. Image aspect ratio must be between 1:4 and 4:1.
`ref_audios`	`{ url }[]`, at most 4	Optional. Reference audio for voice, music or ambience. Each item contains only an uploaded audio `url`. Maximum 15 seconds per file and 20 seconds total across audio files.
`ref_videos`	`{ url }[]`, at most 4	Optional. Reference videos for motion, camera work or visual style. Each item contains only an uploaded video `url`. Maximum 15 seconds per file and 20 seconds total across video files.
`first_frame_image`	string (URL)	Optional. Pins the opening frame. Cannot be combined with reference material.
`last_frame_image`	string (URL)	Optional. Pins the closing frame. Cannot be combined with reference material.

One job per request. The jobs array must contain exactly one item, and unknown fields are rejected with 20004.

Calling Conventions

These conventions apply to every endpoint on this page.

Base URL

https://api.vivix.ai

Authentication

Every request must carry an API key: Authorization: Bearer $VIVIX_API_KEY.

Response Envelope

REST responses use the shared {code, message, data} envelope. Business fields are returned inside data.

Response envelope

{
  "code": 0,
  "message": "success",
  "data": {}
}

code = 0 means the request succeeded.
A non-zero code indicates an API-level error; the HTTP status is derived from it.
An accepted job can still fail later. Poll the job and inspect status and error.

Task Lifecycle

Submit POST /v1/videos/jobs and store the returned job_id.
Poll GET /v1/videos/jobs/{job_id} every few seconds while the job is queued or processing.
When the job reaches succeeded, play or download the video from video_url. Stop polling on failed and read error.

Status	Meaning	Client action
`queued`	The job is waiting to start.	Keep polling.
`processing`	The video is being generated.	Keep polling.
`succeeded`	The generated video is ready.	Read `video_url`.
`failed`	The job did not complete successfully.	Stop polling and read `error.code`.

Submit a Generation Job

Creates an asynchronous W1 video generation job from a prompt and optional reference material. POST /v1/videos/jobs

Body Parameters

"vivix-w1-auto" | "vivix-w1-ultrafast" | "vivix-w1-fast" | "vivix-w1"

required

Required. The W1 model used for this job. vivix-w1-auto automatically selects the fastest available mode, from Normal to Ultra Fast, at the Auto base rate with no acceleration surcharge. See Model Selection for details.

"standard" | "enhanced"

Optional. Defaults to standard, which enhances the prompt in a single multimodal call. Choose enhanced for separate media analysis and prompt planning. This setting does not change video duration, resolution or inference mode.

integer | null

Optional. An integer from 0 to 2147483647. Omit or send null for a backend-generated random seed. When set, all tasks use the same seed, including zero. This controls video inference, not prompt enhancement randomness.

array

required

Required. Exactly one job.

string

required

Required. Natural-language description of the video.

integer

required

Required. Video duration in seconds, between 5 and 15.

string

Optional. One of "16:9", "9:16", "1:1", "4:3", "3:4". Defaults to "16:9".

{ url: string }[]

Optional. Up to 8 reference images to guide subjects, objects or visual style.

Each item contains only a url returned by POST /v1/files/images.
Maximum file size: 10MB.
Image aspect ratio: 1:4 to 4:1.
Cannot be combined with first_frame_image or last_frame_image.

{ url: string }[]

Optional. Up to 4 reference audio files to guide voice, music or ambience.

Each item contains only a url returned by POST /v1/files/audios.
Maximum file size: 10MB.
Maximum duration per file: 15 seconds.
Maximum combined reference audio duration: 20 seconds. Audio and video totals are calculated separately.
Cannot be combined with first_frame_image or last_frame_image.

{ url: string }[]

Optional. Up to 4 reference videos to guide motion, camera work or visual style.

Each item contains only a url returned by POST /v1/files/videos.
Maximum file size: 20MB.
Maximum duration per file: 15 seconds.
Maximum combined reference video duration: 20 seconds. Audio and video totals are calculated separately.
Cannot be combined with first_frame_image or last_frame_image.

"mp4"

Optional. Defaults to "mp4". The returned video_url points to an MP4 file you can download or play directly.

Response Fields

Fields in the response data object:

string

Job identifier used by the query endpoints.

string

Initial job status, usually queued.

Request

curl -X POST https://api.vivix.ai/v1/videos/jobs \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-w1-ultrafast",
  "pe_mode": "standard",
  "seed": 12345,
  "jobs": [
    {
      "prompt": "A traveler crosses a windswept salt flat at sunset as the camera slowly pulls back.",
      "aspect_ratio": "16:9",
      "duration": 8,
      "output_format": "mp4"
    }
  ]
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "results": [
      {
        "job_id": "job_xxxxxxxx",
        "status": "queued"
      }
    ]
  }
}

Query a Job

Returns the current state of one job. See Task Lifecycle for terminal-state handling. GET /v1/videos/jobs/{job_id}

Path Parameters

string

required

Job identifier returned on submission.

Response Fields

string

Job identifier.

string

queued / processing / succeeded / failed.

string

URL of the finished MP4 video. Returned only when the job succeeded.

string

Aspect ratio of the generated video.

number

Requested duration in seconds, echoed back. The encoded media can be marginally longer.

object | null

Non-null only when the job failed. error.code is generation_failed, generation_timeout or generation_cancelled.

timestamp

Job creation time.

timestamp

Most recent job update time.

An unknown job id returns 20005 (HTTP 404).

Request

curl https://api.vivix.ai/v1/videos/jobs/job_xxxxxxxx \
  -H "Authorization: Bearer $VIVIX_API_KEY"

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "job_id": "job_xxxxxxxx",
    "status": "succeeded",
    "video_url": "https://static.vivi-x.ai/videos/2026/09/15/yyyyyyyyyyyyyyyy.mp4",
    "aspect_ratio": "16:9",
    "duration": 8,
    "error": null,
    "created_at": "2026-09-15T07:27:40.938208Z",
    "updated_at": "2026-09-15T07:28:45.207793Z"
  }
}

Failed job

{
  "code": 0,
  "message": "success",
  "data": {
    "job_id": "job_xxxxxxxx",
    "status": "failed",
    "aspect_ratio": "16:9",
    "duration": 8,
    "error": {
      "code": "generation_failed",
      "message": "Video generation failed"
    },
    "created_at": "2026-09-15T07:27:40.938208Z",
    "updated_at": "2026-09-15T07:31:02.771204Z"
  }
}

Query Several Jobs

Returns the same job view for several ids in one call. Results follow the order of job_ids; unknown ids are omitted from items. POST /v1/videos/jobs/batch-get

Body Parameters

string[]

required

Job identifiers to query.

Response Fields

array

Job objects with the same fields as GET /v1/videos/jobs/{job_id}.

Request

curl -X POST https://api.vivix.ai/v1/videos/jobs/batch-get \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "job_ids": [
    "job_xxxxxxxx",
    "job_yyyyyyyy"
  ]
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "job_id": "job_xxxxxxxx",
        "status": "succeeded",
        "video_url": "https://static.vivi-x.ai/videos/2026/09/15/yyyyyyyyyyyyyyyy.mp4",
        "aspect_ratio": "16:9",
        "duration": 8,
        "error": null,
        "created_at": "2026-09-15T07:27:40.938208Z",
        "updated_at": "2026-09-15T07:28:45.207793Z"
      },
      {
        "job_id": "job_yyyyyyyy",
        "status": "processing",
        "aspect_ratio": "9:16",
        "duration": 10,
        "error": null,
        "created_at": "2026-09-15T07:30:11.102338Z",
        "updated_at": "2026-09-15T07:30:44.918227Z"
      }
    ]
  }
}

Error Codes

API errors return the common response envelope with data: null:

Error response

{
  "code": 20004,
  "message": "invalid parameter: jobs[0].duration must be an integer between 5 and 15",
  "data": null
}

code	HTTP	Meaning
`10001`	401	API key is missing.
`10003`	403	API key is invalid.
`10004` / `10005`	402	Workspace billing is inactive or the balance is insufficient.
`10008`	429	API rate limit exceeded.
`20004`	400	Invalid parameter: unsupported model, more than one job, missing prompt or duration, duration outside 5–15, unsupported aspect ratio, unsupported output format, too many references, an unreachable reference URL, or an unknown field.
`20005`	404	Job not found.
`20008`	415	Unsupported media type on upload: the detected file content is not an accepted type, or it does not match the declared Content-Type. The filename extension is not checked.
`30001`	403	Content rejected by moderation.
`30008`	429	Model capacity is exhausted. Retry later.
`50001`	500	Internal error.
`50003`	503	Service unavailable.

Two error layers. The envelope code covers submission and query errors. A job accepted with code = 0 can still end as status = failed, carrying error.code.

When contacting support, include the X-Request-Id and X-Trace-Id response headers.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

W Pricing Update

Purchase W credit packs

November Black Friday Pricing

Reference Fees

API Overview

Model Selection

Vivix W1 Auto

Reference Material

First and Last Frame

Task Types

Text to video

Image reference to video

Audio reference to video

Video reference to video

Image and audio reference to video

First and last frame to video

Generation Inputs

Calling Conventions

Base URL

Authentication

Response Envelope

Task Lifecycle

Submit a Generation Job

Body Parameters

Response Fields

Query a Job

Path Parameters

Response Fields

Query Several Jobs

Body Parameters

Response Fields

Error Codes