Upload and media assets Overview

Upload and asset APIs manage images, audio and video for reuse in generation tasks. Under the legacy contract, uploads and preparation require explicit calls; generation does not automatically create a managed URL or asset reference.

Asset V2 Contract (Active)

Asset V2 is active in the current asset API release. It does not upgrade historical assets automatically; historical records retain the legacy meaning. Use MoonApiX-Asset-Contract: v2 to select the strict creation and query contract.

Do not treat any single ready value as a generation guarantee. For a V2 asset, clients should confirm:

text

asset.status = ready
preparation.status ∈ { ready, not_required }
preparation.generation_ready = true

For a multi-asset request, all assets must satisfy these conditions on the same currently permitted execution path. The generation request must still explicitly include Asset://asset_xxx or a public URL, and the service revalidates it before submission.

Layer	Public Fields	Meaning
Asset	`asset_id`, `asset_ref`, `status`	Stable MoonApiX customer-facing asset identity and content version. `asset_id` is not an external service asset ID; V2 `status=ready` means the identity and content baseline exist, not that storage or model preparation succeeded.
Storage	`storage.status`	Independent managed storage status. `ready` means a verified, accessible copy exists now, not permanent retention.
Preparation	`preparation`	Returned only for an explicit target `model`, as a projection within the current calling scope.

Identity creation, archival and target model preparation are independently executable and retryable operations; see V2 upload operations. Strict creation does not use legacy model / mode fields. storage.enabled expresses only the request intent to archive.

preparation.generation_ready=true means that, at query time, at least one path in the current 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 guarantee immediate execution or change normal capability, permission, price or scheduling policy. Generation validates again. review_status=unknown means independent review evidence is unavailable; it is neither approval nor rejection and does not independently block a confirmed ready preparation.

Query assets is read-only: it does not upload, poll, advance preparation or settle billing. Call Prepare explicitly to advance or retry preparation. config_id is currently unsupported; a non-empty value returns an explicit error.

V2 compatibility mode=asset requests also create a trusted managed snapshot first. Response aliases url / source_url contain only safe managed URLs, never the original input URL. OSS-only archival without model omits preparation and legacy top-level readiness aliases; with model, it reads only a preparation projection. An unavailable model or missing permission does not stop OSS archival or identity creation. Archival or authentication failure preserves the established asset_id and identity status=ready; each layer is independent.

Keep MoonApiX asset_id / asset_ref as the client asset identity. SZ models also provide official Volcengine asset IDs, group IDs and a current media download URL for resources registered to this account. See official asset details and official asset groups. Generation continues to use MoonApiX IDs; resolve an existing official ID to your own MoonApiX resource first.

Legacy Usage Scenarios

scene	Recommendations
File has stabilized public network URL	The URL is passed directly in the request generation and is recommended for priority use.
Use pictures or audio only at one task	Usually the URL is passed directly to a simpler URL.
The media assets ID is required to manage user assets	Call `/v1/assets/uploads` with an existing public network URL, save the returned media assets ID.
Target model explicitly supports media assets quotes	Prefer `mode=asset` to create `Asset://asset_xxx` media assets references.
Local files need to be temporarily converted to a public network URL when connected	Creates a URL using `mode=oss` MoonApiX OSS.
An OSS test URL and model media assets references are required for alignment	`mode=both` is used; this is an advanced scenario and is not recommended as a default option.

Route List

Methodology	Path	Purpose
`POST`	`/v1/assets/uploads`	Upload media assets.
`POST`	`/v1/visual-validate-sessions`	Create a visual liveness verification session.
`POST`	`/v1/visual-validate-results`	Get a visual liveness verification result.
`GET`	`/v1/asset-groups`	Query media assets grouping.
`POST`	`/v1/asset-groups`	Creates a group of media assets.
`GET`	`/v1/asset-groups/{group_id}`	Find out the media assets group details.
`PATCH`	`/v1/asset-groups/{group_id}`	Updates the name or description of the group media assets.
`DELETE`	`/v1/asset-groups/{group_id}`	Delete a custom asset group.
`GET`	`/v1/assets`	Query media assets list.
`GET`	`/v1/assets/{asset_id}`	Find media assets details.
`PATCH`	`/v1/assets/{asset_id}`	Update an asset's name, description, or group.
`DELETE`	`/v1/assets/{asset_id}`	Delete an asset.
`POST`	`/api/asset/createMedia`	Compatible media assets creation portal.
`GET`	`/api/asset/get`	media assets compatible query portal.

