Prepare assets

Specify the target model for an existing asset to establish or confirm a usable generation reference. Continue using the same asset_id instead of uploading again while waiting for readiness.

Start or continue preparation

POST /v1/assets/{asset_id}/prepare

curl https://moonapix.com/v1/assets/asset_xxx/prepare \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.5-cl" }'

model is required: use the public model you will actually generate with. Prepare always returns V2 without a request selector; successful responses include Asset-Contract: v2. A non-empty config_id is currently unsupported.

• HTTP 200: a usable preparation result exists; still check the readiness conditions below.
• HTTP 202: preparation is incomplete. After a delay, call Prepare again for the same asset and model.
• Request error: handle the error code. error.retryable in a preparation result indicates whether that failure can be retried.

Check generation readiness

Key fields in a ready response:

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

Check all of these before including asset_ref in a generation request:

1. Top-level status=ready.
2. preparation.model matches the target model and preparation.status is ready or not_required.
3. preparation.generation_ready=true.

storage.status describes managed storage; review_status provides independent review evidence. Storage readiness or review approval alone is insufficient. review_status=unknown does not independently invalidate confirmed preparation readiness.

Status and next action

preparation.status	Meaning	Next action
not_started	Preparation has not started.	Call Prepare for the same ID.
processing	Preparation is in progress.	Wait briefly, then call Prepare again to continue.
ready / not_required	A reference exists, or this scope needs no dedicated reference.	Also confirm generation_ready=true before generation.
unknown	A historical reference has not been confirmed in this model and calling scope.	Call Prepare to confirm usability; waiting and querying does not establish evidence.
failed	Preparation failed.	Inspect preparation.error. Retry only when permitted and after addressing the cause; use different media for a content rejection.

GET queries only read saved results. They do not start, poll or advance preparation. A preparation failure preserves the established identity and independent storage result.

Advanced: explicit operations and failure recovery

Normally omit operation to reuse a valid reference or advance an active attempt. For explicit control, use operation=create for an initial reference, operation=rebuild to recreate an invalid reference, or operation=refresh to query an existing valid reference. A failed refresh does not overwrite an otherwise valid reference.

Rebuild only when the error permits a retry and its cause has been addressed. Use different media for a content rejection; rebuilding cannot bypass content restrictions. See API Reference for all parameters.

Use the reference for generation

Explicitly include the reference in an input field supported by the target model. This image reference item belongs in the generation request's content array:

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "Asset://asset_xxx"
  }
}

Mentioning an image in the prompt or setting an input mode does not load the asset automatically. See the video model matrix and the model page for complete generation parameters.

Models and reuse scope

The same MoonApiX asset can have preparation results for different models. Keep its asset_id and call Prepare for the new target model; compatible preparation results can be reused.

• The CL family, including seedance-2.5-cl, can reuse preparation within its scope. CL-B Fast / Mini can reuse preparation within CL-B. CL and CL-B scopes are separate.
• Follow the model documentation for KZ, SZ and other model requirements.
• SH image AIGC preparation has been verified ready. Successful video AIGC preparation has not yet been accepted; audio uses stable public URLs. SH does not accept liveness groups, and ordinary preparation does not authorize a real person's likeness. See the SH model page.

Readiness applies only to the current model, identity, API Key permissions and calling configuration. For multiple assets, the same permitted path must satisfy every asset. Generation revalidates permissions and references; readiness does not guarantee immediate execution or change normal scheduling.

Related pages

• Upload assets
• Query assets
• Legacy compatibility