Query media assets

media assets query is used to read the media assets list, media assets details and media assets status. When re-use media assets in task generation, it is recommended that media assets be confirmed as available.

Query media assets List

GET /v1/assets

curl "https://moonnexai.com/v1/assets?type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

If media assets is in the self-constructed group, group_id:

curl "https://moonnexai.com/v1/assets?group_id=group_xxx&type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

List query parameters

Parameters	Type	shall fill	Annotations
group_id	string	No	Asset group ID. When supplied, return only that group's assets; otherwise query the default group.
type	string	Yes	media assets type. Common values are image, audio, video, file.
status	string	Yes	media assets status. Common values are created, syncing, ready, failed, disabled.
domain	string	Yes	media assets domain. Common values are media.
page	integer	Yes	Page number, default 1.
page_size	integer	Yes	Number of pages per page, default 20.

List response fields

field	Type	Annotations
object	string	Fixed to list.
data	array	Array of assets; see Asset fields below for each entry.
count	integer	The current page returns the number.
total	integer	Total number of media assets eligible.
page	integer	Current page number.
page_size	integer	Number of pages per page.
request_id	string	request ID.
trace_id	string	Track ID.

Search for media assets details

GET /v1/assets/{asset_id}

curl https://moonnexai.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

If you need to verify whether media assets belongs to a group, you can upload group_id in the details query. If media assets is not in that group, returns unrecovered.

curl "https://moonnexai.com/v1/assets/asset_xxx?group_id=group_xxx" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

Compatible entry:

GET /api/asset/get

Details query parameters

Parameters	Type	shall fill	Annotations
group_id	string	Yes	For verifying whether media assets is in the specified group. media assets returns unrecovered when it is not in that group.

Asset fields

field	Annotations
object	object type, usually asset.
id	media assets ID, formatted as asset_xxx.
asset_id	media assets ID, and id equivalent.
group_id	Group ID of media assets.
domain	media assets domain. Common values are media.
type / asset_type	media assets type, common values image, audio, video, file.
name	Name of media assets.
description	media assets note.
source_url	You create the original public network URL that you enter when media assets is in.
url	URL available to the user. Usually equals source_url for mode=asset; for mode=oss or mode=both, usually a MoonNexAI OSS URL intended for testing.
oss_url	MoonNexAI OSS test URL. Only mode=oss or mode=both are usually of value and are not guaranteed for long periods.
reference / asset_ref	media assets references, formatted Asset://asset_xxx, that can be used to generate API in part.
content_type	File mimetype.
size	File size, bytes in units.
duration	Audio or video duration in seconds.
status	media assets is recorded. Common values are shown in the below status table.
sync_status	media assets reference readiness.
preparation_status	Preparation status before generation.
generation_ready	Whether to recommend immediate use for generating request.
review_status	media assets audit/availability results. Common values are succeeded, pending, failed, unknown.
review_passed	Whether or not media assets audit/availability check has been performed.
visibility	Visibility. Usually private.
created_at	Created.
updated_at	Update time.
request_id	request ID.
trace_id	Track ID.

Status fields

field	Common Values	Annotations
status	created, syncing, ready, failed, disabled	media assets record state.
sync_status	created, syncing, ready, failed	media assets reference readiness.
preparation_status	created, syncing, ready, failed, disabled	Are you ready to use to generate task?
generation_ready	true / false	Whether to immediately insert it into the generated request.
review_status	succeeded, pending, failed, unknown	media assets audit results. succeeded indicates that the media assets audit has been approved, but is not equal to the completion of the pre-generation synchronous.
review_passed	true / false	Whether or not media assets audit/availability check has been performed.
sync_error	string	Reason for asset synchronization failure; usually populated only on failure.

Before video generation, it is recommended that the following be confirmed:

status = ready
preparation_status = ready
generation_ready = true
review_status = succeeded
review_passed = true

If preparation_status=syncing or generation_ready=false, wait a little while to re-examine the same asset_id. Do not create a new media assets repeatedly for the wait for ready. If preparation_status=failed, look at sync_error, replace media assets or check if media assets URLs are publicly accessible.

Some media assets services return to "media assets has passed" and fail when synchronous goes to the generator. For example, when a photo hits a copyright or content policy, it may occur:

{
  "status": "failed",
  "preparation_status": "failed",
  "generation_ready": false,
  "review_status": "succeeded",
  "review_passed": true,
  "sync_error": "InputImageSensitiveContentDetected.PolicyViolation: The request failed because the input image may be related to copyright restrictions."
}

This means that the media assets audit was passed but could not be used for generation; please judge whether generation_ready and preparation_status are generated.

Example response

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "asset_type": "image",
  "group_id": "group_xxx",
  "domain": "media",
  "name": "reference.png",
  "description": "",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "oss_url": "",
  "reference": "Asset://asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "content_type": "image/png",
  "size": 245678,
  "duration": 0,
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "visibility": "private",
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "request_id": "2026060301010100000000000000000000",
  "trace_id": "2026060301010100000000000000000000"
}

Blocked

group_id is the client side custom group ID. Once media assets is uploaded into group_id, it is also suggested that the list and detailed query should be accompanied by the same group_id.

scene	Result
List Query Transfer group_id=group_xxx	returns media assets only under this group.
Detailed query is correct group_id	Returns normal media assets details.
Details Query Error group_id	Returns unrecovered, which can be used to verify the side save relationship.
Do Not Pass group_id	Use the default group.

Use recommendations

• Confirm generation_ready=true before generating task.
• If the newly created Asset://asset_xxx cannot be used for video generation for the time being, wait for a short time to retry with the same media assets reference.
• Maintain media assets ID, group ID, use, user or project correspondence in the business system.
• If media assets is not ready, save asset_id, trace_id and API original response.

Asset groups

GET /v1/asset-groups
POST /v1/asset-groups
GET /v1/asset-groups/{group_id}
PATCH /v1/asset-groups/{group_id}

Creates examples of groups:

curl https://moonnexai.com/v1/asset-groups \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-a",
    "description": "Project A materials"
  }'

Relevant Pages

• Upload Media Asset
• Uploading and Media Asset Overview
• Video Model Matrix
• API Reference