OpenAPI 参考

Modelink API · 素材

Modelink 素材管理 API，提供素材分组与素材的创建、查询、更新与删除能力，用于视频生成等场景的参考素材管理。所有请求均需通过 Bearer Token 进行身份认证。

版本 1.0.0

查询素材分组列表

GET

/v1/asset-groups

分页查询当前用户的素材分组列表，支持按状态和类型过滤。

按创建时间倒序排序，已删除的分组不会返回。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

查询参数

Name
page
Type
integer
Description
页码，从 1 开始
Name
page_size
Type
integer
Description
每页大小，最大 100
Name
status
Type
enum
Description
状态过滤：pending（待处理）/ active（已激活）/ failed（失败）（awaiting_auth：真人组等待人工核验的中间态）
Name
type
Type
enum
Description
类型过滤：aigc（虚拟人像）（liveness_face：真人人像组）

请求体

暂无请求体

请求

GET/v1/asset-groups

curl 'https://api.qnaigc.com/v1/asset-groups?page={page}&page_size={page_size}&status={status}&type={type}' \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

查询成功

响应体属性

- qgroupidstring, 必填
  分组 ID（用户可见），格式 qgroup-{uid}-{ts}
- - aigc
  - liveness_face
- namestring, 必填
  分组展示名
- descriptionstring, 必填
  分组描述
- modelstring, 必填
  素材使用的模型标识，决定素材绑定的目标模型
- - pending
  - awaiting_auth
  - active
  - failed
- is_defaultboolean, 必填
  是否为该用户的默认分组（真人组恒为 false）
- fail_reasonstring
  失败原因，仅在 status=failed 时有值
- h5_linkstring
  真人认证 H5 刷脸链接，仅真人组 status=awaiting_auth 时返回。⚠️ 有效期约 120 秒，需引导用户尽快打开刷脸。aigc 组及终态不返回。
- byted_tokenstring
  真人认证凭证，仅真人组 status=awaiting_auth 时返回，供调用 visual-validate-result 时透传（可不传，平台有存）。aigc 组及终态不返回。
- created_atinteger<int64>, 必填
  创建时间（Unix 时间戳，秒）
- updated_atinteger<int64>, 必填
  更新时间（Unix 时间戳，秒）
totalinteger<int64>, 必填
总记录数
pageinteger, 必填
当前页码
page_sizeinteger, 必填
每页大小

object

请求参数错误，如 page/page_size 越界或 status/type 非法枚举。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "data": [
    {
      "qgroupid": "qgroup-uid001-1716100000000000000",
      "type": "aigc",
      "name": "我的虚拟人像分组",
      "description": "",
      "model": "bytedance/doubao-seedance-2-0-260128",
      "status": "active",
      "is_default": true,
      "created_at": 1716100000,
      "updated_at": 1716100050
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

创建素材分组

POST

/v1/asset-groups

创建一个新的素材分组。

处理流程：

鉴权检查 API Key
异步提交分组创建任务
立即返回 qgroupid 和 pending 状态

默认分组规则：用户的首个 Group 会自动设为默认（is_default=true）。

说明：分组创建为异步流程，调用方需轮询 GET /v1/asset-groups/{qgroupid} 获取最终状态。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

namestring, 必填
分组展示名（必填），最长 64 字符
descriptionstring
分组描述，可空，最长 300 字符
- aigc
- liveness_face
- bytedance/doubao-seedance-2-0-260128
- bytedance/doubao-seedance-2-0-fast-260128
- bytedance/doubao-seedance-2-0-mini-260615
- byteplus/dreamina-seedance-2-0-260128
- byteplus/dreamina-seedance-2-0-fast-260128
- byteplus/dreamina-seedance-2-0-mini-260615
- kling-element-v1
callback_urlstring<uri>
真人认证回调地址。type=liveness_face 时必填，须为合法 https URL；type=aigc 时忽略。

刷脸完成后浏览器会跳转到此地址并拼接 ?bytedToken=...&resultCode=10000&...，你的服务据此（确认 resultCode==10000）调 POST /v1/asset-groups/{qgroupid}/visual-validate-result 触发认证回查。

请求

POST/v1/asset-groups

curl https://api.qnaigc.com/v1/asset-groups \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "我的虚拟人像分组",
  "description": "用于存放公司形象虚拟人像素材",
  "type": "aigc",
  "model": "bytedance/doubao-seedance-2-0-260128"
}'

响应

object

创建成功（注意：实际状态为 pending，需轮询查询最终状态）

响应体属性

qgroupidstring, 必填
分组 ID（用户可见），格式 qgroup-{uid}-{ts}
- aigc
- liveness_face
namestring, 必填
分组展示名
descriptionstring, 必填
分组描述
modelstring, 必填
素材使用的模型标识，决定素材绑定的目标模型
- pending
- awaiting_auth
- active
- failed
is_defaultboolean, 必填
是否为该用户的默认分组（真人组恒为 false）
fail_reasonstring
失败原因，仅在 status=failed 时有值
h5_linkstring
真人认证 H5 刷脸链接，仅真人组 status=awaiting_auth 时返回。⚠️ 有效期约 120 秒，需引导用户尽快打开刷脸。aigc 组及终态不返回。
byted_tokenstring
真人认证凭证，仅真人组 status=awaiting_auth 时返回，供调用 visual-validate-result 时透传（可不传，平台有存）。aigc 组及终态不返回。
created_atinteger<int64>, 必填
创建时间（Unix 时间戳，秒）
updated_atinteger<int64>, 必填
更新时间（Unix 时间戳，秒）

object

请求参数错误：请求体非法、type 不支持、liveness_face 组缺 callback_url 或非 https、model 不在白名单、name/description 校验失败。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

素材配额或限额超限。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务暂不可用，任务消息发送失败。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "qgroupid": "qgroup-uid001-1716100000000000000",
  "type": "aigc",
  "name": "我的虚拟人像分组",
  "description": "用于存放公司形象虚拟人像素材",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "pending",
  "is_default": true,
  "created_at": 1716100000,
  "updated_at": 1716100000
}

