素材管理

同步或异步上传、任务查询、下载、修改与批量读取素材。

最近更新 2026-11-09

素材上传

大文件建议使用下方异步上传素材，提交后通过任务查询获取结果。

接口路径：/upload-assets

请求方式：POST

接口描述：将素材上传到DAM系统

请求参数：

参数名	类型	必填	描述
-	List<EnterpriseAssetSaveReq>	是	素材保存请求列表

本节介绍通过可下载 URL 上传素材的接入方式，以下参数要求适用于该方式。

EnterpriseAssetSaveReq参数说明：

字段名	类型	必填	描述
folderIds	List<Long>	否	目标文件夹 ID 列表；为空时需具备「上传到全部资产」等全局上传能力；非空时需对每一文件夹有上传权限
name	String	否	展示用文件名；不传时服务端会尽量从 `url` 路径推断
url	String	是	可直链下载的素材 URL（GET 可 200）；服务端下载后以新 key 落库，请勿使用会被防盗链/地域限制的短链
extension	String	是	文件后缀（如 `jpg`、`mp4`），与资源类型一致
size	Long	否	申报大小（字节）；实际上传后会以存储侧文件大小为准，可与客户端本地一致便于校验
width	Integer	否	图片/视频封面宽度（px）；图片未传时会尝试从落地文件读取
height	Integer	否	图片/视频封面高度（px）；图片未传时会尝试从落地文件读取
duration	Long	否	视频时长（毫秒）
link	String	否	关联的网页/来源链接
description	String	否	备注说明
rating	Integer	否	评分（写入素材评分字段；与内部 `score` 对应）
userId	Long	否	素材所有者用户 ID；不传时默认为创建者（当前 API Key 对应用户）；指定的用户须属于当前团队
oldAssetId	Long	否	上传新版本时填原素材 ID（>0）；将作为封面/版本关联的素材 id
metadatas	List<MetadataDTO>	否	自定义元数据；仅当团队开启自定义元数据时生效；`fieldId` 须与「元数据 fields」接口返回的 id 一致，且会校验字段合法性
skipDuplicateByEtag	Boolean	否	是否查重跳过，为 true 时：远端 URL 已拉取到素材 bucket 之后、写入素材库之前，按 OSS ETag 在团队内查重；若已存在相同内容，则不入库；开放接口返回项中的 id、key、accessUrl指向团队内已存在的素材。默认 false，与历史行为一致。
licenseAgreementIds	List<Long>	否	关联版权协议 ID；仅开启版权管理时生效，关闭时忽略
startTime	Date	否	素材有效期开始；仅关闭版权管理时生效，开启时忽略
endTime	Date	否	素材有效期结束；仅关闭版权管理时生效，开启时忽略
isPermanent	Boolean	否	素材是否永久有效；仅关闭版权管理时生效，开启时忽略

上传请求使用 startTime / endTime 写入素材有效期，搜索和批量获取响应对应 validStartTime / validEndTime。开启版权管理时，通过 licenseAgreementIds 关联协议，授权有效期以协议范围为准。

MetadataDTO（metadatas 元素）：

字段名	类型	必填	描述
fieldId	String	条件	元数据字段 ID（上传场景使用，与 fields 接口 id 一致）；与 `value` 成对出现
value	Object	否	字段值，类型需与该字段定义一致

响应参数：

参数名	类型	描述
assets	List<Item>	保存成功的素材列表

Item参数说明：

字段名	类型	描述
id	Long	素材ID
key	String	文件 URL，OSS 的 key 或可下载的文件
storePath	String	素材 OSS 存储路径，与 key 相同
skippedDuplicateByEtag	Boolean	团队内 ETag 查重命中并跳过上传时为 true；id、key、accessUrl 指向已有素材
name	String	标题名称
accessUrl	String	访问URL
uploadResult	String	返回值为 NEW 或者DUPLICATE_BY_ETAG · NEW : 本条为本次新上传并已入库 · DUPLICATE_BY_ETAG : 未入库，有重复的

示例：

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/upload-assets' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "folderIds": [
            23015
        ],
        "url": "https://example.com/assets/sample.jpg",
        "name": "测试图片",
        "extension": "jpeg"
    }
]'

响应示例：

json

{
    "code": "0",
    "message": "OK",
    "result": {
        "assets": [
            {
                "id": 6908936,
                "key": "api_b9648d4570d2e08364a451b1eec88eea.jpeg",
                "storePath": "api_b9648d4570d2e08364a451b1eec88eea.jpeg",
                "uploadResult": "NEW",
                "skippedDuplicateByEtag": false,
                "name": "测试图片",
                "accessUrl": "https://example.com/assets/sample.jpg"
            }
        ]
    }}

