> 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 Experimental: 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](https://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` を使用します。

```cURL
curl --request GET \
  --url https://api.frame.io/v2/assets/<ROOT_ASSET_ID>/children \
  --header 'authorization: Bearer <DEV_TOKEN>'
```

```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'])
```

返されたアセットのリストから、フォルダーである任意のアセットの ID、またはルートアセット ID を使用できます。この ID を使用して、新しいアセットのアップロード先をマークします。

### アセットのアップロード
この例では、新しいファイルをアップロードします。次の情報を含んだリクエストを送信します。

| パラメーター| 説明|
|----------|----------|
| `filesize`| アップロードするファイルのサイズを入力します|
| `filetype`| アップロードするファイルのタイプを選択します。選択肢には、ビデオおよび画像が含まれます。例：`video/mp4`、`image/png`。|
| `name`| ファイル名を表している文字列を、スペースなしで入力します。|
| `type`| これは、`file` を使用しているのか、`folder` を使用しているのかを表します。バージョンスタックは、複数のファイルを互いにスタッキングする場合です。|

新しいフォルダーを作成する場合は、リクエストに `filesize` または `filetype` を含める必要はありません。

`cURL` リクエストの場合は、`"source": {  "url":"URL_FOR_VIDEO" }` パラメーターを使用してファイルへのリンクを含めることで、アセットを Frame.io に素早くアップロードできます。リンクは、一般にアクセス可能である必要があります。そうでない場合は、Python SDK を使用できます。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 '{"filesize":200000,"filetype":"video/mp4","name":"test","source":{"url":"URL_FOR_VIDEO"},"type":"file"}'
```

```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"
)
```

<Info title="アセット URL の有効期限が切れます">
アセット作成 API 呼び出しで取得した URL は、アップロードを認可するために事前に署名されていますが、24 時間後に期限切れになります。
</Info>

# 独自のファイルアップローダーの構築
独自のアップローダーを構築する場合は、最適なパフォーマンスを得るために、チャンクを並列でアップロードすることをお勧めします。各チャンクは、Frame.io API からの応答で提供される Amazon S3 URL に直接、`PUT` する必要があります。

ファイルチャンクは、最終的な連結およびトランスコード済みアセットのシーケンスを決定するので、提供された `upload_urls` の順序と一致する必要があります。 **これは、1 番目の URL が 1 番目のチャンクを取り、2 番目の URL が 2 番目のチャンクを取る、などを意味します。

#### 擬似コードの例

**`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
```

S3 への各リクエストのヘッダーには、次のように、Frame.io API への最初の呼び出しから返された新しいアセットの `filetype`、および、追加のプライバシーヘッダーが含まれる必要があります。

```text
PUT https://frameio-uploads-production.s3/etc/etc
Content-Type: video/mp4
x-amz-acl: private
```
Python SDK でこれがすべて処理される方法の例は、[こちら](https://github.com/Frameio/python-frameio-client/blob/master/examples/upload_asset.py)で確認できます。

<Info title="AWS エラーは XML 形式">
この段階で発生するエラーは AWS から直接返されるエラーなので、XML 形式であり、Frame.io の標準的な JSON エラー処理では対応できません。一般的に、本番環境での使用に合わせて、これらのアップロードに関する再試行ロジックを構築することをお勧めします。不完全にアップロードされたファイル（チャンクが欠落しているファイル）は、トランスコードに失敗し、Frame.io に表示されます
</Info>

以上です。`upload_url` への `PUT` 呼び出しが完了すると、Frame.io に新しいアセットが用意されます。