触发真人认证回查（仅 liveness_face）

POST

/v1/asset-groups/{qgroupid}/visual-validate-result

真人组刷脸完成后，触发平台凭认证凭证向供应商换取认证结果（resolve），把分组从 awaiting_auth 推进到 active/failed。

调用时机（重要）：

必须在分组状态为 awaiting_auth 时调用（即 GET 已返回 h5_link）；分组仍 pending（建会话未完成）时调用返回 409。
⚠️ 务必在刷脸成功后才调用，且只调一次：刷脸成功（resultCode==10000）时，平台会用一次性凭证（byted_token）验证分组，该凭证查询一次即失效。请在浏览器跳回 callback_url 携带的 resultCode==10000 后再调。若 result_code 非 10000：本接口仍受理并返回 202，平台异步将该组判为 failed，不会消耗一次性凭证（不调用供应商换取接口）——但请勿在刷脸成功前用伪造的 10000 调用，否则会触发查询、白白烧掉凭证导致该组只能重建。

异步：本接口仅受理并返回 202，无论成功/失败的最终结果都需轮询 GET /v1/asset-groups/{qgroupid} 看 active/failed（非 10000 也会异步落 failed，而非本接口同步返回失败）。

幂等：分组已是 active/failed 终态时再调，直接返回 200 + 当前分组信息（不再触发回查）。

权限：只能操作当前用户自己的分组（qgroupid 须形如 qgroup-{uid}-*，否则 403）。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
qgroupid
Type
string, 必填
Description
真人分组 ID，格式 qgroup-{uid}-{ts}

请求体

请求体属性

result_codestring, 必填
刷脸结果码（必填），来自刷脸完成后浏览器跳转 callback_url 拼接的 resultCode 参数。10000=刷脸成功（平台才会向供应商换取 group_id）；非 10000 时本接口仍返回 202，平台异步将该组判为 failed 且不消耗一次性认证凭证（不调用供应商）。两种情况都通过轮询 GET 观察最终状态。
byted_tokenstring
认证凭证，可空。留空时平台使用建会话阶段已存储的 byted_token；如传入须与该分组存储的凭证一致，不一致返回 400 byted_token mismatch（防越权/误用一次性凭证）。

请求

POST/v1/asset-groups/{qgroupid}/visual-validate-result

curl https://api.qnaigc.com/v1/asset-groups/{qgroupid}/visual-validate-result \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "result_code": "10000",
  "byted_token": "20260612101859D18B5635A448320E5032"
}'

响应

object

