Upload and media assets Overview

Upload and asset APIs explicitly upload images, audio and video for reuse in generation tasks. Calling a generation API does not automatically create a hosted URL or Asset://asset_xxx reference; asset preparation requires a separate request.

When to use media assets

scene	Recommendations
File has stabilized public network URL	The URL is passed directly in the request generation and is recommended for priority use.
Use pictures or audio only at one task	Usually the URL is passed directly to a simpler URL.
The media assets ID is required to manage user assets	Call `/v1/assets/uploads` with an existing public network URL, save the returned media assets ID.
Target model explicitly supports media assets quotes	Prefer `mode=asset` to create `Asset://asset_xxx` media assets references.
Local files need to be temporarily converted to a public network URL when connected	Creates a URL using `mode=oss` MoonNexAI OSS.
An OSS test URL and model media assets references are required for alignment	`mode=both` is used; this is an advanced scenario and is not recommended as a default option.

Route List

Methodology	Path	Purpose
`POST`	`/v1/assets/uploads`	Upload media assets.
`GET`	`/v1/asset-groups`	Query media assets grouping.
`POST`	`/v1/asset-groups`	Creates a group of media assets.
`GET`	`/v1/asset-groups/{group_id}`	Find out the media assets group details.
`PATCH`	`/v1/asset-groups/{group_id}`	Updates the name or description of the group media assets.
`GET`	`/v1/assets`	Query media assets list.
`GET`	`/v1/assets/{asset_id}`	Find media assets details.
`POST`	`/api/asset/createMedia`	Compatible media assets creation portal.
`GET`	`/api/asset/get`	media assets compatible query portal.

The scene entrance.

POSTUpload assets uploads pictures, audio or video, takes URL or media assets references. GROUPAsset groups creates groups and isolates media assets with group_id. GETQuery assetsRead asset lists, details, status and troubleshooting fields.

Upload request

bash

curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -F "file=@./product.png" \
  -F "type=image" \
  -F "purpose=video_reference" \
  -F "mode=oss"

You can also create media assets references with already existing public web URLs:

bash

curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-kz-fast",
    "mode": "asset",
    "type": "image",
    "url": "https://example.com/reference.png"
  }'

If your public network URL is stable and accessible, it is recommended that JSON request be used to create media assets ID; MoonNexAI saves the URL you have transferred, and will not be transferred to MoonNexAI hosting storage by default.

Mode Description

mode	Behaviour	Fit to scene
`asset`	Creates the `Asset://asset_xxx` media assets reference, saves the URL of the public network you have entered.	The target model clearly supports the media assets reference and media assets needs to be reused.
`oss`	Creates the MoonNexAI OSS test URL.	For use only in connection testing, not as a long-term business memory.
`both`	Creates both the hosting URL and `Asset://asset_xxx` media assets references.	Advanced scene: The same media assets is directly accessible and is referenced in the model.

mode=oss uploads and mode=asset authentication are currently free, as are both preparation steps in mode=both. MoonNexAI OSS is for integration testing and does not promise long-term retention, permanent URLs, continuous availability or a long-term storage service level. For production use, supply anonymously accessible direct URLs from your own storage.

media assets may need a short preparation to be used for video generation after Asset://asset_xxx is created. If you immediately submit video task for an error that media assets is not available, wait for a short time to try again with the same Asset://asset_xxx; normally, media assets does not need to be recreated.

Models to support scavengers

Different video models support boundaries different from those supported by " upload media assets " and " quote media assets when generating " . The upload page is only responsible for the visible creation of MoonNexAI media assets records, hosting URLs or Asset://asset_xxx; can media assets references be used directly at the time of generation, which is based on the corresponding model page.