异步上传素材

接口路径: /upload-assets-async

请求方式: POST

通过可下载 URL 异步上传素材，立即返回任务号，文件下载与入库在后台执行。文件超过 20 MB 时建议使用本接口，避免同步下载超时。提交成功仅表示已获取任务号，素材是否上传成功需查询任务结果。

请求参数

JSON 数组，单次 1–50 条；每条沿用上方素材上传的 EnterpriseAssetSaveReq 公开字段与权限要求。每条必须提供可直接下载的 url；任一条缺少 url 时，请求报错（30313）。

字段名	类型	必填	描述
callbackUrl	String	否	可选的 HTTP 或 HTTPS 回调地址；仅异步上传使用。任务变为 SUCCESS 或 FAILED 后，服务端向该地址 POST 一次任务结果

任务复用与重试

同一团队、同一个 API Key 用户、完全相同的 url 字符串复用同一任务。素材所有者 userId 不参与任务复用判断。
任务进行中或已成功时，返回原 taskId，不重新下载或入库；文件夹、名称、元数据仍以第一次提交为准。
上次失败时，重新提交相同 URL 会复用原 taskId，并按本次请求参数重新执行。
URL 中签名或过期参数变化也会视为不同 URL，创建新任务。

响应参数

字段名	类型	描述
tasks	List<Item>	每个提交的 URL 对应一项任务
tasks[].taskId	String	32 位无横线 UUID；查询任务时使用，非素材 ID
tasks[].url	String	本次提交的 URL 原文

请求示例

bash

curl --request POST 'https://open.musedam.cc/api/muse/upload-assets-async' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '[
  {
    "folderIds": [
      23015
    ],
    "url": "https://example.com/assets/sample.mp4",
    "name": "产品视频",
    "extension": "mp4",
    "callbackUrl": "https://example.com/webhooks/musedam-upload"
  }
]'

响应示例

json

{
  "code": "0",
  "message": "success",
  "result": {
    "tasks": [
      {
        "taskId": "a1b2c3d4e5f64789a0b1c2d3e4f56789",
        "url": "https://example.com/assets/sample.mp4"
      }
    ]
  }
}

回调说明

回调使用 Content-Type: application/json，正文直接是下方查询接口的 result 对象，不包含外层 code、message、result。成功时包含素材信息；失败时 stage 为 FAILED，并返回 failReason。回调失败不影响任务状态；当前只发送一次，建议保留查询接口作为兜底。

json

{
  "taskId": "a1b2c3d4e5f64789a0b1c2d3e4f56789",
  "stage": "SUCCESS",
  "progress": 100,
  "transferredBytes": 52428800,
  "totalBytes": 52428800,
  "failReason": null,
  "materialId": 6908936,
  "storePath": "api_example.mp4",
  "name": "产品视频",
  "accessUrl": "https://example.com/assets/sample.mp4"
}

查询异步上传任务

接口路径: /upload-assets-task

请求方式: POST

按 taskId 查询任务。任务必须属于当前团队及当前 API Key 用户；不存在或归属不符时返回 30312。

请求参数

字段名	类型	必填	描述
taskId	String	是	32 位无横线 UUID；查询任务时使用，非素材 ID

响应参数

字段名	类型	描述
taskId	String	对外任务号
stage	String	当前任务阶段，见下表
progress	Integer	0–100：下载最高 80，写入存储 85，入库 95，成功 100；总大小未知时下载阶段为 0
transferredBytes	Long	已从 URL 下载的字节数
totalBytes	Long	源 URL 响应的 Content-Length；未返回时为空
failReason	String	失败原因；成功或进行中为空
materialId	Long	成功后的素材 ID
storePath	String	成功后的存储 key
name	String	成功后的素材名称
accessUrl	String	仅 SUCCESS 时返回；每次查询重新签发，有效期 1 天

任务阶段

阶段	含义
WAITING	等待处理
DOWNLOADING	从 URL 下载文件
SAVING	写入文件存储
INGESTING	素材入库
SUCCESS	上传完成，可使用返回的素材信息
FAILED	上传失败，查看 failReason；修正原因后重新提交

建议轮询至 stage 为 SUCCESS 或 FAILED 后停止。progress 是整体处理进度；下载总大小未知时，下载阶段保持 0，可通过 transferredBytes 观察已下载字节，不能仅凭进度 0 判定任务停滞。

请求示例

bash

