> This page is for 平台, version 旧版.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 旧版: https://next.developer.frame.io/platform/v2/llms.txt

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

# 上传资产

# 概述




本教程介绍如何将资产上传到 Frame.io。Frame.io 可以处理所有文件类型，不仅是视频，还包括脚本、图片、地图和参考文件。用更具技术性的术语来说，Frame.io 中的资产是对 S3 中一个文件及其在 Frame.io 中上下文（包括转码文件、用户/团队/项目上下文以及元数据）的一种强健表示。有关资产的更多信息，请参考资源定义。





## 核心层级结构




了解 Frame.io 如何构建其核心模型也很有帮助。

**帐户**下拥有多个**项目**，**用户**归属于帐户，而所有项目都包含**资产**。**团队**仅适用于企业帐户，并提供额外一层逻辑隔离。资产并不“知道”自己属于哪个团队，只知道属于哪个项目和帐户，但项目严格归属于团队而非帐户，这使得团队成为资产上传过程中不可或缺的一部分。

## 前提条件




对于本教程，您需要：




* 一个带有开发者令牌的 Frame.io 帐户（令牌说明见下文）
* [Frame.io Python SDK](https://github.com/Frameio/python-frameio-client)




## 上传资产




本节将引导您完成上传资产的操作步骤。




1. 在 [developer.frame.io](/) 上创建一个具有以下权限范围的开发者令牌：




| 权限范围 | 原因 |
| ---------- | ---------- |
| **帐户：**读取 | 获取发起请求的用户的帐户列表。 |
| **团队：**读取 | 获取所需帐户下的可用团队。 |
| **项目：**读取 | 获取所需团队下的可用项目。 |
| **资产：**创建、读取 | 创建新的资产记录，并获取可用资产以遍历项目内的文件夹结构。 |



<Info title="需要有关创建 API 令牌的帮助吗？">
  请参阅[**此处**](doc:get-a-developer-token)的说明。
</Info>

2. 确定资产的目标位置。资产至少需要放置在一个**项目**内。您需要检索某个项目的根资产 ID (`root_asset_id`)，或者某个文件夹的资产 ID，以便指定要上传到的文件层级中的位置。




<Warning title="注意：">
  您不能仅使用项目 ID 进行上传。要上传到项目的根目录，请在请求中指定 `root_asset_id`。
</Warning>


通常您需要检索（按指定顺序）：



* 帐户 ID 并选择一个帐户
* 团队 ID 并选择一个团队
* 与团队关联的项目
* 您要使用的项目的项目 ID
* 根资产 ID 或文件夹 ID

您可以使用 `root_asset_id` 直接上传到项目的根目录。

### 列出资产

要选择您想将新资产上传到的位置，您可以使用 API 列出某个项目或项目内某个文件夹中的所有资产。如果资产是 *文件夹*，它将包含次资产，这些次资产同样可以是文件和文件夹。列出资产信息时，您可以使用任何资产 ID，但如果您想查看与某个项目相关的所有内容，请使用 `root_asset_id`。

```

```

python-sdk
from frameioclient import FrameioClient
import os

ASSET_ID = ""
TOKEN = ""

client = FrameioClient(TOKEN)
response_list = client.assets.get_children(ASSET_ID)
assets = response_list.results

for item in assets:
    print(item['id'], item['name'])
```





```

```python-sdk
# Code sample uses the Python SDK: https://github.com/Frameio/python-frameio-client

from frameioclient import FrameioClient

client = frameioclient("FRAMEIO_TOKEN)

asset = client.assets.upload(
  destination_id="PARENT_ASSET_ID",
  filepath="./my_file.mov"
)

# Create a folder:
asset = client.assets.create_folder(
  parent_asset_id=PARENT_ASSET_ID,
  name="My Awesome Folder"
)
```





从返回的资产列表中，您可以使用任何一个类型为文件夹的资产的 ID，或者使用根资产 ID。您将使用此 ID 来标记要将新资产上传到的目标位置。





### 上传资产




在此示例中，我们将上传一个新文件。您需要发送包含以下信息的请求：




| 参数 | 描述 |
| ---------- | ---------- |
| `filesize` | 输入您要上传的文件大小 |
| `filetype` | 选择您要上传的文件类型。选项包括视频和图像。示例：`video/mp4`、`image/png`。 |
| `name` | 输入表示文件名称的字符串，不含空格。 |
| `type` | 这表示您使用的是`文件`还是`文件夹`。版本堆栈是指将多个文件叠加在一起。 |
如果您要创建新文件夹，则无需在请求中包含 `filesize` 或 `filetype`。对于 `cURL` 请求，您可以使用 `&quot;source&quot;: { &quot;url&quot;:&quot;URL_FOR_VIDEO&quot; }` 参数包含指向您文件的链接，快速将资产上传到 Frame.io。链接必须可公开访问。或者，您可以使用 Python SDK，它会为您处理将文件分解为每个上传链接对应的分片。

```cURL

curl --request POST \

--url https://api.frame.io/v2/assets/<asset_id>/children \ --header 'authorization: Bearer<dev_token>' \

--header 'content-type: application/json' \


  

--data '{&quot;filesize&quot;:200000,&quot;filetype&quot;:&quot;video/mp4&quot;,&quot;name&quot;:&quot;test&quot;,&quot;source&quot;:{&quot;url&quot;:&quot;URL_FOR_VIDEO&quot;},&quot;type&quot;:&quot;file&quot;}'


```

**`Python`**

```python title="Python"
filesize = 30000000
upload_urls = ["https://...", "https://...", "https://..."]
chunk_size = filesize / len(upload_urls)

start_byte = 0 # Set to 0 to start
for i, url in enumerate(upload_urls):
  end_byte = chunk_size * (i + 1)
  upload_chunk(url=url, start_byte, end_byte)
  start_byte = start_byte + chunk_size
```




<Info title="资产 URL 将会过期">
  


您从资产创建 API 调用返回的 URL 已预签名，用于授权您的上传，但会在 24 小时后过期。



</Info>


# 构建您自己的文件上传程序

如果您要构建自己的上传程序，为了获得最佳性能，建议并行上传分片。每个分片都应通过 `PUT` 直接上传到 Frame.io API 响应中提供的 Amazon S3 URL。您的文件分片必须与所提供的 `upload_urls` 的顺序一致，因为它们 *决定了最终连接和转码后资产的序列。*这意味着第 1 个 URL 接收第 1 个分片，第 2 个 URL 接收第 2 个分片，以此类推。

#### 伪代码示例

**`title=&quot;Python&quot;`**

```python title=&quot;Python&quot;

filesize = 30000000




upload_urls = [&quot;https://...&quot;, &quot;https://...&quot;, &quot;https://...&quot;]




chunk_size = filesize / len(upload_urls)





start_byte = 0 # Set to 0 to start




for i, url in enumerate(upload_urls):


  

end_byte = chunk_size * (i + 1)


  

upload_chunk(url=url, start_byte, end_byte)


  

start_byte = start_byte + chunk_size

```

每个发送到 S3 的请求的标头应包含新资产的 `filetype`（文件类型与您最初调用 Frame.io API 时返回的完全一致），以及一个额外的隐私标头：

```text
PUT https://frameio-uploads-production.s3/etc/etc
Content-Type: video/mp4
x-amz-acl: private
```

您可以在[此处](https://github.com/Frameio/python-frameio-client/blob/master/examples/upload_asset.py)查看我们的 Python SDK 如何处理所有这些内容的示例。
<Info title="AWS 错误为采用 XML 格式">
  


请注意，您在此阶段遇到的任何错误都将直接来自 AWS，因此会以 XML 格式返回，而不是 Frame.io 标准的 JSON 错误处理格式。我们通常建议，在任何生产环境中，为这些上传操作构建重试逻辑，因为不完整上传的文件（即缺少分片的文件）将无法在 Frame.io 中转码和显示



</Info>
 就是这样！完成对 `upload_url`s 的 `PUT` 调用后，您将在 Frame.io 中获得一个新资产。