查询素材

素材查询用于读取素材列表、素材详情和素材状态。本页也说明已有素材的编辑、移动分组和删除操作。素材身份存在、托管副本可用和目标模型准备完成是三个不同的判断。

Asset V2 查询契约（当前生效）

Asset V2 已在当前素材接口版本生效。它不会自动升级历史素材；历史记录在完成内容验证前保留原有生命周期语义。请求头 MoonApiX-Asset-Contract: v2 用于选择 V2 响应契约，不会自动归档或认证历史素材。

层级 / 字段	含义
Asset：`asset_id`、`asset_ref`、`status`	新建 V2 素材的稳定 MoonApiX 客户侧身份及已验证的不可变内容。`asset_id` 不是其他服务的素材 ID；其 `status=ready` 只表示身份可用，不表示归档或模型认证成功；历史记录仍按原有生命周期语义解释。
Storage：`storage.status`	独立计算的托管状态。`ready` 表示目前有已验证、可访问的托管副本，不代表永久保存承诺。
Preparation：`preparation.model`、`preparation.status`	指定目标模型在当前调用范围内的准备状态；只有显式传入 `model` 才返回 `preparation`。
`preparation.generation_ready`	查询时点，在当前目标模型和允许的调用范围内，至少有一条无需新增素材准备即可引用的执行路径；多素材必须由同一路径同时满足全部素材要求。它不改变调度顺序，生成前仍会重验。
`preparation.review_status`	独立审核证据。`unknown` 表示没有证据，不等于通过或失败，也不会单独阻断已经独立确认可用的准备结果。

查询目标模型的准备状态：

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"

json

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

未传 model 时只查询 Asset 和 Storage，不返回 preparation 或旧的顶层准备状态别名。只传 model 时，判断范围是当前身份、API Key 权限和默认调用配置；目前不支持 config_id，传入非空值会明确报错。不可把一个模型或调用范围的 true 直接用于另一个范围。

generation_ready=true 不承诺立即执行，也不改变正常的能力、权限、价格或调度策略。实际生成仍按正常策略选取执行路径，并重新验证引用和权限。客户端通常应同时满足 asset.status=ready、preparation.status ∈ {ready, not_required} 和 generation_ready=true。

GET 为只读操作，不上传、不轮询认证、不启动准备、不结算。若准备仍在处理中，GET 只能观察已保存的状态；需要显式调用 Prepare Asset 推进或重试准备。

V2 状态字段	值	含义
`storage.status`	`not_started`、`processing`、`ready`、`failed`、`unknown`	分别表示未归档、归档中、托管副本可用、归档失败、历史证据不足以确认托管状态。
`preparation.status`	`not_started`、`processing`、`ready`、`failed`、`not_required`、`unknown`	分别表示未准备、准备中、已有可用引用、准备失败、当前范围无需建立专用引用、历史引用的当前可用性尚未确认。是否可用仍以同一范围的 `generation_ready` 为准。

历史素材可能返回 preparation.status=unknown、preparation.generation_ready=false：历史引用可能仍存在，但不能据此证明它在当前目标模型和调用范围内已准备可用。这不是准备失败或素材已删除的结论，也不同于 review_status=unknown。GET 不会补充可用性证据，不能仅靠等待就认定已经 ready；需要显式调用 Prepare。

常规素材查询使用 MoonApiX 的 asset_id / asset_ref，并按目标模型查询 Preparation。需要火山官方 ID 和媒体下载地址时，使用下文的官方素材详情；这些额外字段仅出现在明确支持的素材管理子资源中。

列表查询也可以使用 V2 请求头；列表仅返回身份及存储信息，不支持 model 准备投影。

查询素材列表

http

GET /v1/assets

bash

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

如果素材在自建分组中，可以加上 group_id：

bash

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

列表查询参数

参数	类型	必填	说明
`group_id`	string	否	素材分组 ID。传入后只返回该分组下的素材；不传时查询默认分组。
`type`	string	否	素材类型。常见值为 `image`、`audio`、`video`、`file`。
`status`	string	否	素材状态。常见值为 `created`、`syncing`、`ready`、`failed`、`disabled`。
`domain`	string	否	素材用途域。常见值为 `media`。
`page`	integer	否	页码，默认 `1`。
`page_size`	integer	否	每页数量，默认 `20`。

