Legacy Compatibility

This page is for clients that already use legacy upload requests or historical assets. For a new integration, start with Upload Assets: create an asset, prepare it for the target model, then check its state. Archive it separately when you need a hosted copy.

Request Format and Record Semantics

A legacy request format does not necessarily create a legacy record. The V2 compatibility upload flow creates a trusted content snapshot from the old request format. Existing historical records are not automatically upgraded by a service update or a request header.

Case	Input and behavior	Reading the result
Strict V2 creation	POST /v1/assets with Asset-Contract: v2. Does not accept model / mode; creation and model preparation are separate.	Check asset identity, storage, and the target model's preparation separately. Creation does not prepare the asset for a model.
Legacy upload request handled by V2	POST /v1/assets/uploads without a V2 contract header, using legacy fields such as mode. Even mode=asset first creates a trusted hosted snapshot, then prepares the target model.	The url / source_url aliases contain only safe hosted URLs, not the original input URL. Check preparation for the same target model.
Historical record not yet upgraded	Retains its original lifecycle and URL semantics. Legacy mode=asset does not establish that a hosted copy exists.	Interpret the historical fields on this page. Query and explicitly Prepare when current model readiness needs confirmation.

MoonApiX-Asset-Contract: v2 remains a supported header alias. Set only one contract header per request. POST /v1/assets/uploads with either V2 contract header also selects strict V2 creation: do not combine it with a legacy model / mode body. Successful V2 responses use the canonical Asset-Contract: v2 response header.

For a compatibility upload that only archives to OSS, omitting model omits preparation and the old top-level preparation aliases. Supplying model only reads its preparation projection; it does not start preparation. An unavailable or unauthorized model does not prevent identity creation and OSS archiving; the problem is reflected in preparation. Once established, asset_id and identity status=ready remain even if archiving or preparation fails.

Legacy Endpoints

Operation	Path	Compatibility endpoint
Upload	POST /v1/assets/uploads	POST /api/asset/createMedia
List	GET /v1/assets	Use the existing list endpoint.
Get details	GET /v1/assets/{asset_id}	GET /api/asset/get

Use the canonical paths in new code. See Query Assets for list and detail parameters, and Manage Assets for renaming, moving, and deletion.

Upload from a Public URL

This example uses the legacy request format and does not set a V2 contract header. Snapshot creation and returned URLs follow the distinction above; the old request format does not mean a newly created record only stores the original URL.

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

Upload a Local File

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

The pre-V2 upload flow only supports file uploads with mode=oss or mode=both. The V2 compatibility flow also supports files with mode=asset when a target model that supports asset preparation is specified. Strict V2 creation does not use mode.

Field	Purpose
file / url	A local file or an existing public direct URL. JSON also supports urls; each URL creates an asset record.
type	Asset type, such as image, audio, or video.
model	The public target model for asset preparation. Check its asset strategy first.
mode	Legacy upload mode; see below.
group_id	Optional; defaults to the default group. For a liveness verification group, use the group_id returned by verification; that group can initially be empty.
purpose	Optional; for example, video_reference, digital_human_avatar, or voice_training.

Historical Mode Semantics

The original URL and hosting behavior below only describes historical records that have not been upgraded. Newly created V2 compatibility records follow the compatibility upload rules.

Mode	Historical storage behavior	Common result
asset	Stores the customer's public URL and creates an asset reference.	asset_id, asset_ref; url usually equals the original source_url.
oss	Creates a MoonApiX OSS test URL.	asset_id, url, oss_url; this does not establish model readiness.
both	Creates a hosted copy and an asset reference.	asset_id, asset_ref, url, oss_url; preparation still needs a separate check.

MoonApiX OSS is for integration and testing. It does not guarantee long-term retention, URL validity, or continuous availability. For production, use stable, anonymously accessible direct URLs on your own storage. New integrations use separate V2 creation, archive, and preparation operations instead of combining them through mode.

Historical Asset Fields

This table describes historical responses that have not been upgraded. Compatibility aliases in a V2 response retain V2 semantics; in particular, do not treat their source_url as the original input URL.

