Query media assets

Asset queries read asset lists, details and status. This page also covers editing existing assets, moving them between groups and deleting them. An existing asset identity, an accessible managed copy and readiness for a target model are separate facts.

Asset V2 Query Contract (Active)

Asset V2 is active in the current asset API release. It does not upgrade historical assets automatically. Send MoonApiX-Asset-Contract: v2 to select the V2 response contract; this does not automatically archive or authenticate historical assets. Historical records keep their original lifecycle meaning until content verification is complete.

Layer / Field	Meaning
Asset: asset_id, asset_ref, status	A newly created V2 asset has a stable MoonApiX customer-facing identity and verified immutable content. asset_id is not an external service asset ID; status=ready means the identity is available, not that archival or model preparation succeeded. Historical records retain their original lifecycle meaning.
Storage: storage.status	Independently computed managed storage status. ready means a verified, accessible managed copy exists now; it is not a permanent retention promise.
Preparation: preparation.model, preparation.status	Preparation for an explicit target model within the current calling scope. preparation is returned only when model is supplied.
preparation.generation_ready	At query time, at least one path in the current target model and allowed calling scope can reference the asset without new preparation. For multiple assets, the same path must satisfy every asset. It does not change scheduling; generation revalidates it.
preparation.review_status	Independent review evidence. unknown means no evidence is available; it is neither approval nor rejection and does not independently block a confirmed usable preparation.

Query readiness for a target model:

curl "https://moonapix.com/v1/assets/asset_xxx?model=seedance-2.5-cl" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "MoonApiX-Asset-Contract: v2"

{
  "object": "asset",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "status": "ready",
  "storage": {
    "status": "ready"
  },
  "preparation": {
    "model": "seedance-2.5-cl",
    "status": "ready",
    "generation_ready": true,
    "review_status": "unknown"
  }
}

Without model, query only Asset and Storage: omit preparation and legacy top-level readiness aliases. When only model is supplied, the scope uses the current identity, API Key permissions and default calling configuration. config_id is currently unsupported; a non-empty value returns an explicit error. Do not reuse a true result under a different model or calling scope.

generation_ready=true does not promise immediate execution or change normal capability, permission, price or scheduling policy. Generation still selects a path using the normal policy and validates the reference and permissions again. Clients should normally require asset.status=ready, preparation.status ∈ {ready, not_required} and generation_ready=true.

GET is read-only: it does not upload, poll authentication, start preparation or settle billing. While preparation is processing, GET observes only saved state; explicitly call Prepare Asset to advance or retry preparation.

V2 Status Field	Values	Meaning
storage.status	not_started, processing, ready, failed, unknown	Not archived, archival in progress, managed copy available, archival failed, or insufficient historical evidence to confirm storage status.
preparation.status	not_started, processing, ready, failed, not_required, unknown	Not prepared, preparation in progress, usable reference available, preparation failed, no dedicated reference required in the current scope, or current usability of a historical reference is unconfirmed. Use generation_ready in the same scope to determine usability.

Historical assets may return preparation.status=unknown and preparation.generation_ready=false. A historical reference may still exist, but this does not establish readiness for the current target model and calling scope. This is not a finding that preparation failed or the asset was deleted, and is separate from review_status=unknown. GET does not establish new readiness evidence; waiting alone does not prove readiness; call Prepare explicitly when work must start or resume.

Use MoonApiX asset_id / asset_ref for standard asset queries and query preparation for the target model. For official Volcengine IDs and a media download URL, use the official asset subresource below.

List queries can also use the V2 header. Lists return identity and storage information only and do not support a model preparation projection.

Query media assets List

GET /v1/assets

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

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

curl "https://moonapix.com/v1/assets?group_id=group_xxx&type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONAPIX_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	No	media assets type. Common values are image, audio, video, file.
status	string	No	media assets status. Common values are created, syncing, ready, failed, disabled.
domain	string	No	media assets domain. Common values are media.
page	integer	No	Page number, default 1.
page_size	integer	No	Number of items per page, default 20.

A liveness-verified group may not contain assets yet. Upload media before querying that group_id; an empty list alone does not mean verification failed. See Visual liveness verification.

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.
request_id	string	request ID.
trace_id	string	Track ID.

Search for media assets details

GET /v1/assets/{asset_id}

curl https://moonapix.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONAPIX_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://moonapix.com/v1/assets/asset_xxx?group_id=group_xxx" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

Compatible entry:

GET /api/asset/get

Details query parameters

Parameters	Type	shall fill	Annotations
group_id	string	No	Verify that the asset belongs to the specified group; return not found otherwise.
model	string	No	Target public model for a V2 detail query; return preparation within the current calling scope. Asset lists do not support this parameter.
config_id	string	No	Currently unsupported; a non-empty value returns an explicit error.

