素材管理

同步或非同步上傳、任務查詢、下載、修改與批量讀取素材。

最近更新 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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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 去重併合並下載/分享統計）。