Asset resources

The asset API creates reusable image, audio and video resources. Asset IDs and references belong to MoonApiX. Receiving an ID or status=ready alone does not establish that an asset meets the target model's generation requirements.

Video generation does not automatically create MoonApiX-hosted URLs or Asset://asset_xxx references. Supply your public URLs directly, or binary files where the selected endpoint supports them. Hosting URLs and asset references are created only when you explicitly call the asset-upload API.

MoonApiX OSS is for integration testing. OSS uploads and asset authentication are currently free, but there is no promise of long-term retention, permanent URLs, continuous availability or a long-term storage service level. For production and long-term use, provide stable direct URLs from your own storage, accessible anonymously without login or extra headers.

The mode=oss|asset|both requests and top-level status examples on this page describe the legacy compatibility contract. V2 is active in the current asset API release. Creation, archiving and preparation are independent operations. See Upload assets for version selection and scope, and Query assets for the three status layers.

In V2, status=ready means the asset identity and content baseline have been established. storage.status=ready means a hosted copy has been verified. preparation is returned only when a target model is specified. asset_id / asset_ref are MoonApiX identities, not external service asset IDs. Reuse the same MoonApiX asset_id, but confirm the target model's preparation.status and generation_ready; changing models does not require a new asset identity, while incompatible model scopes may require an additional preparation record. Multiple assets must be ready on the same usable path.

When to use media assets

The same picture or the same audio is used repeatedly.
Generating API requires stable reference files to avoid external URLs.
The business system wants to manage user media assets by media assets ID.
The target model explicitly supports the Asset://asset_xxx media assets reference.
digital human image, clone voice, image-to-video, task, etc., need to prepare the document first.

A one-time image-to-video request generally does not require asset creation if the file already has a stable public URL.

Seedance-2 and Moon-2 media assets policy

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. A successful upload or ready image preparation does not establish a validated video-reference generation workflow. Explicitly Prepare for the actual target model and query its preparation result; the asset identity's status=ready alone is insufficient. Audio uses stable public URLs. These models do not offer face scanning or liveness verification. AIGC certification is distinct from liveness verification, and another model's liveness group cannot be reused. See SH models.

Group Scatter Checklist

