AiVideoEditor
免费开始
菜单

审校于 2026-11-10 · API 版本 2026-11-09 · 阅读 Markdown

上传与保留媒体

媒体字节直接传输到临时私有对象存储。REST 和 MCP 返回上传指令;它们不在工具 JSON 中接受二进制文件内容。存储必须在部署上配置,否则创建上传会返回 provider_unavailable。

上传生命周期

  1. 调用 POST /api/v1/media/upload-intents,提供文件名、声明的 MIME 和字节数。将返回的 assetId 和 sessionId 作为单独的标识保存。
  2. 检查 method。对于 presigned_put,使用返回的请求头将整个文件上传到 uploadUrl。对于 multipart_initiated,按 partSizeBytes 分片,将每个编号分片上传到其返回的 URL 并保留其 ETag 回执。绝不要把 AiVideoEditor bearer 密钥加到存储请求中。
  3. 在 POST /api/v1/media/{assetId}/finalize 完成(finalize),提供 sessionId,multipart 时还要提供包含每个 partNumber 和 etag 的 multipart.parts。
  4. 在草稿的 mediaIds 中使用已完成(finalized)的资产 ID。仅上传意图本身不会使资产可发布。

服务器在不可变的最终副本上观察实际字节和格式。声明的大小/MIME 是预留输入,不是文件有效性的证明。支持的基线格式系列是 JPEG、PNG 和 MP4;单个目标可以施加更严格的限制。当前最大文件大小为 500 MiB(524,288,000 字节)。达到或超过 50 MiB 的文件使用 multipart,通常为 16 MiB 分片。始终遵循返回的大小、URL 和过期时间,而不是从这些默认值推导。

{
  "sessionId": "<session UUID from upload-intents>",
  "multipart": {
    "parts": [
      { "partNumber": 1, "etag": "<ETag returned by storage>" }
    ]
  }
}

这是 multipart 结构示例;包含每个实际分片。单次 PUT 完成只发送 sessionId。为每个新 API 变更提供自己的 Idempotency-Key;保留它以便安全的相同重试。

恢复或放弃

过期的签名 URL 不是永久的媒体地址。使用 POST /media/{id}/upload-parts 配合 fromPart 和 toPart(最多 64 个分片的闭区间)请求新的 multipart 分片 URL。有界请求结构参见 API 参考。不要不必要地重新上传已完成的分片,也不要直接通过存储完成 multipart 组装:完成(finalization)由服务器控制。

取消未完成的上传时使用 POST /media/{id}/abandon。这会通过共享清理工作流释放其预留。会话过期或已消耗的 multipart 状态可能需要新的意图;不要猜测存储对象键。

临时保留

GET /media/{id} 返回状态和动态的 deleteAfter 信息,而不是永久的公共 URL。已排期和进行中的使用会在工作期间保护媒体。默认策略将未使用的草稿媒体保留 14 天,已完成的媒体保留 72 小时,失败或结果不明的工作在相关尝试后保留 7 天。实际保留取决于所有剩余引用;deleteAfter 可能为 null。保留原始文件。如果媒体已过期或正在删除,请在发布前重新上传。