> 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.

# 操作指南：整理资产

## 前言





在本指南中，我们将学习如何以及在多大程度上可以控制来自您集成的资产被上传到 *何处*。





## 我需要准备什么？

如果您还未阅读[实施 C2C：设置](./implementing-c2c-setting-up)指南，请先快速浏览一下再继续操作！ 您还需要用到在 [C2C 硬件](./implementing-c2c-authentication-and-authorization-hardware)或 [C2C 应用程序](./implementing-c2c-authentication-and-authorization-c2c-application)身份验证和授权指南中收到的 `access_token`。

## 资产文件夹结构





默认情况下，资产会按照以下文件夹结构进行创建：

`云设备` > `{YYYY}_{MM}_{DD}` > `{ASSET_TYPE}` > `{YOUR_DEVICE}` > `{ASSET_NAME}`，其中 `{ASSET_TYPE}` 为 `VIDEO`、`AUDIO` 或 `DATA`（按通道为您的设备型号配置），`{YOUR_DEVICE}` 是连接到用户项目的项目设备名称，`{ASSET_NAME}` 是您上传的资产名称，也是 Frame.io 中实际可播放的资产。

### 扩展名路由

您可以将设备设置为根据 `{ASSET_NAME}` 中的文件扩展名，将不同资产路由到自定义 `{ASSET_TYPE}` 文件夹。 例如，假设您的集成会产生多种不同的文件类型，每种文件类型都属于特定来源。 您可以按如下方式告知我们如何映射这些资产：

```text
.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans
```





现在，当您创建以下资产时：





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_codes]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "IMAGE_0001.jpeg", 
            "filetype": "image/jpeg", 
            "filesize": 21136250,
            "offset": 10
        }
__JSON__
} | python -m json.tool
```




<Info title="API 端点规范">
  `/v2/assets` 的文档可在[此处找到](/camera-to-cloud/api-reference/device-asset-create)
</Info>
 ... 它将被路由到类似这样的位置：`Cloud Devices` &gt; `2022_04_01` &gt; `STILLS` &gt; `MY_DEVICE` &gt; `IMAGE_0001.jpeg`。 如果文件名为 `A001_C001.mov`，它将被路由到：`Cloud Devices` &gt; `2022_04_01` &gt; `VIDEO` &gt; `MY_DEVICE` &gt; `A001_C001.mov`。

### 令牌化上传路径

一些集成可能希望对其设备创建的文件夹结构拥有更多控制权。 相应地，我们 [Frame.io](http://frame.io/) 需要确保从 C2C 设备上传文件到 [Frame.io](http://frame.io/) 的方式具有一定程度的一致性，特别是要向 [Frame.io](http://frame.io/) 客户保证，C2C 设备可以与其项目的哪一部分交互。 为此，我们允许集成商在 `{YOUR_DEVICE}` 文件夹内自定义其资产的上传位置，但不允许将资产上传到该文件夹之外。

要上传到自定义文件夹结构，您需要与您的合作伙伴经理合作。 自定义文件夹结构是一组令牌化的元数据，必须在创建资产时提供。 我们来看一个简单的示例：

假设我们有一个 3D 相机设备，它具有 `reel_name` 值（如：`&quot;A001&quot;`、`&quot;A002&quot;`、`&quot;A003&quot;` 等）以及 `clip_number` 值（如 `&quot;C001&quot;`、`&quot;C002&quot;` 等）。我们希望为每个片段创建文件夹，并在其中填充左眼和右眼文件，那么在项目中这些文件将如下所示：![令牌化文件夹路径 - 3D 设备示例](/_fern-img/e40b09128d1cbf3c876fd14169a6406642d50d13ce7ab802baff4bbaf50bfd4a.webp)

为此，我们需要配置两个设置：




* 必填的元数据字段
* 令牌化文件路径




必填的元数据字段是一个简单的键列表，在为集成创建资产时必须设置这些键：





```text
[reel_name, clip_number]
```

然后，您可以使用这些键中的任意一个来创建一个以斜杠 `/` 分隔的路径，并使用 `{field_name}` 来表示应注入字段值的位置：

```text
REEL_{reel_name}/{reel_name}_{clip_number}
```

这两个设置都必须提供给我们的 [Frame.io](http://frame.io/) 团队，以便作为您集成详细信息的一部分进行添加。 在我们完成设置之后，当您创建资产时，必须在负载的根层级提供这些值，才能成功创建资产：

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_LEFT.mp4", 
            "filetype": "video/mp4", 
            "filesize": 21136250,
            "offset": 10,
            "metadata": {
              "reel_name": "A001",
              "clip_number": "C001"
            },
        }
__JSON__
} | python -m json.tool
```