活体认证完成后，素材组可能还没有素材。上传媒体后再按该 group_id 查询；空列表本身不代表认证失败，详见真人活体认证。

列表响应字段

字段	类型	说明
`object`	string	固定为 `list`。
`data`	array	素材数组。每一项字段见下方“素材字段”。
`count`	integer	当前页返回数量。
`total`	integer	符合条件的素材总数。
`request_id`	string	请求 ID。排查问题时提供。
`trace_id`	string	跟踪 ID。排查问题时提供。

查询素材详情

http

GET /v1/assets/{asset_id}

bash

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

需要校验素材是否属于某个分组时，可以在详情查询中传 group_id。如果素材不在该分组中，会返回未找到。

bash

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

兼容入口：

http

GET /api/asset/get

详情查询参数

参数	类型	必填	说明
`group_id`	string	否	用于校验素材是否属于指定分组。素材不在该分组内时会返回未找到。
`model`	string	否	V2 详情查询的目标公开模型；传入时返回该模型在当前调用范围内的 `preparation`。列表查询不支持此参数。
`config_id`	string	否	当前不支持；传入非空值会返回明确错误。

编辑素材与移动分组

http

PATCH /v1/assets/{asset_id}

只能编辑当前账号的未禁用素材。请求至少包含 name、description、group_id 中的一个字段；省略的字段保持原值。

bash

curl -X PATCH https://moonapix.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-reference",
    "description": "Updated reference",
    "group_id": "group_target"
  }'

字段	类型	说明
`name`	string	可选。去除首尾空白后不能为空。
`description`	string	可选。传空字符串可清空说明。
`group_id`	string	可选。移动到指定分组；目标组必须属于当前账号、处于 `enabled` 状态，且 `domain` 与素材一致。

成功返回 HTTP 200 和更新后的素材对象。V2 素材保留身份与存储表示，历史素材沿用既有响应表示；编辑不会启动目标模型准备。移动分组保留原 asset_id、文件内容和已有认证引用，不会重新上传或认证。此接口不能用来替换素材文件内容。

HTTP 状态	错误码	说明
`400`	`invalid_asset_id`、`invalid_name`、`invalid_group_id`、`missing_update_fields`	ID、名称或更新字段无效。
`404`	`asset_not_found`	素材不存在、不属于当前账号或已禁用。
`404`	`group_not_found`	目标组不存在、不属于当前账号或未启用。
`409`	`group_domain_mismatch`	目标组与素材的用途域不一致。

删除素材

http

DELETE /v1/assets/{asset_id}

bash

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

删除为软删除：只将当前账号的素材状态改为 disabled。请求无需正文，成功返回 HTTP 200 和带 deleted=true 的素材对象，关键字段如下：

json

{
  "object": "asset",
  "asset_id": "asset_xxx",
  "status": "disabled",
  "deleted": true
}

其余字段随该素材的既有表示返回，不能把本例当作查询目标模型准备状态的响应。请以本次 HTTP 200、deleted=true 和 status=disabled 确认删除结果。素材不存在、不属于当前账号或已经禁用时，返回 HTTP 404 / asset_not_found；重复删除不会再次返回成功对象。

软删除保留历史和审计记录，不物理清除托管文件，也不撤销其他服务中已有的认证引用。它不是清理存储空间、立即使已发出 URL 失效或取消已提交生成任务的操作。删除分组是另一个操作，且不会连带删除组内素材，见删除素材分组。

火山官方素材 ID 与下载地址

seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini 和 seedance-2.5-sz 支持查询当前账号已准备素材的火山官方 ID 和 HTTPS 媒体下载地址。MoonApiX asset_id / asset_ref / group_id 仍为素材管理和生成请求的主标识。

操作	方法与路径	model 位置
准备或续查官方素材	`POST /v1/assets/{asset_id}/upstream`	JSON 正文
查询已登记的官方素材列表	`GET /v1/assets/upstream`	查询参数
查询官方素材详情及当前下载地址	`GET /v1/assets/{asset_id}/upstream`	查询参数
修改官方素材名称	`PATCH /v1/assets/{asset_id}/upstream`	JSON 正文
删除官方素材	`DELETE /v1/assets/{asset_id}/upstream`	查询参数
用官方 ID 找回自己的 MoonApiX ID	`POST /v1/assets/resolve`	JSON 正文

完整调用流程

