Upload media assets

Upload media assets to create reusable pictures, audio or video resources. After uploading successfully, MoonApiX returns media assets ID, accessable URL, media assets quotes and status information.

For an asset with a stable public URL, submit url in a JSON request. Legacy records preserve the original URL and the legacy contract creates a managed URL only with mode=oss or mode=both; see the V2 content snapshot and three-layer contract below.

MoonApiX OSS is for integration testing. Uploads and asset authentication are currently free, but long-term retention, permanent URLs, continuous availability and long-term storage service levels are not promised. Use your own storage for production, with stable public URLs that require neither login nor additional headers.

Asset V2 Operations (Active)

Asset V2 is active in the current asset API release. It does not upgrade historical assets automatically; historical records retain the legacy meaning. Asset identity, Storage and Preparation for a target model are computed independently. status=ready means that the MoonApiX identity and content baseline are available.

Create Asset

bash

curl https://moonapix.com/v1/assets \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "MoonApiX-Asset-Contract: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reference.png",
    "type": "image",
    "storage": { "enabled": false }
  }'

Create reads the file or fetches a URL snapshot to establish an immutable content baseline and stable asset_id; successful identity creation returns 201. It does not prepare a target model and does not accept legacy model / mode fields. storage.enabled expresses the request intent to archive, not archival success. The response reports facts through storage.status without a permanent storage.enabled field. Setting it to false still establishes the content baseline; managed storage can be added later. asset_id / asset_ref are MoonApiX identities, not external service asset IDs; service-side references are maintained by the platform.

POST /v1/assets/uploads with the same V2 header is also an alias for strict creation and accepts the same input. Do not combine a legacy model / mode body with the V2 header.

Archive Asset

bash

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

Archive adds a managed copy to an existing identity. Use {} to reuse a trusted content source, or submit {"url":"https://example.com/reference.png"} or one multipart file. Backfilled bytes must match the established trusted content baseline. The same URL does not prove byte equality; unverified historical content or a content mismatch returns an explicit error and cannot overwrite the original content.

storage.status=ready means the managed copy is verified and accessible now; retention still follows the storage service policy. Archival failure does not delete the asset identity or mark an already successful model preparation as failed.

Prepare Asset

bash

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

Prepare establishes or confirms a usable reference for a public target model. It selects an execution path using normal calling policy and can reuse compatible preparation results. Ready results return 200; pending results return 202. A non-empty config_id is currently unsupported and returns an explicit error.

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, that same path must satisfy every asset. It does not guarantee immediate execution or change normal scheduling commitments. review_status=unknown neither proves review success nor rejection, and does not block an independently confirmed ready preparation. Preparation failure preserves the existing asset_id, identity status=ready and independent storage result.

Query assets is read-only and does not poll or advance authentication. Call Prepare explicitly to advance or retry processing, using the same asset_id.

Legacy Upload Requests Under V2

V2-enabled compatibility uploads can still accept legacy mode requests without the V2 header. mode=asset first creates a trusted managed snapshot before target model preparation. url / source_url aliases contain only safe managed URLs, never the original input URL. Historical records that have not been upgraded still follow the legacy contract below.

For OSS-only archival without model, omit preparation and legacy top-level readiness aliases. With model, read only the model's preparation projection without starting authentication. An unavailable model or missing permission does not stop identity creation or OSS archival; it is reflected in the preparation result. After identity creation, archival or authentication failure preserves asset_id and identity status=ready.

Client-side readiness check: confirm asset.status=ready, then confirm the scoped preparation.status is ready or not_required and preparation.generation_ready=true. status=ready, storage.status=ready or review_status=succeeded alone is insufficient.

Method and Path

http

POST /v1/assets/uploads

Compatible entry:

http

POST /api/asset/createMedia

Upload request

Use customer network URL

The examples below use the legacy request format without the V2 header. Records that have not been upgraded preserve the original URL, and the legacy contract creates a managed URL only with mode=oss or mode=both. See the V2 compatibility snapshot behavior above.

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

Upload file to MoonApiX OSS Test URL

This URL is not a long-term media assets address for a customer's official business.

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"

Legacy upload paths that have not adopted V2 support file uploads only with mode=oss or mode=both. V2-enabled compatibility uploads also support file mode=asset when a target model that supports asset preparation is specified, and first establish a trusted managed snapshot. Strict V2 creation does not use mode. If the target generation API accepts binary files, you can also submit the file directly as required by that API without creating an asset first.

