Create a video task
Video creation API is used to submit text-to-video, image-to-video and reference media assets video task. task is successful and returns id or task_id and requires a query to obtain the final result of API.
Method and Path
POST /v1/videosCompatible entry:
POST /v1/video/generationsStandard request
POST /v1/videos is the common video-task creation endpoint. Parameters, reference types and counts, and duration limits vary by model. Check its detail page before submitting. This page defines common task fields and reference structures, rather than a model catalog.
For models supporting common references, use references[]: media_type identifies the media type, role its purpose, and url the content URL or a supported asset reference. Legacy fields such as images[], videos[] and audios[] remain available where documented for the model.
Volcengine official parameters compatible
NT models seedance-2.0-nt, seedance-2.0-nt-fast, seedance-2.0-nt-mini and seedance-2.5-nt support /v1/videos and /api/v3/contents/generations/tasks, with compatible content[], ratio, resolution, duration, generate_audio and watermark. Both endpoints use NT public model IDs and a MoonNexAI key. Only 720P is supported; Mini is limited to 4 seconds, and 2.5 strict first/last-frame mode preserves the input aspect ratio. Poll NT tasks. See the NT guide for examples and authenticated asset limitations; do not assume callbacks or advanced parameters from other series apply.
seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini, seedance-2.5-sz, seedance-2.5-cl, seedance-2.0-cl-b-fast and seedance-2.0-cl-b-mini in /v1/videos compatible with official Volcengine shapes content[], ratio, resolution, duration, generate_audio, watermark, seed, callback_url et al. field. references[] and these field are two input expressions; the same request Do not submit content and references at the same time.
If the client must keep the Volcengine official request path, it can use:
POST /api/v3/contents/generations/tasksThe portal still uses MoonNexAI public model ID (e.g. seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini, seedance-2.5-sz, seedance-2.5-cl, seedance-2.0-cl-b-fast and seedance-2.0-cl-b-mini The client needs to replace the request path and continue to use MoonNexAI API Key, model to fill out the MoonNexAI public model ID listed on this page. Both access points share task. Rules for processing queries, status and results.
See compatible parameters for seedance-2.5-cl field mappings and a complete content[] example. Request-format compatibility does not imply support for every official parameter. Follow the model page's allowed values. In both formats, Asset:// references must be prepared for this model; failed resolution returns an error without falling back to a public URL.
CL-B compatible mixed-reference requests require a unique alias on each media entry to preserve prompt-to-asset bindings. See the CL-B guide for fields and capabilities.
Volcengine Official field to MoonNexAI field, SZ Model Borders and Conflict Rules seedance-2.0-sz / seedance-2.5-sz.
text-to-video
If media assets is not referenced, only prompt and the generating parameters required by the model shall be submitted:
{
"model": "your-video-model",
"prompt": "A cinematic product shot with a slow camera push-in and clean studio light.",
"duration": 5,
"aspect_ratio": "16:9"
}image-to-video
Pictures can be imported via references[] and are specified as first frame, last frame or normal reference images using role. The specific role is available, which is based on the model details page:
{
"model": "your-video-model",
"prompt": "Animate the product with a slow camera movement.",
"references": [
{
"media_type": "image",
"role": "reference_image",
"url": "https://example.com/product.png",
"alias": "product"
}
],
"duration": 5,
"aspect_ratio": "1:1"
}Multi-media assets input
Pictures, videos and audio can be placed in the same references[] array. The choice of the model is made by whether the audio supports separate submission, the maximum number of each media assets and the name of the role:
{
"model": "your-video-model",
"prompt": "Create a video using @hero and @music as references.",
"references": [
{
"media_type": "image",
"role": "reference_image",
"url": "https://example.com/hero.jpg",
"alias": "hero"
},
{
"media_type": "audio",
"role": "reference_audio",
"url": "https://example.com/music.mp3",
"alias": "music"
}
],
"duration": 5
}If the model does not yet cover the generic media assets protocol, please submit it exclusively by field and the example of the model page, and not by extrapolating the support range based on media type alone.
curl https://moonnexai.com/v1/videos \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "your-video-model",
"prompt": "A cinematic product shot of @product, slow camera push-in, clean studio light.",
"references": [
{
"media_type": "image",
"role": "reference_image",
"url": "https://example.com/product.png",
"alias": "product"
}
],
"duration": 14,
"aspect_ratio": "16:9",
"callback_url": "https://example.com/moonnexai/webhook"
}'Common parameters
| field | Type | Annotations |
|---|---|---|
model | string | Video model name. |
prompt | string | Video description. The proposal contains the subject, scene, lens, action and style. |
references | array | Optional. New access to complex media assets recommended arrays. Entry format { "media_type": "image", "role": "reference_image", "url": "...", "alias": "hero" }. |
image / image_url | string | Optional. Single source image URL; compatible with old writing. Support is described on the model page. |
images | array | Optional. Picture URL or media assets reference array. Whether first frame, last frame or reference images roles are supported, as indicated on the model page. |
reference_image_url / reference_image_urls | string / array | Optional. reference images URL or media assets reference. |
input_reference | string | Optional. Single reference images or first frame diagrams; only for models that support this field. |
first_frame_url / last_frame_url | string | Optional. first frame and last frame; support and format are based on the model page. |
video / video_url | string | Optional. reference video or URL to be extended; compatible with old writing. Support is described on the model page. |
reference_video_url / reference_video_urls | string / array | Optional. reference video URL or media assets reference. Some models do not support video references, based on the corresponding model page. |
videos | array | Optional. Video media assets arrays. Whether video references and roles are supported, as indicated on the model page. |
audio / audio_url | string | Optional. reference audio URL or media assets reference; compatible with old writing. Whether to allow a separate submission is based on the model page. |
audios | array | Optional. Audio media assets arrays. Support and quantitative limits, as on the model page. |
content | array | Optional. Multimedia content arrays supporting text, image_url, video_url, audio_url entries. |
duration | integer | Optional. Video duration, the exact value is based on the range of support provided by the model. |
seconds | string | Optional. The partial compatible model uses this field for duration. |
aspect_ratio / ratio | string | Optional. Video aspect ratio, e.g. 16:9, 9:16, 1:1. |
resolution | string | Optional. resolution, e.g. 480p, 720p, 1080p. |
video_config | object | Optional. Compatible format, common field, aspect_ratio, resolution_name. |
generate_audio | boolean | Optional. Controls whether to generate audio; whether to support, default and available values, as indicated on the model page. |
generateAudio | boolean | Optional field with the same semantics as generate_audio; new access preferred generate_audio. |
metadata | object | Optional. Extension parameters; model parameters content, duration, seconds, resolution can also be inserted. |
callback_url | string | Optional. After task is finished, receive the HTTPS address of callback. |
Common structure for references[] entries:
| field | Type | Annotations |
|---|---|---|
media_type | string | media assets type. Common values are image, video, audio, music. |
role | string | media assets uses. Common values are first_frame, last_frame, reference_image, reference_video, reference_audio, background_music, voice_reference, style_reference, character_reference. Audio reference usually requires both photo or video reference. |
url | string | URLs for the public network, MoonNexAI hosting URLs, or Asset://asset_xxx when the model is clearly supported. |
alias | string | Optional. media assets alias, not including @, and should be unique in the same request; @alias in prompt for media assets. The omission results in the order of the names in 图片1, 视频1, 音频1 by media type. |
asset_id / asset_ref | string | Optional. MoonNexAI media assets ID or media assets reference. Direct generation depends on model support. |
The internal order aliases @图片1 are compatible with the @图片 1 writings, 视频N, 音频N are the same; numbers can then continue directly with the body, such as @图片1保持人物外观. To facilitate reading, it is still recommended to add spaces or points to the aliases. Customized aliases must be separated from the subsequent body, for example, @主体 走到龙椅旁, not @主体走到龙椅旁.
An unmatched alias returns invalid_reference_alias; one alias bound to multiple different references returns duplicate_reference_alias. Aliases bind prompt references to assets but do not guarantee distinct identities for multiple people in the output. Specify each person's appearance, position, clothing and actions in the prompt.
Common structure for content[] entries:
| field | Type | Annotations |
|---|---|---|
type | string | text, image_url, video_url or audio_url. |
text | string | Text content. Video task usually uses the top layer prompt. |
image_url.url | string | Picture URL or media assets reference. |
video_url.url | string | Video URL or media assets reference. |
audio_url.url | string | Audio URL or media assets reference. |
asset_id / asset-id | string | Optional. MoonNexAI asset ID. |
asset_url | string | Optional. media assets Reference Address, e.g. Asset://asset_xxx. |
role | string | Media entries are recommended for completion. Common values are reference_image, first_frame, last_frame, reference_video, reference_audio; role is compatible with media assets for media type when a picture, video or audio entry is missing, but first frame, last frame, reference images binding audio for specific uses must be visible. |
Example response
{
"id": "task_01HX...",
"object": "task",
"status": "submitted",
"model": "your-video-model",
"created_at": 1710000000
}Successful compatible video responses may put the final URL in several fields for different SDKs. Check status first and read URLs only for succeeded. Do not read a URL for pending, submitted, running, failed or cancelled; read error for failed:
{
"id": "task_01HX...",
"task_id": "task_01HX...",
"object": "video",
"model": "your-video-model",
"status": "succeeded",
"url": "https://example.com/result.mp4",
"video_url": "https://example.com/result.mp4",
"output": {
"url": "https://example.com/result.mp4"
},
"metadata": {
"url": "https://example.com/result.mp4"
}
}Save after submitting
| field | Purpose |
|---|---|
id / task_id | Follow-up query on task status and results. |
model | Rewinding parameters, checking billing and queuing. |
trace_id / request_id | Use when contacting MoonNexAI for a check. |
| Original request body | (c) Enable retesting, comparison and positioning field differences. |