以下 Bash 示例需要 curl 和 jq，使用已设置的 MOONAPIX_API_KEY 环境变量和本地 reference.png。示例保存请求回执到权限受限目录，媒体链接可能带短期签名，避免把回执或完整链接写入共享日志。步骤中的创建、上传不要在结果未知时盲目重跑；先用已取得的 MoonApiX ID 查询。

bash

set -euo pipefail
umask 077
: "${MOONAPIX_API_KEY:?Set MOONAPIX_API_KEY in your environment}"
BASE=https://moonapix.com
MODEL=seedance-2.0-sz
RECEIPTS=$(mktemp -d)
MODEL_BODY=$(jq -nc --arg model "$MODEL" '{model:$model}')

# 1. Create a MoonApiX group, then its official group.
curl --silent --show-error --fail-with-body "$BASE/v1/asset-groups" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"project-a","description":"Reference materials","domain":"media"}' \
  -o "$RECEIPTS/group.json"
GROUP_ID=$(jq -er '.group_id' "$RECEIPTS/group.json")
curl --silent --show-error --fail-with-body "$BASE/v1/asset-groups/$GROUP_ID/upstream" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" -d "$MODEL_BODY" \
  -o "$RECEIPTS/official-group.json"

# 2. Upload into this group. mode=oss stores the file before preparation.
curl --silent --show-error --fail-with-body "$BASE/v1/assets/uploads" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -F "file=@./reference.png" -F "type=image" -F "mode=oss" \
  -F "purpose=video_reference" -F "role=reference_image" \
  -F "model=$MODEL" -F "group_id=$GROUP_ID" \
  -o "$RECEIPTS/upload.json"
ASSET_ID=$(jq -er '.asset_id' "$RECEIPTS/upload.json")

# 3. Prepare this same asset; HTTP 202 means it is still processing.
curl --silent --show-error --fail-with-body "$BASE/v1/assets/$ASSET_ID/prepare" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" -d "$MODEL_BODY" \
  -o "$RECEIPTS/prepare.json"
for ATTEMPT in $(seq 1 24); do
  if jq -e '.preparation.generation_ready == true' "$RECEIPTS/prepare.json" >/dev/null; then
    break
  fi
  sleep 10
  curl --silent --show-error --fail-with-body "$BASE/v1/assets/$ASSET_ID/prepare" \
    -H "Authorization: Bearer $MOONAPIX_API_KEY" \
    -H "Content-Type: application/json" -d "$MODEL_BODY" \
    -o "$RECEIPTS/prepare.json"
done
jq -e '.preparation.generation_ready == true' "$RECEIPTS/prepare.json" >/dev/null

# 4. Read current official IDs and the download URL.
curl --silent --show-error --fail-with-body \
  "$BASE/v1/assets/$ASSET_ID/upstream?model=$MODEL" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -o "$RECEIPTS/detail.json"
OFFICIAL_ASSET_ID=$(jq -er '.upstream.asset_id' "$RECEIPTS/detail.json")
CALL_GROUP_ID=$(jq -er '.upstream.group_id' "$RECEIPTS/detail.json")
OFFICIAL_OBSERVED_GROUP_ID=$(jq -er \
  '.upstream.observed_group_id // .upstream.group_id' "$RECEIPTS/detail.json")

# 5. Resolve known official IDs to this account's MoonApiX IDs.
jq -n --arg model "$MODEL" --arg aid "$OFFICIAL_ASSET_ID" --arg gid "$CALL_GROUP_ID" \
  '{model:$model,upstream_asset_id:$aid,upstream_group_id:$gid}' \
  > "$RECEIPTS/resolve-request.json"
curl --silent --show-error --fail-with-body "$BASE/v1/assets/resolve" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -H "Content-Type: application/json" \
  --data-binary "@$RECEIPTS/resolve-request.json" -o "$RECEIPTS/resolved.json"
jq -e --arg aid "$ASSET_ID" --arg gid "$GROUP_ID" \
  '.asset_id == $aid and .group_id == $gid' "$RECEIPTS/resolved.json" >/dev/null

准备返回 HTTP 202 时继续同一素材的 Prepare，HTTP 200 后仍检查 preparation.generation_ready。示例等待约四分钟后退出，退出不表示官方素材已删除；保留回执，再查询或继续 Prepare。不要因处理中而重新上传。POST /upstream 也可以开始或继续此准备流程，并在已取得 ID 时附带 upstream；下载地址始终从详情读取。