分组已是终态（active/failed），幂等返回当前分组信息（未再触发回查）

响应体属性

qgroupidstring, 必填
分组 ID（用户可见），格式 qgroup-{uid}-{ts}
- aigc
- liveness_face
namestring, 必填
分组展示名
descriptionstring, 必填
分组描述
modelstring, 必填
素材使用的模型标识，决定素材绑定的目标模型
- pending
- awaiting_auth
- active
- failed
is_defaultboolean, 必填
是否为该用户的默认分组（真人组恒为 false）
fail_reasonstring
失败原因，仅在 status=failed 时有值
h5_linkstring
真人认证 H5 刷脸链接，仅真人组 status=awaiting_auth 时返回。⚠️ 有效期约 120 秒，需引导用户尽快打开刷脸。aigc 组及终态不返回。
byted_tokenstring
真人认证凭证，仅真人组 status=awaiting_auth 时返回，供调用 visual-validate-result 时透传（可不传，平台有存）。aigc 组及终态不返回。
created_atinteger<int64>, 必填
创建时间（Unix 时间戳，秒）
updated_atinteger<int64>, 必填
更新时间（Unix 时间戳，秒）

object

已受理回查请求（异步处理，请轮询 GET 看最终状态）

响应体属性

- awaiting_auth

object

请求参数错误（缺 result_code / 非 liveness_face 分组 / byted_token 与该组不一致等）

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

资源不存在

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

分组尚未进入 awaiting_auth（建会话未完成），需先等待 h5_link 就绪

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "qgroupid": "qgroup-xxx-1781230723000204313",
  "type": "liveness_face",
  "name": "我的真人人像分组",
  "description": "用于存放公司形象真人人像素材",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "active",
  "is_default": false,
  "created_at": 1781230723,
  "updated_at": 1781230860
}

查询单个素材分组

GET

/v1/asset-groups/{qgroupid}

查询指定 qgroupid 对应的素材分组详情。

权限：只能查询当前用户自己的分组（按 uid 过滤）。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
qgroupid
Type
string, 必填
Description
分组 ID，格式 qgroup-{uid}-{ts}

请求体

暂无请求体

请求

GET/v1/asset-groups/{qgroupid}

curl https://api.qnaigc.com/v1/asset-groups/{qgroupid} \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

查询成功

响应体属性

qgroupidstring, 必填
分组 ID（用户可见），格式 qgroup-{uid}-{ts}
- aigc
- liveness_face
namestring, 必填
分组展示名
descriptionstring, 必填
分组描述
modelstring, 必填
素材使用的模型标识，决定素材绑定的目标模型
- pending
- awaiting_auth
- active
- failed
is_defaultboolean, 必填
是否为该用户的默认分组（真人组恒为 false）
fail_reasonstring
失败原因，仅在 status=failed 时有值
h5_linkstring
真人认证 H5 刷脸链接，仅真人组 status=awaiting_auth 时返回。⚠️ 有效期约 120 秒，需引导用户尽快打开刷脸。aigc 组及终态不返回。
byted_tokenstring
真人认证凭证，仅真人组 status=awaiting_auth 时返回，供调用 visual-validate-result 时透传（可不传，平台有存）。aigc 组及终态不返回。
created_atinteger<int64>, 必填
创建时间（Unix 时间戳，秒）
updated_atinteger<int64>, 必填
更新时间（Unix 时间戳，秒）

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

资源不存在

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "qgroupid": "qgroup-root-1781230723000204313",
  "type": "liveness_face",
  "name": "我的真人人像分组",
  "description": "用于存放公司形象真人人像素材",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "awaiting_auth",
  "is_default": false,
  "h5_link": "https://h5-v2.kych5.com?accessKeyId=AKTP0V8amxFATDZB4p2zHK4vkICoXMCJgG661eKc1iTvQ8&secretAccessKey=lmaeWuqi3bf93I1boAlQUKrohadsewSuWbFchvIcJp1&sessionToken=nChBNa0N4OURzamFsTGZrWVdo.CiQKEEFuM0M5UHh6TDF5cXQ5ZFESELlECpexK0dRsvRfhJXI-HAQjtSt0QYY_92t0QYgvsLI8wcoBDC35IQvOiNSb2xlRm9yVmlzdWFsRmFjZS9Sb2xlRm9yVmlzdWFsRmFjZUIDYXJrUhFSb2xlRm9yVmlzdWFsRmFjZVgDegNhcms.p0qMcwPP7oTvs33tBBtv_C1bfI23NABWY1m-LvpxWzLK5OP2sNMWuiWrMzPHMcouFyzUVcuQNqKf4qMJeQ8l7Q&configId=861c572d-d32e-4260-b76d-9a9ca908e0b7&bytedToken=20260612101859D18B5635A448320E5032&lng=zh",
  "byted_token": "20260612101859D18B5635A448320E5032",
  "created_at": 1781230723,
  "updated_at": 1781230739
}

