跳转到正文
阅读设置
开发支持

存储库 ​

存储库用于将模型生成的文件保存到你自己的云存储。创建任务时指定存储库 ID,平台会在生成成功后自动转存产物,并通过任务查询结果返回文件访问地址。

本文以 Seedance 视频任务为例,转存内容包括生成的视频,以及请求生成并实际返回的尾帧图片。其他模型是否支持自定义存储,请以对应接口文档为准。

使用前准备 ​

  1. 准备云存储桶、访问凭据和文件访问地址。
  2. 登录平台控制台,进入「存储库」页面,创建配置并通过连通性检测。
  3. 复制存储库 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(示例) ​

json
{
  "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 创建请求的请求头形式如下:

http
POST /api/v3/contents/generations/tasks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
oss-id: YOUR_STORAGE_UUID
oss-path: file/images

Authorization 和 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 和签名参数,不要自行替换域名或修改路径。