Modelink

OpenAPI 参考

Modelink API · 素材

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

版本 1.0.0

查询素材列表

GET
/v1/assets

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

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

认证方式

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 / reviewing / approved / failed

  • Name
    type
    Type
    enum
    Description

    类型过滤：image / video / audio

  • Name
    group_id
    Type
    string
    Description

    按分组过滤，传入 qgroup-{uid}-{ts} 形式的 qgroupid。前缀必须属于当前用户，否则返回 400。。若 group_id 前缀不属于当前用户，返回 403。

请求体

暂无请求体

请求

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

响应

object

查询成功

响应体属性

    • qassetidstring, 必填

      素材 ID（用户可见），格式 qasset-{uid}-{ts}

    • namestring, 必填

      素材展示名

    • modelstring, 必填

      素材使用的模型标识，决定素材绑定的目标模型

    • group_idstring

      关联的分组 ID（qgroupid）

    • fail_reasonstring

      失败原因（审核拒绝/提交失败/超时），仅在 status=failed 时有值

    • created_atinteger<int64>, 必填

      创建时间（Unix 时间戳，秒）

    • updated_atinteger<int64>, 必填

      更新时间（Unix 时间戳，秒）

  • totalinteger<int64>, 必填

    总记录数

  • pageinteger, 必填

    当前页码

  • page_sizeinteger, 必填

    每页大小

响应

application/json
{
  "data": [
    {
      "qassetid": "qasset-uid001-1716100100000000000",
      "type": "image",
      "name": "公司虚拟形象",
      "model": "bytedance/doubao-seedance-2-0-260128",
      "status": "approved",
      "group_id": "qgroup-uid001-1716100000000000000",
      "created_at": 1716100100,
      "updated_at": 1716100250
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

创建素材

POST
/v1/assets

提交一个素材进行审核。

处理流程：

  1. 鉴权检查 API Key
  2. 处理 Group：
    • 若传入 group_id，校验该 Group 属于当前用户且 status=active
    • 若未传入，自动选用默认 Group；若无默认 Group，自动异步创建一个 pending Group
  3. 异步提交素材审核任务
  4. 立即返回 qassetid 和 pending 状态

说明：素材审核为异步流程，状态会经过 pending → reviewing → approved/failed。审核完成后才能在视频生成中引用。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

请求体

请求体属性

  • urlstring<uri>

    Seedance 系列素材的源文件 URL，必须公网可访问；model=kling-element-v1 时忽略此字段。

  • namestring, 必填

    素材展示名（必填），最长 64 个字符

  • group_idstring

    关联的分组 ID（qgroupid），可空。

    留空规则：仅适用于虚拟人像——平台自动按 (uid, aigc, model) 维度选默认 active 分组；若无默认分组，自动异步创建 pending 分组并提交素材，素材状态会先停留在 pending 直到分组激活。

    传入规则：传入的 group 必须 status=active 且其 model 与请求的 model 一致，否则返回 400。

    真人素材（liveness_face 组）：⚠️ 必须显式传入已 active 的真人组 group_id——真人组需经活体认证创建，不支持自动建组；留空只会落到/新建 aigc 默认组。

    • frontal_imagestring<uri>

      主体正面图 URL；reference_type=image_refer 时必填。

    • refer_imagesstring<uri>[]

      其他角度的参考图 URL 列表；reference_type=image_refer 时可选，最多 3 张。

    • refer_videostring<uri>

      主体参考视频 URL；reference_type=video_refer 时必填。

请求

POST/v1/assets
curl https://api.qnaigc.com/v1/assets \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "image",
  "url": "https://img.somake.ai/cdn-cgi/image/width=800,quality=80,format=auto,fit=scale-down/tools/examples/face-generator_gallery_1763099237_8262.jpg",
  "name": "年轻男人",
  "model": "bytedance/doubao-seedance-2-0-260128"
}'

响应

object

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

响应体属性

  • qassetidstring, 必填

    素材 ID（用户可见），格式 qasset-{uid}-{ts}

  • namestring, 必填

    素材展示名

  • modelstring, 必填

    素材使用的模型标识，决定素材绑定的目标模型

  • group_idstring

    关联的分组 ID（qgroupid）

  • fail_reasonstring

    失败原因（审核拒绝/提交失败/超时），仅在 status=failed 时有值

  • created_atinteger<int64>, 必填

    创建时间（Unix 时间戳，秒）

  • updated_atinteger<int64>, 必填

    更新时间（Unix 时间戳，秒）

响应

application/json
{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "公司虚拟形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "pending",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100100
}

查询单个素材

GET
/v1/assets/{qassetid}

查询指定 qassetid 对应的素材详情，包括审核状态。

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

轮询建议：素材状态从 pending → reviewing → approved/failed，轮询时关注 status 字段；status=approved 后即可在视频生成中通过 qasset://{qassetid} 引用。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

路径参数

  • Name
    qassetid
    Type
    string, 必填
    Description

    素材 ID，格式 qasset-{uid}-{ts}

请求体

暂无请求体

请求

GET/v1/assets/{qassetid}
curl https://api.qnaigc.com/v1/assets/{qassetid} \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

查询成功

响应体属性

  • qassetidstring, 必填

    素材 ID（用户可见），格式 qasset-{uid}-{ts}

  • namestring, 必填

    素材展示名

  • modelstring, 必填

    素材使用的模型标识，决定素材绑定的目标模型

  • group_idstring

    关联的分组 ID（qgroupid）

  • fail_reasonstring

    失败原因（审核拒绝/提交失败/超时），仅在 status=failed 时有值

  • created_atinteger<int64>, 必填

    创建时间（Unix 时间戳，秒）

  • updated_atinteger<int64>, 必填

    更新时间（Unix 时间戳，秒）

响应

application/json
{
  "qassetid": "string",
  "type": "image",
  "name": "string",
  "model": "string",
  "status": "pending",
  "group_id": "string",
  "fail_reason": "string",
  "created_at": 42
}

删除素材

DELETE
/v1/assets/{qassetid}

删除指定 qassetid 的素材（异步）。

前置约束：仅终态素材可删——status 为 approved 或 failed；pending/reviewing 状态返回 409。

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

权限：只能删除当前用户自己的素材（qassetid 须形如 qasset-{uid}-*，否则 403）。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

路径参数

  • Name
    qassetid
    Type
    string, 必填
    Description

    素材 ID，格式 qasset-{uid}-{ts}

请求体

暂无请求体

请求

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

响应

object

删除已受理

响应体属性

  • messagestring, 必填

    固定为 deleted，表示删除已受理

响应

application/json
{
  "message": "deleted"
}

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify