Коллекция Postman | Frame.io API Documentation

В этом руководстве описываются основы работы с официальной коллекцией Postman для API-интерфейса Frame.io Developer — набором готовых запросов, которые можно использовать для начала работы API-интерфейса V4.

Коллекция охватывает весь спектр конечных точек API-интерфейса V4, которые разделены на стабильные и экспериментальные. Стабильные конечные точки готовы к использованию в производстве, в то время как экспериментальные представляют собой новые функции — они полностью работоспособны, но могут измениться на основе отзывов пользователей перед переносом в категорию стабильных.

Начало работы с коллекцией Postman

В данном руководстве предполагается, что вы уже создали учетные данные для API-интерфейса. Если вы этого еще не сделали, начните с этого шага.

Создание учетной записи Postman и выбор конфигурации

Создайте учетную запись Postman на сайте postman.com и выберите конфигурацию. Вы можете загрузить приложение Postman здесь или использовать веб-версию.

Импорт коллекции Postman для API-интерфейса Frame.io Developer

Коллекция для API-интерфейса Frame.io Developer

Получить или загрузить здесь

Настройка среды

Коллекция для API-интерфейса Frame.io Developer имеет стандартную среду с рядом определенных переменных. Значения BASE_URL и IMS_BASE_URL статичны. Дополнительные переменные среды можно настроить в соответствии с данными вашей учетной записи.

Ниже представлена таблица с описанием каждой переменной, используемой в стандартной и тестовой средах коллекции.

Переменная	Описание	Как получить	Среда
`BASE_URL`	Базовый URL-адрес для всех запросов к API-интерфейсу V4	Предварительно задана, не подлежит изменению	Стандартная
`IMS_BASE_URL`	Базовый URL-адрес аутентификации Adobe IMS	Предварительно задана, не подлежит изменению	Стандартная, тестовая
`IMS_CLIENT_ID`	Идентификатор Client ID вашего приложения Frame.io	Страница учетных данных в Adobe Developer Console	Тестовая
`IMS_CLIENT_SECRET`	Секретный ключ клиента вашего приложения Frame.io	Страница учетных данных в Adobe Developer Console	Тестовая
`FOLDER_ID`	Уникальный идентификатор для папки назначения	Возвращается в объекте ответа папки	Стандартная
`WEBHOOK_ID`	Уникальный идентификатор для настроенного веб-перехватчика	Возвращается в объекте ответа веб-перехватчика	Стандартная
`ASSET_ID`	Уникальный идентификатор для файла или папки	Возвращается в объекте ответа файла или папки	Стандартная
`SHARE_ID`	Уникальный идентификатор для ссылки общего доступа	Возвращается в объекте ответа ссылки общего доступа	Стандартная

Настройка авторизации

В этом руководстве для аутентификации в API-интерфейсе Frame.io V4 используется протокол OAuth 2.0. Подробнее о других методах аутентификации, например межсерверной аутентификации (S2S), — в руководстве по аутентификации.

Переменные среды IMS_CLIENT_ID и IMS_CLIENT_SECRET должны соответствовать значениям, полученным из раздела Сведения об учетных данных вашего проекта в Adobe Developer Console.

В разделе Сведения об учетных данных вашего проекта установите URI перенаправления и Шаблон URL-адреса перенаправления на публичную конечную точку обратного вызова Postman. URI перенаправления

https://oauth/pstmn.io/v1/callback

Шаблон URL-адреса перенаправления

https://oauth\\.pstmn\\.io