Upload to the specified group

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",
    "group_id": "group_xxx",
    "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.
`group_id`	string	Optional. Asset group ID; the default group is used when omitted. A liveness-verified group may be empty until an upload creates an asset. See Visual liveness verification.
`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`. Suggested for explicit entry.

JSON request can pass url or urls. urls is used to submit multiple public network URLs at a time; each URL creates a media assets record.

Legacy Mode Selection

The storage behavior and original URL fields below apply only to legacy records that have not been upgraded.

mode	Save Contents	Main return	Fit to scene
`asset`	Saves the customer's public network URL and creates a media assets reference.	`id` / `asset_id`, `reference` / `asset_ref`.	Models clearly support `Asset://asset_xxx`, media assets needs to be reused.
`oss`	Creates the MoonApiX OSS test URL.	`id` / `asset_id`, `url`, `oss_url`.	For use only in connection testing, not as a long-term business memory.
`both`	Saves both the URL and media assets references.	Returns `url`/ `oss_url` and `reference`/`asset_ref` at the same time.	Advanced scene: The same media assets is to be accessed directly and used for the media assets reference.

Two layers of asset results

MoonApiX returns the customer stable media assets ID:

text

asset_id = asset_xxx
asset_ref = Asset://asset_xxx

media assets may have two layers of results at the same time, depending on mode:

field	Meaning
`source_url`	The URL you enter is the original public network. This is the URL when `mode=asset` is used.
`url`	URL available to the user. Usually equals `source_url` for `mode=asset`; usually a MoonApiX-hosted URL for `mode=oss` / `both`.
`oss_url`	MoonApiX hosts URLs. Only `mode=oss` or `mode=both` are usually of value.
`reference` / `asset_ref`	media assets references, formatted `Asset://asset_xxx`, that can be used to generate API in part.
`content`	Enables you to enter the content clip that generates request directly. Pictures are usually `content.image_url.url`.

For legacy requests with a stable public file URL, use mode=asset; use mode=oss for a temporary integration test URL. mode=both is an advanced option rather than a default. V2 computes archival and authentication independently, so one failure does not overwrite success in another layer.

Supporting models

The table below describes legacy preparation strategies. In V2, asset_id is a stable identity. When changing models, query the target model's preparation; do not infer availability from preparation for another model.