curl --request POST 'https://open.musedam.cc/api/muse/upload-assets-task' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "taskId": "a1b2c3d4e5f64789a0b1c2d3e4f56789"
}'

响应示例

json

{
  "code": "0",
  "message": "success",
  "result": {
    "taskId": "a1b2c3d4e5f64789a0b1c2d3e4f56789",
    "stage": "SUCCESS",
    "progress": 100,
    "transferredBytes": 52428800,
    "totalBytes": 52428800,
    "failReason": null,
    "materialId": 6908936,
    "storePath": "api_example.mp4",
    "name": "产品视频",
    "accessUrl": "https://example.com/assets/sample.mp4"
  }
}

素材下载

素材下载不需要单独的接口，可以通过以下两种方式获取素材下载链接：

通过素材检索接口：调用 /search-assets 接口返回的数据中，每个素材对象都包含 downloadUrl 字段，该字段为素材的下载链接。
通过批量获取素材接口：调用批量获取素材接口返回的数据中同样包含下载链接。

获取到 downloadUrl 后，可以直接使用该 URL 进行素材下载。下载链接通常包含必要的认证信息和访问权限，可以直接在浏览器中打开或使用下载工具进行下载。

注意事项：

下载链接可能有10个小时的过期时间限制，建议在获取后尽快使用
下载大文件时，请确保网络连接稳定
如需批量下载，建议采用服务端脚本处理，避免客户端下载失败

素材原文件公开链接

团队须已开通「素材衍生 / 公开链接」扩展模块，否则请求会返回未开通模块错误。这两个接口仅处理原文件，不校验文件夹的公开链接开关或角色设置。

字段	类型	必填	说明
assetIds	`List<Long>`	是	素材检索或上传返回的 `materialId` 列表；单次最多 200 个。

查询原文件公开链接

POST /public-links-get

仅读取已有链接，不会创建链接。业务结果是以 materialId 为键的对象：值为不带图片处理参数的原始公开 URL；素材不存在或尚无公开链接时，值为 ""。

bash

curl --request POST 'https://open.musedam.cc/api/muse/public-links-get' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"assetIds": [1234567890, 9876543210]}'

业务结果示例

json

{
  "1234567890": "https://cdn.example.com/assets/photo.jpg",
  "9876543210": ""
}

生成原文件公开链接

POST /public-links-generate

为原文件发布公开链接。已有链接时直接返回，重复调用不会创建新链接。结果格式与查询相同；素材不存在或单条生成失败时，该 ID 的值为 ""，同批其他素材继续处理。

bash

curl --request POST 'https://open.musedam.cc/api/muse/public-links-generate' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"assetIds": [1234567890, 9876543210]}'

如需缩放或转换格式，请使用 processed-public-links；如需获取衍生版本的公开链接，请使用 asset-derivative-versions。详见智能解析与分发。

素材修改

接口路径：/modify-assets

请求方式：POST

接口描述：修改素材的基本信息，如名称、描述、评分等

请求参数：

参数名	类型	必填	描述
-	AssetModifyReq	是	素材修改请求参数

AssetModifyReq参数说明：

字段名	类型	必填	描述
id	Long	是	素材ID
name	String	否	文件名称
description	String	否	描述信息
score	Integer	否	评分（1-5）
link	String	否	网页链接
tags	List<Long>	否	标签ID列表

响应参数：

参数名	类型	描述
-	MiniDamAssetDTO	修改后的素材信息

MiniDamAssetDTO参数说明：

查看素材检索中的 MiniDamAssetDTO 参数说明

示例：

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/modify-assets' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id":6908914,
    "name":"bottomTip45",
    "description":"description 451",
    "score":5,
    "link":"wwww.baidu.com"
}'

响应示例：

json

{
  "code": "0",
  "message": "OK",
  "result": {
    "id": 6908914,
    "parentIds": [],
    "userId": "1673603133161799680",
    "name": "bottomTip45",
    "downloadUrl": "https://example.com/assets/sample.jpg",
    "source": null,
    "link": "wwww.baidu.com",
    "extension": "png",
    "duration": null,
    "size": 111948,
    "width": 290,
    "height": 220,
    "description": "description 451",
    "score": 5,
    "createTime": 1753428273000,
    "createUser": "1673603133161799680",
    "updateTime": 1753942888000,
    "updateUser": 367024606,
    "tags": [],
    "thumbnailAccessUrl": "https://example.com/assets/sample.jpg"
  },
  "traceId": "17539429013299310816"
}

素材移动到文件夹

接口路径：/move-assets-to-folder

请求方式：POST

接口描述：将一批素材从指定源文件夹移动或添加到目标文件夹。

