MoonApiX Docs

Appearance

素材分组 ​

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

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

创建分组 ​

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

请求字段 ​

字段类型必填说明
namestring是分组名称。建议使用你的项目名、业务用户 ID 或场景名。
descriptionstring否分组说明。
domainstring否分组用途。素材上传常用 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>"

查询参数 ​

参数类型说明
pageinteger页码，默认 1。
page_sizeinteger每页数量，默认 20。
domainstring可选。按用途筛选，例如 media。
statusstring可选。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"
  }'

请求字段 ​

字段类型必填说明
namestring否新分组名称。
descriptionstring否新分组说明。

name 和 description 至少传一个。

在上传中使用分组 ​

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_idgroup_id 格式不正确。使用 group_xxx 格式的 ID。
asset_group_not_found分组不存在、已不可用，或不属于当前账号。重新查询分组列表，确认使用正确账号和 group_id。
missing_name创建分组时没有传 name。补充分组名称。
missing_update_fields更新分组时没有传可更新字段。传入 name 或 description。

相关页面 ​