Upload media assets

Upload media assets to create reusable pictures, audio or video resources. After uploading successfully, MoonNexAI returns media assets ID, accessable URL, media assets quotes and status information.

If media assets already has a stable public network URL, it is recommended that media assets ID be created with JSON request to url. MoonNexAI saves the URL you have imported; MoonNexAI hosting URLs only be created when mode=oss or mode=both is used.

MoonNexAI OSS is for integration testing. Uploads and asset authentication are currently free, but long-term retention, permanent URLs, continuous availability and long-term storage service levels are not promised. Use your own storage for production, with stable public URLs that require neither login nor additional headers.

Method and Path

http

POST /v1/assets/uploads

Compatible entry:

http

POST /api/asset/createMedia

Upload request

Use customer network URL

This method is recommended for priority. MoonNexAI will save the URL you have entered; it will not be transferred to MoonNexAI hosting storage by default unless you use mode=oss or mode=both in a visible way.

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

Upload file to MoonNexAI OSS Test URL

This URL is not a long-term media assets address for a customer's official business.

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"

File upload only supports mode=oss or mode=both. If the target generates API as a binary file, you can also submit the file directly as required by generating API without having to create media assets first.

Upload to the specified group

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",
    "group_id": "group_xxx",
    "url": "https://example.com/reference.png"
  }'

Common field

field	Type	Annotations
`file`	file	File to upload.
`url`	string	Optional. A public network file URL already exists. It is commonly used when using JSON request.
`group_id`	string	Optional. media assets Group ID; use default grouping when not passing.
`model`	string	Optional. It is recommended that the target model name be entered when media assets references are created.
`type`	string	media assets type, common values `image`, `audio`, `video`.
`purpose`	string	Optional. media assets uses, e.g. `video_reference`, `digital_human_avatar`, `voice_training`.
`mode`	string	Optional. `oss`, `asset` or `both`. Suggested for explicit entry.

JSON request can pass url or urls. urls is used to submit multiple public network URLs at a time; each URL creates a media assets record.

Mode Selection

mode	Save Contents	Main return	Fit to scene
`asset`	Saves the customer's public network URL and creates a media assets reference.	`id` / `asset_id`, `reference` / `asset_ref`.	Models clearly support `Asset://asset_xxx`, media assets needs to be reused.
`oss`	Creates the MoonNexAI OSS test URL.	`id` / `asset_id`, `url`, `oss_url`.	For use only in connection testing, not as a long-term business memory.
`both`	Saves both the URL and media assets references.	Returns `url`/ `oss_url` and `reference`/`asset_ref` at the same time.	Advanced scene: The same media assets is to be accessed directly and used for the media assets reference.

Two layers of asset results

MoonNexAI returns the customer stable media assets ID:

text

asset_id = asset_xxx
asset_ref = Asset://asset_xxx

media assets may have two layers of results at the same time, depending on mode:

field	Meaning
`source_url`	The URL you enter is the original public network. This is the URL when `mode=asset` is used.
`url`	URL available to the user. Usually equals `source_url` for `mode=asset`; usually a MoonNexAI-hosted URL for `mode=oss` / `both`.
`oss_url`	MoonNexAI hosts URLs. Only `mode=oss` or `mode=both` are usually of value.
`reference` / `asset_ref`	media assets references, formatted `Asset://asset_xxx`, that can be used to generate API in part.
`content`	Enables you to enter the content clip that generates request directly. Pictures are usually `content.image_url.url`.

If your file has a stable public network URL, use mode=asset as a priority; only if the connection test requires a temporary OSS URL will use mode=oss. mode=both is an advanced scenario and is not recommended as a default option. Both the OOSS upload and the media assets authentication are free, but any preparatory action fails will affect the ultimate availability.

Supporting models

mode=asset is only suitable for a scenario created by the target model that explicitly supports the media assets reference. When using a different model line, use Seedance-2 to create or confirm media assets by actually generating a model and avoid mixing media assets IDs of different models.

Models	Upload to `Asset://`	Recommended Mode	Annotations
`seedance-2.0-kz-fast`	Support	`asset` / `both`	Fits to media assets for images, videos, audio, etc.
`seedance-2.0-kz`	Support	`asset` / `both`	Fits to higher quality task and long-term media assets reuses.
`seedance-2.0-cl-fast`	Supported	`asset` / `both`	A different model line from `seedance-2.0-kz-fast`; do not mix asset IDs between lines.
`seedance-2.0-cl`	Supported	`asset` / `both`	A different model line from `seedance-2.0-kz`; do not mix asset IDs between lines.
`seedance-2.0-cl-mini`	Support	`asset` / `both`	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`	Support	`asset` / `both`	Press `seedance-2.5-cl` to prepare the authentication media assets; the status must be ready and the authentication reference failure cannot be downgraded to a public network URL.
`seedance-2.0-cl-b-fast`, `seedance-2.0-cl-b-mini`	Support	`asset` / `both`	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`	Support	`asset` / `both`	Create or confirm media assets by target SZ model; support pictures, videos and audio references, media assets ID not to mix over model lines.
`moon-2.0-am-720p-fast`	Not the primary workflow	`oss` or direct URL	Prefer public URLs, MoonNexAI-hosted URLs or `references[]` for new integrations. Suitable for one image, image + background music and fast mixed-reference tasks.