请求参数：

字段名	类型	必填	描述
assetIds	List<Long>	是	素材 ID 列表；单次最多 200 条
fromFolderId	Long	条件	operationType=0（移动）时必填且 >0；素材当前所在、需解除关联的文件夹 ID
toFolderId	Long	是	目标文件夹 ID（>0）
operationType	Integer	否	0：移动（从 fromFolderId 解除后加入 toFolderId）；1：添加（保留源关系并加入目标）。默认 0

响应：Boolean

请求示例（移动）：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/move-assets-to-folder' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assetIds": [6908914, 6908820],
  "fromFolderId": 10001,
  "toFolderId": 10002,
  "operationType": 0
}'

注意事项：

素材、文件夹须存在且属于当前团队；需具备对应文件夹的编辑权限。
operationType=0 为移动，=1 为添加（素材同时存在于源文件夹和目标文件夹）。

批量删除素材

POST /delete-assets 将指定素材移入回收站。仅支持素材，不支持删除文件夹；开放 API 不提供永久删除或从回收站恢复的接口。

权限：仅限管理员类型的 API Key 或 appKey。企业版密钥须绑定系统管理员角色；成员类型密钥和用户登录会话不能调用。此接口不单独校验文件夹或素材的操作权限。限流：5 QPS。

请求字段	类型	必填	说明
assetIds	`List<Long>`	是	素材 `materialId` 列表，使用素材检索或上传返回的 ID。每次传 1–200 个。

响应：业务结果为 Boolean，成功时为 true；失败时返回开放 API 或业务错误。

请求示例：

bash

curl --request POST 'https://open.musedam.cc/api/muse/delete-assets' \
  --header 'Authorization: Bearer your_admin_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"assetIds": [6908914, 6908820]}'

批量获取素材

接口路径：/assets-by-ids

请求方式：POST

接口描述：根据素材ID列表批量获取素材详细信息

请求参数：

参数名	类型	必填	描述
-	List<Long>	是	素材ID列表

响应参数：

参数名	类型	描述
-	List<MiniDamAssetDTO>	素材信息列表

MiniDamAssetDTO参数说明：

查看素材检索中的 MiniDamAssetDTO 参数说明

批量获取返回的每条 MiniDamAssetDTO 同样包含 externalApp（外部应用标识）和 externalResourceRef（外部资源引用）。IngenOps 画布分别返回 ingenops 与对应的 workspace_ref；无外部关联时两者为 null。

示例：

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/assets-by-ids' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '[6908914,6908820]'

响应示例：

json

{
    "code": "0",
    "message": "OK",
    "result": [
        {
            "id": 6908914,
            "parentIds": [
                28566
            ],
            "userId": "1673603133161799680",
            "name": "bottomTip45",
            "downloadUrl": "https://example.com/assets/sample.jpg",
            "source": null,
            "link": "wwww.baidu.com",
            "extension": "png",
            "duration": null,
            "size": 111948,
            "width": 290,
            "height": 220,
            "description": "description 451",
            "score": 5,
            "createTime": 1753428273000,
            "createUser": "1673603133161799680",
            "updateTime": 1753942901660,
            "updateUser": 367024606,
            "tags": [],
            "thumbnailAccessUrl": "https://example.com/assets/sample.jpg"
        },
        {
            "id": 6908820,
            "parentIds": [],
            "userId": "1673603133161799680",
            "name": "Full-Stack-Serverless",
            "downloadUrl": "https://example.com/assets/sample.jpg",
            "source": null,
            "link": null,
            "extension": "epub",
            "duration": null,
            "size": 4567444,
            "width": null,
            "height": null,
            "description": null,
            "score": null,
            "createTime": 1753264933000,
            "createUser": "1673603133161799680",
            "updateTime": 1753264933000,
            "updateUser": 1673603133161799680,
            "tags": [
                {
                    "name": "社交媒体设计",
                    "id": 8223
                },
                {
                    "name": "平台定制",
                    "id": 8247
                },
                {
                    "name": "cadahsjdkhasdhasjkdhajshdasjkhdajskhdjakshdasjhdajshdjkashd",
                    "id": 9084
                },
                {
                    "name": "asdashdlajksdhjkashdjksahdjashdlasdj",
                    "id": 9096
                },
                {
                    "name": "ccc",
                    "id": 9097
                },
                {
                    "name": "网页设计",
                    "id": 8224
                },
                {
                    "name": "交互元素",
                    "id": 8270
                }
            ],
            "thumbnailAccessUrl": "https://example.com/assets/sample.jpg"
        }
    ],
    "traceId": "1753943463848693869"
}