Field	Historical meaning
object	Object type, usually asset.
id / asset_id	The MoonApiX asset ID, in the form asset_xxx.
reference / asset_ref	The MoonApiX asset reference, in the form Asset://asset_xxx. You still need to include it in an asset input field of the generation request.
group_id / domain	The asset's group and usage domain; a common domain is media.
type / asset_type	Asset type, such as image, audio, video, or file.
name / description	Asset name and description.
source_url	The original public URL supplied when the asset was created.
url	A customer-accessible URL. Historical mode=asset usually uses the original URL; oss / both usually use a hosted URL.
oss_url	A hosted test URL, usually present for historical mode=oss / both. Long-term validity is not guaranteed.
content	An input fragment for generation requests; images commonly use content.image_url.url.
content_type / size / duration	MIME type, size in bytes, and audio/video duration in seconds.
State and review fields	See Historical States and Next Actions.
visibility	Usually private.
created_at / updated_at	Creation and update timestamps.
request_id / trace_id	Request and trace IDs to provide when troubleshooting.

Historical States and Next Actions

Field	Common historical values	Meaning
status	created, syncing, ready, failed, disabled	Asset record state. ready alone does not establish target model readiness.
sync_status	created, syncing, ready, failed	Asset reference preparation state.
preparation_status	created, syncing, ready, failed, disabled	Preparation state before generation.
generation_ready	true / false	Readiness in the same target model and invocation scope; it does not promise immediate execution.
review_status	succeeded, pending, failed, unknown	Review evidence. succeeded does not mean preparation is complete.
review_passed	true / false	Whether review or availability checks passed; it does not replace the generation readiness check.
sync_error	string	Preparation failure reason.

For historical responses, preparation is normally checked through preparation_status=ready and generation_ready=true. Do not require every review field to be positive. review_status=unknown does not by itself block independently confirmed readiness; a successful review cannot override failed preparation.

In V2 compatibility responses, any returned sync_status / preparation_status aliases map to preparation.status in the same target model and invocation scope. They may therefore also be not_started, processing, not_required, or unknown. New code should read preparation.* instead of applying historical enums.

Query result	Next action
A confirmed historical preparation workflow is still syncing	Keep the same asset_id, and wait or query again as that workflow requires. Do not repeatedly create assets.
V2 not_started, processing, or unknown	Explicitly Prepare the same asset to start, advance, or confirm preparation. GET only reads saved results; waiting alone cannot establish missing evidence.
Preparation failed	Read the preparation error and check content, permissions, or the asset source. Reuse the same asset_id when a retry is appropriate; use different content if the content itself is unsuitable.
Only generation_ready=false is known	Query the complete preparation state for the target model, then decide whether to Prepare or resolve an error. Do not handle every false result by waiting and repeating GET.

For V2, generation readiness requires identity status=ready, preparation.status equal to ready or not_required, and preparation.generation_ready=true, all for the same target model and invocation scope. When changing models, query that model's preparation; do not reuse true from another scope.

Historical Response Example

This illustrative fragment represents a historical record that has not been upgraded. Its original URL semantics do not apply to newly created V2 records.

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

The historical record exists, but this result does not establish generation readiness. Preparation can fail after review succeeds, resulting in review_status=succeeded, preparation_status=failed, and generation_ready=false. Read sync_error; do not generate based on review evidence alone. V2 retains the identity and reports the failure in the relevant preparation layer.

Switch to V2

1. Use V2 creation for new uploads. Remove legacy model / mode from creation requests, and call archive and Prepare separately when needed.
2. Select Asset-Contract: v2 for list and detail queries. When preparation is needed, supply the target model in the detail query and read storage.* / preparation.*.
3. Keep existing MoonApiX asset_id / asset_ref values. A request header selects a response contract; it does not validate historical content, archive it, or prepare it. Explicitly handle missing historical evidence based on the returned state.
4. Keep creation and preparation receipts. Reuse the same asset while processing, when a result is uncertain, or when changing models; do not upload again merely to wait for readiness.

See Uploads and Assets Overview for the full workflow, or Official Asset Management for official IDs and media download URLs.