После настройки и сохранения переменных среды следующим шагом является настройка параметров авторизации. Для этого нажмите значок коллекций в верхней части левой боковой панели, чтобы открыть браузер коллекций. В браузере коллекций выберите корневой элемент коллекции для API-интерфейса Frame.io V4 Developer (обычно называется Коллекция для API-интерфейса Frame.io Developer, после чего следует имя вашей копии) и перейдите на вкладку Авторизация. alt image Области доступа OAuth предварительно настроены в коллекции. После установки переменных среды нажмите кнопку <strong>Получить новый токен доступа**, чтобы запустить процесс OAuth 2.0. Откроется окно браузера для завершения аутентификации, после чего токен будет передан обратно в Postman. Чтобы проверить настройки авторизации, выберите запрос GET user details в папке «Пользователи» и нажмите Отправить. Ответ 200 OK подтверждает, что коллекция настроена правильно и вы успешно прошли аутентификацию в нужной учетной записи. В случае возникновения ошибки см. ****](</span)этот раздел руководства по началу работы для получения сведений об ошибках и предупреждениях. Пример ответа

{
  "data": {
    "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": "00000000-1111-2222-3333-444444444444",
    "name": "Name"
  }
}

Получение идентификатора учетной записи

Идентификатор account_id является обязательным параметром пути для большинства конечных точек API-интерфейса V4 и необходим для тестирования других запросов. Получить account_id можно с помощью запроса GET List accounts, расположенного в папке Учетные записи коллекции. Справочник по API-интерфейсу Пример ответа

{
  "data": [
    {
      "created_at": "2023-09-25T19:18:29.614189Z",
      "display_name": "Integration Account",
      "id": "11111111-2222-3333-4444-555555555555",
      "roles": [
        "admin"
      ],
      "storage_limit": 300,
      "storage_usage": 300,
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "image": null
    }
  ],
  "links": {
    "next": "/v4/accounts"
  }
}

Если у вас несколько учетных записей Frame.io, каждая из них будет отображаться в ответе как отдельный объект.

После получения идентификатора учетной записи скопируйте значение id из ответа и сохраните его как переменную среды. Вы будете ссылаться на него как на параметр пути account_id, параметр пути используя конструкцию {{ACCOUNT_ID}} в будущих запросах.

Операции с рабочими средами и проектами

Ваши файлы в Frame.io хранятся в папках, систематизированных в проекты внутри рабочей среды. Полный обзор иерархии ресурсов в версии V4 — в <strong>](</span)этом руководстве**.

Создание списков рабочих сред

Запрос GET list workspaces в папке Рабочие среды обращается к конечной точке /v4/accounts/:account_id/workspaces и возвращает список рабочих сред, к которым имеет доступ ваша учетная запись. Некоторые операции с проектами требуют указания workspace_id в качестве параметра пути, поэтому сначала сохраните идентификатор вашей рабочей среды, если планируете просматривать или получать проекты. Успешный запрос вернет статус 200 OK и тело ответа, аналогичное приведенному ниже примеру. Пример ответа

