> This page is for Платформа, version Предыдущая версия. > 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. Frame.io может работать со всеми типами файлов, не только с видео, но также со сценариями, изображениями, картами и справочными файлами. Говоря техническим языком, ресурс в Frame.io — это детальное представление файла в S3 и его контекста в Frame.io, включая перекодировки, контекст пользователя/команды/проекта и метаданные. Дополнительные сведения о ресурсах см. в определении ресурса.​ ## Основные иерархии Также полезно знать, как Frame.io структурирует свои основные модели. **Учетные записи**, к которым принадлежат **Пользователи**, имеют множество **Проектов**, которые содержат **Ресурсы**. **Команды** доступны только для корпоративных учетных записей и обеспечивают дополнительный уровень логического разделения. Ресурсы не «знают», какой команде они принадлежат — только какому проекту и учетной записи — но проекты строго принадлежат командам, а не учетным записям, что делает команды неотъемлемой частью процесса добавления ресурсов. ## Требования Для работы с этим руководством понадобится: * Учетная запись Frame.io с токеном разработчика (токены объясняются ниже). * [SDK для Python в Frame.io](https://github.com/Frameio/python-frameio-client) ## Добавление ресурса Этот раздел пошагово описывает процесс добавления ресурса. 1. Создайте токен разработчика на [developer.frame.io](/) со следующими областями доступа: | Область доступа | Причина | | ---------- | ---------- | | **Учетные записи:** чтение | Получение списка учетных записей для запрашивающего пользователя. | | **Команды:** чтение | Получение доступных команд для нужной учетной записи. | | **Проекты:** чтение | Получение доступных проектов для нужной команды. | | **Ресурсы:** создание, чтение | Создание новой записи ресурса и получение доступных ресурсов для навигации по структуре папок в проекте. | Ознакомьтесь с инструкциями [**здесь**](doc:get-a-developer-token). 2. Найдите место назначения для вашего ресурса. Как минимум, ресурсы должны быть размещены в **проекте**. Вам необходимо получить идентификатор корневого ресурса (`root_asset_id`) для проекта или идентификатор ресурса для папки, чтобы указать местоположение в иерархии файлов, куда вы хотите добавить. Вы не можете добавлять, используя только идентификатор проекта. Для добавления в корень вашего проекта укажите `root_asset_id` в вашем запросе. Вам необходимо получить (в указанном порядке): * идентификаторы учетных записей и выбор учетной записи; * идентификаторы команд и выбор команды; * проекты, связанные с командой; * идентификатор проекта для проекта, с которым вы хотите работать; * идентификатор корневого ресурса или идентификатор папки. Можно добавить файлы непосредственно в корень проекта, используя `root_asset_id`. ### Список ресурсов Чтобы выбрать, куда добавить новый ресурс, можно использовать API-интерфейс для перечисления всех ресурсов в проекте или папке внутри проекта. Если ресурс является *папкой*, он содержит дочерние ресурсы, которые также могут быть файлами и папками. При перечислении информации о ресурсах можно использовать любой идентификатор ресурса, но если хотите просмотреть все, что связано с проектом, используйте `root_asset_id`. ``` ``` python-sdk from frameioclient import FrameioClient import os ASSET_ID = "" TOKEN = "" client = FrameioClient(TOKEN) response_list = client.assets.get_children(ASSET_ID) assets = response_list.results for item in assets: print(item['id'], item['name']) ``` ``` ```python-sdk # Code sample uses the Python SDK: https://github.com/Frameio/python-frameio-client from frameioclient import FrameioClient client = frameioclient("FRAMEIO_TOKEN) asset = client.assets.upload( destination_id="PARENT_ASSET_ID", filepath="./my_file.mov" ) # Create a folder: asset = client.assets.create_folder( parent_asset_id=PARENT_ASSET_ID, name="My Awesome Folder" ) ``` Из возвращенного списка ресурсов можно использовать идентификатор любого ресурса, который является папкой, или идентификатор корневого ресурса. Этот идентификатор вы будете использовать, чтобы отметить, куда хотите добавить ваш новый ресурс. ### Добавить ресурс В этом примере мы собираемся добавить новый файл. Отправьте запрос со следующей информацией: | Параметр | Описание | | ---------- | ---------- | | `filesize` | Введите размер файла для добавления | | `filetype` | Выберите тип добавляемого файла. Варианты включают видео и изображение. Примеры: `video/mp4`, `image/png`. | | `имя` | Введите строку, представляющую имя файла, без пробелов. | | `тип` | Это указывает, используете ли вы `файл` или `папку`. Стек версий — это наложение нескольких файлов друг на друга. | Чтобы создать новую папку, вам не нужно включать `filesize` или `filetype` в ваш запрос. Для запроса `cURL` можно быстро добавить ресурс в Frame.io, включив ссылку на ваш файл с помощью параметра `"source": { "url":"URL_FOR_VIDEO" }`. Ссылка должна быть общедоступной. В противном случае можно использовать SDK для Python, который автоматически разбивает ваш файл на фрагменты для каждой ссылки добавления. ```cURL curl --request POST \ --url https://api.frame.io/v2/assets/<asset_id>/children \ --header 'authorization: Bearer<dev_token>' \ --header 'content-type: application/json' \ --data '{"filesize":200000,"filetype":"video/mp4","name":"test","source":{"url":"URL_FOR_VIDEO"},"type":"file"}' ``` **`Python`** ```python title="Python" filesize = 30000000 upload_urls = ["https://...", "https://...", "https://..."] chunk_size = filesize / len(upload_urls) start_byte = 0 # Set to 0 to start for i, url in enumerate(upload_urls): end_byte = chunk_size * (i + 1) upload_chunk(url=url, start_byte, end_byte) start_byte = start_byte + chunk_size ``` URL-адреса, полученные в ответ на вызов API-интерфейса для создания ресурсов, являются предварительно подписанными для авторизации добавления, но их срок действия истекает через 24 часа. # Создание собственного средства для добавления файлов Чтобы создать собственное средство добавления, для лучшей производительности рекомендуется добавлять фрагменты параллельно. Каждый фрагмент следует передавать методом `PUT` напрямую по URL-адресам Amazon S3, предоставленным в ответе от API-интерфейса Frame.io. Фрагменты вашего файла должны соответствовать порядку предоставленных `upload_urls`, поскольку они *диктуют последовательность итогового объединенного и перекодированного ресурса*. Это означает, что 1-й URL-адрес принимает 1-й фрагмент, 2-й URL-адрес принимает 2-й фрагмент и так далее. #### Пример псевдокода **`title="Python"`** ```python title="Python" filesize = 30000000 upload_urls = ["https://...", "https://...", "https://..."] chunk_size = filesize / len(upload_urls) start_byte = 0 # Задайте 0 для начала for i, url in enumerate(upload_urls): end_byte = chunk_size * (i + 1) upload_chunk(url=url, start_byte, end_byte) start_byte = start_byte + chunk_size ``` Заголовки для каждого запроса к S3 должны включать `filetype` вашего нового ресурса точно так, как он был возвращен из первоначального вызова к API-интерфейсу Frame.io, а также дополнительный заголовок конфиденциальности: ```text PUT https://frameio-uploads-production.s3/etc/etc Content-Type: video/mp4 x-amz-acl: private ``` Вы можете посмотреть пример того, как все это обрабатывается в нашем SDK для Python [здесь](https://github.com/Frameio/python-frameio-client/blob/master/examples/upload_asset.py). Обратите внимание, что все ошибки, которые вы получаете на данном этапе, поступают непосредственно от AWS и поэтому будут отформатированы как XML, а не в стандартной обработке ошибок JSON Frame.io. Мы обычно рекомендуем создавать логику повторных попыток для этих операций добавления при любом рабочем использовании, поскольку не полностью добавленные файлы (например, файлы с отсутствующими фрагментами) не смогут быть перекодированы и отображены в Frame.io/ Вот и все! После завершения вызовов `PUT` к `upload_url`s у вас будет новый ресурс в Frame.io.