> This page is for Camera to Cloud. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # 操作指南：上传（实时） ## 前言在我们掌握了基本的上传知识后，让我们进一步探讨如何在资产创建过程中进行实时上传。这种方法支持在录制、渲染或流式传输过程中上传文件，无需等待确定最终文件大小。通过实时上传 API，资产在录制完成后仅需数秒即可在 Frame.io 中播放，显著提升了工作流程效率。 ## 演示视频如需快速预览此功能，请观看我们的[视频演示](https://f.io/qjwfGmTa)。该演示展示了从 Adobe Media Encoder 实时上传渲染文件的过程，视频在渲染完成后仅需 5 秒即可在 Frame.io 中播放。 ## 前提条件如果您尚未阅读，请先参阅[实施 C2C：设置](./implementing-c2c-setting-up)指南。您需要用到在[身份验证和授权流程](./implementing-c2c-authentication-and-authorization)中获取的 `access_token`。在示例中，我们将使用基础上传指南中的同一个[测试资产](https://f.io/Rq1q5CzB)。建议先熟悉[基础上传指南](./how-to-basic-upload)，因为我们将基于其中的概念进行扩展。 ## 创建实时资产实时上传始于修改后的资产创建流程。创建资产时，需将 `is_realtime_upload` 设置为 `true`，并省略 `filesize` 参数（或将其设置为 `null`），因为在创建过程中无法确定最终大小： ```shell { curl -X POST https://api.frame.io/v2/devices/assets \ --header 'Authorization: Bearer [access_token]' \ --header 'Content-Type: application/json' \ --header 'x-client-version: 2.0.0' \ --data-binary @- <<'__JSON__' { "name": "C2C_TEST_CLIP.mp4", "filetype": "video/mp4", "is_realtime_upload": true } __JSON__ } | python -m json.tool ``` `/v2/devices/assets` 的文档可以在[此处找到](/camera-to-cloud/api-reference/device-asset-create)。实时资产需要提供文件扩展名。如果在创建资产时不知道文件名，您可以使用 `extension` 字段代替（格式：`'.mp4'`）。如果您计划稍后更新资产名称，建议采用此方式。与标准资产创建相比，实时资产的响应得到了简化： ```json { "id": "{asset_id}", "name": "C2C_TEST_CLIP.mp4" } ``` 请注意，结果中不包含 `upload_urls`——对于实时上传，我们将在创建文件时按需生成上传 URL。 ## 请求上传 URL 接下来，我们将使用上一个响应中的 `asset_id`，为文件的前半部分（10,568,125 字节）请求一个 URL： ```shell { curl -X POST https://api.frame.io/v2/devices/assets/{asset_id}/realtime_upload/parts \ --header 'Authorization: Bearer [access_token]' \ --header 'Content-Type: application/json' \ --header 'x-client-version: 2.0.0' \ --data-binary @- <<'__JSON__' { "parts": [ { "number": 1, "size": 10568125, "is_final": false } ] } __JSON__ } | python -m json.tool ``` `/v2/devices/assets/{asset_id}/realtime_upload/parts` 的文档可以在[此处找到](/camera-to-cloud/api-reference/device-create-realtime-upload-parts)。理解请求参数： * `parts`：我们需要获取 URL 的上传分段列表。在单次调用中请求多个 URL 可提高效率。 * `number`：分段的顺序编号，从 1 开始。编号可以跳过，且分段可以按任意顺序上传，但会按顺序进行组装。不能超过 10,000（AWS 限制）。 * `size`：分段大小（以字节为单位）。必须符合 [AWS 多分段上传限制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html)。 * `is_final`：指示是否为文件的最后一个分段。响应包含所请求的上传 URL： ```json { "upload_urls": [ "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path]" ] } ``` `upload_urls` 列表直接对应于 `parts` 请求顺序。现在按照基础上传指南中的方式上传第一个分片： ```shell head -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \ curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @- ``` 接下来，为第二个也是最后一个分段请求 URL： ```shell { curl -X POST https://api.frame.io/v2/devices/assets/{asset_id}/realtime_upload/parts \ --header 'Authorization: Bearer [access_token]' \ --header 'Content-Type: application/json' \ --header 'x-client-version: 2.0.0' \ --data-binary @- <<'__JSON__' { "asset_filesize": 21136250, "parts": [ { "number": 2, "size": 10568125, "is_final": true } ] } __JSON__ } | python -m json.tool ``` 请注意以下重要的新增内容： * 对于最后一个分段，将 `is_final` 设置为 `true`，表示上传将在该分片完成后结束 * `asset_filesize` 提供文件的总大小，当任何分段设置 `is_final: true` 时，此参数均为必填项在响应中收到 URL 后： ```json { "upload_urls": [ "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path]" ] } ``` 上传最后一个分片： ```shell tail -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \ curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @- ``` 当最后一个分段上传完成后，Frame.io 开始组装完整文件。此过程包括一个 60 秒的宽限期，用于等待其余分段完成上传。我们建议仅在所有其他分段成功上传之后，再上传最后一个分段。就是这样！导航到 Frame.io 即可查看您成功上传的实时资产。 🎉 ## 管理资产名称如果在创建资产时文件名未知，您可以使用`扩展名`字段而不指定`名称`： ```shell { curl -X POST https://api.frame.io/v2/devices/assets \ --header 'Authorization: Bearer [access_token]' \ --header 'Content-Type: application/json' \ --header 'x-client-version: 2.0.0' \ --data-binary @- <<'__JSON__' { "extension": ".mp4", "filetype": "video/mp4", "is_realtime_upload": true } __JSON__ } | python -m json.tool ``` 系统将分配一个默认名称： ```json { "id": "{asset_id}", "name": "[new file].mp4" } ``` 您可以在请求上传 URL 时包含 `asset_name` 字段来更新此名称： ```shell { curl -X POST https://api.frame.io/v2/devices/assets/{asset_id}/realtime_upload/parts \ --header 'Authorization: Bearer [access_token]' \ --header 'Content-Type: application/json' \ --header 'x-client-version: 2.0.0' \ --data-binary @- <<'__JSON__' { "asset_name": "C2C_TEST_CLIP.mp4", "asset_filesize": 21136250, "parts": [ { "number": 2, "size": 10568125, "is_final": true } ] } __JSON__ } | python -m json.tool ``` 仅当资产仍为其默认名称时，该名称才会更新；如果资产已在 Frame.io UI 中重命名或之前已更新，则请求将被忽略。 ## 优化 URL 请求为了提高效率，请根据当前可用的数据量，请求尽可能多的分段 URL，而不是逐个请求。这种方法对于上传速度可能落后于数据生成速度的大文件尤其有价值。 ## 处理媒体文件标头某些媒体格式需要在文件开头包含标头，而这些标头只有在整个文件完成后才会写入。当标头大小低于 AWS 最小分段大小 5 MiB（5,242,880 字节）时，就会带来问题。我们的建议如下： 1. 保留媒体数据的前 5,242,880 字节，暂不上传 2. 从 `part_number=2` 开始上传后续分段 3. 文件完成后，将标头添加到所保留数据的前面 4. 为 `part_number=1` 请求一个 URL，并上传此合并后的分片这种方法既能确保您的第一个分片满足最小大小要求，又能保持正确的文件结构。 ## 调整分段大小以获得最佳性能 AWS 对上传策略施加了以下限制： * 最大文件大小：5 TiB（5,497,558,138,880 字节） * 最大分段数量：10,000 * 最小分段大小：5 MiB（5,242,880 字节）固定分段大小会产生以下权衡： * 若所有 10,000 个分段都使用最小大小 (5 MiB)，则总文件大小上限约为 52.4 GB * 若要平均分配最大文件大小，则需要约 550 MB 分片，这对于较小文件的高效流传输来说又太大了我们需要一个能在这些约束之间取得平衡的公式：从较小的分段开始以实现响应式上传，同时确保在需要时能够处理非常大的文件。 ### 推荐的分段大小公式以下是我们建议的 Python 方法： **`Python`** ```python title="Python" import math from typing import Callable # Constants MINIMUM_PART_SIZE = 5_242_880 MAXIMUM_PART_COUNT = 10_000 MAXIMUM_FILE_SIZE = 5_497_558_138_880 # Maximum uniform data rate that allows for 10,000 parts MAXIMUM_DATA_RATE = MAXIMUM_FILE_SIZE // MAXIMUM_PART_COUNT def part_size(part_number: int, format_bytes_per_second: int) -> int: """ Returns the payload size for a specific part number given the file's expected data rate. """ if part_number < 1: raise ValueError("part_number must be greater than 0") if part_number > 10_000: raise ValueError("part_number must be less than 10,000") # Make sure we never go above the maximum data rate or fall below the # minimum part size, even if the data rate is lower. data_rate = min(format_bytes_per_second, MAXIMUM_DATA_RATE) data_rate = max(data_rate, MINIMUM_PART_SIZE) # Calculate a scalar given our data rate. We will explain this step # futher on in the guides. scalar = -(2 * (125 * data_rate - 68_719_476_736)) / 8_334_583_375 part_size = math.floor(scalar * pow(part_number, 2)) + data_rate return part_size ``` …其中 `part_number` 介于 `1` 和 `10_000` 之间（包含边界值），`format_bytes_per_second` 是您的文件预计每秒消耗的平均字节数。我们将在[后面](/camera-to-cloud/how-to-upload-realtime#showing-our-work)详细介绍该公式的推导过程。 `标量`变量及其计算初看可能有些费解，但它是一个数学工具，可以确保：无论我们为 `format_bytes_per_second` 取何值，只要将 `1` 到 `10_0000` 之间所有允许的 `part_number` 值输入到函数中，我们都会得到一组值，其总和 *恰好* 等于 5 TiB 的文件大小限制——或者说尽可能精确。我们将在后面[展示该公式的推导过程](/camera-to-cloud/how-to-upload-realtime#showing-our-work)。通过使用向下取整，我们会舍弃少量字节，但可确保对 10,000 个分段进行常规四舍五入时不会意外导致超出允许的最大文件大小。通过这种方式，最多只会舍弃 10,000 个字节（即 10 KB），这是一个可以接受的权衡。此公式的重要特性如下： * 当上传 10,000 个分段时，上传的数据总量与 5 TiB 文件大小上限的差距在 10 KB 以内。 * 在开始阶段针对较小、更高效的负载进行优化，以提高中短时长片段的响应速度。 * 对于超长片段，从文件写入完成到可在 Frame 中播放之间的响应速度会有所降低。第二点与第三点之间的权衡之所以可以接受，是因为大多数片段不会达到触发第三点的大小。我们是以极少数文件的响应速度降低为代价，换取了 *绝大多数* 文件响应速度的提升。一个更先进、更高效的公式版本（该版本会生成一个匿名函数 `part_size_calculator`，其中预先计算并内嵌了我们的静态标量和数据速率）可能如下所示： **`Python`** ```python title="Python" def create_part_size_calculator(format_bytes_per_second: int) -> Callable[[int], int]: """ Returns a function that takes in a `part_number` and returns a `part_size` based on `data_rate`. """ # Make sure we never go above the maximum data rate or fall below the # minimum part size, even if the data rate is lower. data_rate = min(format_bytes_per_second, MAXIMUM_DATA_RATE) data_rate = max(data_rate, MINIMUM_PART_SIZE) static_scalar = -(2 * (125 * data_rate - 68_719_476_736)) / 8_334_583_375 def part_size_calculator(part_number: int) -> int: """Calculates size in bytes of upload for `part_number`.""" if part_number < 1: raise ValueError("part_number must be greater than 0") if part_number > 10_000: raise ValueError("part_number must be less than 10,000") return math.floor(static_scalar * pow(part_number, 2) + data_rate) return part_size_calculator ``` ### 公式的表现情况。我们来看看上述公式在几种常见文件类型上的输出特征。 **示例 1**：Web 格式对于数据速率约为 5.3MB/s 或更低（大多数 H.264/H.265/HEVC 文件）的可网页播放格式，我们将获得如下所示的负载大小递进序列： | 总分段数 | 负载字节数 (Bytes) | 负载兆字节数 (MB) | 文件总字节数 (Bytes) | 文件总吉字节数 (GB) | | ----------: | ------------: | ---------: | ----------------: | -------------: | | 1 | 5,242,896 | 5.2 MB | 5,242,896 | 0.0 GB | | 1,000 | 21,575,817 | 21.6 MB | 10,695,361,357 | 10.7 GB | | 5,000 | 413,566,329 | 413.6 MB | 706,957,655,928 | 707.0 GB | | 10,000 | 1,638,536,679 | 1,638.5 MB | 5,497,558,133,921 | 5,497.6 GB | **表格列键** - `总分段数`：上传到 AWS 的文件分段总数。 - `负载字节数 (Bytes)`：当 `part_number` 等于`总分段数`时，AWS PUT 负载的大小。 - `负载兆字节数 (MB)`：与`负载字节数`相同，但以兆字节 (MB) 为单位。 - `文件总字节数 (Bytes)`：当按顺序上传完`总分段数`个分段后，文件已上传的总字节数。 - `文件总吉字节数 (GB)`：与`文件总字节数`相同，但以吉字节 (GB) 为单位。这些数值在实际上传中取得了很好的平衡，尤其是对于 H.264 等 Web 播放编解码器；大多数文件都将小于 10.7 GB，因此能在 1,000 个分段内完成上传。负载大小永远不会超过 21.6 MB。即使我们处理了一半的分段，负载大小仍然不会超过 413.5 MB。此时上传总量将达到 707 GB，对于绝大多数 Web 文件来说已经绰绰有余。只有当我们接近允许的分段数量上限时，文件大小才会开始急剧增大。但是，它永远不会超过 1.7 GB，远低于 AWS 规定的每个分段 5 GiB 的限制。 **示例 2**：Prores 422 LT Prores 422 LT [的数据速率为 102 Mbps](https://www.wolframalpha.com/input?i=-%282+%28-68%2C719%2C476%2C736+%2B+125+12%2C750%2C000%29%29%2F8%2C334%2C583%2C375)，生成如下表格： | 总分段数 | 负载字节数 (Bytes) | 负载兆字节数 (MB) | 文件总字节数 (Bytes) | 文件总吉字节数 (GB) | | ----------: | ------------: | ---------: | ----------------: | -------------: | | 1 | 12,750,016 | 12.8 MB | 12,750,016 | 0.0 GB | | 1,000 | 28,857,758 | 28.9 MB | 18,127,308,783 | 18.1 GB | | 5,000 | 415,443,954 | 415.4 MB | 735,107,948,432 | 735.1 GB | | 10,000 | 1,623,525,817 | 1,623.5 MB | 5,497,558,133,958 | 5,497.6 GB | 此表格展示了与我们针对 Web 优化后的公式相比的一些有用特性。在前 1,000 个分段中，我们能够多上传 8 GB 的文件。较大的初始负载意味着我们在开始时不需要过快地请求 URL，从而使上传在更高数据速率下更加高效。在上传过程的末尾阶段，我们的负载大小仍然保持在较大水平。 **示例 2**：Camera Raw 最后，让我们尝试一种数据速率为 280 MB/s 的相机 RAW 格式。面对如此高速的数据输入，如果一开始还尝试以 5 MiB 大小的分片进行上传，那就完全没有意义了： | 总分段数 | 负载字节数 (Bytes) | 负载兆字节数 (MB) | 文件总字节数 (Bytes) | 文件总吉字节数 (GB) | | ----------: | ------------: | ---------: | ----------------: | -------------: | | 1 | 280,000,008 | 280.0 MB | 280,000,008 | 0.3 GB | | 1,000 | 288,091,460 | 288.1 MB | 282,701,200,139 | 282.7 GB | | 5,000 | 482,286,516 | 482.3 MB | 1,737,245,341,542 | 1,737.2 GB | | 10,000 | 1,089,146,065 | 1,089.1 MB | 5,497,558,133,870 | 5,497.6 GB | 不仅早期的负载更高效，而且我们在上端节省了超过半吉字节的数据，这将使那些网络调用更不易受到不良网络事件的影响。 ### 展示我们的推导过程在我们将所有内容整合到一个示例上传程序之前，让我们先看看我们是如何得出这个公式的。我们需要做的是设计一个公式，用允许分段数量末尾的大体积重型负载（大多数上传永远不会达到这个阶段）来换取靠近开头部分的轻量高效负载，这是每一次上传都能受益的一点。与此同时，我们还要确保我们的算法能够 *恰好* 在第 10,000 个分段时，接近 5 TiB 的文件大小限制。是时候运用一些微积分了。我们希望曲线呈指数级增长，因此公式应该类似于： ```math n^2 ``` …其中 `n` 是分段编号。我们还希望确保每个分段至少是我们公式中的数据速率，我们将其称为 `r`： ```math n^2 + r ``` 现在我们需要找到一个公式，可以计算 *这个* 公式在前 10,000 个自然数（1、2、3…）上的总和。 Sigma `Σ` 符号表示求和。我们把它添加到公式中： ```math Σxn^2 + r ``` …并将 `n` 重新定义为 1 到 10,000（含边界值）之间的自然数序列。这个方程式对我们来说还不是很有用。它具有正确的直观形状，但如果像我们希望的那样代入 `n=10,000` 和 `r=5,242,880`，它只会[输出一个结果](https://www.wolframalpha.com/input?i=%CE%A3n%5E2+%2B+r+where+n+%3D+1+to+10%2C000+and+r+%3D+5%2C242%2C880)：`385,812,135,000` (385 GB)。这个结果不仅远低于我们 5 TiB 的文件大小限制，而且也没有办法调整这个公式使其输出我们想要的结果。让我们给自己加一个可以调节的旋钮： ```math Σxn^2 + r ``` …其中 `x` 是一个标量，我们可以通过求解它来使得结果为 5 TiB。现在我们可以将方程式设置为等于我们的文件大小限制，然后求解 `x`： ```math Σxn^2 + r = 5,497,558,138,880 ``` 通常，求和必须通过迭代（如在 `for` 或 `while` 循环中）来求解。但事实证明，有一个完美的公式适合我们：[一种已知的方法](https://www.math-only-math.com/sum-of-the-squares-of-first-n-natural-numbers.html)，能够以低成本计算前 `n` 个自然数的平方和： ```math Σn^2 = n(n+1)(2n+1)/6 ``` 将其重新排列为多项式，使其更易于查看： ```math Σn^2 = (2n^3 + 3n^2 + n)/6 ``` 我们可以将变量 `x` 和 `r` 添加到等式两边： ```math Σxn^2 + r = x(2n^3 + 3n^2 + n)/6 + rn ``` 最后，我们将新公式设为等于 5 TiB： ```math x(2n^3 + 3n^2 + n)/6 + rn = 5,497,558,138,880 ``` 现在，我们需要做的就是通过代入 `n=10,000`（我们的总分段数）来求解 `x`。这将为我们提供一种针对给定数据速率计算静态标量的方法。让我们[把它交给 Wolfram Alpha](https://www.wolframalpha.com/input?i=x%282n%5E3+%2B+3n%5E2+%2B+n%29%2F6+%2B+r+*+n+%3D+5%2C497%2C558%2C138%2C880+solve+for+x+where+n+%3D+10%2C000) 来求解，而不是手动计算： ```math x = -(2 (125 r - 68719476736)) / 8334583375 ``` 现在我们有所进展了！如果我们的数据速率为最小分段大小 (5 MiB)，[我们会得到](https://www.wolframalpha.com/input?i=x%282n%5E3+%2B+3n%5E2+%2B+n%29%2F6+%2B+r+*+n+%3D+5%2C497%2C558%2C138%2C880+solve+for+x+where+n+%3D+10%2C000+and+r+%3D+5%2C242%2C880)一个静态标量： ```math 136,128,233,472 / 8,334,583,375 ``` 在计算机领域，这表示一个 float64 值：`16.33293799427617`。在这种情况下，我们确定分段大小的公式为： ```math s = 16.33293799427617n^2 + 5,242,880 ``` 其中 `s` 是我们的分段大小。我们还有一个问题。在现实世界中，我们不能使用非整数字节的负载。我们需要对每个值进行取整。我们将使用 Python，并向下取整： **`Python`** ```python title="Python" math.floor(16.33293799427617 * pow(part_number, 2)) + 5_242_880 ``` 至此，我们得到了本指南所给原始函数的一个具体示例。 ## 构建一个基础上传程序让我们来看一些简单的类似 Python 的伪代码，用于实时上传正在渲染的文件，其中用到了我们在本指南中学到的所有内容： **`Python`** ```python title="Python" import math from datetime import datetime, timezone from typing import Callable # The minimum size, in bytes, for a single, non-final part upload. MINIMUM_PART_SIZE = 5_242_880 # The maximum filesize in MAXIMUM_PART_COUNT = 10_000 # The maximum size, in bytes, for an AWS upload. MAXIMUM_FILE_SIZE = 5_497_558_138_880 # The data rate at which every part is an equal size, and could not # be any uniformly larger without violating the maximum total file # size if 10_000 parts were to be uploaded. it works out to # ~549.8 MB per payload. By enforcing this we actually never need # to check if a part exceeds the maximum allowed part size, as our # parts will never exceed ~549.8 MB. MAXIMUM_DATA_RATE = MAXIMUM_FILE_SIZE // MAXIMUM_PART_COUNT def create_part_size_calculator(format_bytes_per_second: int) -> Callable[[int], int]: """ Returns a function that takes in a `part_number` and returns a `part_size` based on `data_rate`. """ ... def upload_render(data_stream: DataStream, channel: int = 0) -> None: """ Uploads an asset for data_stream, which is a custom IO class that pulls remaining upload data from an internal buffer or file, depending on how well the upload is keeping pace with the render. Uploads to `channel` """ asset = c2c.asset_create( extension=data_stream.extension, filetype=data_stream.mimetpye, channel=channel, offset=datetime.now(timezone.utc) - data_stream.created_at() ) calculate_part_size = create_part_size_calculator(data_stream.data_rate()) next_part_number = 0 while True: next_payload_size = calculate_part_size(next_part_number) # Waits until one or more chunks worth of data is ready for upload. Cache # whether our data stream has completed writing the file, and the current # number of bytes we have remaining to upload at this time. available_bytes, stream_complete = data_stream.wait_for_available_data( minimum_bytes=next_payload_size ) # Build the list of parts to request based on our available data. parts = [] while available_bytes > 0: payload_size = calculate_part_size(next_part_number) if available_bytes < payload_size and not stream_complete: break payload_size = min(payload_size, available_bytes) parts.append( c2c.RealtimeUploadPart( part_number=next_part_number, part_size=payload_size, is_final=False ) ) available_bytes -= payload_size next_part_number += 1 # If our stream is done writing, mark the last part as final. if stream_complete: parts[-1].is_final = True # Create the part URLs using the C2C endpoint. response = c2c.create_realtime_parts( asset_id=asset.id, asset_name=None if not stream_complete else data_stream.filename, asset_filesize=None if not stream_complete else data_stream.size(), parts=parts ) # Upload each part to its URL. for part, part_url in zip(parts, response.upload_urls): part_data = data_stream.read(bytes=part.size) c2c.upload_chunk(part_data, part_url, data_stream.mimetype) if stream_complete: break ``` 上面的代码仅演示了实时上传文件的基本流程。实际上，此逻辑需要通过[错误处理](/camera-to-cloud/how-to-handle-errors)和[高级上传](/camera-to-cloud/how-to-advanced-uploads)技术进行增强。 ## 下一步实时上传提供了一种方法，让您的集成尽可能响应迅速，素材在录制完成后几秒钟内便可在 Frame.io 中播放。 [后续指南](/camera-to-cloud/how-to-advanced-uploads)将涵盖高级上传技术和相关要求。尽管本指南主要针对基础上传而编写，但其中大部分内容仍适用于实时上传。如果您还没有联系我们的团队，我们鼓励您这样做，然后继续阅读下一份指南。我们期待收到您的回复！