如果您正在使用 Seedance 2.0 或 2.0-Fast 构建视频工作流，资源库（Asset Library）是您将参考媒体（图像、视频和音频）干净利落地导入生成任务的方式。您无需在每次调用时都传递原始媒体，只需注册一次文件，Atlas 会对其进行验证和预处理，之后您就可以通过一个稳定的 ID 在任意多次生成中引用它。

本指南将带您通过三个 cURL 调用，从零开始实现一个有效的参考引用。

什么是资源库（以及它不是什么）

这是一个专为 Seedance 2.0 / 2.0-Fast 视频生成任务设计的托管媒体存储库。您注册一个资源，系统对其进行预处理，一旦状态变为 Active，您就可以在生成请求中通过 asset://<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 → 在生成中引用。

第 1 步 — 注册资源

将 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（处理中）状态。

如下图所示：

请保留该 ID（上图中高亮部分）——这是您后续轮询和引用时需要用到的。

小贴士：什么是“公共 URL”？

这是人们最常出错的一步，所以必须明确：Atlas 通过对 URL 执行简单的 HTTP GET 来获取您的文件。该 URL 必须直接返回原始文件字节 —— 不需要登录、不需要 Cookie、不需要“点击查看”页面，也不需要 JavaScript 渲染。

快速测试：在无痕/隐私模式的浏览器标签页中打开该 URL。如果图像直接显示或视频直接下载，无需登录，那么 Atlas 就可以获取它。如果您看到一个查看页面、登录提示或预览 UI，则无法获取。

这意味着 Google 相册或 Google 云端硬盘的共享链接无法使用。 这些链接指向的是网页，您的媒体资源被保护在 Google 的身份验证和重定向系统之后，并非指向文件本身。Atlas 获取的将是页面外壳，而非媒体文件。

可行的替代方案：

• 支持公共读取或预签名 URL 的对象存储 — 如 Amazon S3、Google Cloud Storage、Cloudflare R2、Azure Blob。预签名 URL 是理想的选择：既公开又有时效限制。
• CDN 或您自己的 Web 服务器，直接提供文件服务。
• Atlas 自身的上传端点 — 如果您只有本地文件（或从 Google 相册导出的文件），请先将其上传到 Atlas 以获取公共存储 URL，然后再注册该 URL：

plaintextCopy
1# 上传本地文件 → 返回一个 public 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"

获取该响应中的

1download_url

第 2 步 — 轮询直到 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 会告诉您原因——通常是格式、大小、时长或尺寸限制问题。请在重新注册前查看下方的要求表格。

偶尔，您会看到如下的策略违规错误——这通常是因为资源违反了审核准则。如果您确信该资源未违反任何规则，或者您本人即为版权所有者，请联系我们解决！

第 3 步 — 在生成任务中引用它

一旦资源处于 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。轮询该 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

图像 (Image)

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;}

视频 (Video)

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;}

音频 (Audio)

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 模型
• 文档