Edit an asset or move it to another group

PATCH /v1/assets/{asset_id}

Only an asset owned by the authenticated account and not disabled can be edited. Send at least one of name, description or group_id; omitted fields keep their current values.

curl -X PATCH https://moonapix.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-reference",
    "description": "Updated reference",
    "group_id": "group_target"
  }'

Field	Type	Description
name	string	Optional. Must not be empty after trimming whitespace.
description	string	Optional. An empty string clears the description.
group_id	string	Optional. Move to this group, which must belong to the authenticated account, be enabled and have the same domain as the asset.

Success returns HTTP 200 with the updated asset object. V2 assets retain their identity and storage representation; historical assets keep their existing response representation. Editing does not start model preparation. Moving preserves the asset_id, file content and existing authentication references without uploading or authenticating again. This operation cannot replace the asset's file content.

HTTP status	Error code	Description
400	invalid_asset_id, invalid_name, invalid_group_id, missing_update_fields	Invalid ID, name or update fields.
404	asset_not_found	The asset does not exist, belongs to another account or is disabled.
404	group_not_found	The target group does not exist, belongs to another account or is not enabled.
409	group_domain_mismatch	The target group and asset have different domains.

Delete an asset

DELETE /v1/assets/{asset_id}

curl -X DELETE https://moonapix.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

Deletion is a soft delete: it changes the asset owned by the authenticated account to status=disabled. No request body is required. Success returns HTTP 200 with the asset object and deleted=true. Key response fields are:

{
  "object": "asset",
  "asset_id": "asset_xxx",
  "status": "disabled",
  "deleted": true
}

Other fields follow the asset's existing representation. This example is not a target-model preparation query. Confirm deletion using HTTP 200, deleted=true and status=disabled. A missing asset, an asset owned by another account or an already disabled asset returns HTTP 404 / asset_not_found; a repeated deletion does not return another success object.

Soft deletion retains history and audit records. It does not physically remove managed files or revoke existing authentication references in other services. It is not a storage cleanup operation, an immediate invalidation of issued URLs or cancellation of submitted generation tasks. Deleting a group is a separate operation and does not delete its member assets; see Delete an asset group.

Official Volcengine Asset IDs and Media URLs

seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini and seedance-2.5-sz support official asset details for resources registered to your account. MoonApiX asset_id, asset_ref and group_id remain the primary identifiers for management and generation.

Operation	Method and Path
Prepare or resume an official asset	POST /v1/assets/{asset_id}/upstream
List registered official assets	GET /v1/assets/upstream
Read official asset IDs and a current download URL	GET /v1/assets/{asset_id}/upstream
Rename an official asset	PATCH /v1/assets/{asset_id}/upstream
Delete an official asset	DELETE /v1/assets/{asset_id}/upstream
Resolve a known official ID to a MoonApiX resource	POST /v1/assets/resolve

Pass the public model in JSON for POST/PATCH, or as a query parameter for GET/DELETE. First create a MoonApiX group and its official group, then upload the image into that MoonApiX group with mode=oss and the selected model. This example uses fictitious IDs and an API key already set in the MOONAPIX_API_KEY environment variable:

curl --fail-with-body https://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -F "file=@./reference.png" -F "type=image" -F "mode=oss" \
  -F "model=seedance-2.0-sz" -F "group_id=group_example" \
  -F "purpose=video_reference" -F "role=reference_image"

curl --fail-with-body https://moonapix.com/v1/assets/asset_example/prepare \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" -d '{"model":"seedance-2.0-sz"}'

Use the returned real MoonApiX IDs in subsequent requests. HTTP 202 means preparation is incomplete; advance the same asset with Prepare rather than uploading it again. Check preparation.generation_ready even after HTTP 200. POST to the asset's /upstream subresource can also start or resume preparation and include official IDs once available. Read detail for a fresh download URL:

curl --fail-with-body \
  "https://moonapix.com/v1/assets/asset_example/upstream?model=seedance-2.0-sz" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

{
  "object": "asset",
  "asset_id": "asset_example",
  "asset_ref": "Asset://asset_example",
  "group_id": "group_example",
  "upstream": {
    "asset_id": "asset-official-example",
    "group_id": "group-official-example",
    "url": "https://media.example.test/reference.png",
    "status": "Active"
  }
}

upstream.asset_id is the original official asset ID. upstream.group_id is the registered official group ID used for resolution. If detail reports a different official group ID, upstream.observed_group_id preserves that observation separately. To read the group ID observed in this detail use upstream.observed_group_id when present, otherwise upstream.group_id. Keep the registered value for resolution.

