存储库
存储库用于将模型生成的文件保存到你自己的云存储。创建任务时指定存储库 ID,平台会在生成成功后自动转存产物,并通过任务查询结果返回文件访问地址。
本文以 Seedance 视频任务为例,转存内容包括生成的视频,以及请求生成并实际返回的尾帧图片。其他模型是否支持自定义存储,请以对应接口文档为准。
使用前准备
- 准备云存储桶、访问凭据和文件访问地址。
- 登录平台控制台,进入「存储库」页面,创建配置并通过连通性检测。
- 复制存储库 ID(UUID),确认存储库属于 API Key 所属用户,且处于可用状态。
云存储访问凭据与调用模型的 API Key 不同,不要把桶名或云存储访问密钥当作存储库 ID。
请求说明
在创建任务的请求头中添加 OSS 参数,不放入 JSON 请求体。oss-id 和 oss-path 均为选填。
oss-id:存储库 UUID。需要使用自定义存储时填写;不传时使用平台默认存储。仅在服务开放自定义存储功能时使用。oss-path:存储库目录前缀,例如file/images。不传oss-id时,此参数不生效。
只在控制台创建存储库配置不会自动改变任务的存储位置。每次需要使用自定义存储时,都应在创建请求中传入 oss-id。
请求头 Headers(示例)
{
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY",
"oss-id": "YOUR_STORAGE_UUID",
"oss-path": "file/images"
}以上 JSON 用于展示请求头名称和值,并非请求体。将 YOUR_API_KEY、YOUR_STORAGE_UUID 和 file/images 替换为实际 API Key、存储库 UUID 和目录前缀。
Seedance 创建请求的请求头形式如下:
POST /api/v3/contents/generations/tasks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
oss-id: YOUR_STORAGE_UUID
oss-path: file/imagesAuthorization 和 Content-Type 为创建任务的必填请求头。完整模型参数见创建视频任务,认证方式见身份认证。
存储路径规则
oss-path最多 128 个字符,支持英文字母、数字、下划线、连字符、点及/。- 首尾空白和首尾
/会被去除;不允许..、单独的点目录、连续/、中文、空格或其他特殊字符。 - 有效示例:
file/images、videos/2026-11、output_v1。 - 无效示例:
../videos、projects//demo、./videos、我的视频。
该参数是目录前缀,不是文件名或完整 URL。平台会继续追加资源类型、日期和文件名。
省略或留空时,不添加自定义目录前缀,文件仍会按资源类型和日期组织,不表示文件直接保存在存储桶根目录。最终地址以任务查询结果为准。
获取转存结果
受理成功后保存返回的任务 id,使用创建时的同一个 API Key 查询任务。查询请求无需重复添加 oss-id 和 oss-path,存储目标已在创建时确定。
模型生成成功与文件转存完成是两个进度。status=succeeded 表示模型生成成功,此时文件仍可能正在转存。查询时还需关注:
custom_storage_status:PENDING待转存、PROCESSING转存中、SUCCESS转存成功、FAILED转存失败。content.video_url:已就绪的视频访问地址。content.last_frame_url:请求生成且已就绪的尾帧图片访问地址。can_retry_transfer:是否存在仍可重试的失败产物;为true不代表已经发起重试。transfer_source_expired:是否存在来源已过期或无法下载的失败产物。transfer_error_message:转存失败说明。
请继续查询,取得所需文件地址后再下载。下载产物时无需向文件地址发送平台 API Key。
查询方式及完整响应说明见查询视频任务。
常见问题
提示存储库无效或参数错误怎么办?
InvalidStorageRepo:检查 UUID、所属用户,以及存储库是否已删除或不可用。CustomStorageDisabled:当前服务未开放自定义存储,请联系平台支持确认。InvalidParameter:检查oss-id的 UUID 格式及oss-path的长度和字符规则。
模型生成成功,但转存失败怎么办?
查看 transfer_error_message,检查云存储凭据、权限、桶和网络配置。若 can_retry_transfer=true,可通过平台提供的转存重试功能重试原任务,或联系平台支持处理。
转存重试只重新保存已有产物,不会再次调用模型生成。源文件失效后,对应产物无法继续转存;多产物任务中,can_retry_transfer 与 transfer_source_expired 可能同时为 true,表示只有部分失败产物仍可重试。不要仅因转存失败重复创建生成任务,以免产生新的生成费用。
修改或删除存储库会影响已有任务吗?
任务使用创建时绑定的配置版本。修改配置后,新创建的任务使用新版本,已受理任务及其转存重试继续使用原配置;请保持在途任务所需的旧配置可用。
删除存储库会阻止新任务继续选择该库,不会删除云存储中已有的产物。已受理任务仍可能按原配置继续转存,云端文件由你在云存储侧管理。
私有链接过期后如何访问文件?
私有读链接的有效期为配置的 1~7 天,从链接签发时起计算。重复查询任务不会刷新链接,也不会延长有效期。
链接过期不代表文件被删除。请通过自己的云存储管理方式获取文件或签发新链接,并保留完整 URL 和签名参数,不要自行替换域名或修改路径。

