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.

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.

Conditions préalables

Avant de commencer à charger des fichiers, assurez-vous d’avoir suivi toutes les étapes de configuration suivantes :

1

Compte Frame.io V4

Vous disposez d’un compte Frame.io V4 géré via l’Adobe Admin Console OU vous êtes passé à l’authentification Adobe pour votre compte utilisateur.

2

Configuration de l’Adobe Developer Console

Vous vous êtes connecté à l’Adobe Developer Console et avez ajouté l’API Frame.io à un projet nouveau ou existant.

3

Informations d’authentification

Vous avez généré les informations d’authentification appropriées pour votre projet.

4

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.

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.

Exemple de requête

{
"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 :

{
"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

{
"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.

{
"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"
}
}

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.

Recommandation : le Guide de chargement du SDK Python 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
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

1

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).

2

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.

3

Gérer les URL de chargement

Pour les chargements locaux, traitez les uploard_urls renvoyées (en une ou plusieurs parties).

4

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.

5

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é.

É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.