Group	Representative Model	`mode=oss`	`mode=asset`	`mode=both`	Use recommendations
..seedance-2.0-sz series	`seedance-2.0-sz`, `seedance-2.0-sz-fast`, `seedance-2.0-sz-mini`	Selectable rotations	Support	Advanced scene available	Creates a picture, video or audio media assets based on a physical generated model; up to 9 + 3 video + 3 audio, for a total of up to 15.
seedance-2.5-sz	`seedance-2.5-sz`	Selectable rotations	Support	Advanced scene available	`seedance-2.5-sz` to prepare media assets individually; up to 30 figure + 10 video + 10 audio, for a total of 50 audio.
& & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & (((((()	`seedance-2.0-kz-fast`, `seedance-2.0-kz`	Support	Support	Advanced scene available	This group is given priority when media assets is required.
seedance-2.0-cl family	`seedance-2.0-cl-fast`, `seedance-2.0-cl`, `seedance-2.0-cl-mini`, `seedance-2.5-cl`	Supported	Supported	Advanced scene available	CL models share an asset compatibility scope; no per-model re-authentication is needed. CL is isolated from CL-B and KZ. Query the target model's preparation before generation.
seedance-2.0-cl-b family	`seedance-2.0-cl-b-fast`, `seedance-2.0-cl-b-mini`	Supported	Supported	Advanced scene available	CL-B models share a separate asset compatibility scope, isolated from CL and KZ. Query the target model's preparation before generation.
& View-2.0-gl series	`seedance-2.0-gl`, `seedance-2.0-gl-fast`, `seedance-2.0-gl-mini`	Selectable rotations	Support	Advanced scene available	Client has a SURL priority; created by the target model when media assets ID is needed, up to 9 + 3 video + 3 audio, 15 in total.
Moon-2.0-wc series	`moon-2.0-wc-720p`, `moon-2.0-wc-b-720p`, `moon-2.0-wc-b-720p-fast`, `moon-2.0-wc-c-720p`, `moon-2.0-wc-d-720p`, `moon-2.0-wc-e-720p`, `moon-2.0-wc-f-720p`	Support	Not as Current Input Path	Not recommended	RECOMMENDS the public network URL; seven models support the real person. Base, B and B Fast up to 9 + 3 video + 3 audio and a total of 12, of which B/ B Fast does not support pure text; F up to 9 + 3 video + 3 audio, up to 12 pictures; C up to 9 graphics and the video/ audio is disabled; D / E up to 4 figure + 3 video + 1 audio and is not allowed to speak pure.
Moon-2.0-ld series	`moon-2.0-ld-a`, `moon-2.0-ld-b`	Support	Support	Advanced scene available	The two models have the same capacity; `references[]` is recommended; the picture is up to 9 and the video up to 3 and the audio up to 3 and the audio up to 15; the audio should be used with the picture or video.
moon-2.0-am family	`moon-2.0-am-720p-fast`	Supported	Not a current input method	Not recommended	Use your own public URLs for production; `mode=oss` can provide temporary integration-test URLs. Suitable for one image, image plus background music, and fast mixed-media tasks.
Moon-2.0-me series	`moon-2.0-me-a-720p`, `moon-2.0-me-b-720p`, `moon-2.0-me-a-fast`	Support	Based on model capabilities	Advanced scene available	A / A Fast up to 9 pictures; B up to 9 + 3 videos + 3 audio, up to a total of 15; recommended to use `references[]` and stabilize public network URLs.

Which groups are the best for `Asset://`?

seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini and seedance-2.5-sz support mode=asset authentication for the target model. Explicitly supply image, video and audio references in mixed-media generation requests; completing review or preparation does not attach assets automatically.
The seedance-2.0-kz family is well suited to integrating the asset API into reusable workflows.
The seedance-2.0-cl family, including seedance-2.5-cl, shares one asset compatibility scope, so compatible preparation can be reused across those models without repeating authentication.
seedance-2.0-cl-b-fast and seedance-2.0-cl-b-mini share a separate scope. CL and CL-B preparation are isolated. Keep the same MoonApiX asset ID when switching models and query that model's Preparation; generation_ready confirms availability in the current calling scope without changing route order.
The seedance-2.0-gl family supports mode=asset for image, video and audio references usable by the selected model. Existing stable public URLs can be used directly. Multipart or mode=oss upload is optional for local files, not required for production use.
The moon-2.0-wc family supports 720P mixed-media tasks billed per task. Base, B and B Fast accept up to 12 references total: 9 images, 3 videos and 3 audio files. F supports text-only input, real people and 4–15 seconds, with the same per-type and total limits. C accepts up to 9 images without video or audio. D/E accept up to 4 images + 3 videos + 1 audio file and reject audio-only input. Use your own public URLs in production; mode=oss is for local integration tests.
moon-2.0-ld-a and moon-2.0-ld-b suit 720P character, pose, multiple-image, multiple-video and background-audio references. They share the same capabilities, accepting public URLs, MoonApiX-hosted URLs and supported asset references, at most 15 references total.
The moon-2.0-am family supports fast 720P mixed-media tasks billed per task. Use your own public URLs for production; mode=oss is for local integration tests.
moon-2.0-me-a-720p, moon-2.0-me-a-fast and moon-2.0-me-b-720p recommend references[] for URL into the Stable Public Network; A / A Fast only supports pictures, B supports images, videos and audio mix references, and audio needs to be matched with pictures or videos.

Upload media assets

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"

Create media assets references using an existing public network URL:

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"
  }'

Common field:

field	Type	Annotations
`file`	file	File to upload.
`url`	string	Optional. A public network file URL already exists. It is commonly used when using JSON request.
`model`	string	Optional. It is recommended that the target model name be entered when media assets references are created.
`type`	string	media assets type, common values `image`, `audio`, `video`.
`purpose`	string	Optional. media assets uses, e.g. `video_reference`, `digital_human_avatar`, `voice_training`.
`mode`	string	Optional. `oss`, `asset` or `both`. Default is based on the current configuration of API and suggests a visible entry.

mode Description:

mode	Behaviour	billing Rules
`oss`	Creates a MoonApiX OSS URL for testing only, returning media assets ID.	Free.
`asset`	Authenticate media and create an `Asset://asset_xxx` reference. Returns an explicit error if the model does not support this operation.	Free.
`both`	Creates both the OSS URL and `Asset://asset_xxx` media assets references.	Both of the prep moves are free.

mode=both requests hosting and asset preparation. Legacy responses may combine their results. V2 reports storage and preparation separately: an archive failure does not revoke valid preparation, and a preparation failure does not remove the asset identity or verified hosted copy. See Upload assets for the V2 compatibility scope.

Example of a legacy compatibility success response:

json

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

Legacy records may return created or syncing during asynchronous preparation. Read review and preparation states separately. Review approval does not replace preparation for the target model, and there is no five-field readiness requirement shared by every contract.

In a V2 query for a specified model, preparation.generation_ready=true means at least one path allowed by the current calling configuration can use the asset without new preparation. Generation follows the normal configuration and revalidates the asset; this does not guarantee immediate generation. preparation.review_status=unknown means independent review evidence is unavailable and establishes neither failure nor successful authentication.

Reference media assets

Generate API with direct access Asset://asset_xxx:

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "Turn this product image into a short premium ad shot.",
  "image": "Asset://asset_xxx",
  "duration": 5,
  "aspect_ratio": "16:9"
}

Review approval or generation_ready=true does not attach assets to later video tasks. Explicitly include references or URLs in every generation request. input_type: "reference" alone does not select recently uploaded or approved assets.

Seedance-2 reference images video example:

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "mode": "fast",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": true,
  "watermark": false,
  "web_search": false,
  "input_type": "reference",
  "generation_type": "video",
  "content": [
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "Asset://asset_xxx"
      }
    }
  ]
}

