Avatar Video Generation

This page covers asynchronous video generation powered by Vivix-A1: you provide a first-frame image plus either an audio clip or a line of dialogue, and A1 generates a video of the character speaking and performing. From photorealistic portraits to anime characters, A1 is designed to keep expressions, lip sync, and motion working together while preserving the character identity and style throughout the video. Unlike the realtime sessions of Streaming Avatar, video generation is an asynchronous task: submit one request to get a video_id, poll the task status, and fetch the playable video URL once the task completes. Material is uploaded first, so the whole flow touches three endpoints:

POST /v1/files/images / POST /v1/files/audios — upload the first-frame image and the audio material, and keep the returned url;
POST /v1/videos/generations — submit a generation task;
GET /v1/videos/generations/{video_id} — query the task status and result.

For the capabilities of the A1 model itself and the product-line split, see Models.

Model Selection

A1 video generation selects its model with the model field of the request body:

model	Output resolution	Notes
`vivix-a1`	720p	A1 avatar video generation

For first-frame image sizes, see Material Upload.

Voice Source

Provide one of the two: audio or audio_data for voice audio you already have, or dialogue + voice_id to synthesize speech on the server (set the provider in tts_config). For voice ids, see Choose a voice and Clone Voice.

Material Upload

Upload the first-frame image and the audio material to your workspace first, then pass the url from the upload response in first_frame_image / audio.

POST /v1/files/images — the first-frame image, up to 10MB per file;
POST /v1/files/audios — the driving audio, up to 10MB per file.

Any other publicly reachable URL is accepted as well, but its availability is then yours to guarantee; uploading to the workspace is the supported path. First-frame image size. Provide the first frame at the size of the target resolution; an image of any other size is automatically compressed to it:

Output resolution	Landscape	Portrait
720p (`vivix-a1`)	1280×672	672×1280

Calling Conventions

The conventions below apply to every endpoint in this group.

Base URL

https://api.vivix.ai

Authentication

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

Response Envelope

Every REST response is wrapped in a {code, message, data} envelope, and all business fields live in data:

Response envelope

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

code = 0 means success; any non-zero value means failure (the HTTP status code is derived from the mapping of code, see Error Codes).
JSON fields use snake_case; 64-bit integers may be returned as strings, for example "cost_time_ms": "16562".

Business Errors

Business errors from task-submission endpoints usually surface as HTTP 200 with data.error_code != 0. To decide whether a submission succeeded, check both the outer code and data.error_code. Authentication failures return HTTP 401/403 directly.

Task Lifecycle

The complete lifecycle of a generation task:

Submit: POST /v1/videos/generations. On success the response carries a video_id and the task enters queued.
Poll: check the task status with GET /v1/videos/generations/{video_id}.
Terminal state: when the status is succeeded, fetch the video from playback_url; stop polling on failed / timeout.

Interpret each polling result with the rules below:

Query result	Meaning	Next step
`items` is empty	The task has not been written yet, or the `video_id` does not exist	Retry later
`status = queued / processing / ready`	The task is in progress	Keep short polling
`status = succeeded` and `playback_url` is non-empty	The task is complete	Play or download from `playback_url`
`status = failed / timeout`	The task failed or timed out	Stop polling

Submit a Generation Task

Submits a video generation task driven by an audio clip or by dialogue text. POST /v1/videos/generations

Body Parameters

string

Model name. For A1 generation use vivix-a1 (720p).

string

required

Main video prompt describing the shot and the performance. Required.

string

required

Character first-frame image URL. Required; for the expected size see Material Upload.

string

required

TTS dialogue text. Required when driving with dialogue.

string

required

Voice id. Required when driving with dialogue; see Voice Source.

string

required

Audio URL. When driving with audio, send exactly one of audio or audio_data.

string

required

Base64-encoded audio. When driving with audio, send exactly one of audio or audio_data.

object

Fine-grained TTS settings when driving with dialogue.

Show properties

number

Volume.

integer

Random seed.

number

Speech rate.

number

Stability.

string

TTS model id matching tts_provider.

string

TTS provider, the same provider as voice_id; see Choose a voice. ElevenLabs is used when omitted; for a cloned voice (voice_…) it is filled automatically.

string

Resolution: 720p / 480p.

string

Aspect ratio, for example 16:9 or 9:16.

Response Fields

Fields of the response data object:

string

Video task ID, used for subsequent queries.

int32

Business error code; 0 means success.

string

Human-readable status or error detail; empty on success.

string

Usually queued on a successful submission.

object

Playback information.

Show properties

string

Playback type.

string

Playback URL.

Dialogue request (server-side TTS)