详情的示意字段如下，所有值均为虚构值：

json

{
  "object": "asset",
  "asset_id": "asset_example",
  "asset_ref": "Asset://asset_example",
  "group_id": "group_example",
  "upstream": {
    "asset_id": "asset-official-example",
    "group_id": "group-official-example",
    "url": "https://media.example.test/reference.png",
    "status": "Active"
  }
}

字段	含义
顶层 `asset_id`、`asset_ref`、`group_id`	MoonApiX 标识，后续生成及管理请求继续使用这些值。
`upstream.asset_id`	官方素材详情返回的火山原始素材 ID。
`upstream.group_id`	当前素材已登记、可用于 ID 解析的官方组 ID。
`upstream.observed_group_id`	可选；当详情实际返回的官方组 ID 与已登记的组 ID 不同时单独提供，不覆盖 `upstream.group_id`。获取本次详情观察到的组 ID 时读取此值，否则读取 `upstream.group_id`。
`upstream.url`	官方素材详情提供的 HTTPS 媒体下载地址，处理中或尚未提供地址时可缺省。
`upstream.status`	官方素材状态；不能替代同模型的 `preparation.generation_ready` 判断。

下载和刷新地址

upstream.url 可能含短期下载签名，常见有效期约 12 小时，不作为永久地址。需要下载时重新 GET 同一个素材的 /upstream?model=... 详情，使用此次返回的完整地址，保留全部查询参数；刷新地址无需重新上传或创建素材。ID 解析和列表不返回新的下载地址。

部分地址不接受 HEAD，可能返回 403，但匿名 Range GET 可返回 206、完整 GET 可返回 200。遇到 HEAD 拒绝时，用 Range: bytes=0-0 GET 核验 HTTP 状态及匹配的媒体 Content-Type；如果 GET 也失败，重新查询详情取得当前地址后再核验。媒体下载无需携带 MoonApiX API Key；不要把 API Key 发送给媒体域名。完整下载后可验证文件大小、媒体规格和 SHA-256。

下面的 Python 3 示例接续前面的详情回执，匿名验证并下载图片；不把完整 URL 放入命令参数或输出：

bash

python3 - "$RECEIPTS" <<'PY'
import hashlib
import json
from pathlib import Path
import sys
import urllib.request
from urllib.parse import urlparse

receipts = Path(sys.argv[1])
detail = json.loads((receipts / "detail.json").read_text())
url = detail["upstream"]["url"]
assert urlparse(url).scheme == "https"
request = urllib.request.Request(url, headers={"Range": "bytes=0-0"})
with urllib.request.urlopen(request, timeout=60) as response:
    assert response.status in (200, 206)
    assert response.headers.get_content_type() == "image/png"
    response.read(1)
digest = hashlib.sha256()
with urllib.request.urlopen(url, timeout=120) as response:
    assert response.status == 200
    assert response.headers.get_content_type() == "image/png"
    with (receipts / "reference-downloaded.png").open("wb") as output:
        while chunk := response.read(1024 * 1024):
            output.write(chunk)
            digest.update(chunk)
print("Downloaded image/png; SHA-256:", digest.hexdigest())
PY

列表与名称更新

bash

curl --fail-with-body "https://moonapix.com/v1/assets/upstream?model=seedance-2.0-sz&offset=0&limit=20" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

curl --fail-with-body -X PATCH https://moonapix.com/v1/assets/asset_example/upstream \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-sz","name":"product-reference-updated"}'

列表只包含当前账号在所选模型素材范围内已经登记的资源，以 offset / limit 分页，默认 0 / 20，limit 范围 1..100。列表是摘要，不提供实时下载地址。名称更新仅接受 name，最长 64 个字符且不能全为空白；不接受 description。成功后详情中的名称可能延迟数分钟更新，间隔查询确认即可。

官方 ID 解析规则

POST /v1/assets/resolve 必须传 model，upstream_asset_id 和 upstream_group_id 至少传一个，同时传入时必须属于同一 MoonApiX 组。只传组 ID 的成功结果中 asset_id 和 asset_ref 为空字符串；取得素材时才返回可供生成使用的素材标识。

