Skip to content

Upload assets ​

Create a reusable image, audio or video asset. Save the returned asset_id and asset_ref, then query its readiness before using a model reference.

Method and path ​

http
POST /v1/assets/uploads

Use the registered /v1/assets/uploads endpoint for current and existing clients.

Upload request ​

Use a public URL ​

For a model that supports asset references, submit its public model ID with the source URL:

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

mode=asset keeps the source URL and requests preparation for the chosen model. Keep that URL available; it does not promise a MoonNexAI-hosted copy. Replace the example URL with media you may use that allows anonymous downloads.

Upload a file for OSS testing ​

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

Use mode=oss for a test URL. For file uploads that also need model preparation, see mode options. OSS has no long-term retention or availability guarantee.

Upload to a group ​

Add "group_id": "group_xxx" to the JSON example, or -F "group_id=group_xxx" to multipart. Create the group first; omission uses your default group.

Common fields ​

FieldMeaning
url / filePublic URL in JSON, or a local multipart file.
typeMedia type: image, audio, video or file, subject to the model.
modelActual public model when requesting a model asset reference.
modeExplicitly choose asset, oss or both.
group_idOptional group belonging to your account.
purposeOptional purpose, such as video_reference.

JSON batches use urls; each URL creates an asset. Batch fields and media roles are documented in advanced options.

Response ​

A successful upload returns HTTP 200. This example is still preparing:

json
{
  "object": "asset",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "reference": "Asset://asset_xxx",
  "group_id": "group_xxx",
  "domain": "media",
  "asset_type": "image",
  "mode": "asset",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "reference_url": "https://example.com/reference.png",
  "status": "syncing",
  "sync_status": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false
}

An ID or URL alone does not prove readiness. Preserve this ID and query its detail.

Status fields ​

Before using an asset reference, require status=ready, preparation_status=ready and generation_ready=true, and confirm that the model selected during upload supports the reference. review_status / review_passed provide additional status information; they do not replace readiness. Resolve a reported review failure or error first. An available OSS URL does not establish Asset:// support for every model.

When a model requires an asset reference, send the actual target model and mode=asset in the upload request and save the returned asset_id. While it is syncing, query details for the same ID; detail queries attempt to synchronize the preparation already submitted. On failure, inspect sync_error instead of repeatedly uploading or proceeding with generation.

Full states and next actions are on Query assets.

Mode options ​

asset requests a model reference, oss creates a hosted test URL, and both requests both. See advanced options for URL meanings and complete examples.

Supported models ​

Use the model enabled for your API key and check its media requirements. Asset references are not interchangeable across model lines. See model selection.

Use an asset reference ​

After readiness is confirmed, put the returned Asset://asset_xxx in a supported media field. The role, number, size and duration of references still follow the generation model's limits. See the asset guide.

Asset groups ​

Use groups for project organization; membership does not establish model readiness.

Related pages ​