> 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 > - Версия 4 экспериментальная: 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-интерфейс, базовый ответ содержит основные метаданные, такие как имя файла, его статус и ссылку `view_url` для открытия в приложении Frame.io. Для получения доступа к фактическому содержимому файла (оригинала, копии для предпросмотра или версий различного качества) используются включения (**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 **`SDK для Python`** ```python title="SDK для Python" import frameio client = frameio.Frameio(auth="") file = client.files.get( file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", include=["media_links.thumbnail", "media_links.original"] ) print(file.media_links.thumbnail.url) ``` **`SDK для TypeScript`** ```typescript title="SDK для TypeScript" import Frameio from "frameio"; const client = new Frameio({ auth: "" }); 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, содержащий миниатюры кадров видео для реализации интерфейса перемотки ## media\_links.original Возвращает подписанные URL-адреса, указывающие на **исходный файл в том самом виде, в каком он был добавлен**, без обработки и конвертации. ### Поля | Поле | Тип | Описание | | | -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | Подписанный URL-адрес, который принудительно запускает загрузку файла (`Content-Disposition: attachment`) | | `inline_url` | строка \\ | null | Подписанный URL-адрес, который открывает файл прямо в браузере (`Content-Disposition: inline; filename=`) | ### Когда использовать Используйте включение `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-адрес каждый раз, когда он необходим. ## media\_links.thumbnail Возвращает **изображение ресурса для предпросмотра в формате PNG** с максимальной высотой 540 пикселей. Это обработанная версия, а не исходный файл. В зависимости от настроек вашей учетной записи на нее могут быть наложены водяные знаки. ### Поля | Поле | Тип | Описание | | | -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | Подписанный URL-адрес, который принудительно запускает загрузку миниатюры в формате PNG | | `url` | строка \\ | null | Подписанный URL-адрес, который отображает миниатюру в формате PNG прямо в браузере без заголовка `Content-Disposition` | ### Когда использовать Используйте включение `media_links.thumbnail`, когда нужна **визуализация для предпросмотра** ресурса, например в виде сетки, галереи или средства выбора файлов. Миниатюры загружаются быстрее, чем исходный файл, и всегда представлены в безопасном для веб-интерфейсов формате 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-интерфейс будет возвращать ссылку на нее до тех пор, пока не будут готовы версии в более высоком качестве. ### Поля | Поле | Тип | Описание | | | -------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------- | | `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 Возвращает URL-адреса для потоковой передачи и загрузки **перекодированного видео в низком разрешении 180p H264**. > **Warning** > > Это устаревшее включение. Его значение будет `null`, если для данного ресурса не было создано перекодированное видео 180p. Для большинства сценариев использования рекомендуется выбирать включение `media_links.efficient`, которое автоматически подбирает лучшую из доступных версий низкого качества, а не требует перекодирования. ### Поля | Поле | Тип | Описание | | | -------------- | --------- | -------- | ---------------------------------------------------------------------- | | `download_url` | string \\ | null | Подписанный URL-адрес для загрузки видео в формате H264 180p | | `url` | строка \\ | null | Подписанный URL-адрес для потоковой передачи видео в формате H264 180p | ### Когда использовать Используйте включение `media_links.video_h264_180`, когда вам нужно перекодированное видео в формате H264 180p, например для интеграции с устаревшим проигрывателем или цепочкой обработки, которым требуется именно этот формат. Если для данного ресурса такого перекодированного видео нет, оба 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** — одно изображение, содержащее сетку из миниатюр кадров видео, взятых через равные промежутки времени на протяжении всей длительности видеоролика. Это включение используется для реализации интерфейса перемотки, когда проигрыватель показывает кадр для предпросмотра по мере того, как пользователь перемещает ползунок по шкале времени. > **Info** > > Спрайт-листы для перемотки создаются **только для видеоресурсов**. Для изображений, документов PDF и других типов файлов, которые не являются видео, это включение вернет значение `null` для всех URL-адресов. ### Поля | Поле | Тип | Описание | | | -------------------------------- | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `download_url` | string \\ | null | Подписанный URL-адрес для загрузки спрайт-листа в формате WebP | | `url` | строка \\ | null | Подписанный URL-адрес для загрузки спрайт-листа в формате WebP прямо в браузере | | `metadata` | объект \\ | null | Информация о плиточной структуре для извлечения отдельных кадров (только в экспериментальном API-интерфейсе) | | Поля метаданных (**`metadata`**) | | | | | Поле | Тип | Описание | | | --- | --- | --- | | | `tile_x` | целое число | Количество столбцов миниатюр в сетке | | | `tile_y` | целое число | Количество строк миниатюр в сетке | | | `thumb_width` | целое число | Ширина каждой миниатюры в пикселях | | | `thumb_height` | целое число | Высота каждой миниатюры в пикселях | | | `padding` | целое число | Расстояние между миниатюрами в пикселях | | | `frames` | целое число | Общее количество кадров на листе | | ### Когда использовать Используйте включение `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. В стабильной версии API-интерфейса v4 включение `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/..." } } } } ``` ## Выбор подходящего включения | Цель | Используемое включение | | ----------------------------------------------------------------------------------- | -------------------------------------------------- | | Отображение изображения для предпросмотра в интерфейсе | `media_links.thumbnail` | | Загрузка пользователем исходного файла | `media_links.original` | | Открытие исходного файла непосредственно в браузере | `media_links.original` → `inline_url` | | Получение версии лучшего качества для экспорта | `media_links.high_quality` | | Получение небольшой версии для использования при низкой пропускной способности сети | `media_links.efficient` | | Потоковая передача или загрузка видео в низком разрешении (устаревшее) | `media_links.video_h264_180` | | Создание интерфейса перемотки видео с предпросмотром кадров | `media_links.scrub_sheet` | | Направление пользователя к файлу в Frame.io | Используйте `view_url` из базового ответа по файлу | > **Info** > > Ссылка `view_url`, которая доступна в каждом ответе по файлу без необходимости в использовании включений, является постоянной прямой ссылкой на веб-приложение Frame.io. Это **не** ссылка на медиафайл. Она открывает интерфейс Frame.io и не имеет срока действия. Используйте ее, когда вам нужно направить пользователя для рецензирования или комментирования ресурса непосредственно в Frame.io, а не тогда, когда требуется программным путем отобразить или загрузить файл. ## Доступность включений Включения в ссылках на медиафайлы заполняются только после того, как Frame.io завершит обработку добавленного файла. Если вы запросите включение сразу после добавления, URL-адреса могут иметь значение `null`, пока выполняется перекодирование. Проверяйте поле состояния (`status`) объекта файла — включения станут доступны, как только состояние изменится на «готов» (`ready`).