本地和远程上传的工作原理

本指南详细介绍了使用 Frame.io V4 API 上传文件的完整流程。 其中涵盖了本地和远程上传的原始 API 请求和响应。

还在寻找 SDK 特定的指南? 对于具有内置分片、重试和进度跟踪的上传实施,请参阅 Python SDK 上传指南

前提条件

在开始上传文件之前,请确保您已完成这些设置步骤:

1

Frame.io V4 帐户

您拥有通过 Adobe Admin Console 管理的 Frame.io V4 帐户,或者已为您的帐户用户切换到 Adobe 身份验证

2

Adobe Developer Console 设置

您已登录 Adobe Developer Console 并已将 Frame.io API 添加到一个新项目或现有项目中

3

身份验证凭据

您已为您的项目生成了适当的身份验证凭据

4

访问令牌

您已成功使用这些凭据生成访问令牌

选择您的上传方式

使用 Frame.io API 上传文件有两种方式:创建文件(本地上传)创建文件(远程上传)

本地上传

当媒体可在您的应用程序本地访问时使用,类似于从桌面拖拽文件

远程上传

当通过网络访问媒体时使用,例如通过与其他服务的集成

在本指南中,我们将从完成远程上传这一项比较简单的情况开始。

远程上传

要通过远程上传创建文件,请选择**创建文件(远程上传)**端点。 请求体需要文件名称及其来源 URL。

远程上传目前有 50 GB 的文件大小限制。 对于超过 50 GB 的文件,请改用本地上传

请求示例

1{
2 "data": {
3 "name": "my_file.jpg",
4 "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
5 }
6}

响应示例

成功的请求将产生如下响应:

1{
2 "data": {
3 "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 518,
8 "updated_at": "2025-06-26T20:14:33.796116Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:14:33.159489Z",
13 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e"
14 },
15 "links": {
16 "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status"
17 }
18}

本地上传

要通过本地上传创建文件,请选择**创建文件(本地上传)**端点。 请求体需要文件名称及其以字节为单位的文件大小。

请求示例

1{
2 "data": {
3 "name": "my_file.jpg",
4 "file_size": 50645990
5 }
6}

响应示例

如果请求成功,会创建一个没有任何内容的占位符文件资源。 根据具体的文件大小,响应体将包含一个或多个 upload_urls。 以这个例子为例,我们将需要分多个分段管理此上传。

1{
2 "data": {
3 "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 50645990,
8 "updated_at": "2025-06-26T20:08:06.823170Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:08:06.751313Z",
13 "upload_urls": [
14 {
15 "size": 16881997,
16 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
17 },
18 {
19 "size": 16881997,
20 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
21 },
22 {
23 "size": 16881996,
24 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
25 }
26 ],
27 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
28 }
29}

重要的上传要求:

发送后续上传请求时需要牢记以下重要详细信息:

  • HTTP 请求方法必须为 PUT
  • x-amz-acl 标头必须包含并设置为私密
  • Content-Type 标头必须与原始 创建文件(本地上传) 请求中指定的 media_type 匹配。 在将文件作为单独分段上传时也是如此。 在上述示例中,media_type 的值是 image/jpeg。 因此,Content-Type 的值也必须是 image/jpeg

多分段上传

当给定文件产生多个上传 url 时,您需要将源文件拆分为分片,并为每个分片发出 PUT 请求。

推荐操作:Python SDK 上传指南涵盖使用 FrameioUploader 进行多分段上传,它可以开箱即用地处理分片、并行上传、重试和跟踪进度。

如果您需要手动实施上传(例如,在没有 SDK 的语言中,或者为了完全控制上传过程),下面的脚本展示了如何将文件分成多个分片,并使用预签名 URL 上传每个分片。

Python 实施示例

多分段上传脚本
1import requests
2import math
3from typing import List
4from tqdm import tqdm # For progress bar
5
6def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
7 """
8 Upload a file in chunks using presigned URLs.
9 """
10 try:
11 # Auto-detect content type based on file extension
12 if content_type is None:
13 detected_content_type, _ = mimetypes.guess_type(file_path)
14 content_type = detected_content_type # Default fallback
15
16 print(f"Detected content type: {content_type}")
17
18 # Get file size
19 with open(file_path, 'rb') as f:
20 f.seek(0, 2) # Seek to end of file
21 file_size = f.tell()
22
23 # Calculate chunk size if not provided
24 if chunk_size is None:
25 chunk_size = math.ceil(file_size / len(upload_urls))
26
27 print(f"File size: {file_size} bytes")
28 print(f"Chunk size: {chunk_size} bytes")
29 print(f"Number of chunks: {len(upload_urls)}")
30
31 # Upload each chunk
32 with open(file_path, 'rb') as f:
33 with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
34 for i, url in enumerate(upload_urls):
35 start_byte = i * chunk_size
36 end_byte = min(start_byte + chunk_size, file_size)
37
38 # Read chunk from file
39 f.seek(start_byte)
40 chunk = f.read(end_byte - start_byte)
41
42 print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
43
44 # Upload chunk with minimal headers matching the signature
45 response = requests.put(
46 url,
47 data=chunk,
48 headers={
49 'content-type': content_type,
50 'x-amz-acl': 'private'
51 }
52 )
53
54 if response.status_code != 200:
55 print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
56 print(f"Response text: {response.text}")
57 print(f"Response headers: {dict(response.headers)}")
58 return False
59 else:
60 print(f"Chunk {i+1} uploaded successfully!")
61
62 pbar.update(1)
63
64 return True
65
66 except Exception as e:
67 print(f"Error during upload: {str(e)}")
68 return False
69
70# Example usage
71if __name__ == "__main__":
72 # Replace these with your actual values
73 file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
74 upload_urls = [
75 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
76 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
77 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
78 ]
79 content_type = "image/jpeg"
80
81 print("Starting file upload...")
82 success = upload_file_in_chunks(file_path, upload_urls, content_type)
83
84 if success:
85 print("File upload completed successfully!")
86 else:
87 print("File upload failed!")

上传流程总结

1

选择上传方法

决定是远程上传(通过 URL 访问文件)还是本地上传(系统上的文件)

2

创建文件请求

发出初始请求来使用所需元数据创建文件资源

3

处理上传 URL

对于本地上传,处理返回的 upload_urls(单个或多个分段)

4

上传文件内容

使用带有适当标头的 PUT 请求将文件内容上传到提供的 URL

5

验证上传

检查文件状态以确认上传和处理是否成功

后续步骤:文件上传后,您可以使用返回的文件 ID 来添加评论、创建共享项或使用 Frame.io V4 API 执行其他操作。