> 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は、プロジェクトにアップロードされたファイル（画像、動画、PDF など）を保存および処理します。APIを使用してファイルを取得する場合、基本応答にはファイル名、ステータス、Frame.ioアプリで開くための`view_url`などのコアメタデータが含まれます。実際のファイルコンテンツ（オリジナル、プレビュー、または異なる品質のレンディション）にアクセスするには、**includes**を使用します。このガイドでは、**List Files**および**Get File**エンドポイントで利用可能なメディアリンクインクルード、それぞれが返すもの、いつ使用するかについて説明します。

## インクルードとは何ですか？

インクルードは、ファイル応答と一緒にリクエストできるオプションフィールドです。デフォルトでは、APIはコアファイルメタデータ（名前、ステータス、タイプ、タイムスタンプ、`view_url`）のみを返します。インクルードを使用すると、すべてが必要でない場合に応答を軽量に保ちながら、追加データをオプトインできます。

### インクルードの追加方法

**Get File**または**List Files**リクエストで、インクルード名のカンマ区切りリストを`include`クエリパラメータとして渡します：

**`単一インクルード`**

```bash title="単一インクルード"
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail
```

**`複数インクルード`**

```bash title="複数インクルード"
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original
```

**`List Filesでのインクルード`**

```bash title="List Filesでのインクルード"
GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail
```

インクルードは、単一ファイルエンドポイントとリストエンドポイントの両方で同じように動作します。List Filesで使用する場合、インクルードは応答内のすべてのファイルに対して解決されます。

### SDK例

**`Python SDK`**

```python title="Python SDK"
import frameio

client = frameio.Frameio(auth="<YOUR_TOKEN>")

file = client.files.get(
    file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    include=["media_links.thumbnail", "media_links.original"]
)

print(file.media_links.thumbnail.url)
```

**`TypeScript SDK`**

```typescript title="TypeScript SDK"
import Frameio from "frameio";

const client = new Frameio({ auth: "<YOUR_TOKEN>" });

const file = await client.files.get("93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", {
  include: ["media_links.thumbnail", "media_links.original"],
});

console.log(file.media_links?.thumbnail?.url);
```

リクエストされていないインクルードは、応答から完全に省略されます。

## メディアリンクインクルード概要

#### media\_links.original

アップロードされたオリジナルファイル（アップロード時とまったく同じ状態）

#### media\_links.thumbnail

表示目的のPNGプレビュー画像

#### media\_links.high\_quality

利用可能な最高品質の処理済みレンディション

#### media\_links.efficient

低帯域幅のユースケース向けの最小サイズのレンディション

#### media\_links.video\_h264\_180

ストリーミングと再生用の低解像度180p H264動画トランスコード

#### media\_links.scrub\_sheet

スクラビングUIを作成するための動画フレームサムネイルのWebPスプライトシート

## media\_links.original

**アップロードされた元のファイルそのまま**を指す署名付きURLを返します。処理やコンバージョンは行われません。

### フィールド

| フィールド          | 書式        | 説明   |                                                                               |
| -------------- | --------- | ---- | ----------------------------------------------------------------------------- |
| `download_url` | string \\ | null | ファイルのダウンロードを強制する署名付きURL（`Content-Disposition: attachment`）                    |
| `inline_url`   | string \\ | null | ブラウザーでファイルを直接開く署名付きURL（`Content-Disposition: inline; filename=<name></name>`) |

### 使用する場合

ソースファイルが必要な場合に`media_links.original`を使用します。例えば、ユーザーが元のMOV、MP4、MXF、AVI、PSD、PNG、またはTIFFをダウンロードできるようにする場合や、元のバイトを別のシステムに渡す場合などです。

### リクエスト例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original
```

### レスポンス例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "hero-banner.png",
    "type": "file",
    "media_links": {
      "original": {
        "download_url": "https://s3.amazonaws.com/...",
        "inline_url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

> **Warning**
>
> これらのURLは**一時的な署名付きS3 URL**で、有効期限があります。キャッシュや保存は行わず、必要な時に毎回新しいURLをリクエストしてください。

## media\_links.thumbnail

アセットの**PNGプレビュー画像**を返します。高さは540pxに制限されます。これは処理済みレンディションで、元のファイルではありません。アカウント設定によっては透かしが適用される場合があります。

### フィールド

| フィールド          | 書式        | 説明   |                                                       |
| -------------- | --------- | ---- | ----------------------------------------------------- |
| `download_url` | string \\ | null | PNGサムネールの強制ダウンロードを行う署名付きURL                           |
| `url`          | string \\ | null | `Content-Disposition`ヘッダーなしでPNGサムネールをインライン表示する署名付きURL |

### 使用する場面

`media_links.thumbnail`は、グリッドビュー、ギャラリー、ファイルピッカーなどで**アセットの視覚的なプレビューを表示**する必要がある場合に使用します。オリジナルよりも高速に読み込まれ、常にweb対応のPNG形式です。

### リクエスト例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail
```