upstream.url may be absent while processing. It may contain a short-lived media signature, commonly valid for approximately 12 hours. Re-read this detail endpoint to refresh it without creating or uploading another asset. Preserve all URL query parameters, download promptly and do not treat the address as permanent storage. Lists and ID resolution do not refresh download URLs. Media download is anonymous; never send your MoonApiX API key to the media domain. Some addresses reject HEAD with HTTP 403 while allowing Range GET 206 and full GET 200; check a Range: bytes=0-0 GET and matching media Content-Type before declaring the download unavailable. Re-query detail if GET fails.

curl --fail-with-body https://moonapix.com/v1/assets/resolve \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-sz","upstream_asset_id":"asset-official-example","upstream_group_id":"group-official-example"}'

curl --fail-with-body "https://moonapix.com/v1/assets/upstream?model=seedance-2.0-sz&offset=0&limit=20" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

curl --fail-with-body -X PATCH https://moonapix.com/v1/assets/asset_example/upstream \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-sz","name":"reference-updated"}'

Resolution requires model and at least one of upstream_asset_id or upstream_group_id. Both IDs must refer to the same MoonApiX group when supplied together. Group-only results contain empty asset_id and asset_ref strings. Only current resources registered to the authenticated account and selected model asset scope can be resolved. Unknown, invalidated or cross-account resources return 404; ambiguous resources return 409. The differing observed_group_id is not accepted in place of the registered group_id. Generation uses the returned top-level MoonApiX asset ID or reference, never an arbitrary official ID.

Lists include only your registered resources and use offset / limit, defaulting to 0 / 20, with a limit of 1..100. Name updates accept only a non-blank name of at most 64 characters, not description. Detail may keep showing the old name for several minutes after a successful update; query the same resource again at intervals.

Delete the official asset, then its empty official group, then soft-delete the MoonApiX asset and group if no longer needed:

curl --fail-with-body -X DELETE \
  "https://moonapix.com/v1/assets/asset_example/upstream?model=seedance-2.0-sz" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"
curl --fail-with-body -X DELETE \
  "https://moonapix.com/v1/asset-groups/group_example/upstream?model=seedance-2.0-sz" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"
curl --fail-with-body -X DELETE https://moonapix.com/v1/assets/asset_example \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"
curl --fail-with-body -X DELETE https://moonapix.com/v1/asset-groups/group_example \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

Official deletion returns HTTP 200, deleted=true. Resources being prepared or deleted, shared resources and nonempty groups may return 409. An uncertain official delete can be retried on the same resource. Local soft deletion alone does not prove official deletion. Deleting an official resource invalidates ID resolution; it does not guarantee immediate expiry of issued URLs or cancel submitted generation tasks. Preserve receipts privately and do not blindly replay creation or upload after an unknown outcome.

Legacy Asset Fields

The flat fields and original URL descriptions below apply only to legacy compatibility records, not to the three-layer V2 contract. If V2 compatibility aliases are returned, url / source_url contain only safe managed URLs, never the original input URL.

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 MoonApiX OSS URL intended for testing.
oss_url	MoonApiX 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	Preparation result within the target generation scope; it does not guarantee immediate execution.
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.

Legacy Status Fields

field	Common Values	Annotations
status	created, syncing, ready, failed, disabled	Asset record state; ready alone does not prove authentication success.
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	Preparation result within the current target generation scope; no immediate execution guarantee.
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.

In the current V2 three-layer compatibility response, returned sync_status and preparation_status aliases mirror preparation.status within the same explicit target model and calling scope. They may therefore also be not_started, processing, not_required or unknown. unknown pairs with generation_ready=false and has the V2 preparation meaning above; historical responses that have not been upgraded retain their original semantics.

For legacy records, check the target model's preparation_status and generation_ready; do not check status alone or require all five readiness and review fields together. review_status=unknown does not independently block a confirmed ready preparation, and review_status=succeeded alone does not prove preparation is complete.

preparation_status = ready
generation_ready = 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.

A legacy record may pass review and then fail during generation preparation. The legacy response below can occur after a copyright or content policy rejection. V2 preserves the established asset_id and identity status=ready, recording failure only in the affected preparation layer:

{
  "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.

Legacy Response Example

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

• Query preparation for the actual target model within the current calling scope; V2 uses preparation.generation_ready.
• If V2 preparation is incomplete, explicitly call Prepare to advance it, then query the same asset_id. For legacy records, wait and retry according to the corresponding preparation workflow.
• 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}
DELETE /v1/asset-groups/{group_id}

Creates examples of groups:

curl https://moonapix.com/v1/asset-groups \
  -H "Authorization: Bearer <MOONAPIX_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