The scene entrance.

VVSVisual liveness verificationVerification returns a group; upload media to create an asset ID.POSTUpload assets uploads pictures, audio or video, takes URL or media assets references. GROUPAsset groups creates groups and isolates media assets with group_id. GETQuery assetsRead asset lists, details, status and troubleshooting fields.

Upload request

bash

curl https://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -F "file=@./product.png" \
  -F "type=image" \
  -F "purpose=video_reference" \
  -F "mode=oss"

You can also create media assets references with already existing public web URLs:

bash

curl https://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-kz-fast",
    "mode": "asset",
    "type": "image",
    "url": "https://example.com/reference.png"
  }'

The examples without a V2 header use the legacy request format. Records that have not been upgraded preserve the original URL; legacy mode=asset does not create a managed copy by default. See the V2 compatibility snapshot behavior above.

Legacy Mode Description

The original URL preservation behavior below applies only to legacy records that have not been upgraded.

mode	Behaviour	Fit to scene
`asset`	Creates the `Asset://asset_xxx` media assets reference, saves the URL of the public network you have entered.	The target model clearly supports the media assets reference and media assets needs to be reused.
`oss`	Creates the MoonApiX OSS test URL.	For use only in connection testing, not as a long-term business memory.
`both`	Creates both the hosting URL and `Asset://asset_xxx` media assets references.	Advanced scene: The same media assets is directly accessible and is referenced in the model.

mode=oss uploads and mode=asset authentication are currently free, as are both preparation steps in mode=both. MoonApiX OSS is for integration testing and does not promise long-term retention, permanent URLs, continuous availability or a long-term storage service level. For production use, supply anonymously accessible direct URLs from your own storage.

media assets may need a short preparation to be used for video generation after Asset://asset_xxx is created. If you immediately submit video task for an error that media assets is not available, wait for a short time to try again with the same Asset://asset_xxx; normally, media assets does not need to be recreated.

Models to support scavengers

For seedance-2.0-sh, seedance-2.0-sh-fast, seedance-2.0-sh-mini, and seedance-2.5-sh, image AIGC preparation has reached ready in validation. Successful video AIGC preparation has not been validated; uploading a video does not establish generation readiness. Explicitly call Prepare for the actual target model, then check preparation.status and preparation.generation_ready. Audio uses stable, anonymously accessible public URLs without a separate AIGC certification result. These models do not offer face scanning or liveness verification, and cannot reuse another model's liveness group. Ready image preparation does not establish a validated reference-generation workflow. See SH models.

Different video models support boundaries different from those supported by " upload media assets " and " quote media assets when generating " . The upload page is only responsible for the visible creation of MoonApiX media assets records, hosting URLs or Asset://asset_xxx; can media assets references be used directly at the time of generation, which is based on the corresponding model page.