### レスポンス例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "hero-banner.png",
    "type": "file",
    "media_links": {
      "thumbnail": {
        "download_url": "https://s3.amazonaws.com/...",
        "url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

## media\_links.high\_quality

**利用可能な最高品質の処理済みレンディション**のダウンロードURLを返します。Frame.ioは最大2160pの解像度ラダーを通じてアップロードを処理します。APIは**リクエスト時点で利用可能な最高のレンディション**を返します。つまり、リクエスト時に540pレンディションのみが処理完了している場合、より高いレンディションが準備できるまでAPIは540pを返します。

### フィールド

| フィールド          | 書式        | 説明   |                                  |
| -------------- | --------- | ---- | -------------------------------- |
| `download_url` | string \\ | null | リクエスト時点で利用可能な最高品質レンディションの署名付きURL |

### 使用する場面

`media_links.high_quality`は、ダウンストリーム処理用の高解像度レンディションの書き出しや、フル解像度プレビューの表示など、**オリジナルを必要とせずに最高品質のバージョン**が必要な場合に使用します。可能な限り最高の品質が必要な場合は、ファイルの`status`フィールドを確認し、ファイルが`ready`になったらこのincludeをリクエストして、完全な解像度ラダーが処理されていることを確認してください。

### リクエスト例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality
```

### レスポンス例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "hero-banner.png",
    "type": "file",
    "media_links": {
      "high_quality": {
        "download_url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

## media\_links.efficient

**利用可能な最小の処理済みレンディション**のダウンロードURLを返します。これは`high_quality`の反対です。Frame.ioは利用可能な最低解像度のレンディションを選択します。

### フィールド

| フィールド          | 書式        | 説明   |                          |
| -------------- | --------- | ---- | ------------------------ |
| `download_url` | string \\ | null | 最小/最も効率的なレンディションの署名付きURL |

### 使用する場合

**品質よりも帯域幅やファイルサイズが重要な場合**に`media_links.efficient`を使用します。例えば、低帯域幅環境での素早いプレビュー生成や、フル解像度を必要としないサムネイルパイプラインへの供給などです。

### リクエスト例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient
```

### レスポンス例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "hero-banner.png",
    "type": "file",
    "media_links": {
      "efficient": {
        "download_url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

## media\_links.video\_h264\_180

アセットの**低解像度180p H264動画トランスコード**のストリーミングおよびダウンロードURLを返します。

> **Warning**
>
> これはレガシーインクルードです。アセットに対して180pトランスコードが生成されなかった場合は`null`になります。ほとんどのユースケースでは、特定のトランスコードの存在に依存するのではなく、利用可能な最適な低品質レンディションを選択する`media_links.efficient`を推奨します。

### フィールド

| フィールド          | 書式        | 説明   |                                 |
| -------------- | --------- | ---- | ------------------------------- |
| `download_url` | string \\ | null | 180p H264動画をダウンロードするための署名付きURL  |
| `url`          | string \\ | null | 180p H264動画をストリーミングするための署名付きURL |

### 使用する場合

具体的に保証された180p H264トランスコードが必要な場合に`media_links.video_h264_180`を使用します。例えば、この正確なフォーマットを必要とするレガシープレーヤーやパイプラインとの統合などです。特定のアセットにトランスコードが存在しない場合、両方のURLが`null`になります。

> **Warning**
>
> video\_h264\_180ファイルにはオーディオは含まれていません。必要に応じて非常に効率的なプレビューに使用することを目的としています。

### リクエストの例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180
```

### 応答の例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "interview-clip.mp4",
    "type": "file",
    "media_links": {
      "video_h264_180": {
        "download_url": "https://s3.amazonaws.com/...",
        "url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

## media\_links.scrub\_sheet

**WebPスプライトシート**を返します。これは、ビデオの長さ全体にわたって均等にサンプリングされたビデオフレームのサムネイルのグリッドを含む単一の画像です。これは、ユーザーがタイムライン上でドラッグするとプレーヤーがプレビューフレームを表示するビデオスクラビングUIの作成に使用されます。

> **Info**
>
> スクラブシートは**ビデオアセットのみ**に対して生成されます。includeは画像、PDF、その他の非ビデオファイルに対して`null` URLを返します。

### フィールド

| フィールド                | 書式        | 説明                   |                                      |
| -------------------- | --------- | -------------------- | ------------------------------------ |
| `download_url`       | string \\ | null                 | WebPスプライトシートをダウンロードするための署名付きURL      |
| `url`                | string \\ | null                 | WebPスプライトシートをインラインで読み込むための署名付きURL    |
| `metadata`           | object \\ | null                 | 個々のフレームを抽出するためのタイル レイアウト情報（実験的APIのみ） |
| **`metadata`フィールド：** |           |                      |                                      |
| フィールド                | 書式        | 説明                   |                                      |
| ---                  | ---       | ---                  |                                      |
| \`\`                 | integer   | グリッド内のサムネイル列数        |                                      |
| \`\`                 | integer   | グリッド内のサムネイル行数        |                                      |
| `thumb_width`        | integer   | 各サムネイルの幅（ピクセル単位）     |                                      |
| `thumb_height`       | integer   | 各サムネイルの高さ（ピクセル単位）    |                                      |
| \`\`                 | integer   | サムネイル間のギャップ（ピクセル単位）  |                                      |
| \`\`                 | integer   | シートでサンプリングされたフレームの総数 |                                      |

### 使用する場合

ユーザーがスクラブするときにプレビューサムネイルを表示する必要があるカスタムビデオプレーヤーやタイムライン UI を作成する場合は、`media_links.scrub_sheet` を使用します。各フレームに対して個別のリクエストを行うのではなく、スプライトシートはすべてのプレビューフレームを単一の画像ダウンロードにまとめます。

### リクエストの例

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet
```

### レスポンスの例

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "interview-clip.mp4",
    "type": "file",
    "media_links": {
      "scrub_sheet": {
        "download_url": "https://assets.frame.io/...",
        "url": "https://assets.frame.io/...",
        "metadata": {
          "tile_x": 10,
          "tile_y": 10,
          "thumb_width": 160,
          "thumb_height": 90,
          "padding": 1,
          "frames": 100
        }
      }
    }
  }
}
```

### スプライトシートからフレームを抽出する

スプライトシートは `tile_x` 列 × `tile_y` 行のグリッドです。指定されたフレームインデックス（ゼロベース）のサムネイルを表示するには、画像内での位置を計算します：

```javascript
function getFrameOffset(frameIndex, metadata) {
  const { tile_x, thumb_width, thumb_height, padding } = metadata;

  const col = frameIndex % tile_x;
  const row = Math.floor(frameIndex / tile_x);

  return {
    x: col * (thumb_width + padding),
    y: row * (thumb_height + padding),
    width: thumb_width,
    height: thumb_height,
  };
}
```

CSS `background-position` を使用して、スプライトシートから正しいタイルを表示できます：

```javascript
function applyFrameToElement(el, frameIndex, scrubSheet) {
  const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata);

  el.style.backgroundImage = `url(${scrubSheet.url})`;
  el.style.backgroundPosition = `-${x}px -${y}px`;
  el.style.width = `${width}px`;
  el.style.height = `${height}px`;
}
```

再生位置（秒単位）をフレームインデックスにマッピングするには、ビデオの総再生時間とシート内のフレーム数を使用します：

```javascript
function positionToFrameIndex(currentSeconds, durationSeconds, metadata) {
  const progress = currentSeconds / durationSeconds;
  return Math.min(
    Math.floor(progress * metadata.frames),
    metadata.frames - 1
  );
}
```

> **Info**
>
> `metadata` フィールドは実験的な API バージョンでのみ利用できます。安定版 v4 API では、`scrub_sheet` は `download_url` と `url` のみを返します。

## 複数のインクルードの組み合わせ

単一の API 呼び出しで複数のインクルードをリクエストできます：

```bash
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original
```

```json
{
  "data": {
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    "name": "hero-banner.png",
    "type": "file",
    "media_links": {
      "thumbnail": {
        "download_url": "https://s3.amazonaws.com/...",
        "url": "https://s3.amazonaws.com/..."
      },
      "original": {
        "download_url": "https://s3.amazonaws.com/...",
        "inline_url": "https://s3.amazonaws.com/..."
      }
    }
  }
}
```

## 適切なERPの選定

| 目的                             | 使用するインクルード                            |
| ------------------------------ | ------------------------------------- |
| UI にプレビュー画像を表示する               | `media_links.thumbnail`               |
| ユーザーが元のファイルをダウンロードできるようにする     | `media_links.original`                |
| ブラウザーで元のファイルを直接開く              | `media_links.original` → `inline_url` |
| エクスポート用の最高品質のレンディションを取得する      | `media_links.high_quality`            |
| 低帯域幅使用のための小さなレンディションを取得する      | `media_links.efficient`               |
| ストリームまたは低解像度ビデオ（レガシー）をダウンロードする | `media_links.video_h264_180`          |
| フレームプレビューでビデオスクラブUIを作成する       | `media_links.scrub_sheet`             |
| Frame.ioでユーザーをファイルにナビゲーションする   | ベースファイル応答から`view_url`を使用する            |

> **Info**
>
> `view_url` — インクルードを必要とせずにすべてのファイル応答で利用可能 — は、Frame.io webアプリへの永続的なディープリンクです。これは**メディア**URLではありません。Frame.io UIを開き、有効期限はありません。プログラムでファイルを提供またはダウンロードする必要がある場合ではなく、ユーザーをFrame.ioで直接アセットをレビューまたはコメントするように誘導したい場合に使用してください。

## インクルード可用性

メディアリンクインクルードは、Frame.ioがアップロードされたファイルの処理を完了した後にのみ入力されます。アップロード直後にインクルードをリクエストした場合、トランスコーディングが進行中の間、URLは`null`になる可能性があります。ファイルオブジェクトの`status`フィールドを確認してください — ステータスが`ready`になると、インクルードが利用可能になります。