按素材 ID 查询自定义元数据

接口路径：/metadata-records-by-ids

请求方式：POST

接口描述：按素材 ID 批量查询已写入的自定义元数据字段值。团队未开启自定义元数据、或某素材尚无元数据记录时，该 ID 不会出现在结果中。

请求参数：

字段名	类型	必填	描述
materialIds	List<Long>	是	素材 ID 列表；单次最多 50

响应：Map<Long, Object>，key 为素材 ID；value 为元数据对象（字段 name → value，并含 recordId、materialId 等）。

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/metadata-records-by-ids' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{"materialIds":[6908914,6908820]}'

响应示例：

json

{
  "code": "0",
  "message": "OK",
  "result": {
    "6908914": {
      "materialId": 6908914,
      "recordId": "rec_xxx",
      "你的字段名": "自定义值"
    }
  },
  "traceId": "..."
}

注意事项：

仅返回有元数据记录的素材；无记录的 ID 不会出现在 result 中。
上传时写元数据需使用字段 fieldId（见上传接口）；本接口读出的自定义字段以字段 name 为 key。

查询团队元数据字段列表

接口路径：/metadata-fields

请求方式：GET

接口描述：查询当前团队已配置的自定义元数据字段定义。上传素材时 metadatas[].fieldId 须取自本接口返回的字段 id。团队未开启自定义元数据时返回空列表。

响应：List<Object>，每项为字段定义对象：

字段名	类型	说明
id	String	字段 ID（上传时作为 fieldId）
name	String	字段名（修改素材元数据时作为 name）
field_type / type	String	字段类型（如 text、number、select 等，以实际返回为准）

请求示例：

bash

curl --location --request GET 'https://open.musedam.cc/api/muse/metadata-fields' \
--header 'Authorization: Bearer your_api_key'

注意事项：系统内置字段（如 materialId）也会出现在列表中，业务侧可按需过滤。

批量查询转移素材

说明： 根据素材 ID 列表，判断各素材是否为「成员资源转移」产生的素材（例如成员退出/移出时，资源被转给其他成员后生成的新素材记录）。

接口路径： /check-transferred-materials

请求方式： POST

请求参数： enterpriseTransferMaterialCheckReq

字段名	类型	必填	描述
assetIds	List<Long>	是	素材 ID 列表（与开放接口其它处 `id` / `assetIds` 含义一致，即 materialId）

响应： Map<Long, Boolean>;

Key： 请求中的素材 ID（assetId）
Value： true 表示为转移产生的素材；false 表示不是，或素材不存在

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/check-transferred-materials' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "assetIds": [1234567890, 9876543210]
}'

响应示例：

json

{
    "code": "0",
    "message": "OK",
    "result": {
        "1234567890": true,
        "9876543210": false
    },
    "traceId": "17561978534182325498"
}

注意事项：

请求参数字段名为 assetIds
请求中不存在的素材 ID 也会出现在响应中，对应值为 false。

查询素材取用者

说明：分页查询对指定素材有过下载或分享行为的用户（取用者）。数据来源于操作日志，按用户聚合统计次数与最近操作时间。素材须存在于当前团队。

接口路径：/material-access-users-query

请求方式：POST

请求参数：

字段名	类型	必填	说明
assetId	Long	是	素材 ID
operationTypes	List<Integer>	否	操作类型：1 下载，2 分享；不传或空则同时统计下载与分享
page	Integer	否	页码，默认 1
pageSize	Integer	否	每页条数，默认 20，最大 100

响应：含 total、items。items 元素：

字段名	类型	说明
userId	Long	用户 ID
realName	String	真实姓名
nickName	String	昵称
email	String	邮箱
phone	String	手机
avatarUrl	String	头像 URL
downloadCount	Long	下载次数（operationTypes 不含 1 时为 0）
lastDownloadTime	Date	最近下载时间
shareCount	Long	分享次数（operationTypes 不含 2 时为 0）
lastShareTime	Date	最近分享时间
lastOperationTime	Date	最近取用时间（下载或分享中较晚者）

请求示例：

bash

curl --location --request POST 'https://open.musedam.cc/api/muse/material-access-users-query' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assetId": 123456789,
  "operationTypes": [1, 2],
  "page": 1,
  "pageSize": 20
}'

注意事项：

仅统计当前团队内用户对目标素材的操作记录；已离职或已删除用户若日志中仍有记录，仍会返回其 userId 及统计字段，姓名等资料可能为空。
同一 userId 仅返回一条记录（按 userId 去重并合并下载/分享统计）。