curl -X POST https://api.vivix.ai/v1/videos/generations \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-a1",
  "prompt": "A confident host smiles and greets the audience.",
  "first_frame_image": "https://static.vivi-x.ai/images/2026/09/16/xxxxxxxxxxxxxxxx.png",
  "dialogue": "Welcome back. It is a beautiful day to show you something new.",
  "voice_id": "<elevenlabs_voice_id>",
  "tts_config": {
    "tts_provider": "elevenlabs",
    "tts_model_id": "eleven_v3",
    "speed": 1,
    "vol": 1
  },
  "resolution": "720p"
}'

Audio request

curl -X POST https://api.vivix.ai/v1/videos/generations \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vivix-a1",
  "prompt": "A confident host speaks to the camera.",
  "first_frame_image": "https://static.vivi-x.ai/images/2026/09/16/xxxxxxxxxxxxxxxx.png",
  "audio": "https://static.vivi-x.ai/audios/2026/09/16/xxxxxxxxxxxxxxxx.mp3",
  "resolution": "720p"
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "video_id": "vid_xxx",
    "error_code": 0,
    "message": "",
    "status": "queued"
  }
}

Query Task Status

Queries the status of a video generation task. See Task Lifecycle for how to interpret each status. GET /v1/videos/generations/{video_id}

Path Parameters

string

required

Video generation task ID.

Response Fields

The response data.items is a list of tasks (an empty list means the task has not been written yet or does not exist). Each item has the following fields:

string

Video generation task ID.

string

Current task status: queued / processing / succeeded / failed / timeout.

string

Most recent task event: status / completed / failed.

timestamp

Time of the most recent event.

string

Playback URL of the generated video; may be empty while the task is still processing.

string

Error detail for the task when it failed; empty otherwise.

string

Total processing time in ms (int64, returned as a string).

timestamp

Task creation time.

timestamp

Task update time.

Request

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

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "video_id": "vid_xxx",
        "status": "succeeded",
        "event": "completed",
        "event_timestamp": "2026-06-18T08:19:50Z",
        "playback_url": "https://example.com/video.m3u8",
        "watch_error": "",
        "cost_time_ms": "16562",
        "task_created_at": "2026-06-18T08:19:34.385558Z",
        "task_updated_at": "2026-06-18T08:19:50.948557Z"
      }
    ]
  }
}

Error Codes

Error responses share a single format, with data set to null:

Error response

{
  "code": 50001,
  "message": "internal error",
  "data": null
}

code = 0 means success; any non-zero value means failure, and the HTTP status code is derived from the mapping of code. Common error codes for video generation:

code	message	HTTP	Description
0	success	200	Success
10001	missing api key	401	API key is missing
10003	invalid api key	403	API key is invalid
10004	workspace billing is not active	402	Workspace billing is not active
10005	insufficient workspace balance	402	Workspace balance is insufficient
10008	API rate limit exceeded	429	API key rate limit hit (60 req/min by default; RPM is configurable per key). Responses include `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
20001	invalid request body	400	Request body is invalid
20002	invalid json body	400	Malformed JSON
20003	missing required parameter	400	A required parameter is missing
20004	invalid parameter	400	A parameter is invalid
20005	not found	404	Resource not found
30001	content rejected by moderation	403	Content failed moderation
30004	invalid argument	422	Parameter or business validation failed, for example neither `audio` / `audio_data` nor `dialogue` + `voice_id` was provided (`data.detail` is `generation mode invalid`)
50001	internal error	500	Internal error
50003	service unavailable	503	Service unavailable

Two error layers. The outer code is a gateway-level error. Task-level business errors usually surface as HTTP 200 with an outer code = 0, but data.error_code != 0 (submit endpoint) or status = failed / timeout (query endpoint).

When reporting an issue, include the X-Request-Id and X-Trace-Id response headers so the request can be located in the pipeline logs.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Model Selection

Voice Source

Material Upload

Calling Conventions

Base URL

Authentication

Response Envelope

Business Errors

Task Lifecycle

Submit a Generation Task

Body Parameters

Response Fields

Query Task Status

Path Parameters

Response Fields

Error Codes

​Model Selection

​Voice Source

​Material Upload

​Calling Conventions

​Base URL

​Authentication

​Response Envelope

​Business Errors

​Task Lifecycle

​Submit a Generation Task

​Body Parameters

​Response Fields

​Query Task Status

​Path Parameters

​Response Fields

​Error Codes

Model Selection

Voice Source

Material Upload

Calling Conventions

Base URL

Authentication

Response Envelope

Business Errors

Task Lifecycle

Submit a Generation Task

Body Parameters

Response Fields

Query Task Status

Path Parameters

Response Fields

Error Codes