> This page is for Платформа, version Версия 4 экспериментальная. > 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. # Как работает локальное и удаленное добавление файлов В этом руководстве подробно описан весь процесс добавления файлов с использованием API-интерфейса Frame.io V4. В нем рассматриваются необработанные запросы к API-интерфейсу и ответы как для локального, так и для удаленного добавления. > **Info** > > **Ищете руководства по конкретным SDK?** Инструкции по добавлению с встроенным разделением на фрагменты, выполнением повторных попыток и отслеживанием прогресса — в [руководстве по добавлению через SDK для Python](./python-sdk-upload-guide). ## Предварительные требования Перед тем как приступить к добавлению файлов, убедитесь, что вы выполнили следующие шаги по настройке. #### Учетная запись Frame.io V4 У вас есть учетная запись Frame.io V4, управляемая через [Adobe Admin Console](https://adminconsole.adobe.com/), ИЛИ вы перевели пользователей своей учетной записи на [аутентификацию Adobe](https://help.frame.io/ru/articles/11758018-connecting-to-adobe-authentication). #### Настройка Adobe Developer Console Вы вошли в [Adobe Developer Console](https://developer.adobe.com/console) и добавили API-интерфейс Frame.io в новый или существующий проект. #### Учетные данные для аутентификации Вы создали [соответствующие учетные данные для аутентификации](https://developer.adobe.com/frameio/guides/Authentication/) в своем проекте. #### Токен доступа Вы успешно использовали эти учетные данные для создания токена доступа. ## Выбор метода добавления Существует два способа добавления файлов через API-интерфейс Frame.io: `Создать файл (локальное добавление)` и `Создать файл (удаленное добавление)`. #### Локальное добавление Используйте этот метод, если медиафайл доступен вашему приложению локально (аналогично перетаскиванию файла с рабочего стола). #### Удаленное добавление Используйте этот метод, если доступ к медиафайлу осуществляется по сети (например, в рамках интеграции с другим сервисом). В этом руководстве мы начнем с более простого случая — удаленного добавления. ## Удаленное добавление Чтобы создать файл путем удаленного добавления, выберите конечную точку **Создать файл (удаленное добавление)**. В теле запроса необходимо передать имя файла и URL-адрес его источника. > **Warning** > > В настоящее время для удаленного добавления установлено **ограничение на размер файла 50 ГБ**. Для файлов размером более 50 ГБ используйте [локальное добавление](#local-upload). ### Пример запроса ```json { "data": { "name": "my_file.jpg", "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg" } } ``` ### Пример ответа Успешный запрос вернет ответ, аналогичный приведенному ниже. ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "my_file.jpg", "status": "created", "type": "file", "file_size": 518, "updated_at": "2025-06-26T20:14:33.796116Z", "media_type": "image/jpeg", "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec", "project_id": "7e46e495-4444-4555-8649-bee4d391a997", "created_at": "2025-06-26T20:14:33.159489Z", "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e" }, "links": { "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status" } } ``` ## Локальное добавление Чтобы создать файл путем локального добавления, выберите конечную точку **Создать файл (локальное добавление)**. В теле запроса необходимо указать имя файла и его размер в байтах. ### Пример запроса ```json { "data": { "name": "my_file.jpg", "file_size": 50645990 } } ``` ### Пример ответа В случае успешного выполнения запроса создается пустой файл-заполнитель. В зависимости от размера файла тело ответа будет содержать один или несколько URL-адресов добавления `upload_urls`. В данном примере нам потребуется управлять добавлением частями. ```json { "data": { "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d", "name": "my_file.jpg", "status": "created", "type": "file", "file_size": 50645990, "updated_at": "2025-06-26T20:08:06.823170Z", "media_type": "image/jpeg", "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec", "project_id": "7e46e495-4444-4555-8649-bee4d391a997", "created_at": "2025-06-26T20:08:06.751313Z", "upload_urls": [ { "size": 16881997, "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..." }, { "size": 16881997, "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..." }, { "size": 16881996, "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..." } ], "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d" } } ``` > **Warning** > > **Важные требования к добавлению** > > Ниже приведены важные детали, которые необходимо учитывать при отправке последующих запросов на добавление. > > * Метод HTTP-запроса должен быть `PUT` > * Заголовок `x-amz-acl` должен быть обязательно включен и иметь значение private. > * Заголовок `Content-Type` должен соответствовать типу данных `media_type`, указанному в исходном запросе **Создать файл (локальное добавление)**. Это правило действует даже в том случае, если файл добавляется отдельными частями. В приведенном выше примере значением `media_type` является `image/jpeg`. Соответственно, значение `Content-Type` также должно быть `image/jpeg`. ## Добавление частями Если для определенного файла создается более одного URL-адреса добавления, необходимо разделить исходный файл на фрагменты и отправить запрос PUT для каждого из них. > **Info** > > **Рекомендация.** В [руководстве по добавлению с помощью SDK для Python](./python-sdk-upload-guide) описано добавление частями с помощью компонента `FrameioUploader`, который обеспечивает разделение на фрагменты, параллельное добавление, выполнение повторных попыток и отслеживание прогресса. Если необходимо выполнить добавление вручную (например, на языке, для которого нет готового SDK, или ради полного контроля над процессом), приведенный ниже сценарий показывает, как разбить файл на фрагменты и добавить каждый из них с использованием предварительно подписанных URL-адресов. ### Пример выполнения на Python **`Сценарий добавления частями`** ```python title="Сценарий добавления частями" import requests import math from typing import List from tqdm import tqdm # For progress bar def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool: """ Upload a file in chunks using presigned URLs. """ try: # Auto-detect content type based on file extension if content_type is None: detected_content_type, _ = mimetypes.guess_type(file_path) content_type = detected_content_type # Default fallback print(f"Detected content type: {content_type}") # Get file size with open(file_path, 'rb') as f: f.seek(0, 2) # Seek to end of file file_size = f.tell() # Calculate chunk size if not provided if chunk_size is None: chunk_size = math.ceil(file_size / len(upload_urls)) print(f"File size: {file_size} bytes") print(f"Chunk size: {chunk_size} bytes") print(f"Number of chunks: {len(upload_urls)}") # Upload each chunk with open(file_path, 'rb') as f: with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar: for i, url in enumerate(upload_urls): start_byte = i * chunk_size end_byte = min(start_byte + chunk_size, file_size) # Read chunk from file f.seek(start_byte) chunk = f.read(end_byte - start_byte) print(f"Uploading chunk {i+1}: {len(chunk)} bytes") # Upload chunk with minimal headers matching the signature response = requests.put( url, data=chunk, headers={ 'content-type': content_type, 'x-amz-acl': 'private' } ) if response.status_code != 200: print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}") print(f"Response text: {response.text}") print(f"Response headers: {dict(response.headers)}") return False else: print(f"Chunk {i+1} uploaded successfully!") pbar.update(1) return True except Exception as e: print(f"Error during upload: {str(e)}") return False # Example usage if __name__ == "__main__": # Replace these with your actual values file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file upload_urls = [ "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...", "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...", "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..." ] content_type = "image/jpeg" print("Starting file upload...") success = upload_file_in_chunks(file_path, upload_urls, content_type) if success: print("File upload completed successfully!") else: print("File upload failed!") ``` ## Сводка процесса добавления #### Выбор метода добавления Выберите между удаленным добавлением (файл доступен по URL-адресу) или локальным добавлением (файл находится в вашей системе). #### Запрос на создание файла Выполните первичный запрос, чтобы создать ресурс для файла с необходимыми метаданными. #### Обработка URL-адресов добавления В случае локального добавления обработайте возвращенные URL-адреса (для одной или нескольких частей). #### Добавление содержимого файла Используйте запросы PUT с соответствующими заголовками для отправки содержимого файла по предоставленным URL-адресам. #### Подтверждение добавления Проверьте статус файла, чтобы подтвердить успешное завершение добавления и обработки. > **Info** > > **Следующие шаги**. Как только ваш файл будет добавлен, вы сможете использовать полученный идентификатор файла, чтобы оставлять комментарии, создавать общие ресурсы или выполнять другие операции, используя API-интерфейс Frame.io V4.