媒体链接 | Frame.io API Documentation

Frame.io 存储和处理上传到您项目中的文件（图像、视频、PDF 等）。当您通过 API 检索文件时，基本响应包括核心元数据，如文件名称、状态，以及用于在 Frame.io 应用程序中打开文件的 view_url。要访问实际文件内容，包括原始文件、预览或不同质量的呈现版本，您需要使用 includes。本指南解释了列出文件和获取文件端点上可用的媒体链接包含项、每个包含项返回的内容，以及何时使用每个包含项。

什么是包含项？

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

如何添加包含项

在任何获取文件或列出文件请求中，通过 include 查询参数传递以逗号分隔的包含项名称列表：

单个包含项

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

多个包含项

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

“列出文件”上的包含项

$ GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail

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

SDK 示例

1 import frameio
2 
3 client = frameio.Frameio(auth="<YOUR_TOKEN>")
4 
5 file = client.files.get(
6     file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
7     include=["media_links.thumbnail", "media_links.original"]
8 )
9 
10 print(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
`inline_url`	string \	null

使用场景

在需要源文件时使用 media_links.original，例如让用户下载原始 MOV、MP4、MXF、AVI、PSD、PNG 或 TIFF，或将原始字节传递给其他系统时。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "hero-banner.png",
5     "type": "file",
6     "media_links": {
7       "original": {
8         "download_url": "https://s3.amazonaws.com/...",
9         "inline_url": "https://s3.amazonaws.com/..."
10       }
11     }
12   }
13 }

这些 URL 是临时签名 S3 URL，会过期。请勿缓存或存储它们；每次需要时请求新的 URL。

media_links.thumbnail

返回资产的 PNG 预览图像，限制高度为 540px。这是处理过的渲染版，而非原始文件，根据您的帐户设置可能会有水印。

字段

字段	类型	描述
`download_url`	string \	null
`url`	string \	null

使用场景

当您需要显示资产的视觉预览时（例如在网格视图、库或文件选择器中），请使用 media_links.thumbnail。它的加载速度比原始文件更快，且始终为 Web 安全的 PNG 格式。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "hero-banner.png",
5     "type": "file",
6     "media_links": {
7       "thumbnail": {
8         "download_url": "https://s3.amazonaws.com/...",
9         "url": "https://s3.amazonaws.com/..."
10       }
11     }
12   }
13 }

media_links.high_quality

返回资产最佳可用的处理演绎版的下载 URL。 Frame.io 通过分辨率阶梯处理上传，最高支持 2160p。 API 返回请求时可用的最高演绎版，因此如果在您发出请求时只有 540p 格式演绎版完成处理，那么 API 会先返回 540p，直到更高的演绎版准备就绪。

字段

字段	类型	描述
`download_url`	string \	null

使用场景

当您想要最佳质量版本而无需原始版本时（例如，为下游处理导出高分辨率的演绎版，或呈现全分辨率预览），请使用 media_links.high_quality。如果您需要最高质量，请检查文件 status 字段，并在文件变为 ready 后请求此包含项，确保已处理完整的分辨率阶梯。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "hero-banner.png",
5     "type": "file",
6     "media_links": {
7       "high_quality": {
8         "download_url": "https://s3.amazonaws.com/..."
9       }
10     }
11   }
12 }

media_links.efficient

返回最削可用的处理演绎版的下载 URL。这与 high_quality 相反，Frame.io 会选择可用的最低分辨率演绎版。

字段

字段	类型	描述
`download_url`	string \	null

使用场景

当带宽或文件大小比质量更重要时，使用 media_links.efficient，例如在低带宽环境中生成快速预览，或为不需要全分辨率的缩略图管道提供图像。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "hero-banner.png",
5     "type": "file",
6     "media_links": {
7       "efficient": {
8         "download_url": "https://s3.amazonaws.com/..."
9       }
10     }
11   }
12 }

media_links.video_h264_180

返回资产的低分辨率 180p H264 视频转码 的流媒体和下载 URL。

这是一个旧版包含项。如果没有为资产生成 180p 转码，则该值为 null。对于大多数用例，建议使用 media_links.efficient，它会选择可用的最佳低质量演绎版，而不是依赖特定转码的存在。

字段

字段	类型	描述
`download_url`	string \	null
`url`	string \	null

使用场景

当您需要专门保证 180p H264 转码时，请使用 media_links.video_h264_180，例如与需要这种确切格式的旧版播放器或管道集成。如果给定资产不存在转码，两个 URL 均将为 null。

