> 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. # Коллекция Postman В этом руководстве описываются основы работы с официальной коллекцией Postman для API-интерфейса Frame.io Developer — набором готовых запросов, которые можно использовать для начала работы API-интерфейса V4. Коллекция охватывает весь спектр конечных точек API-интерфейса V4, которые разделены на стабильные и экспериментальные. Стабильные конечные точки готовы к использованию в производстве, в то время как экспериментальные представляют собой новые функции — они полностью работоспособны, но могут измениться на основе отзывов пользователей перед переносом в категорию стабильных. ## Начало работы с коллекцией Postman > **Tip** > > В данном руководстве предполагается, что вы уже создали учетные данные для API-интерфейса. Если вы этого еще не сделали, начните с [этого](/platform/docs/quick-start) шага. #### Создание учетной записи Postman и выбор конфигурации Создайте учетную запись Postman на сайте [postman.com](http://auth.postman.com/__redirect/login) и выберите конфигурацию. Вы можете загрузить приложение Postman [здесь](https://www.postman.com/downloads/) или использовать веб-версию. #### Импорт коллекции Postman для API-интерфейса Frame.io Developer #### [Коллекция для API-интерфейса Frame.io Developer](https://www.postman.com/adobe/workspace/frame-io-v4-public-api/collection/33150877-924315f2-cc62-45f5-8153-77ff2aaa9067?action=share\&creator=33150877\&active-environment=33150877-cffd66a8-23bd-4c50-8891-29157ead1185) Получить или загрузить здесь ### Настройка среды Коллекция для API-интерфейса Frame.io Developer имеет стандартную среду с рядом определенных переменных. Значения `BASE_URL` и `IMS_BASE_URL` статичны. Дополнительные переменные среды можно настроить в соответствии с данными вашей учетной записи. ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp) ![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) Ниже представлена таблица с описанием каждой переменной, используемой в стандартной и тестовой средах коллекции. | Переменная | Описание | Как получить | Среда | | ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------- | | `BASE_URL` | Базовый URL-адрес для всех запросов к API-интерфейсу V4 | Предварительно задана, не подлежит изменению | Стандартная | | `IMS_BASE_URL` | Базовый URL-адрес аутентификации Adobe IMS | Предварительно задана, не подлежит изменению | Стандартная, тестовая | | `IMS_CLIENT_ID` | Идентификатор Client ID вашего приложения Frame.io | Страница учетных данных в **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Тестовая | | `IMS_CLIENT_SECRET` | Секретный ключ клиента вашего приложения Frame.io | Страница учетных данных в **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Тестовая | | `FOLDER_ID` | Уникальный идентификатор для папки назначения | Возвращается в объекте ответа папки | Стандартная | | `WEBHOOK_ID` | Уникальный идентификатор для настроенного веб-перехватчика | Возвращается в объекте ответа веб-перехватчика | Стандартная | | `ASSET_ID` | Уникальный идентификатор для файла или папки | Возвращается в объекте ответа файла или папки | Стандартная | | `SHARE_ID` | Уникальный идентификатор для ссылки общего доступа | Возвращается в объекте ответа ссылки общего доступа | Стандартная | --- ### Настройка авторизации > **Tip** > > [ В этом руководстве для аутентификации в API-интерфейсе Frame.io V4 используется протокол OAuth 2.0. Подробнее о других методах аутентификации, например межсерверной аутентификации (S2S), — в ](\Получить новый токен доступа\*\*, чтобы запустить процесс OAuth 2.0. Откроется окно браузера для завершения аутентификации, после чего токен будет передан обратно в Postman. Чтобы проверить настройки авторизации, выберите запрос **`GET user details`** в папке «Пользователи» и нажмите **Отправить**. Ответ **`200 OK`** подтверждает, что коллекция настроена правильно и вы успешно прошли аутентификацию в нужной учетной записи. В случае возникновения ошибки см. \*\*\*\*]\(\ **Tip** > > Если у вас несколько учетных записей Frame.io, каждая из них будет отображаться в ответе как отдельный объект. После получения идентификатора учетной записи скопируйте значение `id` из ответа и сохраните его как переменную среды. Вы будете ссылаться на него как на параметр пути `account_id`, параметр пути используя конструкцию `{{ACCOUNT_ID}}` в будущих запросах. --- ## Операции с рабочими средами и проектами Ваши файлы в Frame.io хранятся в папках, систематизированных в проекты внутри рабочей среды. Полный обзор иерархии ресурсов в версии V4 — в \**]\(\ **Tip** > > Вы можете добавить пользователя в недавно созданный проект с ограниченным доступом с помощью последующего запроса **`PATCH Update user role in a Project`**, расположенного в папке **Разрешения на уровне проекта**. (**[Справочник по API-интерфейсу](/platform/docs/guides/postman-collection)**) --- ## Операции с папками и файлами ### Создание списков дочерних элементов папки Запрос **`GET list folder children`** обращается к конечной точке **[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)** для создания списка дочерних элементов в указанной папке. В данном случае это корневая папка проекта, установленная в качестве переменной среды **`FOLDER_ID`**. Вы можете использовать следующие дополнительные параметры запроса для уточнения ответа. | Параметр | Тип | Описание | | ------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`page_size`** | Целое число | Ограничивает количество возвращаемых папок в диапазоне **1–100. По умолчанию — 50**. | | **`type`** | Строка | Фильтрует дочерние элементы папки по типу ресурса: **`file`** или **`folder`**. | | **`after`** | Строка | Непрозрачный курсор для запросов, возвращающих разбитые на страницы результаты. **Он создается автоматически и возвращается в объекте `links` предыдущего ответа.** Не предназначен для чтения человеком. | | **`include_total_count`** | Логический | Возвращает общее количество всех сущностей. **По умолчанию — False**. | | **`include`** | Перечисление | Добавляет дополнительные данные к каждому возвращаемому объекту, такие как `creator`, `project`, `media_links`. Полный список поддерживаемых параметров — в **[справочнике по API-интерфейсу](/platform/api-reference/folders/index#request.query.include)**. | Успешный запрос вернет статус **`200 OK`** и тело ответа, аналогичное приведенному ниже примеру. **Пример ответа** ``` { "data": [ { "type": "file", "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "media_type": "image/png", "name": "asset.png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "creator": { "active": true, "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "email": "user_email@example.com", "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e", "name": "Jon Doe" }, "media_links": { "high_quality": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN" }, "original": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "inline_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=inline%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragSDFXDFh&1Key-Pair-Id=KKI497NESTHMN" }, "thumbnail": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "url": "https://picture2.frame.io/image/s3://frameio-assets-development/image/cd58cb8e-24b3-4498-8d0f-9532fcd04d11/image_full.png?alg=HS256&sig=0_u7w_wz2MwQHOXp000ibbQSMRijujyaUu8V3YYPxu4&exp=1729857600" } }, "metadata": [ { "field_type": "select", "field_definition_id": "b859ccec-9536-4bf2-bc6f-5e9206e26606", "field_definition_name": "Fields definition name", "mutable": true, "value": [ { "display_name": "Display name", "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8" } ], "field_options": [ { "display_name": "Display name", "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8" }, { "display_name": "Display name 2", "id": "c6eb873f-125b-4317-b857-1a22eb3dbf22" } ] } ], "project": { "created_at": "2024-01-25T19:18:29.614189Z", "description": "Project Description", "id": "e0e30b1d-c3aa-44ee-926e-c6c326fb10dc", "name": "My Project", "root_folder_id": "be733511-6f15-4d97-8ee7-bc23b2fb0bd7", "status": "active", "storage": 15000, "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/", "workspace_id": "91b10e83-5874-44de-9b57-41c937b87256", "owner": { "active": true, "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "email": "user_email@example.com", "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e", "name": "Jon Doe" }, "restricted": false } } ], "links": { "next": "/v4/accounts/123/folders/123/folders" }, "total_count": 10 } ``` > **Тестирование параметра \\after\\** > > Если вы тестируете разбитые на страницы результаты, найдите объект **`links`** в своем ответе. > > * Из URL-адреса свойства **`next`** скопируйте только строковое значение, следующее после **`after=`**. > > * Установите его в качестве значения параметра запроса **`after`** в своем следующем запросе. > > * **Избегайте двойного кодирования!** Если URL-адрес содержит закодированные символы (например, %3D%3D), замените их на исходную версию (**==**). Postman интерпретирует ваш ввод буквально и может закодировать эти символы повторно, что приведет к ошибке **`422`**. --- ### Создание файла — локальное добавление Запрос **`POST create file - local upload`** обращается к **[`/v4/accounts/:account_id/folders/:folder_id/files/local_upload`](/platform/v4/api-reference/files/create-local-upload)** для добавления локального файла в указанную папку. Для локального добавления файлов требуется два или более запроса в зависимости от их размера. Для первого теста используйте небольшой файл (менее 10 МБ), чтобы ограничить процесс одним URL-адресом для добавления. #### Создание файла-заполнителя В редакторе запросов перейдите на вкладку **Тело**, чтобы задать имя и размер файла (указанный в **байтах**) в объекте `data`. Успешный запрос вернет статус **`201 Created`** и тело ответа, аналогичное приведенному ниже примеру. **Пример ответа** ``` { "data": { "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "media_type": "image/png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "type": "file", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "name": "asset.png", "upload_urls": [ { "size": 20000000, "url": "https://my.fileupload.url.dev" } ] } } ``` Этот вызов создал файл-заполнитель в указанной папке. На следующем шаге используйте предварительно подписанный URL-адрес для добавления из массива `upload_urls`, чтобы завершить добавление. #### Добавление содержимого файла Нажмите на URL-адрес в массиве `upload_urls` в ответе, чтобы открыть новую вкладку запроса в Postman. Измените метод запроса на **`PUT`**. В редакторе запросов перейдите на вкладку **Заголовки**, чтобы добавить следующие заголовки в ваш запрос. * **`x-amz-acl`:`private`*** **`Content-Type`**: этот заголовок должен точно соответствовать типу расширения, указанному в имени файла (например, для файла с именем **`IMG.png`** необходимо указать значение **`image/png`**) ![alt image](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) В редакторе запросов перейдите на вкладку **Тело** и нажмите **двоичный**, чтобы выбрать файл. После выбора нажмите **Отправить**, чтобы выполнить свой запрос. Успешный запрос вернет статус **`200 OK`**, подтверждающий, что файл был добавлен. После добавления файла система обработки медиафайлов Frame.io автоматически выполнит перекодирование и создаст миниатюру. Для файлов большого размера переход из состояния **`created`** в состояние **`ready`** может занять некоторое время. --- ### Создание файла — удаленное добавление Запрос **`POST create file - remote upload`** обращается к конечной точке **[`/v4/accounts/:account_id/folders/:folder_id/files/remote_upload`](/platform/v4/api-reference/files/create-remote-upload)**, чтобы добавить внешний файл в указанную папку, используя предоставленный URL-адрес источника. В редакторе запросов перейдите на вкладку **Тело**, чтобы задать имя и исходный URL-адрес файла в объекте `data`. Успешный запрос вернет статус **`202 Accepted`** и тело ответа, аналогичное приведенному ниже примеру. **Пример ответа** ``` { "data": { "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "media_type": "image/png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "type": "file", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "name": "asset.png" }, "links": { "status": "/v4/accounts/fb4dd62f-8a89-4e98-8fa1-ad4b29a0094f/files/eab70952-966c-4d99-949b-f0a947ca5754/status" } } ```