Avatar Video Generation

This page covers asynchronous video generation powered by Vivix-A1: you provide a first-frame image plus either an audio clip, a line of dialogue, or an ordered sequence of segments, 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). In multi-segment requests, configure the voice source inside each segment (audio_url / audio_data for a2v, or dialogue + voice_id for ta2v). 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 and audio (or segments[].audio_url in multi-segment requests).

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

Multi-Segment Generation

By default, POST /v1/videos/generations generates a single video clip from the root-level fields (prompt, first_frame_image, and either audio / audio_data or dialogue + voice_id). To combine multiple speaking turns and silent listening pauses into a single continuous output video (playback_url), pass the segments array (1 to 20 segments per request). Each item in segments defines its own mode and prompt:

Segment `mode`	Required & optional segment fields	Description
`a2v` (audio-driven speech)	`prompt` + (`audio_url` or `audio_data`)	Drives lip sync and performance from an audio URL (`audio_url`) or Base64 audio (`audio_data`). Segment duration matches the audio length.
`ta2v` (dialogue TTS speech)	`prompt` + `dialogue` + `voice_id` (+ optional `tts_config`)	Synthesizes speech from `dialogue` on the server and drives the character with the generated audio. Segment duration matches the synthesized speech length.
`a2v` or `ta2v` (silent pause)	`prompt` (+ optional `duration_ms`)	Omit `audio_url` / `audio_data` (for `a2v`) or `dialogue` (for `ta2v`) to generate a silent listening or reaction segment. Duration is controlled by `duration_ms` and defaults to `6000` ms (6 seconds) when omitted.

Key rules when segments is provided:

Default vs. per-segment first_frame_image: Set first_frame_image at the root level as the default reference image for the task. Segments that omit first_frame_image automatically inherit the root first_frame_image; you can also set first_frame_image on a specific segment to switch to a different reference image for that segment.
No root-level speech inputs: Place all prompts (prompt), audio (audio_url, audio_data), and dialogue (dialogue, voice_id, tts_config) inside the corresponding items of segments. Setting audio, audio_data, or dialogue at the root level alongside segments returns HTTP 422 (code = 30004).
Audio URL field name: Inside segments[], pass the audio URL in audio_url (whereas single-segment requests use audio at the root level).
Voice configuration in ta2v segments: When a segment uses mode: "ta2v" with dialogue, voice_id is required on that segment. Pass a provider voice ID from Choose a voice along with the matching tts_config.

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 single-segment or multi-segment video generation task. POST /v1/videos/generations

Body Parameters

string

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

string

Main video prompt describing the shot and the performance. Required for single-segment requests; when segments is provided, specify prompt inside each segment instead.

string

required

Character first-frame image URL. Required; for the expected size see Material Upload. In multi-segment requests, this root field serves as the default reference image across all items in segments.

string

TTS dialogue text for a single-segment dialogue request. Cannot be combined with segments (set dialogue inside segments[] instead).

string

Voice id for a single-segment dialogue request; see Voice Source.

string

Audio URL for a single-segment audio request. Send at most one of audio or audio_data. Cannot be combined with segments (set audio_url inside segments[] instead).

string

Base64-encoded audio for a single-segment audio request. Send at most one of audio or audio_data. Cannot be combined with segments (set audio_data inside segments[] instead).

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.

object[]

Ordered list of segments (1 to 20 items) for multi-segment generation. All segments are rendered in sequence into a single output video (playback_url). When segments is provided, do not set audio, audio_data, or dialogue at the root level.

Show properties

string

required

Generation mode for this segment: a2v (audio-driven or silent pause) or ta2v (dialogue TTS or silent pause).

string

required

Visual and performance prompt for this segment.

string

First-frame image URL for this segment. Optional: when omitted, this segment inherits the root first_frame_image; set it only when you want this segment to start from a different reference image.

string

Driving audio URL for an a2v segment. Provide at most one of audio_url or audio_data. Omit both on an a2v segment to generate a silent listening or reaction segment for duration_ms milliseconds.

string

Base64-encoded driving audio for an a2v segment. Provide at most one of audio_url or audio_data.

string

TTS dialogue text for a ta2v segment. When dialogue is set, voice_id is also required on the segment. Omit dialogue on a ta2v segment to generate a silent listening or reaction segment for duration_ms milliseconds.

string

Provider voice id for a ta2v segment (required when dialogue is provided); see Choose a voice.

object

Fine-grained TTS settings for a ta2v segment (vol, seed, speed, stability, tts_model_id, tts_provider). Uses the same structure as the root tts_config.

integer

Duration in milliseconds (> 0) for a silent a2v or ta2v segment (when neither audio nor dialogue is provided in the segment). Defaults to 6000 (6 seconds) when omitted. For speaking segments, duration is determined automatically by the audio or synthesized speech length.

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"
}'

Multi-segment 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",
  "first_frame_image": "https://static.vivi-x.ai/images/2026/09/16/xxxxxxxxxxxxxxxx.png",
  "resolution": "720p",
  "video_ratio": "16:9",
  "segments": [
    {
      "mode": "a2v",
      "prompt": "A confident host greets the audience with a warm smile.",
      "audio_url": "https://static.vivi-x.ai/audios/2026/09/16/part1.mp3"
    },
    {
      "mode": "a2v",
      "prompt": "The host listens attentively and nods gently.",
      "duration_ms": 3000
    },
    {
      "mode": "ta2v",
      "prompt": "The host responds with enthusiasm and gestures naturally.",
      "dialogue": "Let us dive right into today'\''s highlights.",
      "voice_id": "<elevenlabs_voice_id>",
      "tts_config": {
        "tts_provider": "elevenlabs",
        "tts_model_id": "eleven_v3",
        "speed": 1,
        "vol": 1
      }
    }
  ]
}'

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.

int32

Duration of the generated video in milliseconds (for multi-segment tasks, the total duration across all segments); 0 while the task is still in progress.

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 missing speech inputs in a single-segment request, invalid `segments[].mode`, missing `segments[].prompt`, `duration_ms <= 0`, or combining root-level speech fields (`audio` / `audio_data` / `dialogue`) with `segments`
50001	internal error	500	Internal error
50003	service unavailable	503	Service unavailable

Two error layers. The outer code is an API-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

Multi-Segment Generation

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