> 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](/)에서 다음 권한을 포함하는 개발자 토큰을 생성하세요.
| 범위 | 이유 |
| ---------- | ---------- |
| **Accounts:** Read | 요청한 사용자의 계정 목록을 가져옵니다. |
| **Teams:** Read | 원하는 계정에서 사용 가능한 팀 목록을 가져옵니다. |
| **Projects:** Read | 원하는 팀에서 사용 가능한 프로젝트 목록을 가져옵니다. |
| **Assets:** Create, Read | 새로운 에셋 레코드를 생성하고 사용 가능한 에셋을 가져와 프로젝트 내의 폴더 구조를 탐색합니다. |
[**여기**](doc:get-a-developer-token)에서 지침을 확인하세요.
2. 에셋을 업로드할 대상을 지정하세요. 최소한 에셋은 **프로젝트** 내에 배치되어야 합니다. 프로젝트의 루트 에셋 ID(`root_asset_id`)나 특정 폴더의 에셋 ID를 가져와야만 파일 계층 구조에서 업로드할 위치를 명확히 지정할 수 있습니다.
프로젝트 ID만으로는 업로드할 수 없습니다. 프로젝트의 루트에 업로드하려면 요청에 `root_asset_id`를 지정해야 합니다.
일반적으로 다음 항목들을 (지정된 순서대로) 검색해야 합니다.
* 계정 ID를 검색하여 계정 선택
* 팀 ID를 검색하여 팀 선택
* 팀과 연결된 프로젝트 검색
* 작업할 프로젝트의 프로젝트 ID 확인
* 루트 에셋 ID 또는 폴더 ID 확인
`root_asset_id`를 사용하면 프로젝트의 루트 경로로 직접 업로드할 수 있습니다.
### 에셋 나열
새 에셋을 업로드할 위치를 선택하기 위해 API를 활용하여 특정 프로젝트나 폴더 내의 모든 에셋을 나열할 수 있습니다. 에셋이 *folder*인 경우 하위 에셋이 포함되며, 이는 파일 및 폴더일 수도 있습니다. 에셋 정보를 나열할 때는 어떤 에셋 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와 image가 있습니다. 예시: `video/mp4`, `image/png`. |
| `name` | 파일의 이름을 공백 없이 문자열 형태로 입력합니다. |
| `type` | 이것이 `file`인지 `folder`인지를 나타냅니다. 버전 스택은 여러 파일을 하나로 겹쳐 놓은 형태입니다. |
새 폴더를 생성하려는 경우 요청에 `filesize` 또는 `filetype`을 포함할 필요가 없습니다. `cURL` 요청 시 `"source": { "url":"URL_FOR_VIDEO" }` 매개변수를 사용하여 파일 링크를 포함하면, Frame.io로 에셋을 매우 빠르게 업로드할 수 있습니다. 링크는 공개적으로 액세스 가능해야 합니다. 그렇지 않은 경우 Python SDK를 사용할 수 있으며, 이 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 '{"filesize":200000,"filetype":"video/mp4","name":"test","source":{"url":"URL_FOR_VIDEO"},"type":"file"}'
```
**`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
```
에셋 생성 API 호출에서 반환된 URL은 업로드 권한을 부여하기 위해 미리 서명된 URL이지만 24시간 후에 만료됩니다.
# 자체 파일 업로더 구축
최상의 성능을 위해 자체 업로더를 구축하려는 경우 청크를 병렬로 업로드하는 것을 권장합니다. 각 청크는 Frame.io API의 응답으로 제공된 Amazon S3 URL로 직접 `PUT` 요청을 보내야 합니다. 파일 청크는 제공된 `upload_urls`의 순서와 일치해야 합니다. 이는 *최종적으로 병합되고 트랜스코딩된 에셋의 순서를 결정하기 때문입니다.* 즉, 첫 번째 URL이 첫 번째 청크를, 두 번째 URL이 두 번째 청크를 가져가는 방식을 의미합니다.
#### 의사 코드 예시
**`title="Python"`**
```python title="Python"
filesize = 30000000
upload_urls = ["https://…", "https://…", "https://…"]
chunk_size = filesize / len(upload_urls)
start_byte = 0 # 0으로 설정하여 시작
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로 보내는 각 요청의 헤더에는 Frame.io API 초기 호출에서 반환된 새 에셋의 `filetype`과 추가적인 개인정보 보호 헤더가 반드시 정확히 포함되어야 합니다.
```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를 통해 어떻게 처리되는지 예시를 확인할 수 있습니다.
이 단계에서 발생하는 모든 오류는 AWS에서 직접 전송되므로, Frame.io의 표준 JSON 오류 처리가 아닌 XML 형식으로 반환된다는 점에 유의하세요. 불완전하게 업로드된 파일(즉, 일부 청크가 누락된 파일)은 트랜스코딩에 실패하여 Frame.io에 표시되지 않으므로, 프로덕션 환경에서 사용할 때는 이러한 업로드 과정에 대해 재시도 로직을 구축하는 것을 강력히 권장합니다.
이것이 전부입니다! `upload_urls에 대한 `PUT` 호출을 모두 완료하면 Frame.io에 새 에셋이 추가된 것을 확인할 수 있습니다.