Skip to content

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 ​

bash
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 ​

ParameterMeaning
pPage number, starting at 1.
page_sizePage size, default 10, up to 100.
group_idOptional group owned by the current account.
typeOptional image, audio, video or file.
domainOptional usage domain, such as media.
statusOptional 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 ​

bash
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.

StateNext action
status=ready, preparation_status=ready, generation_ready=trueUse the reference only with a supported model and explicit media role.
created / syncingKeep the ID, wait briefly and read its detail again with bounded retries.
preparation_status=failed or status=failedInspect sync_error and reported errors; resolve the cause before another attempt.
disabledThe asset is no longer usable; update your saved references.
Only generation_ready=false, without a clear pending stateInspect 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 ​

json
{
  "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 ​

FieldsMeaning
id / asset_idMoonNexAI asset ID.
asset_ref / referenceReference for a supported generation input.
group_id, domain, asset_typeGroup, usage domain and media type.
source_url, url, oss_urlOriginal and usable URLs; meanings depend on upload mode.
content_type, size, durationMIME type, bytes and audio/video duration in seconds.
status, preparation_status, generation_readyRecord and preparation result. sync_status is the compatibility preparation field.
review_status, review_passed, sync_errorAdditional review information and preparation errors.
request_id, trace_idSafe 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.

Related pages ​