Video Generation

MoonNexAI video APIs create text-to-video, image-to-video and reference-based tasks. Video usually runs asynchronously: submission returns a task ID, then polling or a callback provides the final status and result.

This page only describes the call process and field engagement that will be applied to all video models. The model supports some type of media assets, role, aspect ratio, resolution, duration or audio control, which is based on the corresponding model details page and Video Model Matrix.

Basic processes

1. Select a currently available video model from the model list or model details page.
2. Confirm the mode of input, media assets quantity, role, aspect ratio, resolution and duration that the model supports.
3. Prepare reference media. Prefer stable public URLs from your own storage for production. Use the asset API when reuse is needed or the model explicitly requires an asset reference.
4. Call POST /v1/videos to create task.
5. Saves returned id or task_id, query by GET /v1/tasks/{task_id}.
6. Read and save a result URL only when status is succeeded and no error is present.

Unlock the portal

POST /v1/videos

Compatible entry:

POST /v1/video/generations

POST /v1/videos is a unified video task creation portal, but field does not have exactly the same capabilities and capabilities for different models. The client only submits the public standard field; the role conversion and model differences for models field, media assets are handled by the service side by model details.

text-to-video

(b) Submission of the generation parameters supported by models, prompt and models when media assets is not referenced:

{
  "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

Models that support the image reference can be used to use references[] and to describe media assets types and uses by media_type and role:

{
  "model": "your-video-model",
  "prompt": "Animate the product with a slow camera movement.",
  "references": [
    {
      "media_type": "image",
      "role": "first_frame",
      "url": "https://example.com/product.png"
    }
  ],
  "duration": 5,
  "aspect_ratio": "1:1"
}

Multi-media assets input

For models that support multi-media assets, you can submit pictures, videos and audio in the same references[]. Each entry should clearly indicate media_type, role and media assets addresses:

{
  "model": "your-video-model",
  "prompt": "Keep the subject appearance from the image and follow the motion in the video.",
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/subject.png",
      "alias": "subject"
    },
    {
      "media_type": "video",
      "role": "reference_video",
      "url": "https://example.com/motion.mp4",
      "alias": "motion"
    },
    {
      "media_type": "audio",
      "role": "audio",
      "url": "https://example.com/music.mp3",
      "alias": "music"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9"
}

references[].alias must be unique within a request and omit @. Use @alias in prompts only where the model page explicitly supports it. Roles such as first_frame, last_frame, reference_image, reference_video and audio cannot be inferred from file type alone; follow the model's field definitions.

Enter media assets

URL

The following conditions must be met for the public network media assets:

• Accessible without login or extra authentication headers.
• Maintains validity during task creation and execution without the temporary signature address that will quickly expire.
• response Content-Type corresponds to the type of media that the statement is made.
• The file size, resolution, duration and total media assets quantities correspond to the selected model limits.

Check image, video and audio URLs before submission. If any reference cannot be confirmed accessible, repair or replace it first. Do not include expired URLs.

references[] and compatible field

Models supporting universal media assets protocols are recommended references[]:

field	Purpose
media_type	image, video or audio type of media assets
role	first frame, last frame, General Reference, reference video, or Audio, etc., the value of which is based on the model page.
url	The customer has its own public network media assets address or media assets reference address that the model clearly supports.
alias	An optional prompt quotes aliases, which should be the only one within the same request.

images[], videos[], audios[], content[], image_url, video_url and audio_url remain compatible where supported. Availability, precedence and structure depend on the model page. Do not copy one model's fields to another without checking.

media assets Reference

If the model requires an asset ID or long-term reuse is needed, call the asset API and explicitly pass the returned reference in the video request. See asset APIs and the model page for uploads, authentication and expiration. Not all models accept the same reference type.

Common parameters

field	Type	Annotations
model	string	Current available video model ID.
prompt	string	The description of the subject, scene, action, lens and style.
references	array	The recommended multi-media assets input array, with capabilities and quantities based on model pages.
images / videos / audios	array	Compatible input field by media type.
duration / seconds	number / string	Target duration or compatible duration field, within the model's supported range.
aspect_ratio / ratio	string	Draw aspect ratio, which is based on the range of support provided by the model.
resolution	string	resolution, based on the range of support provided by the model.
generate_audio	boolean	Only if the model details page is explicitly supported.
metadata	object	Model-supported extension parameters.
callback_url	string	Optional HTTPS callback address.

Successful task creation does not mean generation has finished. Check the query response's status and error fields; an HTTP success or task ID alone is insufficient.

Query task

curl https://moonnexai.com/v1/tasks/task_01HX... \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

Common state:

Status	Annotations
pending	Systems are in preparation.
submitted	Submitted, pending processing.
running	Generating.
succeeded	Completed, readable.
failed	Task failed; inspect error.
cancelled	task cancelled.

Clients should use an incremental interval of polling and stop polling when business time is over. callback and polling can be used simultaneously, but should be reprocessed with the same task ID.

Results and Downloads

field, output, url, video_url or result_url, etc., is only read if status=succeeded and error is empty. The result addresses may be in arrays, objects or metadata, and the client should resolve and preserve the full address according to the actual response structure.

You can also call after task success:

GET /v1/videos/{task_id}/content

This endpoint is a download fallback. Do not call it before completion or after failure, and do not treat URL presence as success. Follow response redirects and archive media in your own storage as needed.

Cancel task

Uncompleted video task can call Cancel API:

curl -X POST https://moonnexai.com/v1/videos/task_01HX.../cancel \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

Whether cancellation stops an executing model task depends on remote_cancel and model capabilities. Cancellation and refunds are separate related operations. Check the final state and refund fields; avoid duplicate cancellation requests.

Recommendation troubleshooting

• Create failure: Record request ID, task ID (if returned), model ID and security error summary; check model field and media assets accessibility first.
• Long time outstanding: Continue searching for the same task and do not create task because the client is time-out.
• task failed: View error and task chain summaries to distinguish between creation, polling, media assets preparation and results downloading.
• Result cannot be downloaded: preserve the task response and HTTP status, then retry the download or use /content; do not generate again.
• billing Question: Based on task status, withholding record and refund record, the judgement cannot be based solely on the front end display or result URL.

prompt suggests keeping it simple and clear: describe the subject, action, environment and lens; refer to media assets ' s reservation requirement in prompt; and avoid mixing undeclared roles or controls over field on a request model page at a time.

For more field and response structures, please look at Create Video Job, Query Video Job, Video Model Matrix and the details of the specific model.