{
  "data": [
    {
      "account_id": "11111111-2222-3333-4444-555555555555",
      "created_at": "2024-01-25T19:18:29.614189Z",
      "id": "88888888-bbbb-4444-aaaa-ffffffffffff",
      "name": "My Workspace",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "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": "196C1A5777BF4CV00A49411B@176719f5667d82g5594324.e",
        "name": "Name"
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/workspaces"
  }
}

Создание рабочей среды

Запрос POST create workspace обращается к конечной точке /v4/accounts/:account_id/workspaces для создания новой рабочей среды в вашей учетной записи. В редакторе запросов перейдите на вкладку Тело, чтобы задать имя рабочей среды в объекте data. Успешный запрос вернет статус 201 Created и тело ответа, аналогичное приведенному ниже примеру. Пример ответа

{
  "data": {
    "account_id": "11111111-2222-3333-4444-555555555555",
    "created_at": "2024-01-25T19:18:29.614189Z",
    "id": "77777777-999-4444-8888-000000000000",
    "name": "My New Workspace",
    "updated_at": "2024-02-07T16:44:41.986478Z"
  }
}

Обновление рабочей среды

Запрос PATCH update workspace обращается к конечной точке /v4/accounts/:account_id/workspaces/:workspace_id для обновления имени рабочей среды. В редакторе запросов перейдите на вкладку Тело, чтобы задать новое имя рабочей среды в объекте data. Успешный запрос вернет статус 200 OK и тело ответа, аналогичное приведенному ниже примеру. Пример ответа

{
    "data": {
        "id": "77777777-9999-4444-8888-000000000000",
        "name": "New Workspace Name",
        "updated_at": "2026-05-01T02:42:00.462467Z",
        "account_id": "11111111-2222-3333-4444-555555555555",
        "created_at": "2025-09-22T19:17:02.565496Z"
    }
}

Создание проекта

Запрос POST create project обращается к конечной точке /v4/accounts/:account_id/workspaces/:workspace_id/projects для создания нового проекта в указанной рабочей среде. В редакторе запросов перейдите на вкладку Тело, чтобы задать имя проекта в объекте data. Дополнительное свойство restricted — логическое значение, используемое для создания проекта с ограниченным доступом. Успешный запрос вернет статус 201 Created и тело ответа, аналогичное приведенному ниже примеру. Пример ответа

{
    "data": {
        "id": "fd26defb-8bdf-5c39-9746-24d38f109cc3",
        "name": "test",
        "status": "active",
        "restricted": true,
        "updated_at": "2026-05-01T03:39:58.910884Z",
        "storage": 0,
        "workspace_id": "77777777-999-4444-8888-000000000000",
        "created_at": "2026-05-01T03:39:58.853797Z",
        "root_folder_id": "d4fca8b4-5fd8-4a94-90aa-de13de4b2021",
        "view_url": "https://next.frame.io/project/fd26defb-8bdg-5c39-9746-24d38f109cc3"
    }
}

Скопируйте значение root_folder_id из ответа и установите его в качестве значения для вашей переменной среды FOLDER_ID. Эта переменная понадобится вам в остальных разделах этого руководства.

Вы можете добавить пользователя в недавно созданный проект с ограниченным доступом с помощью последующего запроса PATCH Update user role in a Project, расположенного в папке Разрешения на уровне проекта. (Справочник по API-интерфейсу)

Операции с папками и файлами

Создание списков дочерних элементов папки

Запрос GET list folder children обращается к конечной точке /v4/accounts/:account_id/folders/:folder_id/children для создания списка дочерних элементов в указанной папке. В данном случае это корневая папка проекта, установленная в качестве переменной среды FOLDER_ID.

Вы можете использовать следующие дополнительные параметры запроса для уточнения ответа.

Параметр	Тип	Описание
`page_size`	Целое число	Ограничивает количество возвращаемых папок в диапазоне 1–100. По умолчанию — 50.
`type`	Строка	Фильтрует дочерние элементы папки по типу ресурса: `file` или `folder`.
`after`	Строка	Непрозрачный курсор для запросов, возвращающих разбитые на страницы результаты. Он создается автоматически и возвращается в объекте `links` предыдущего ответа. Не предназначен для чтения человеком.
`include_total_count`	Логический	Возвращает общее количество всех сущностей. По умолчанию — False.
`include`	Перечисление	Добавляет дополнительные данные к каждому возвращаемому объекту, такие как `creator`, `project`, `media_links`. Полный список поддерживаемых параметров — в справочнике по API-интерфейсу.

Успешный запрос вернет статус 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 для добавления локального файла в указанную папку.

Для локального добавления файлов требуется два или более запроса в зависимости от их размера. Для первого теста используйте небольшой файл (менее 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 В редакторе запросов перейдите на вкладку Тело и нажмите двоичный, чтобы выбрать файл. После выбора нажмите Отправить, чтобы выполнить свой запрос. Успешный запрос вернет статус 200 OK, подтверждающий, что файл был добавлен.

После добавления файла система обработки медиафайлов Frame.io автоматически выполнит перекодирование и создаст миниатюру. Для файлов большого размера переход из состояния created в состояние ready может занять некоторое время.

Создание файла — удаленное добавление

Запрос POST create file - remote upload обращается к конечной точке /v4/accounts/:account_id/folders/:folder_id/files/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"
  }
}