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
POST /v1/assets/uploadsUse 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:
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
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
| Field | Meaning |
|---|---|
url / file | Public URL in JSON, or a local multipart file. |
type | Media type: image, audio, video or file, subject to the model. |
model | Actual public model when requesting a model asset reference. |
mode | Explicitly choose asset, oss or both. |
group_id | Optional group belonging to your account. |
purpose | Optional 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:
{
"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.