素材分组

素材分组用于把同一账号下的素材按项目、业务用户或场景隔离。创建分组后，在上传、列表和详情查询中传入 group_id，只会访问该分组内的素材。

如果不传 group_id，MoonApiX 会使用默认分组。

真人活体认证完成时返回的是私有认证组 group_id，不是素材 ID。该组可能暂时为空；将素材上传到该组后才会创建 asset_xxx。详见真人活体认证。

创建分组

http

POST /v1/asset-groups

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

请求字段

字段	类型	必填	说明
`name`	string	是	分组名称。建议使用你的项目名、业务用户 ID 或场景名。
`description`	string	否	分组说明。
`domain`	string	否	分组用途。素材上传常用 `media`；不传时按默认素材用途处理。

响应示例

json

{
  "object": "asset_group",
  "id": "group_xxx",
  "group_id": "group_xxx",
  "domain": "media",
  "name": "project-a",
  "description": "Project A materials",
  "group_type": "custom",
  "status": "enabled",
  "visibility": "private",
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "trace_id": "2026060301010100000000000000000000",
  "request_id": "2026060301010100000000000000000000"
}

保存返回的 group_id，后续上传和查询都使用这个值。

查询分组列表

http

GET /v1/asset-groups

bash

curl "https://moonapix.com/v1/asset-groups?domain=media&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

查询参数

参数	类型	说明
`page`	integer	页码，默认 `1`。
`page_size`	integer	每页数量，默认 `20`。
`domain`	string	可选。按用途筛选，例如 `media`。
`status`	string	可选。`enabled` 或 `disabled`。

响应示例

json

{
  "object": "list",
  "data": [
    {
      "object": "asset_group",
      "id": "group_xxx",
      "group_id": "group_xxx",
      "domain": "media",
      "name": "project-a",
      "description": "Project A materials",
      "group_type": "custom",
      "status": "enabled",
      "visibility": "private",
      "created_at": 1710000000,
      "updated_at": 1710000000
    }
  ],
  "count": 1,
  "total": 1,
  "trace_id": "2026060301010100000000000000000000",
  "request_id": "2026060301010100000000000000000000"
}

查询分组详情

http

GET /v1/asset-groups/{group_id}

bash

curl https://moonapix.com/v1/asset-groups/group_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

如果 group_id 不属于当前账号，或格式不正确，会返回错误。

更新分组

http

PATCH /v1/asset-groups/{group_id}

bash

curl -X PATCH https://moonapix.com/v1/asset-groups/group_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-a-updated",
    "description": "Updated materials"
  }'

请求字段

字段	类型	必填	说明
`name`	string	否	新分组名称。
`description`	string	否	新分组说明。

name 和 description 至少传一个。

删除分组

http

DELETE /v1/asset-groups/{group_id}

bash

curl -X DELETE https://moonapix.com/v1/asset-groups/group_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

删除采用软删除方式：自定义分组的 status 变为 disabled。即使分组内已有素材，也可以删除；删除分组不会删除或移动组内素材，也不会物理清除托管文件或撤销其他服务中已有的认证引用。

默认分组和系统分组不能删除，返回 HTTP 409，错误码为 protected_group。重复删除已停用的分组返回 HTTP 404，错误码为 group_not_found。

成功响应

HTTP 200，返回分组对象，并包含 status: "disabled" 和 deleted: true：

json

{
  "object": "asset_group",
  "id": "group_xxx",
  "group_id": "group_xxx",
  "domain": "media",
  "name": "project-a",
  "description": "Project A materials",
  "group_type": "custom",
  "status": "disabled",
  "visibility": "private",
  "created_at": 1710000000,
  "updated_at": 1710000060,
  "deleted": true,
  "trace_id": "2026060301010100000000000000000000",
  "request_id": "2026060301010100000000000000000000"
}

在上传中使用分组

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

上传成功后，响应里的 group_id 会等于你传入的分组 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>"

bash

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

详情查询带 group_id 时，如果素材不在该分组内，会返回未找到。这个机制可用于校验业务侧保存的素材和分组关系。

常见错误

code	说明	处理方式
`invalid_group_id`	`group_id` 格式不正确。	使用 `group_xxx` 格式的 ID。
`group_not_found`	分组不存在、不属于当前账号，或删除时已停用。	重新查询分组列表，确认使用正确账号、`group_id` 和分组状态。
`protected_group`	HTTP `409`。默认分组和系统分组不能删除。	仅删除自定义分组。
`missing_name`	创建分组时没有传 `name`。	补充分组名称。
`missing_update_fields`	更新分组时没有传可更新字段。	传入 `name` 或 `description`。

