如果您正在 Seedance 2.0 或 2.0-Fast 上構建影片工作流，「素材庫」(Asset Library) 是您將參考媒體（圖像、影片和音訊）清晰地匯入生成任務的方式。您無需在每次呼叫時都傳遞原始媒體，只需註冊一次檔案，Atlas 會進行驗證和預處理，隨後您即可透過一個穩定的 ID 在任意數量的生成任務中引用該檔案。

本指南將帶您透過三個 cURL 呼叫，從零開始建立一個有效的參考素材。

什麼是素材庫（以及它不是什麼）

這是一個專為 Seedance 2.0 / 2.0-Fast 影片生成所設計的受管媒體儲存庫。您註冊一個素材，系統進行預處理，待其狀態變為「Active」後，您即可在生成請求中以

1asset://<asset_id>

在開始之前，請務必了解以下兩點，這將節省您的除錯時間：

• 影片和音訊必須先在此處註冊。 它們不能在生成請求中以 URL 的形式直接傳入。只有圖像可以內聯傳入。因此，對於任何影片或音訊參考工作流，素材庫是必經的入口，而非可選的便利功能。
• 僅支援透過公開 URL 上傳。 不支援 Base64 / 資料 URL。註冊時，檔案必須位於一個可公開存取的 URL 上。

開始之前

您需要從 控制台 取得 Atlas Cloud API 金鑰。

一個容易讓人混淆的細節：素材庫和生成 API 位於不同的主機上。

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

兩者使用相同的驗證標頭：

plaintextCopy
1export ATLASCLOUD_API_KEY="your-api-key-here"

plaintextCopy
1Authorization: Bearer $ATLASCLOUD_API_KEY

三步驟流程

註冊 → 輪詢直到變為「Active」 → 在生成中引用。

第一步 — 註冊素材

將 Atlas 指向一個公開 URL。設定類型為 Image（圖像）、Video（影片）或 Audio（音訊）（預設為 Image）。

plaintextCopy
1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "type": "Video",
6    "url": "https://your-public-host.com/reference-clip.mp4"
7  }'

回應會傳回素材的 id 以及 Processing（處理中）的狀態。

如下所示：

請記住該

1id

小提醒：什麼是「公開 URL」？

這是人們最常出錯的步驟，因此值得精確說明。Atlas 透過對該 URL 執行普通的 HTTP GET 請求來獲取檔案。該 URL 必須直接傳回原始檔案位元組——無需登入、無需 Cookie、無「點擊檢視」頁面，且無需 JavaScript 渲染。

快速測試方法：在無痕模式的瀏覽器分頁中開啟該 URL。如果圖片顯示或影片可下載且無需登入，Atlas 就可以獲取它。如果您看到的是檢視頁面、登入提示或預覽 UI，則無法使用。

這意味著 Google 相簿或 Google 雲端硬碟的分享連結是無法使用的。 這些連結指向的是一個網頁，該網頁在 Google 的驗證和重新導向系統後顯示您的媒體，而非直接指向檔案本身。Atlas 獲取到的會是網頁外殼，而非媒體。

可行方案：

• 設為公開讀取或使用預簽名 URL (Presigned URL) 的物件儲存 —— 如 Amazon S3、Google Cloud Storage、Cloudflare R2、Azure Blob。預簽名 URL 是理想選擇：公開但有時效限制。
• CDN 或您自己的 Web 伺服器 直接託管檔案。
• 使用 Atlas 自帶的上傳端點 —— 如果您只有本機檔案（或從 Google 相簿導出的檔案），請先將其上傳至 Atlas 以獲取公開的儲存 URL，然後再註冊該 URL：

plaintextCopy
1# 上傳本機檔案 → 傳回一個公開的 storage.atlascloud.ai URL
2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
4  -F "file=@./reference-clip.mp4"

取得回應中的 download_url，並將其用作第一步註冊素材時的 URL。

第二步 — 輪詢直到狀態變為「Active」

Atlas 會對檔案進行驗證和預處理。請輪詢該素材直到其狀態變為 Active。（當任務仍在 Processing 時，此端點會自動檢查上游作業狀態。）

plaintextCopy
1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

生命週期如下：

plaintextCopy
1Create → Processing → Active → (準備就緒)
2                  ↓
3                Failed → 檢查 error_code / error_message

若狀態為 Failed，error_code 和 error_message 會告知您原因——通常是格式、大小、時長或尺寸限制問題。請在重新註冊前參考下方的要求列表。

偶爾會看到如下所示的政策違規錯誤，這通常是因為素材觸發了安全限制。如果您堅信素材並未違反任何規則，或您本人即為著作權所有者，請聯絡我們以解決此問題！

第三步 — 在生成任務中引用

當素材狀態變為 Active 後，將 asset://<asset_id> 傳入您的 Seedance 請求對應欄位中——根據不同的端點，可能是 image、last_image、reference_images、reference_video 或 reference_audio。

注意此處的主機變更：生成任務位於 api.atlascloud.ai。

plaintextCopy
1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "bytedance/seedance-2.0/image-to-video",
6    "input": {
7      "prompt": "A cinematic dolly shot, warm sunset light",
8      "image": "asset://<asset_id>"
9    }
10  }'

這會傳回一個 prediction_id。請輪詢它以獲取最終生成的影片：

plaintextCopy
1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

當狀態為 completed（或 succeeded）時，結果 URL 將位於 outputs 中。

這就是完整的迴圈。素材的意義在於重複使用：註冊一次，即可在任意數量的生成任務中引用相同的 asset://<asset_id>。

管理素材

素材庫賦予您完整的生命週期控制權。

plaintextCopy
1# 列出您的素材（支援分頁與過濾）
2curl "https://console.atlascloud.ai/api/v1/sd/assets" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
4
5#重新命名素材
6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
7  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
8  -H "Content-Type: application/json" \
9  -d '{ "name": "sunset-reference-v2" }'
10
11# 移至垃圾桶（可復原——這是軟刪除，而非永久刪除）
12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
13  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
14
15# 列出垃圾桶中的素材
16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \
17  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
18
19# 從垃圾桶中還原
20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \
21  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

刪除操作設計為可復原的——素材會移至垃圾桶並可隨時還原，因此誤操作不會導致素材遺失。

輸入要求

驗證在註冊時進行，因此格式錯誤的檔案會在註冊階段失敗，不會浪費您的生成配額。請符合以下限制以避免

1Failed

圖像

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

影片

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

音訊

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

錯誤代碼

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

值得記住的注意事項

• 影片和音訊必須預先註冊。 只有圖像可以內聯傳遞。如果對影片/音訊跳過註冊，生成任務將無可引用的對象。
• 僅支援 URL，不支援 base64。 原始檔案在註冊時必須位於一個公開的 URL 上。
• 兩個主機。 素材庫在 console.atlascloud.ai；生成任務在 api.atlascloud.ai。混淆它們是導致 404 / 401 錯誤最常見的原因。
• 先驗證，後生成。 無效的輸入會在註冊階段就失敗，而不是等到生成過程中才報錯——這正是此機制的目的。請務必先參考要求表格。

開始構建

獲取 API 金鑰，並針對真實的 Seedance 2.0 端點嘗試此流程。

• 獲取 API 金鑰
• Seedance 2.0 模型
• 文件