只解析当前账号在同一目标模型素材范围内已登记且有效的资源。未知、已失效、其他账号或不属于该范围的 ID 返回 404；无法唯一确定资源时返回 409。此接口不导入任意官方资源。若返回过不同的 upstream.observed_group_id，解析仍使用 upstream.group_id。生成接口不能把官方 ID 直接当作 MoonApiX asset_id 或 Asset://asset_xxx 使用，先解析再提交顶层 MoonApiX 标识。

清理本次资源

以下命令接续完整示例，只删除本次创建的资源。先删除官方素材，再删除空的官方组，最后对 MoonApiX 素材和分组软删除；执行成功前保留对应回执。

bash

curl --silent --show-error --fail-with-body -X DELETE \
  "$BASE/v1/assets/$ASSET_ID/upstream?model=$MODEL" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -o "$RECEIPTS/delete-official-asset.json"
curl --silent --show-error --fail-with-body -X DELETE \
  "$BASE/v1/asset-groups/$GROUP_ID/upstream?model=$MODEL" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -o "$RECEIPTS/delete-official-group.json"
curl --silent --show-error --fail-with-body -X DELETE "$BASE/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -o "$RECEIPTS/delete-asset.json"
curl --silent --show-error --fail-with-body -X DELETE "$BASE/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" -o "$RECEIPTS/delete-group.json"

官方删除成功返回 HTTP 200、deleted=true。正在准备、删除中或资源共用时可能返回 409。删除结果不明时可对同一个官方子资源重试 DELETE；不要把本地软删除成功当作官方资源已删除的证明。官方资源删除后对应 ID 不再可解析；它不保证已发出的媒体链接立即失效，也不撤销已经提交的生成任务。

旧兼容素材字段

以下平铺字段和原始 URL 描述仅适用于旧兼容记录，不是 V2 的三层响应契约。V2 兼容别名如有返回，url / source_url 只使用安全托管 URL，不返回原始输入 URL。

字段	说明
`object`	对象类型，通常为 `asset`。
`id`	素材 ID，格式为 `asset_xxx`。
`asset_id`	素材 ID，和 `id` 等价。
`group_id`	素材所属分组 ID。
`domain`	素材用途域。常见值为 `media`。
`type` / `asset_type`	素材类型，常见值为 `image`、`audio`、`video`、`file`。
`name`	素材名称。
`description`	素材说明。
`source_url`	你创建素材时传入的原始公网 URL。
`url`	客户可用 URL。`mode=asset` 时通常等于 `source_url`；`mode=oss` 或 `mode=both` 时通常是仅供测试的 MoonApiX OSS URL。
`oss_url`	MoonApiX OSS 测试 URL。只有 `mode=oss` 或 `mode=both` 时通常有值，不保证长期有效。
`reference` / `asset_ref`	可用于部分生成接口的素材引用，格式为 `Asset://asset_xxx`。
`content_type`	文件 MIME 类型。
`size`	文件大小，单位字节。
`duration`	音频或视频时长，单位秒。
`status`	素材记录状态。常见值见下方状态表。
`sync_status`	素材引用准备状态。
`preparation_status`	生成前准备状态。
`generation_ready`	目标生成范围内的准备结果；不保证立即执行。
`review_status`	素材审核/可用性结果。常见值为 `succeeded`、`pending`、`failed`、`unknown`。
`review_passed`	是否已通过素材审核/可用性检查。
`visibility`	可见性。通常为 `private`。
`created_at`	创建时间。
`updated_at`	更新时间。
`request_id`	请求 ID。排查问题时提供。
`trace_id`	跟踪 ID。排查问题时提供。

旧兼容状态字段

字段	常见值	说明
`status`	`created`、`syncing`、`ready`、`failed`、`disabled`	素材记录状态；单独为 `ready` 不证明认证成功。
`sync_status`	`created`、`syncing`、`ready`、`failed`	素材引用准备状态。
`preparation_status`	`created`、`syncing`、`ready`、`failed`、`disabled`	是否已经适合用于生成任务的准备状态。
`generation_ready`	`true` / `false`	当前目标生成范围内的准备结果；不保证立即执行。
`review_status`	`succeeded`、`pending`、`failed`、`unknown`	素材审核结果。`succeeded` 表示素材审核已通过，但不等于已经完成生成前同步。
`review_passed`	`true` / `false`	是否已通过素材审核/可用性检查。
`sync_error`	string	素材同步失败原因。仅失败时通常有值。