火山官方素材组

seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini 和 seedance-2.5-sz 支持为自己的 MoonApiX 分组建立火山官方素材组。先创建本页的 MoonApiX 分组，再调用下列子资源；请求始终使用 MoonApiX group_id，model 使用实际要调用的公开模型名。

操作	方法与路径	model 位置
创建官方素材组	`POST /v1/asset-groups/{group_id}/upstream`	JSON 正文
查询官方组列表	`GET /v1/asset-groups/upstream`	查询参数
查询官方组详情	`GET /v1/asset-groups/{group_id}/upstream`	查询参数
更新官方组名称、说明	`PATCH /v1/asset-groups/{group_id}/upstream`	JSON 正文
删除空的官方素材组	`DELETE /v1/asset-groups/{group_id}/upstream`	查询参数

以下示例从已设置的 MOONAPIX_API_KEY 环境变量读取 API Key，ID 均为虚构值：

bash

curl --fail-with-body https://moonapix.com/v1/asset-groups/group_example/upstream \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-sz"}'

首次创建成功返回 HTTP 201，已有该组关系时返回 HTTP 200：

json

{
  "object": "asset_group",
  "group_id": "group_example",
  "upstream": {
    "group_id": "group-official-example"
  }
}

顶层 group_id 是 MoonApiX 组 ID；upstream.group_id 是此组已登记、可用于解析的火山官方组 ID。如果详情同时返回不同的 upstream.observed_group_id，它表示此次详情实际观察到的官方组 ID。请分别保存这两个值；调用 ID 解析时使用 upstream.group_id，不要用观测值覆盖它。

bash

curl --fail-with-body "https://moonapix.com/v1/asset-groups/group_example/upstream?model=seedance-2.0-sz" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

curl --fail-with-body "https://moonapix.com/v1/asset-groups/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/asset-groups/group_example/upstream \
  -H "Authorization: Bearer $MOONAPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-sz","name":"project-a-updated","description":"Updated materials"}'

name 最长 64 个字符且不能全为空白；description 最长 300 个字符。PATCH 至少提供两者之一。更新成功后，详情中的名称和说明可能延迟数分钟才更新；用同一个 MoonApiX 组 ID 间隔查询，不要因旧名称仍可见而重复创建。

列表只包含当前账号在所选模型素材范围内已有的组，使用 offset / limit 分页。offset 默认 0，limit 默认 20、范围 1..100。列表不会导入其他账号或未登记的官方资源。

bash

curl --fail-with-body -X DELETE \
  "https://moonapix.com/v1/asset-groups/group_example/upstream?model=seedance-2.0-sz" \
  -H "Authorization: Bearer $MOONAPIX_API_KEY"

删除官方组与本页的 MoonApiX 分组软删除是两个操作。先删除组内官方素材，待没有准备中的素材后再删除官方组；非空组返回 HTTP 409。成功返回 HTTP 200、deleted=true，MoonApiX 分组仍保留。删除结果不明时可以对同一个子资源重试 DELETE；请勿改建一个新组来代替核对原操作。

普通默认组或历史共用组可能无法执行独占修改、删除或反向解析。需要完整组管理时，按上述流程为自己的自定义组创建官方组。完整创建、上传、准备、取 ID 和清理示例见查询素材。

对话协议

向量

音频

模型

GPT Image

Gemini Nano

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

素材分组

创建分组

请求字段

响应示例

查询分组列表

查询参数

响应示例

查询分组详情

更新分组

请求字段

删除分组

成功响应

在上传中使用分组

在查询中使用分组

常见错误

火山官方素材组

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

素材分组 ​

创建分组 ​

请求字段 ​

响应示例 ​

查询分组列表 ​

查询参数 ​

响应示例 ​

查询分组详情 ​

更新分组 ​

请求字段 ​

删除分组 ​

成功响应 ​

在上传中使用分组 ​

在查询中使用分组 ​

常见错误 ​

火山官方素材组 ​

相关页面 ​

素材分组

创建分组

请求字段

响应示例

查询分组列表

查询参数

响应示例

查询分组详情

更新分组

请求字段

删除分组

成功响应

在上传中使用分组

在查询中使用分组

常见错误

火山官方素材组

相关页面