> This page is for プラットフォーム, version V4 (default).
> 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 Python SDK — アップロードガイド

このガイドでは、**Frame.io Python SDK**（`frameio`）を使用してFrame.ioにファイルをアップロードする方法について説明します。SDKは、事前署名されたURLを介してS3へのチャンク化されたマルチパートアップロードを処理し、並列サブ、自動再試行、およびオプションの進行状況トラッキングを提供します。一般的なアップロードAPIの概念（アップロードURL、ヘッダー、チャンク化）については、[ローカル＆リモートアップロードの仕組み](./how-local-remote-uploads-work)を参照してください。---

---

## クイックスタート

```python
import os
from frameio import Frameio
from frameio.files import FileCreateLocalUploadParamsData
from frameio.upload import FrameioUploader

client = Frameio(token="YOUR_TOKEN")

file_path = "/path/to/video.mp4"
file_size = os.path.getsize(file_path)

# 1. Create the file resource and get pre-signed upload URLs
response = client.files.create_local_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateLocalUploadParamsData(
        name="video.mp4",
        file_size=file_size,
    ),
)

# 2. Upload the file to S3
with open(file_path, "rb") as f:
    FrameioUploader(response.data, f).upload()
```

これで完了です。 SDKは、APIから返されたアップロードURLに基づいてファイルをチャンクに分割し、並列でアップロードし、自動的に再試行を処理します。

---

## 活用方法

これには2段階の手順が必要です。

#### ファイルリソースを作成

`client.files.create_local_upload()`をファイル名とサイズで呼び出します。APIはプレースホルダーファイルを作成し、事前署名されたS3 PUT URLを返します — チャンクごとに1つ。URLの数（したがってチャンクの数）は、ファイルサイズによって決まります。

#### S3にアップロード

`FrameioUploader`は応答からアップロードURLを読み取り、ファイルを対応するチャンクに分割し、スレッドプールを使用して各チャンクを並列でそのURLにPUTします。各リクエストには、必要な`x-amz-acl: private`および`Content-Type`ヘッダーが含まれます。

> **Note**
>
> アップロードはアプリケーションからS3に直接行われ、Frame.io APIサーバーを通過しません。これは、YouTube、Vimeo、Dropboxなどのサービスが大きなファイルのアップロードに使用するのと同じパターンです。

---

## `FrameioUploader`の使用

`FrameioUploader`は、ファイルをアップロードする推奨方法です。低レベルのチャンク化アップローダーをラップし、すべての詳細を処理します — API応答からのアップロードURLの抽出、必要なヘッダーの設定、ファイルのチャンク化、並列アップロード。

### 進捗管理

`on_progress`コールバックを使用してアップロードの進行状況をトラッキングします：

```python
def on_progress(bytes_uploaded: int, total_bytes: int) -> None:
    pct = bytes_uploaded / total_bytes * 100
    print(f"\r{pct:.1f}% ({bytes_uploaded:,} / {total_bytes:,} bytes)", end="", flush=True)

with open(file_path, "rb") as f:
    FrameioUploader(response.data, f, on_progress=on_progress).upload()

print("\nUpload complete!")
```

コールバックは各チャンクの完了後に一度呼び出され、これまでにアップロードされた累積バイト数と総ファイルサイズが渡されます。

#### リッチプログレスバー

洗練されたターミナルエクスペリエンスには、[Rich](https://github.com/Textualize/rich)を使用します：

```python
from rich.progress import Progress, BarColumn, DownloadColumn, TransferSpeedColumn, TimeRemainingColumn

with Progress(
    "[progress.description]{task.description}",
    BarColumn(),
    DownloadColumn(),
    TransferSpeedColumn(),
    TimeRemainingColumn(),
) as progress:
    task = progress.add_task("Uploading...", total=file_size)

    with open(file_path, "rb") as f:
        FrameioUploader(
            response.data, f,
            on_progress=lambda done, total: progress.update(task, completed=done),
        ).upload()
```

### 設定

`FrameioUploader`はいくつかのオプションパラメータを受け入れます：

| パラメータ         | Default                                        | 説明                                                 |
| ------------- | ---------------------------------------------- | -------------------------------------------------- |
| \`\`          | `5`                                            | 同時アップロードスレッド数                                      |
| `headers`     | `{"x-amz-acl": "private"}` | すべてのS3 PUT リクエストで送信されるヘッダー。カスタムヘッダーはデフォルトとマージされます。 |
| \`\`          | `3`                                            | チャンクごとの再試行回数（指数バックオフ：1秒、2秒、4秒、...）                 |
| `on_progress` | `なし`                                           | 各チャンク後に発生するコールバック`(bytes_uploaded, total_bytes)`   |

```python
with open(file_path, "rb") as f:
    FrameioUploader(
        response.data,
        f,
        max_workers=10,       # more parallelism for high-bandwidth connections
        max_retries=5,        # more resilient on flaky networks
        on_progress=on_progress,
    ).upload()
```

### 完全な例

認証、アップロード、進行状況トラッキングを含む完全な例：

```python
import os
from frameio import Frameio
from frameio.auth import ServerToServerAuth
from frameio.files import FileCreateLocalUploadParamsData
from frameio.upload import FrameioUploader

# Authenticate
auth = ServerToServerAuth(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)
client = Frameio(token=auth.get_token)

# Prepare the file
file_path = "/path/to/video.mp4"
file_name = os.path.basename(file_path)
file_size = os.path.getsize(file_path)

# Create the file resource
response = client.files.create_local_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateLocalUploadParamsData(
        name=file_name,
        file_size=file_size,
    ),
)

print(f"Uploading {file_name} ({file_size:,} bytes) in {len(response.data.upload_urls)} chunks...")

# Upload with progress
def on_progress(uploaded: int, total: int) -> None:
    print(f"\r{uploaded / total:.0%}", end="", flush=True)

with open(file_path, "rb") as f:
    FrameioUploader(response.data, f, on_progress=on_progress).upload()

print(f"\nDone! View at: {response.data.view_url}")
```

---

> **Tip**
>
> アップロード処理を完全にコントロールする必要がある場合（例：チャンクを手動で処理する、非同期パイプラインと統合する、再試行ロジックをカスタマイズするなど）は、[ローカル＆リモートアップロードの仕組み](./how-local-remote-uploads-work)で生のAPIフローとスタンドアロンPythonスクリプトの例を参照してください。

---

## リモートアップロード

ファイルが既にパブリックURLでアクセス可能な場合は、代わりにリモートアップロードを使用してください。チャンクは不要です — Frame.ioがファイルを直接取得します：

```python
from frameio.files import FileCreateRemoteUploadParamsData

response = client.files.create_remote_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateRemoteUploadParamsData(
        name="video.mp4",
        source_url="https://example.com/video.mp4",
    ),
)
print(f"File created: {response.data.id}")
```

> **Warning**
>
> リモートアップロードには現在**50 GBのファイルサイズ制限**があります。50 GBを超えるファイルの場合は、代わりに[ローカルアップロード](#quick-start)を使用してください。

---

## アップロードステータスの確認

アップロード後、ファイルが受信されたことを確認できます：

```python
status = client.files.show_file_upload_status(
    account_id="YOUR_ACCOUNT_ID",
    file_id=response.data.id,
)
print(f"Upload complete: {status.data.upload_complete}")
```