video_h264_180 文件中不包含音频。其旨在用于在需要时进行非常高效的预览。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "interview-clip.mp4",
5     "type": "file",
6     "media_links": {
7       "video_h264_180": {
8         "download_url": "https://s3.amazonaws.com/...",
9         "url": "https://s3.amazonaws.com/..."
10       }
11     }
12   }
13 }

media_links.scrub_sheet

返回 WebP 精灵表 — 即包含视频帧缩略图网格的单个图像，这些缩略图均匀地分布在在视频播放中。这可以用于构建视频拖动 UI，在用户拖拽时间线时播放器可以显示预览帧。

拖动表仅针对视频资产生成。对于图像、PDF 和其他非视频文件，包含项将返回 null URL。

字段

字段	类型	描述
`download_url`	string \	null
`url`	string \	null
`metadata`	object \	null
`metadata` 字段：
字段	类型	描述
---	---	---
`tile_x`	整数	网格中的缩略图列数
`tile_y`	整数	网格中的缩略图行数
`thumb_width`	整数	每个缩略图的宽度（以像素为单位）
`thumb_height`	整数	每个缩略图的高度（以像素为单位）
`padding`	整数	缩略图之间的内边距（以像素为单位）
`frames`	整数	图表中取样的总帧数

使用场景

在构建需要显示预览缩略图的自定义视频播放器或时间线 UI 时，可以使用 media_links.scrub_sheet，以便在用户拖动进度条时显示预览缩略图。精灵图不是对每一帧单独请求，而是将所有预览帧打包到一个图像下载中。

示例请求

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

示例响应

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "interview-clip.mp4",
5     "type": "file",
6     "media_links": {
7       "scrub_sheet": {
8         "download_url": "https://assets.frame.io/...",
9         "url": "https://assets.frame.io/...",
10         "metadata": {
11           "tile_x": 10,
12           "tile_y": 10,
13           "thumb_width": 160,
14           "thumb_height": 90,
15           "padding": 1,
16           "frames": 100
17         }
18       }
19     }
20   }
21 }

从精灵表中提取帧

精灵表是一个 tile_x 列 × tile_y 行的网格。要显示给定帧索引（从零开始）的缩略图，请计算其在图像中的位置：

1 function getFrameOffset(frameIndex, metadata) {
2   const { tile_x, thumb_width, thumb_height, padding } = metadata;
3 
4   const col = frameIndex % tile_x;
5   const row = Math.floor(frameIndex / tile_x);
6 
7   return {
8     x: col * (thumb_width + padding),
9     y: row * (thumb_height + padding),
10     width: thumb_width,
11     height: thumb_height,
12   };
13 }

然后，您可以使用 CSS background-position 从精灵表中显示正确的图块：

1 function applyFrameToElement(el, frameIndex, scrubSheet) {
2   const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata);
3 
4   el.style.backgroundImage = `url(${scrubSheet.url})`;
5   el.style.backgroundPosition = `-${x}px -${y}px`;
6   el.style.width = `${width}px`;
7   el.style.height = `${height}px`;
8 }

要将播放位置（以秒为单位）映射到帧索引，请使用视频总时长和图表中的帧数：

1 function positionToFrameIndex(currentSeconds, durationSeconds, metadata) {
2   const progress = currentSeconds / durationSeconds;
3   return Math.min(
4     Math.floor(progress * metadata.frames),
5     metadata.frames - 1
6   );
7 }

metadata 字段仅在实验性 API 版本中可用。在稳定的 v4 API 中，scrub_sheet 只会返回 download_url 和 url。

组合多个包含项

您可以在单个 API 调用中请求多个包含项：

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

1 {
2   "data": {
3     "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4     "name": "hero-banner.png",
5     "type": "file",
6     "media_links": {
7       "thumbnail": {
8         "download_url": "https://s3.amazonaws.com/...",
9         "url": "https://s3.amazonaws.com/..."
10       },
11       "original": {
12         "download_url": "https://s3.amazonaws.com/...",
13         "inline_url": "https://s3.amazonaws.com/..."
14       }
15     }
16   }
17 }

选择正确的包含项

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

view_url（在每个文件响应中均可找到，无需包含项）是指向 Frame.io web 应用程序的永久性深度链接。它不是媒体 URL；它会打开 Frame.io UI 且没有过期时间。请在您想要引导用户直接在 Frame.io 中审阅或评论资产时使用它，而不是在需要以编程方式提供或下载文件时使用。

包含项可用性

只有在 Frame.io 完成对上传文件的处理后，才会填充媒体链接。如果您在上传后立即请求包含项，则在转码进行期间，URL 可能为 null。检查文件对象上的 status 字段，一旦状态为 ready，包含项将可用。