Uploads and assets
Use a public media URL directly when the generation API accepts it. Create an asset when the model requires an asset reference or you need to reuse media.
Choose a workflow
| Your input | Next step |
|---|---|
| A stable public URL accepted by the model | Include it in the generation request. |
| A reusable model asset reference | Upload the URL, then check readiness. |
| A local file for integration testing | Upload with multipart and use the returned URL where supported. |
| Assets organized by project | Create an asset group and pass its group_id. |
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.
IDs, URLs and readiness
asset_xxx identifies your MoonNexAI asset. Asset://asset_xxx is a reference accepted only by supported models; put it explicitly in the generation request. Uploading does not attach the asset to later tasks automatically.
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.
MoonNexAI OSS is for integration testing, with no long-term retention or availability guarantee. For production media, use storage you control with stable URLs that allow anonymous downloads. Check the console and actual usage records for upload and preparation billing; generation is billed separately by its model.