Models	Recommended Upload Mode	Upload to `Asset://`	Use `Asset://` on generation	Recommendations
`seedance-2.0-kz-fast`	`mode=asset` or `mode=both`	Supported	Supported	Prefer this group for long-term asset reuse.
`seedance-2.0-kz`	`mode=asset` or `mode=both`	Support	Support	Fits to higher quality task and full media assets reuses.
`seedance-2.0-cl-fast`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.0-kz-fast` is different from the model line, media assets ID does not mix across lines.
`seedance-2.0-cl`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.0-kz` is different from the model line, media assets ID does not mix across lines.
`seedance-2.0-cl-mini`	`mode=asset` or `mode=both`	Support	Support	Use the CL series media assets parameter system to support the image and video media assets reference; media assets ID do not mix with sighted-2.0-kz series across lines.
`seedance-2.5-cl`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.5-cl` must be prepared and wait for `generation_ready=true`, `preparation_status=ready`; request direct error is generated when reference resolve failed, without returning to public web URL.
`seedance-2.0-cl-b-fast`, `seedance-2.0-cl-b-mini`	`mode=asset` or `mode=both`	Support	Support	Create or confirm media assets by the selected official Fast / Mini; media assets ID does not mix the Seedance-2 model.
`seedance-2.0-sz`, `seedance-2.0-sz-fast`, `seedance-2.0-sz-mini`, `seedance-2.5-sz`	`mode=asset` or `mode=both`	Support	Support	Create or confirm media assets by target SZ model; support pictures, videos and audio references, media assets ID not to mix over model lines.
`seedance-2.0-gl`, `seedance-2.0-gl-fast`, `seedance-2.0-gl-mini`	`mode=asset`;stable URLs are available directly	Support	Support	media assets by target GL model; customer public network URL priority, multipart/`mode=oss` only as a select transfer.
`moon-2.0-am-720p-fast`	`mode=oss` or direct URL	Not the primary workflow	Not the primary workflow	Suitable for public or MoonNexAI-hosted URLs, one image, image + background music, and fast mixed-reference tasks.

When Asset://asset_xxx is used, create or confirm media assets by the actual generation model. The media assets preparation results of the different Seedance-2 model line are not cross-lined, e.g. media assets prepared by seedance-2.0-kz-fast is not directly used as media assets for seedance-2.0-sz-fast, seedance-2.0-cl-fast, seedance-2.0-cl-mini, seedance-2.0-cl-b-fast or seedance-2.0-gl-mini.

Asset groups

You can create your own media assets group and upload group_id in upload, list and detailed query. Under the same account, the media assets of the different groups will be isolated by group_id; the default group will be used when group_id is not passed.

Create group:

bash

curl https://moonnexai.com/v1/asset-groups \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-a",
    "description": "Project A materials",
    "domain": "media"
  }'

Save returned group_id after successful creation, upload and import:

json

{
  "model": "seedance-2.0-kz-fast",
  "mode": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://example.com/reference.png"
}

group_id:

bash

curl "https://moonnexai.com/v1/assets/asset_xxx?group_id=group_xxx" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

If media assets is not in the group, return unrecovered. See Asset groups for details field.

Status judgement

field	Common Values	Annotations
`status`	`created`, `syncing`, `ready`, `failed`	Status of the MoonNexAI asset record.
`sync_status`	`created`, `syncing`, `ready`, `failed`	media assets reference readiness.
`preparation_status`	`created`, `syncing`, `ready`, `failed`, `disabled`	Are you ready to use to generate task?
`generation_ready`	`true` / `false`	Whether to immediately insert it into the generated request.

Before video generation, it is recommended that the following be confirmed:

text

status = ready
preparation_status = ready
generation_ready = true

If preparation_status=syncing or generation_ready=false, wait a little while to re-examine the same asset_id, do not create media assets.

Example response

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://example.com/reference.png",
  "source_url": "https://example.com/reference.png",
  "oss_url": "",
  "reference": "Asset://asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

Conversation APIs

Embeddings

Audio

Models

GPT Image

Gemini Nano

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload and media assets Overview

When to use media assets

Route List

The scene entrance.

Upload request

Mode Description

Models to support scavengers

Asset groups

Status judgement

Example response

Relevant Pages

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload and media assets Overview ​

When to use media assets ​

Route List ​

The scene entrance. ​

Upload request ​

Mode Description ​

Models to support scavengers ​

Asset groups ​

Status judgement ​

Example response ​

Relevant Pages ​

Upload and media assets Overview

When to use media assets

Route List

The scene entrance.

Upload request

Mode Description

Models to support scavengers

Asset groups

Status judgement

Example response

Relevant Pages