Asset groups

media assets groups are used to isolate media assets under the same account by project, business user or scene. Once a grouping is created, group_id is entered in upload, list and detailed query, only to access media assets within that grouping.

If group_id, MoonApiX will use default grouping.

Visual liveness verification returns a private asset-group group_id, not an asset ID. The group may initially be empty; uploading media into it creates the asset_xxx. See Visual liveness verification.

Create Group

POST /v1/asset-groups

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

Request fields

field	Type	shall fill	Annotations
name	string	Yes.	Group Name. Suggest your project name, business user ID or scene name.
description	string	Yes	Description of the cluster.
domain	string	Yes	Grouping uses. media assets uploads commonly used media; treated with default media assets applications when not uploaded.

Example response

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

Saves the returned group_id, which is used for subsequent uploads and queries.

Query Group List

GET /v1/asset-groups

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

Query Parameters

Parameters	Type	Annotations
page	integer	Page number, default 1.
page_size	integer	Number of pages per page, default 20.
domain	string	Optional. Filter by use, e.g. media.
status	string	Optional. enabled or disabled.

Example response

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

Query Group Details

GET /v1/asset-groups/{group_id}

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

If group_id is not currently account, or the format is incorrect, the error returns.

Update Group

PATCH /v1/asset-groups/{group_id}

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

Request fields

field	Type	shall fill	Annotations
name	string	Yes	New group name.
description	string	Yes	Note on new groups.

name and description pass at least one.

Delete a group

DELETE /v1/asset-groups/{group_id}

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

Deletion is a soft delete: the custom group's status changes to disabled. A group can be deleted even when it contains assets. Deleting a group does not delete or move its assets, physically remove hosted files, or revoke existing authentication references in other services.

Default and system groups cannot be deleted and return HTTP 409 with error code protected_group. Deleting an already disabled group returns HTTP 404 with error code group_not_found.

Success response

HTTP 200 returns the group object with status: "disabled" and deleted: true:

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

Use Grouping in Upload

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

After uploading successfully, the group_id in response will be equal to the group ID you have uploaded.

Use grouping in queries

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

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

The details search belt group_id returns if media assets is not in that group. This mechanism can be used to verify the media assets and grouping relationships that are saved side by side of the operation.

Common Errors

code	Annotations	Treatment
invalid_group_id	The group_id format is incorrect.	Use the ID in group_xxx format.
group_not_found	The group does not exist, belongs to another account, or is already disabled when deletion is requested.	Check the group list, account, group_id, and group status.
protected_group	HTTP 409. Default and system groups cannot be deleted.	Delete custom groups only.
missing_name	Creates a group without passing name.	Additional group name.
missing_update_fields	No updates of field were sent to update the group.	Import name or description.

Official Volcengine Asset Groups

seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini and seedance-2.5-sz support official asset groups. Create a MoonApiX custom group first, then create its official group. Management paths always use your MoonApiX group_id; use the actual public model selected for the assets.

Operation	Method and Path	Model Location
Create official group	POST /v1/asset-groups/{group_id}/upstream	JSON body
List registered official groups	GET /v1/asset-groups/upstream	Query parameter
Read official group	GET /v1/asset-groups/{group_id}/upstream	Query parameter
Update name or description	PATCH /v1/asset-groups/{group_id}/upstream	JSON body
Delete an empty official group	DELETE /v1/asset-groups/{group_id}/upstream	Query parameter

The examples use fictitious IDs and an API key already provided in the MOONAPIX_API_KEY environment variable:

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

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

Creation returns HTTP 201, or 200 for an existing relationship:

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

Top-level group_id is the MoonApiX group ID. upstream.group_id is the registered official group ID used by ID resolution. A differing official group ID observed in a later detail appears as upstream.observed_group_id; keep both rather than overwriting the registered value. Resolve using upstream.group_id.

PATCH requires at least one of name or description. Names must not be blank and are limited to 64 characters; descriptions allow at most 300. Updates affect the official group, not the MoonApiX group. Reads may show the previous name for several minutes; query the same group at intervals rather than creating a replacement.

Lists include only groups registered to your account in the selected model asset scope. They do not import other or unregistered official resources. Pagination uses offset / limit, defaulting to 0 / 20, with limit 1..100.

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"

Delete the official assets first. A nonempty group or active preparation returns 409. Successful deletion returns 200, deleted=true, and keeps the MoonApiX group. An uncertain delete can be retried on the same subresource. Default or historical shared groups may not allow independent edits, deletion or resolution; create a dedicated official group for full group management. For upload, preparation, official IDs and cleanup, see official assets.

Relevant Pages

• Upload Media Asset
• Query Media Asset
• Uploading and Media Asset Overview