Advanced asset options
The main workflow is upload, then query. This page covers modes, URL fields and existing-client aliases.
Choose a mode
| Mode | Behavior | Use |
|---|---|---|
asset | Keeps the public source URL and requests a model asset reference. | A supported model needs reusable media. Send its actual model. |
oss | Creates a MoonNexAI-hosted test URL. | Local-file integration tests; it does not authenticate media for every model. |
both | Requests a hosted copy and a model asset reference. | You need both results, and the target model supports asset creation. |
Use oss as the general file-upload example. both needs a supported target model. File asset uploads are accepted only when the selected model supports that creation flow; do not assume every model accepts a multipart asset. If a generation API accepts a file directly, you may use its own multipart contract instead.
Both outputs
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": "both",
"type": "image",
"url": "https://example.com/reference.png"
}'Only use the resulting reference after its preparation succeeds. A hosted URL can exist while model preparation is pending or failed.
URL fields
| Field | Meaning |
|---|---|
source_url | URL actually used for the asset: usually your source in asset mode, but it may be the hosted URL after copying. |
url | Usable URL; usually the source for asset, and a hosted URL for oss / both. |
oss_url | Hosted test URL when a copy was created; it may be empty. |
asset_ref / reference | MoonNexAI Asset://asset_xxx, not a public HTTP URL. |
Keep the complete returned URL, including any query needed for access. Never send your API key to a media host. OSS is for testing and does not guarantee long-term storage or availability. Check the console and actual records for upload and preparation billing; generation has its own model billing.
When copying changes the source URL, the upload response may include the original URL as input_url. Save it from that response when needed; the detail response does not promise to return the original input URL.
Batch URLs and media roles
Use either url or urls, with a common type, model, mode and optional group_id. Each URL creates an asset. A single result is an asset object; multiple results use object=list, data[] and count. Keep every returned ID and inspect each state.
Optional purpose, role and subject_type express a supported model's media purpose. They do not bypass media limits or enable unsupported features. Upload names and descriptions are edited afterward through Manage assets.
Model selection
Use the actual generation model enabled for your account; the upload example uses seedance-2.0-kz-fast. Check its model page for media types, roles, counts and duration limits. A successful upload for one model does not prove that another model can use the reference. The detail query reports existing upload preparation; it does not select another model's preparation through a query parameter.
For models that accept public media URLs, use your stable URL directly when a model asset reference is unnecessary. Uploading does not automatically add media to a generation request.
Existing-client endpoints
| Operation | Preferred path | Existing alias |
|---|---|---|
| Upload | POST /v1/assets/uploads | Use the same registered endpoint. |
| Detail | GET /v1/assets/{asset_id} | Use the same registered endpoint. |
POST /v1/assets also accepts the current media upload fields. It does not introduce separate identity, archive and preparation stages. The documented Nex workflow uses preparation requested during upload and continued through detail queries. Separate model-preparation, archive, official-media management and liveness-session APIs are not part of this site's current documented asset API.