Models	Upload to `Asset://`	Recommended Mode	Annotations
`seedance-2.0-kz-fast`	Support	`asset` / `both`	Fits to media assets for images, videos, audio, etc.
`seedance-2.0-kz`	Support	`asset` / `both`	Fits to higher quality task and long-term media assets reuses.
`seedance-2.0-cl-fast`	Supported	`asset` / `both`	A different model line from `seedance-2.0-kz-fast`; do not mix asset IDs between lines.
`seedance-2.0-cl`	Supported	`asset` / `both`	A different model line from `seedance-2.0-kz`; do not mix asset IDs between lines.
`seedance-2.0-cl-mini`	Supported	`asset` / `both`	Shares the CL asset compatibility scope; do not mix with KZ or CL-B scopes.
`seedance-2.5-cl`	Support	`asset` / `both`	Confirm preparation for the target model; `status=ready` alone is insufficient. A failed authenticated reference cannot be downgraded to a public URL.
`seedance-2.0-cl-b-fast`, `seedance-2.0-cl-b-mini`	Supported	`asset` / `both`	CL-B models share one asset compatibility scope, 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`	Support	`asset` / `both`	Create or confirm media assets by target SZ model; support pictures, videos and audio references, media assets ID not to mix over model lines.
`moon-2.0-am-720p-fast`	Not the primary workflow	`oss` or direct URL	Prefer public URLs, MoonApiX-hosted URLs or `references[]` for new integrations. Suitable for one image, image + background music and fast mixed-reference tasks.

CL models, including seedance-2.5-cl, can reuse preparation within the CL compatibility scope. The CL-B Fast and Mini models can reuse preparation within their separate CL-B scope. CL and CL-B preparation cannot be reused across scopes. Keep the same MoonApiX asset_id when changing models, then query that model's preparation.generation_ready; this confirms availability in the current calling scope without repeating compatible preparation or changing normal routing.

If you do not determine whether the target model supports mode=asset, confirm the media assets policy by the corresponding model page. After media assets is created successfully, it is recommended that asset_id, asset_ref, target model and media assets status be maintained in the operating system at the same time.

Use media assets Reference

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.

review_status=succeeded alone does not prove preparation is complete. The target model's generation_ready=true is a readiness judgment within the current calling scope; it does not make later tasks use the asset automatically or guarantee immediate execution. Put Asset://asset_xxx into an input such as image, reference_image_urls, first_frame_url or content[] when creating the 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"
      }
    }
  ]
}

The following request does not load an asset because it contains no image URL or asset reference:

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "input_type": "reference",
  "duration": 5
}

Asset groups

If you need to isolate media assets by project, user or business scene, you can create a grouping of media assets and then upload group_id:

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

json

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

See Asset groups for detailed group API.

SH Model Preparation Boundaries

Image AIGC Prepare has reached ready in validation for seedance-2.0-sh, seedance-2.0-sh-fast, seedance-2.0-sh-mini, and seedance-2.5-sh. Successful video AIGC preparation has not been validated; an upload or asset_id does not make a video ready for generation. With V2, reuse the same asset identity, explicitly call Prepare for the target model, and check its preparation.status and preparation.generation_ready. GET queries do not advance preparation. Audio uses stable public URLs rather than separate AIGC certification. These models do not offer face scanning or liveness verification and do not accept liveness groups. Ordinary AIGC preparation does not establish a person's consent or liveness. See SH models for capabilities and validation scope.

Legacy Status Fields

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`	Preparation status before generation.
`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.

For legacy records, check preparation for the target model without requiring all five readiness and review fields together. review_status=unknown does not independently block a confirmed ready preparation.

text

preparation_status = ready
generation_ready = true

If generation_ready=false or preparation_status=syncing, do not recreate media assets. Wait for a short time to search for the same asset_id, ready to continue with the same Asset://asset_xxx. If preparation_status=failed, look at sync_error, replace media assets or check if media assets URL is 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 identity and records failure only in the preparation layer:

json

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

mode=asset

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": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

mode=asset may return to syncing when it is created. Query to generation_ready=true before it is used for video generation.

mode=both

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://media.moonapix.com/user-assets/image/example.png",
  "source_url": "https://example.com/reference.png",
  "oss_url": "https://media.moonapix.com/user-assets/image/example.png",
  "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
}

mode=both is only used when an OSS test URL and model media assets are required for a connection. If it is only a one-time creation, it is easier to pass the client 's own public network URL; if only media assets is required, use mode=asset; if only a temporary test URL is required, use mode=oss.

Conversation APIs

Embeddings

Audio

Models

GPT Image

Gemini Nano

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload media assets

Asset V2 Operations (Active)

Create Asset

Archive Asset

Prepare Asset

Legacy Upload Requests Under V2

Method and Path

Upload request

Use customer network URL

Upload file to MoonApiX OSS Test URL

Upload to the specified group

Common field

Legacy Mode Selection

Two layers of asset results

Supporting models

Use media assets Reference

Asset groups

SH Model Preparation Boundaries

Legacy Status Fields

Legacy Response Examples

mode=asset

mode=both

Relevant Pages

Ideogram Image

Midjourney Task

Seedance-2 Video

Moon-2 Video

Upload media assets ​

Asset V2 Operations (Active) ​

Create Asset ​

Archive Asset ​

Prepare Asset ​

Legacy Upload Requests Under V2 ​

Method and Path ​

Upload request ​

Use customer network URL ​

Upload file to MoonApiX OSS Test URL ​

Upload to the specified group ​

Common field ​

Legacy Mode Selection ​

Two layers of asset results ​

Supporting models ​

Use media assets Reference ​

Asset groups ​

SH Model Preparation Boundaries ​

Legacy Status Fields ​

Legacy Response Examples ​

mode=asset ​

mode=both ​

Relevant Pages ​

Upload media assets

Asset V2 Operations (Active)

Create Asset

Archive Asset

Prepare Asset

Legacy Upload Requests Under V2

Method and Path

Upload request

Use customer network URL

Upload file to MoonApiX OSS Test URL

Upload to the specified group

Common field

Legacy Mode Selection

Two layers of asset results

Supporting models

Use media assets Reference

Asset groups

SH Model Preparation Boundaries

Legacy Status Fields

Legacy Response Examples

mode=asset

mode=both

Relevant Pages