Query assets
Look up your assets and check a previously submitted model preparation. Save the same asset_id throughout upload, polling and generation.
Query the asset list
curl "https://moonnexai.com/v1/assets?group_id=group_xxx&type=image&p=1&page_size=20" \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>"List query parameters
| Parameter | Meaning |
|---|---|
p | Page number, starting at 1. |
page_size | Page size, default 10, up to 100. |
group_id | Optional group owned by the current account. |
type | Optional image, audio, video or file. |
domain | Optional usage domain, such as media. |
status | Optional asset record state. |
Use p, not page, for pagination.
List response fields
The envelope contains object=list, data[], count (items on this page), total (matching items), and request/trace IDs. Assets are in data, not items.
Query asset details
curl https://moonnexai.com/v1/assets/asset_xxx \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>"Detail query parameters
The path uses your asset_id, such as asset_xxx. An optional group_id checks group membership; a mismatch returns not found. Use this registered /v1/assets/{asset_id} endpoint for current and existing clients.
Details use the model preparation selected during upload. Adding a different model query parameter does not create preparation for that model. While the asset is syncing, reading details attempts to synchronize the pending preparation; the list endpoint does not perform this synchronization.
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.
| State | Next action |
|---|---|
status=ready, preparation_status=ready, generation_ready=true | Use the reference only with a supported model and explicit media role. |
created / syncing | Keep the ID, wait briefly and read its detail again with bounded retries. |
preparation_status=failed or status=failed | Inspect sync_error and reported errors; resolve the cause before another attempt. |
disabled | The asset is no longer usable; update your saved references. |
Only generation_ready=false, without a clear pending state | Inspect the full detail; do not assume every false value will become ready through waiting. |
Review success alone does not override preparation failure. Readiness also does not guarantee generation success or immediate execution. Do not treat an OSS-only upload as proof of model-specific authentication.
Example response
{
"object": "asset",
"id": "asset_xxx",
"asset_id": "asset_xxx",
"asset_ref": "Asset://asset_xxx",
"reference": "Asset://asset_xxx",
"group_id": "group_xxx",
"domain": "media",
"asset_type": "image",
"source_url": "https://example.com/reference.png",
"url": "https://example.com/reference.png",
"oss_url": "",
"status": "ready",
"sync_status": "ready",
"preparation_status": "ready",
"generation_ready": true,
"review_status": "succeeded",
"review_passed": true
}Asset fields
| Fields | Meaning |
|---|---|
id / asset_id | MoonNexAI asset ID. |
asset_ref / reference | Reference for a supported generation input. |
group_id, domain, asset_type | Group, usage domain and media type. |
source_url, url, oss_url | Original and usable URLs; meanings depend on upload mode. |
content_type, size, duration | MIME type, bytes and audio/video duration in seconds. |
status, preparation_status, generation_ready | Record and preparation result. sync_status is the compatibility preparation field. |
review_status, review_passed, sync_error | Additional review information and preparation errors. |
request_id, trace_id | Safe IDs to provide for troubleshooting. |
Group isolation
Queries operate within the authenticated account. A group filter selects your own group, and a detail group check does not grant access to other accounts' media.
Usage recommendations
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.
Keep input URLs accessible for the model's required lifetime. A changed or expired source URL can invalidate reuse. See Manage assets for renaming, moving and disabling records.
Asset groups
See Asset groups for creation and membership.