> 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 实验版: 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**。 本指南解释了**列出文件**和**获取文件**端点上可用的媒体链接包含项、每个包含项返回的内容，以及何时使用每个包含项。

## 什么是包含项？

包含项是您可以随文件响应一起请求的可选字段。 默认情况下，API 仅返回核心文件元数据，包括名称、状态、类型、时间戳和 `view_url`。 包含项让您可以选择加入其他数据，在您不需要所有内容时保持响应精简。

### 如何添加包含项

在任何**获取文件**或**列出文件**请求中，通过 `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
```

**`“列出文件”上的包含项`**

```bash title="“列出文件”上的包含项"
GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail
```

包含项在单文件和列表端点上的工作原理相同。 在“列出文件”上使用时，系统会解析响应中每个文件的包含项。

### 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

用于构建视频帧缩略图的 WebP 精灵图，用于构建拖动 UI

## 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` 后请求此包含项，确保已处理完整的分辨率阶梯。

### 示例请求

```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**
>
> 拖动表仅针对**视频资产**生成。 对于图像、PDF 和其他非视频文件，包含项将返回 `null` URL。

### 字段

| 字段                 | 类型        | 描述                |                           |
| ------------------ | --------- | ----------------- | ------------------------- |
| `download_url`     | string \\ | null              | 下载 WebP 精灵表的签名 URL        |
| `url`              | string \\ | null              | 内联加载 WebP 精灵表的签名 URL      |
| `metadata`         | object \\ | null              | 用于提取单个帧的图块布局信息（仅限实验性 API） |
| **`metadata` 字段：** |           |                   |                           |
| 字段                 | 类型        | 描述                |                           |
| ---                | ---       | ---               |                           |
| `tile_x`           | 整数        | 网格中的缩略图列数         |                           |
| `tile_y`           | 整数        | 网格中的缩略图行数         |                           |
| `thumb_width`      | 整数        | 每个缩略图的宽度（以像素为单位）  |                           |
| `thumb_height`     | 整数        | 每个缩略图的高度（以像素为单位）  |                           |
| `padding`          | 整数        | 缩略图之间的内边距（以像素为单位） |                           |
| `frames`           | 整数        | 图表中取样的总帧数         |                           |

### 使用场景

在构建需要显示预览缩略图的自定义视频播放器或时间线 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/..."
      }
    }
  }
}
```

## 选择正确的包含项

| 目标                   | 要使用的包含项                               |
| -------------------- | ------------------------------------- |
| 在您的 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`，包含项将可用。