在当前 V2 三层兼容响应中，sync_status、preparation_status 如有返回，会在同一明确的目标模型和调用范围内映射 preparation.status，因此也可能为 not_started、processing、not_required 或 unknown。其中 unknown 对应 generation_ready=false，含义与上面的 V2 准备状态相同；尚未升级的历史响应仍按原有语义解释。

使用旧兼容记录时，应结合目标模型的 preparation_status 和 generation_ready 判断准备结果，不应只检查 status，也不需要把五个字段同时当成成功前提。已独立确认准备可用时，review_status=unknown 不单独阻断使用；review_status=succeeded 本身也不能证明已准备完成。

text

preparation_status = ready
generation_ready = true

如果 preparation_status=syncing 或 generation_ready=false，请等待一小段时间后重新查询同一个 asset_id。不要为了等待 ready 反复创建新素材。如果 preparation_status=failed，请查看 sync_error，更换素材或检查素材 URL 是否可公开访问。

旧兼容记录可能先返回“素材已过审”，随后在同步到生成引擎时失败。例如图片命中版权或内容策略时，可能出现以下旧响应；V2 则保留已经建立的 asset_id 和身份 status=ready，仅在对应准备层记录失败：

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

这种情况表示素材审核通过，但不能用于生成；请以 generation_ready 和 preparation_status 判断是否可生成。

旧兼容响应示例

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "asset_type": "image",
  "group_id": "group_xxx",
  "domain": "media",
  "name": "reference.png",
  "description": "",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "oss_url": "",
  "reference": "Asset://asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "content_type": "image/png",
  "size": 245678,
  "duration": 0,
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "visibility": "private",
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "request_id": "2026060301010100000000000000000000",
  "trace_id": "2026060301010100000000000000000000"
}

分组隔离

group_id 是客户侧自定义分组 ID。上传素材时传入 group_id 后，列表和详情查询也建议带同一个 group_id。

场景	结果
列表查询传 `group_id=group_xxx`	只返回该分组下的素材。
详情查询传正确 `group_id`	正常返回素材详情。
详情查询传错误 `group_id`	返回未找到，可用于校验业务侧保存关系。
不传 `group_id`	使用默认分组。

使用建议

查询实际目标模型在当前调用范围内的准备结果；V2 使用 preparation.generation_ready。
V2 准备未完成时，显式调用 Prepare 推进，再查询同一个 asset_id；旧兼容记录按对应准备流程等待和重试。
在业务系统保存素材 ID、分组 ID、用途、用户或项目的对应关系。
如果素材准备失败，请保存 asset_id、trace_id 和接口原始响应。

素材分组

http

GET /v1/asset-groups
POST /v1/asset-groups
GET /v1/asset-groups/{group_id}
PATCH /v1/asset-groups/{group_id}
DELETE /v1/asset-groups/{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"
  }'

对话协议

向量

音频

模型

GPT Image

Gemini Nano

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

查询素材

Asset V2 查询契约（当前生效）

查询素材列表

列表查询参数

列表响应字段

查询素材详情

详情查询参数

编辑素材与移动分组

删除素材

火山官方素材 ID 与下载地址

完整调用流程

下载和刷新地址

列表与名称更新

官方 ID 解析规则

清理本次资源

旧兼容素材字段

旧兼容状态字段

旧兼容响应示例

分组隔离

使用建议

素材分组

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

查询素材 ​

Asset V2 查询契约（当前生效） ​

查询素材列表 ​

列表查询参数 ​

列表响应字段 ​

查询素材详情 ​

详情查询参数 ​

编辑素材与移动分组 ​

删除素材 ​

火山官方素材 ID 与下载地址 ​

完整调用流程 ​

下载和刷新地址 ​

列表与名称更新 ​

官方 ID 解析规则 ​

清理本次资源 ​

旧兼容素材字段 ​

旧兼容状态字段 ​

旧兼容响应示例 ​

分组隔离 ​

使用建议 ​

素材分组 ​

相关页面 ​

查询素材

Asset V2 查询契约（当前生效）

查询素材列表

列表查询参数

列表响应字段

查询素材详情

详情查询参数

编辑素材与移动分组

删除素材

火山官方素材 ID 与下载地址

完整调用流程

下载和刷新地址

列表与名称更新

官方 ID 解析规则

清理本次资源

旧兼容素材字段

旧兼容状态字段

旧兼容响应示例

分组隔离

使用建议

素材分组

相关页面