Elements & Voices (Element / Voice)
The v3 series supports elements (custom subjects) in image-to-video; the v2.6 / omni series supports voices (custom dubbing). Create elements and voices first via two management models (async tasks, free of charge), then reference them in generation requests through metadata.contents.
Create and Query
Step 1: create and query — call the management model with the chat format; business parameters all live in metadata (the messages content plays no business role), and the response content is the raw upstream JSON string:
Management operations are free (upstream quota is constantly "0").
Management operations are free; the platform offers no element / voice listing API, so keep element_id / voice_id safe. Deleted assets can no longer be referenced. Preview links are temporary — download promptly.
Reference in Generation Requests
Step 2: reference in generation requests — asset references live in the metadata.contents array, one item per asset:
Rules:
- Limits: at most 3 elements (v3 / v3-omni / o1 only) and 2 voices (v2.6 / v3 / omni series).
- Requests referencing a voice must carry
audio(nativefor v2.6 / v3,native/originalfor omni / o1): a voice needs sound; silent videos do not support voices — violations get a 400 before submission. - Use
@element_namefor elements and@indexfor voices; do not mix the two. Avoid element names that are prefixes of one another (e.g.@Zhangvs@ZhangSan).
Single element / voice:
Multiple Elements / Voices
Multiple elements / voices: add more items to the contents array — a two-voice contents (v2.6 image-to-video, two characters talking):
Use @narr and @guest in the prompt to assign lines:
Direct Assets & Video Editing
Besides elements / voices, metadata.contents accepts direct asset items, and metadata.options carries task options:
Most common scenario — omni editing of an existing video (base video + keep original audio):
When editing videos (base_video / feature_video), pass size explicitly (e.g. 1280x720, matching the base video): without it the output defaults to 16:9 instead of following the source. audio: "original" requires the reference video to carry an audio track; text-to-video output on this platform is silent, so prefer source material with an audio track for editing.
Asset URLs must be publicly downloadable direct links (images jpg/jpeg/png ≤ 50MB, both dimensions ≥ 300px; audio ≥ 5 seconds; video mp4/mov ≤ 200MB). Direct links from reputable sites generally work (your own domains, mainstream object storage, etc.), but some sites fail upstream fetches (w3school.com.cn and the overseas image host wikimedia are known to fail; failed image/audio fetches are not charged). If you see a "fetch failed" error, switch to another source. Note in particular: when video assets such as base_video fail to fetch, the task does not error and still bills at the editing price, but the output has nothing to do with the base video — verify the link is reachable before editing (output links on this platform expire in about 45 minutes and cannot be reused as base videos). Prefer direct links on your own domain, links produced by this platform (most stable), or Base64 input.