If you do not determine whether the target model supports mode=asset, confirm the media assets policy by the corresponding model page. After media assets is created successfully, it is recommended that asset_id, asset_ref, target model and media assets status be maintained in the operating system at the same time.

Use media assets Reference

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.

Passing asset review, review_status=succeeded or generation_ready=true means the asset is available for reference. It does not make later video tasks use it automatically. Put Asset://asset_xxx into an input such as image, reference_image_urls, first_frame_url or content[] when creating the video.

Example:

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "mode": "fast",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": true,
  "watermark": false,
  "web_search": false,
  "input_type": "reference",
  "generation_type": "video",
  "content": [
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "Asset://asset_xxx"
      }
    }
  ]
}

The following request does not load an asset because it contains no image URL or asset reference:

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "input_type": "reference",
  "duration": 5
}

Asset groups

If you need to isolate media assets by project, user or business scene, you can create a grouping of media assets and then upload group_id:

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

json

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

See Asset groups for detailed group API.

Status fields

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`	Preparation status before generation.
`generation_ready`	`true` / `false`	Whether to recommend immediate use for generating request.
`review_status`	`succeeded`, `pending`, `failed`, `unknown`	media assets audit results. `succeeded` indicates that the media assets audit has been approved, but is not equal to the completion of the pre-generation synchronous.
`review_passed`	`true` / `false`	Whether or not media assets audit/availability check has been performed.
`sync_error`	string	Reason for asset synchronization failure; usually populated only on failure.

It is recommended that, before generation, confirmation be given that:

text

status = ready
preparation_status = ready
generation_ready = true
review_status = succeeded
review_passed = true

If generation_ready=false or preparation_status=syncing, do not recreate media assets. Wait for a short time to search for the same asset_id, ready to continue with the same Asset://asset_xxx. If preparation_status=failed, look at sync_error, replace media assets or check if media assets URL is publicly accessible.

Some media assets services return to "media assets has passed" and fail when synchronous goes to the generator. For example, when a photo hits a copyright or content policy, it may occur:

json

{
  "status": "failed",
  "preparation_status": "failed",
  "generation_ready": false,
  "review_status": "succeeded",
  "review_passed": true,
  "sync_error": "InputImageSensitiveContentDetected.PolicyViolation: The request failed because the input image may be related to copyright restrictions."
}

This means that the media assets audit was passed but could not be used for generation; please judge whether generation_ready and preparation_status are generated.

Example response

mode=asset

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": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

mode=asset may return to syncing when it is created. Query to generation_ready=true before it is used for video generation.

mode=both

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://media-nex.windfimusic.com/user-assets/image/example.png",
  "source_url": "https://example.com/reference.png",
  "oss_url": "https://media-nex.windfimusic.com/user-assets/image/example.png",
  "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
}

mode=both is only used when an OSS test URL and model media assets are required for a connection. If it is only a one-time creation, it is easier to pass the client 's own public network URL; if only media assets is required, use mode=asset; if only a temporary test URL is required, use mode=oss.

Conversation APIs

Embeddings

Audio

Models

GPT Image

Gemini Nano

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload media assets

Method and Path

Upload request

Use customer network URL

Upload file to MoonNexAI OSS Test URL

Upload to the specified group

Common field

Mode Selection

Two layers of asset results

Supporting models

Use media assets Reference

Asset groups

Status fields

Example response

mode=asset

mode=both

Relevant Pages

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload media assets ​

Method and Path ​

Upload request ​

Use customer network URL ​

Upload file to MoonNexAI OSS Test URL ​

Upload to the specified group ​

Common field ​

Mode Selection ​

Two layers of asset results ​

Supporting models ​

Use media assets Reference ​

Asset groups ​

Status fields ​

Example response ​

mode=asset ​

mode=both ​

Relevant Pages ​

Upload media assets

Method and Path

Upload request

Use customer network URL

Upload file to MoonNexAI OSS Test URL

Upload to the specified group

Common field

Mode Selection

Two layers of asset results

Supporting models

Use media assets Reference

Asset groups

Status fields

Example response

mode=asset

mode=both

Relevant Pages