If media assets is desired as first frame, replace role with first_frame or use first_frame_url: "Asset://asset_xxx".

Part API also supports direct public domain URLs. For long-term business processes, media assets IDs can be used to facilitate tracking, but media files should remain in customer-owned storage; for one-time task, direct client-owned public service URLs are usually simpler.

URL and binary files

The asset API is not required for every file input:

There is a public network URL: URL is passed directly in the request generation.
Generate API for multipart/binary: direct to the API requirement.
Only the MoonApiX OSSS URL is required for the inter-coordination test on a temporary basis: Call /v1/assets/uploads, use mode=oss.
Asset://asset_xxx media assets Quoted: Call /v1/assets/uploads after confirming model support, use mode=asset.
The combination will also need to test OSS URL and Asset://asset_xxx: use mode=both and handle two types of readiness.

Neither billing nor ZXQXZ authentication is available for OSS uploading and media assets; any follow-up video or other generation of task still follows the corresponding model billing. MoonApiX OSS cannot replace the customer ' s own official business media assets storage.

Query media assets

bash

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

bash

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

list API supports the page break. You can either screen by media assets type or you can keep asset_id in your own business system.

Query responses include trace_id or the X-MoonApiX-Trace-Id header. If synchronization fails or review_status=failed, retain asset_id, trace_id and the original response for troubleshooting.

With the active V2 contract, query preparation for a target model:

bash

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

V2 GET is read-only. It starts no authentication and does not poll external preparation progress. Without model, Preparation is omitted. To start or continue preparation, explicitly call Prepare with the same asset ID. See Upload assets and Query assets. The progress updates performed by some legacy compatibility queries do not apply to V2.

Groups, editing and deletion

MoonApiX provides asset group and asset management operations for resources owned by the authenticated account:

Operation	Endpoint
Create or list groups	`POST /v1/asset-groups`, `GET /v1/asset-groups`
Get or edit a group	`GET /v1/asset-groups/{group_id}`, `PATCH /v1/asset-groups/{group_id}`
Delete a group	`DELETE /v1/asset-groups/{group_id}`
Edit an asset name or description, or move it to another group	`PATCH /v1/assets/{asset_id}`
Delete an asset	`DELETE /v1/assets/{asset_id}`

Deletion is a soft delete that sets status=disabled; success returns HTTP 200 and deleted=true. Default and system groups cannot be deleted. A custom group can be soft deleted even when it contains assets, without deleting or moving its members. Moving an asset requires an enabled target group owned by the same account with the same domain.

Soft deletion retains history. It does not physically remove managed files, revoke existing authentication references in other services or cancel submitted generation tasks, and it does not guarantee immediate invalidation of issued URLs. See Asset groups, Edit an asset and Delete an asset for requests, responses and error codes.

Documentation recommendations

Type	Recommendations
Picture	Use clear subject matter to avoid overcompression; the proposed background of the commodity chart is clean.
Audio	Use clear human voice to reduce mixing, noise and background music.
Video	Maintaining the subject ' s stability, avoiding a strong cover and frequent lenses.

More parameters and response structures are found in API Reference.

Conversation APIs

Embeddings

Audio

Models

GPT Image

Gemini Nano

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Asset resources

When to use media assets

Seedance-2 and Moon-2 media assets policy

Group Scatter Checklist

Which groups are the best for `Asset://`?

Upload media assets

Reference media assets

URL and binary files

Query media assets

Groups, editing and deletion

Documentation recommendations

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Asset resources ​

When to use media assets ​

Seedance-2 and Moon-2 media assets policy ​

Group Scatter Checklist ​

Which groups are the best for Asset://? ​

Upload media assets ​

Reference media assets ​

URL and binary files ​

Query media assets ​

Groups, editing and deletion ​

Documentation recommendations ​

Asset resources

When to use media assets

Seedance-2 and Moon-2 media assets policy

Group Scatter Checklist

Which groups are the best for `Asset://`?

Upload media assets

Reference media assets

URL and binary files

Query media assets

Groups, editing and deletion

Documentation recommendations