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, MoonNexAI will use default grouping.

Create Group

POST /v1/asset-groups

curl https://moonnexai.com/v1/asset-groups \
  -H "Authorization: Bearer <MOONNEXAI_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://moonnexai.com/v1/asset-groups?domain=media&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONNEXAI_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://moonnexai.com/v1/asset-groups/group_xxx \
  -H "Authorization: Bearer <MOONNEXAI_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://moonnexai.com/v1/asset-groups/group_xxx \
  -H "Authorization: Bearer <MOONNEXAI_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.

Use Grouping in Upload

curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_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://moonnexai.com/v1/assets?group_id=group_xxx&type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

curl "https://moonnexai.com/v1/assets/asset_xxx?group_id=group_xxx" \
  -H "Authorization: Bearer <MOONNEXAI_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.
asset_group_not_found	Grouping does not exist, is no longer available or does not belong to the current account.	Re-examine the group list to confirm the correct account and group_id.
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.

Relevant Pages

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