> This page is for Plate-forme, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 expérimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Hérité: 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. # Fonctionnement des chargements locaux et distants Ce guide décrit en détail la procédure complète pour charger des fichiers à l’aide de l’API Frame.io V4. Il couvre les requêtes et les réponses brutes de l’API pour les chargements locaux et à distance. > **Info** > > **Vous recherchez des guides spécifiques au SDK ?** Pour les implémentations de chargement intégrant le fractionnement en blocs, les tentatives et le suivi de la progression, consultez le [Guide de chargement du SDK Python](./python-sdk-upload-guide). ## Conditions préalables Avant de commencer à charger des fichiers, assurez-vous d’avoir suivi toutes les étapes de configuration suivantes : #### Compte Frame.io V4 Vous disposez d’un compte Frame.io V4 géré via l’[Adobe Admin Console](https://adminconsole.adobe.com/) OU [vous êtes passé à l’authentification Adobe](https://help.frame.io/fr/articles/11758018-connecting-to-adobe-authentication) pour votre compte utilisateur. #### Configuration de l’Adobe Developer Console Vous vous êtes connecté à l’[Adobe Developer Console](https://developer.adobe.com/console) et avez ajouté l’API Frame.io à un projet nouveau ou existant. #### Informations d’authentification Vous avez généré les [informations d’authentification appropriées](https://developer.adobe.com/frameio/guides/Authentication/) pour votre projet. #### Jeton d’accès Vous avez utilisé ces identifiants avec succès pour générer un jeton d’accès. ## Choix de votre méthode de chargement Il existe deux façons de charger un fichier à l’aide de l’API Frame.io : `Créer un fichier (chargement local)` et `Créer un fichier (chargement à distance)`. #### Chargement local À utiliser lorsque le contenu est accessible localement depuis votre application, comme lorsque vous faites glisser un fichier depuis votre bureau. #### Chargement à distance À utiliser lorsque le contenu est accessible via le réseau, par exemple dans le cadre d’une intégration avec un autre service. Dans ce guide, nous commencerons par le cas le plus simple : un chargement à distance. ## Chargement à distance Pour créer un fichier via un chargement à distance, sélectionnez le point d’entrée **Créer un fichier (chargement à distance)**. Le corps de la requête doit contenir le nom du fichier et son URL source. > **Warning** > > Il est actuellement possible de **charger jusqu’à 50 Go** via le chargement à distance. Pour les fichiers de plus de 50 Go, veuillez utiliser le [chargement local](#local-upload). ### Exemple de requête ```json { "data": { "name": "my_file.jpg", "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg" } } ``` ### Exemple de réponse Une requête réussie donnera lieu à une réponse semblable à celle ci-dessous : ```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" } } ``` ## Chargement local Pour créer un fichier via un chargement local, sélectionnez le point d’entrée **Créer un fichier (chargement local)**. Le corps de la requête doit comporter le nom du fichier et sa taille en octets. ### Exemple de requête ```json { "data": { "name": "my_file.jpg", "file_size": 50645990 } } ``` ### Exemple de réponse Si la requête aboutit, un espace réservé de ressource de fichier est créé, sans aucun contenu. En fonction de la taille du fichier, le corps de la réponse comprendra une ou plusieurs `upload_urls`. Compte tenu de cet exemple, nous devrons gérer ce chargement en plusieurs parties. ```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** > > **Conditions importantes relatives au chargement :** > > Voici quelques points importants à garder à l’esprit lorsque vous envoyez la ou les requêtes de chargement suivantes : > > * La méthode de requête HTTP doit être `PUT`. > * L’en-tête `x-amz-acl` doit être inclus et défini sur « private ». > * L’en-tête `Content-Type` doit correspondre au `media_type` spécifié dans la requête **Créer un fichier (chargement local)** originale. Cela vaut également lorsque vous chargez le fichier en plusieurs parties. Dans l’exemple ci-dessus, la valeur de `media_type` est `image/jpeg`. Par conséquent, la valeur de `Content-Type` doit également être `image/jpeg`. ## Chargement en plusieurs parties Lorsqu’un fichier donné génère plusieurs URL de chargement, vous devez diviser le fichier source en plusieurs blocs et envoyer une requête PUT pour chacun d’entre eux. > **Info** > > **Recommandation :** le [Guide de chargement du SDK Python](./python-sdk-upload-guide) traite du chargement en plusieurs parties à l’aide de `FrameioUploader`, qui gère d’emblée le fractionnement en blocs, les chargements parallèles, les nouvelles tentatives et le suivi de la progression. Si vous devez effectuer le chargement manuellement (par exemple, dans une langue pour laquelle il n’existe pas de SDK ou pour bénéficier d’un contrôle total sur le processus), le script ci-dessous vous montre comment fractionner un fichier en blocs et charger chacun d’entre eux à l’aide d’URL pré-signées. ### Exemple d’implémentation en Python **`Script de chargement en plusieurs parties`** ```python title="Script de chargement en plusieurs parties" 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!") ``` ## Résumé du flux de chargement #### Choisir la méthode de chargement Choisissez entre le chargement à distance (fichier accessible via une URL) ou le chargement local (fichier stocké sur votre système). #### Créer une requête de fichier Effectuez la requête initiale de création de la ressource de fichier avec les métadonnées requises. #### Gérer les URL de chargement Pour les chargements locaux, traitez les uploard\_urls renvoyées (en une ou plusieurs parties). #### Charger le contenu du fichier Utilisez des requêtes PUT avec les en-têtes appropriés pour charger le contenu des fichiers vers les URL indiquées. #### Vérifier le chargement Vérifiez le statut du fichier pour vous assurer qu’il a bien été chargé et que le traitement s’est bien déroulé. > **Info** > > **Étapes suivantes** : une fois votre fichier chargé, vous pouvez utiliser l’identifiant du fichier fourni pour ajouter des commentaires, créer des partages ou effectuer d’autres opérations à l’aide de l’API Frame.io V4.