上述操作将创建一个文件，其完整路径类似于：`Cloud Devices` &gt; `2022_04_01` &gt; `VIDEO` &gt; `MY_DEVICE` &gt; `REEL_A001` &gt; `A001_C001` &gt; `A001_C001_LEFT.mp4`
<Error title="元数据错误">
  


如果您的设备未明确设置为允许使用这些字段，当您尝试进行相同的调用时，将会收到一个错误。 同样地，如果设置了必填的元数据字段，您必须在资产创建负载中提供这些字段，否则将返回错误。



</Error>


负载将接受任何有效的 JSON 值。 非字符串值的呈现方式如下：




* **整数**：以十进制形式呈现：`10` -&gt; `&quot;10&quot;`
* **浮点数**：根据《SIGPLAN '96 程序设计语言设计与实现会议论文集》中《快速准确地打印浮点数》一文所描述的算法，使用最短的表示形式。
* **布尔值**：`true` 和 `false` 分别呈现为 `&quot;true&quot;` 和 `&quot;false&quot;`
* **null**：呈现为空字符串。 如果将 `reel_name` 设置为 `null`，则第一个自定义文件夹将呈现为 `REEL_`




通常，我们建议您将值限制为字符串，并根据需要格式化其他值（例如，整数总是会不带前导零打印，这可能是您想要改变的地方）。





通常情况下，只应使用对每个片段都有有效值的字段；如果某个字段并非始终有有效值，您应该有一个计划来处理未设置或为 null 的值。





## 版本堆叠

[Frame.io](http://frame.io/) 支持[版本堆栈](https://support.frame.io/en/articles/4431-version-stacking-and-comparison)——这是一种在 UI 中捆绑同一内容多次迭代的方法。 C2C API 允许设备上传资产的新迭代版本，这些版本将与之前的版本一起放入一个版本堆栈中。 为了创建版本堆栈，您必须提供 `autoversion_id` 来标识资产属于哪个版本堆栈。 该值可以是任何内容：UUID、文件名等。请务必仅使用那些在资产文件夹中不会意外重复的值。 例如，如果您的集成可能会多次创建相同的文件名，那么文件名就 *不* 适合用作 `autoversion_id`。

我们提供一个如下所示的 autoversion_id：





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v01.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```





现在，每当您上传一个新资产时，如果使用相同的 autoversion_id，该资产将作为堆栈中的最新版本与原始资产添加到一起：





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v02_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```





*资产只有在上传到同一个文件夹时才会堆叠*，因此如果您希望实施版本堆栈，需要记住以下几点：




* 令牌化元数据必须解析到同一个主文件夹，才能创建版本堆栈。
* 由于创建日期是文件路径的一部分，在 UTC 午夜之后创建的新版本可能无法正确堆叠，除非您为原始上传的创建时间提供一个偏移量。




第二点很重要。 假设在初次上传 48 小时后，创建了该资产的一个新版本。 为了能够与原始资产堆叠在一起，我们必须提供一个 48 小时前的偏移量：172800 秒。





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v03_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 172800,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```

如果当前资产 *原本* 会上传到 `2022_04_03`，那么现在它将上传到 `2022_04_01`，并与正确的资产堆叠在一起。

## 下一步





这是创建出色 C2C 集成的最后一份指南！ 花点时间，为自己鼓鼓掌吧！ 或许再去吃点零食。 剩下唯一要做的事情就是查看集成商检查表，您会在其中找到一个创建完美集成所需一切内容的摘要。





如果您还没有联系我们的团队，我们鼓励您这样做，然后继续阅读下一份指南。 我们期待收到您的回复！