Models	Recommended Upload Mode	Upload to `Asset://`	Use `Asset://` on generation	Recommendations
`seedance-2.0-kz-fast`	`mode=asset` or `mode=both`	Supported	Supported	Prefer this group for long-term asset reuse.
`seedance-2.0-kz`	`mode=asset` or `mode=both`	Support	Support	Fits to higher quality task and full media assets reuses.
`seedance-2.0-cl-fast`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.0-kz-fast` is different from the model line, media assets ID does not mix across lines.
`seedance-2.0-cl`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.0-kz` is different from the model line, media assets ID does not mix across lines.
`seedance-2.0-cl-mini`	`mode=asset` or `mode=both`	Support	Support	Shares the CL asset compatibility scope with the other CL models; do not mix with KZ or CL-B scopes.
`seedance-2.5-cl`	`mode=asset` or `mode=both`	Support	Support	`seedance-2.5-cl` must be prepared and wait for `generation_ready=true`, `preparation_status=ready`; request direct error is generated when reference resolve failed, without returning to public web URL.
`seedance-2.0-cl-b-fast`, `seedance-2.0-cl-b-mini`	`mode=asset` or `mode=both`	Support	Support	Share one CL-B asset compatibility scope; keep it separate from CL, KZ and other scopes.
`seedance-2.0-sz`, `seedance-2.0-sz-fast`, `seedance-2.0-sz-mini`, `seedance-2.5-sz`	`mode=asset` or `mode=both`	Support	Support	Create or confirm media assets by target SZ model; support pictures, videos and audio references, media assets ID not to mix over model lines.
`seedance-2.0-gl`, `seedance-2.0-gl-fast`, `seedance-2.0-gl-mini`	`mode=asset`;stable URLs are available directly	Support	Support	media assets by target GL model; customer public network URL priority, multipart/`mode=oss` only as a select transfer.
`moon-2.0-am-720p-fast`	`mode=oss` or direct URL	Not the primary workflow	Not the primary workflow	Suitable for public or MoonApiX-hosted URLs, one image, image + background music, and fast mixed-reference tasks.

Asset preparation reuse scope: seedance-2.0-cl-fast, seedance-2.0-cl, seedance-2.0-cl-mini and seedance-2.5-cl share one CL compatibility scope. seedance-2.0-cl-b-fast and seedance-2.0-cl-b-mini share a separate CL-B scope. Preparation can be reused within a scope without creating or preparing the asset again for every model; CL and CL-B preparation cannot be reused across scopes. KZ and other scopes are also separate. V2 preserves one MoonApiX asset_id; after changing the target model, query its Preparation because capabilities, permissions and selectable routes may differ. Use preparation.generation_ready in the same calling scope to determine current availability.

Asset groups

You can create your own media assets group and upload group_id in upload, list and detailed query. Under the same account, the media assets of the different groups will be isolated by group_id; the default group will be used when group_id is not passed.

Create group:

bash

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",
    "domain": "media"
  }'

Save returned group_id after successful creation, upload and import:

json

{
  "model": "seedance-2.0-kz-fast",
  "mode": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://example.com/reference.png"
}

group_id:

bash

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

If media assets is not in the group, return unrecovered. See Asset groups for details field.

Legacy Status Checks

field	Common Values	Annotations
`status`	`created`, `syncing`, `ready`, `failed`	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.

For legacy records, check the target model's preparation fields rather than the record status alone:

text

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 media assets.

Legacy Response Example

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://example.com/reference.png",
  "source_url": "https://example.com/reference.png",
  "oss_url": "",
  "reference": "Asset://asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

Conversation APIs

Embeddings

Audio

Models

GPT Image

Gemini Nano

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload and media assets Overview

Asset V2 Contract (Active)

Legacy Usage Scenarios

Route List

The scene entrance.

Upload request

Legacy Mode Description

Models to support scavengers

Asset groups

Legacy Status Checks

Legacy Response Example

Relevant Pages

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload and media assets Overview ​

Asset V2 Contract (Active) ​

Legacy Usage Scenarios ​

Route List ​

The scene entrance. ​

Upload request ​

Legacy Mode Description ​

Models to support scavengers ​

Asset groups ​

Legacy Status Checks ​

Legacy Response Example ​

Relevant Pages ​

Upload and media assets Overview

Asset V2 Contract (Active)

Legacy Usage Scenarios

Route List

The scene entrance.

Upload request

Legacy Mode Description

Models to support scavengers

Asset groups

Legacy Status Checks

Legacy Response Example

Relevant Pages