删除素材分组

DELETE

/v1/asset-groups/{qgroupid}

删除指定 qgroupid 的素材分组（异步）

前置约束：

分组必须为空：组内仍有未软删素材时返回 409，需先逐个删除素材；
分组不能处于 pending 状态：返回 409，需等待处理完成；
仅 active/failed 终态分组可删。

幂等：重复删除已删除/不存在的分组返回 404。

权限：只能删除当前用户自己的分组（qgroupid 须形如 qgroup-{uid}-*，否则 403）。

默认分组：允许删除默认分组，删除后下次创建素材时会自动重建。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
qgroupid
Type
string, 必填
Description
分组 ID，格式 qgroup-{uid}-{ts}

请求体

暂无请求体

请求

DELETE/v1/asset-groups/{qgroupid}

curl https://api.qnaigc.com/v1/asset-groups/{qgroupid} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

删除已受理

响应体属性

messagestring, 必填
固定为 deleted，表示删除已受理

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

资源不存在

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

分组无法删除：分组非空（仍有素材），或处于 pending/awaiting_auth 非终态。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务暂不可用，删除消息发送失败。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "message": "deleted"
}

更新素材分组

PATCH

/v1/asset-groups/{qgroupid}

更新指定分组的 name 或 description。

约束：

name 最长 64 字符
description 最长 300 字符
至少需要传入 name 或 description 中的一个

权限：只能更新当前用户自己的分组。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
qgroupid
Type
string, 必填
Description
分组 ID

请求体

请求体属性

namestring
分组展示名，最长 64 字符
descriptionstring
分组描述，最长 300 字符

请求

PATCH/v1/asset-groups/{qgroupid}

curl https://api.qnaigc.com/v1/asset-groups/{qgroupid} \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "更新后的分组名",
  "description": "新的分组描述"
}'

响应

object

更新成功，返回更新后的分组信息

响应体属性

qgroupidstring, 必填
分组 ID（用户可见），格式 qgroup-{uid}-{ts}
- aigc
- liveness_face
namestring, 必填
分组展示名
descriptionstring, 必填
分组描述
modelstring, 必填
素材使用的模型标识，决定素材绑定的目标模型
- pending
- awaiting_auth
- active
- failed
is_defaultboolean, 必填
是否为该用户的默认分组（真人组恒为 false）
fail_reasonstring
失败原因，仅在 status=failed 时有值
h5_linkstring
真人认证 H5 刷脸链接，仅真人组 status=awaiting_auth 时返回。⚠️ 有效期约 120 秒，需引导用户尽快打开刷脸。aigc 组及终态不返回。
byted_tokenstring
真人认证凭证，仅真人组 status=awaiting_auth 时返回，供调用 visual-validate-result 时透传（可不传，平台有存）。aigc 组及终态不返回。
created_atinteger<int64>, 必填
创建时间（Unix 时间戳，秒）
updated_atinteger<int64>, 必填
更新时间（Unix 时间戳，秒）

object

请求参数错误：请求体非法、name 超 64 或含控制字符、description 超 300、name 与 description 均未提供。

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

未提供有效的 API Key

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

鉴权通过但无权限访问

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

资源不存在

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

object

服务器内部错误

响应体属性

- messagestring, 必填
  人类可读的错误描述。
- - authentication_error
  - access_denied_error
  - invalid_request_error
  - quota_exceeded_error
  - rate_limit_exceeded_error
  - internal_server_error
  - service_unavailable_error
- codestring
  细分错误码（可选，素材接口通常不返回）。

响应

{
  "qgroupid": "string",
  "type": "aigc",
  "name": "string",
  "description": "string",
  "model": "string",
  "status": "pending",
  "is_default": true,
  "fail_reason": "string"
}