视频生成/Seedance / 素材库

管理 Seedance 兼容的资产组和资产，用于可复用的视频工作流。

Seedance / 素材库

UniGateway 在自身媒体系统之上，对外提供了 Seedance 兼容的素材库接口。

调用面

项目值
Base URLhttps://api.unigateway.ai
鉴权Authorization: Bearer $UNIGATEWAY_API_KEY

覆盖路径

  • POST /api/v3/contents/generations/asset-groups
  • POST /api/v3/contents/generations/assets
  • POST /api/v3/contents/generations/assets/list
  • DELETE /api/v3/contents/generations/assets/{id}
  • 兼容别名：GET /v1/asset/groups、POST /v1/asset/list、POST /v1/delete/asset

运行规则

  • 同一条工作流内保持 ProjectName / project_name 一致。
  • 资产组归属校验属于公开契约的一部分，不要当成内部细节忽略。
  • 至少跑通一次“创建 -> 查询列表”的闭环后，再开放删除和批量操作。

创建资产组

  • 方法：POST
  • 路径：/api/v3/contents/generations/asset-groups

常见字段：

字段类型说明
Namestring必填，资产组名称。
Descriptionstring可选，资产组描述。
GroupTypestring常见值为 AIGC。
ProjectNamestring可选，用于逻辑项目隔离。

请求示例

{
  "Name": "character-references",
  "Description": "Approved Seedance reusable references",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

创建资产

  • 方法：POST
  • 路径：/api/v3/contents/generations/assets

常见字段：

字段类型说明
Namestring资产显示名。
AssetTypestring例如 Image 或 Video。
URLstring源文件 URL。
GroupIdstring绑定资产组时需要传。

补充说明：

  • 也接受小写别名字段，如 name、asset_type、url、group_id。
  • PollInterval、PollTimeout 这类轮询提示字段不属于公开契约，服务端会忽略。

请求示例

{
  "Name": "hero-reference-01",
  "AssetType": "Image",
  "URL": "https://images.example.com/hero-reference-01.png",
  "GroupId": "group-20260406234335-4t6cj"
}

响应示例

{
  "asset_id": "asset-upstream-1",
  "GroupId": "group-20260406234335-4t6cj",
  "AssetType": "Image",
  "URL": "https://images.example.com/hero-reference-01.png",
  "Status": "Creating"
}

查询资产

  • 方法：POST
  • 路径：/api/v3/contents/generations/assets/list
  • 兼容别名：POST /v1/asset/list

请求示例

{
  "Filter": {
    "GroupIds": ["group-20260406234335-4t6cj"],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc"
}

响应示例

{
  "Items": [
    {
      "Id": "asset-upstream-1",
      "Name": "hero-reference-01",
      "URL": "https://images.example.com/hero-reference-01.png",
      "GroupId": "group-20260406234335-4t6cj",
      "AssetType": "Image",
      "Status": "Processing",
      "ProjectName": "default",
      "CreateTime": "2026-04-07T00:00:00.000Z",
      "UpdateTime": "2026-04-07T00:00:03.000Z"
    }
  ],
  "TotalCount": 1,
  "PageNumber": 1,
  "PageSize": 20
}

删除资产

  • 方法：DELETE
  • 路径：/api/v3/contents/generations/assets/{id}
  • 兼容别名：POST /v1/delete/asset

可选字段：

  • ProjectName 或查询参数 project_name

cURL 示例

curl -X DELETE "https://api.unigateway.ai/api/v3/contents/generations/assets/asset-upstream-1?project_name=default" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

成功响应

{
  "success": true,
  "asset_id": "asset-upstream-1",
  "response": {
    "Result": {
      "Id": "asset-upstream-1"
    }
  }
}

访问与风控说明

  1. 创建资产前会先校验调用方是否拥有对应资产组。
  2. Seedance 每用户审核提交上限可能触发 429。
  3. 查询和删除资产时，UniGateway 会同步修正本地绑定状态与上游供应商状态。

常见失败场景

状态常见原因处理建议
400缺少资产组绑定或字段命名不合法重新检查必填字段，并在同一客户端保持一种请求结构
403调用方不拥有目标资产组修正账号或项目作用域
404资产或资产组不存在核对 ID 和项目命名空间
429审核限制或频控对写操作排队，并降低列表刷新频率