Come funzionano i caricamenti locali e remoti

Questa guida illustra nel dettaglio l’intero flusso per caricare file utilizzando l’API Frame.io V4. Copre richieste e risposte API non elaborate per i caricamenti locali e remoti.

Cerchi guide specifiche per gli SDK? Per implementare caricamenti con funzioni integrate di suddivisione in chunk, nuovi tentativi e tracciamento dello stato di avanzamento, consulta la guida al caricamento dell’SDK Python.

Prerequisiti

Prima di iniziare a caricare i file, assicurati di aver completato questi passaggi di configurazione:

1

Account Frame.io V4

Hai un account Frame.io V4 amministrato tramite Adobe Admin Console, OPPURE sei passato all’autenticazione Adobe per l’utente dell’account

2

Configurazione di Adobe Developer Console

Hai effettuato l’accesso ad Adobe Developer Console e hai aggiunto l’API Frame.io a un progetto nuovo o esistente

3

Credenziali di autenticazione

Hai generato le credenziali di autenticazione appropriate per il tuo progetto

4

Token di accesso

Hai utilizzato con successo quelle credenziali per generare un token di accesso

Scelta del metodo di caricamento

Esistono due modi per caricare un file utilizzando l’API Frame.io: Create File (local upload) e Create File (remote upload).

Caricamento locale

Da utilizzare quando i media sono accessibili localmente alla tua applicazione; è simile al trascinamento di un file dal desktop

Caricamento remoto

Da utilizzare quando i media sono accessibili tramite rete, ad esempio attraverso un’integrazione con un altro servizio

In questa guida inizieremo con il caso più semplice del completamento di un caricamento remoto.

Caricamento remoto

Per creare un file tramite caricamento remoto, seleziona l’endpointCreate File (remote upload). Il corpo della richiesta richiede il nome del file e il suo URL di origine.

Il caricamento remoto ha attualmente un limite di dimensione del file di 50 GB. Per file più grandi di 50 GB, utilizza il caricamento locale.

Esempio di richiesta

1{
2 "data": {
3 "name": "my_file.jpg",
4 "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
5 }
6}

Esempio di risposta

Una richiesta riuscita restituirà una risposta come quella di seguito:

1{
2 "data": {
3 "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 518,
8 "updated_at": "2025-06-26T20:14:33.796116Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:14:33.159489Z",
13 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e"
14 },
15 "links": {
16 "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status"
17 }
18}

Caricamento locale

Per creare un file tramite caricamento locale, seleziona l’endpointCreate File (local upload). Il corpo della richiesta richiede il nome del file e la sua dimensione specificata in byte.

Esempio di richiesta

1{
2 "data": {
3 "name": "my_file.jpg",
4 "file_size": 50645990
5 }
6}

Esempio di risposta

Se la richiesta riesce, viene creata una risorsa di file segnaposto senza contenuto. In base alla dimensione del file, il corpo della risposta includerà uno o più upload_url. In base a questo esempio, dovremo gestire il caricamento in più parti.

1{
2 "data": {
3 "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 50645990,
8 "updated_at": "2025-06-26T20:08:06.823170Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:08:06.751313Z",
13 "upload_urls": [
14 {
15 "size": 16881997,
16 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
17 },
18 {
19 "size": 16881997,
20 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
21 },
22 {
23 "size": 16881996,
24 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
25 }
26 ],
27 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
28 }
29}

Requisiti di caricamento importanti:

Questi sono alcuni dettagli importanti da tenere presenti quando invii le successive richieste di caricamento:

  • Il metodo di richiesta HTTP deve essere PUT
  • L’intestazione x-amz-acl deve essere inclusa e impostata su private
  • L’intestazione Content-Type deve corrispondere al media_type specificato nella richiesta Create File (local upload) originale. Questo vale anche durante il caricamento del file come parti separate. Nell’esempio precedente, il valore per media_type è image/jpeg. Pertanto, anche il valore per Content-Type deve essere image/jpeg.

Caricamento multi-parte

Quando un determinato file restituisce più di un URL di caricamento, occorre dividere il file di origine in chunk e inviare una richiesta PUT per ciascuno.

Consigliato: la guida al caricamento dell’SDK Python tratta il caricamento multi-parte usando FrameioUploader, che gestisce automaticamente la suddivisione in chunk, i caricamenti paralleli, i nuovi tentativi e il tracciamento dello stato di avanzamento.

Se devi implementare il caricamento manualmente, ad esempio in un linguaggio senza SDK o per il controllo completo del processo, lo script in basso mostra come dividere un file in chunk e come caricare ciascuno usando gli URL pre-firmati.

Esempio di implementazione Python

Script di caricamento multi-parte
1import requests
2import math
3from typing import List
4from tqdm import tqdm # For progress bar
5
6def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
7 """
8 Upload a file in chunks using presigned URLs.
9 """
10 try:
11 # Auto-detect content type based on file extension
12 if content_type is None:
13 detected_content_type, _ = mimetypes.guess_type(file_path)
14 content_type = detected_content_type # Default fallback
15
16 print(f"Detected content type: {content_type}")
17
18 # Get file size
19 with open(file_path, 'rb') as f:
20 f.seek(0, 2) # Seek to end of file
21 file_size = f.tell()
22
23 # Calculate chunk size if not provided
24 if chunk_size is None:
25 chunk_size = math.ceil(file_size / len(upload_urls))
26
27 print(f"File size: {file_size} bytes")
28 print(f"Chunk size: {chunk_size} bytes")
29 print(f"Number of chunks: {len(upload_urls)}")
30
31 # Upload each chunk
32 with open(file_path, 'rb') as f:
33 with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
34 for i, url in enumerate(upload_urls):
35 start_byte = i * chunk_size
36 end_byte = min(start_byte + chunk_size, file_size)
37
38 # Read chunk from file
39 f.seek(start_byte)
40 chunk = f.read(end_byte - start_byte)
41
42 print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
43
44 # Upload chunk with minimal headers matching the signature
45 response = requests.put(
46 url,
47 data=chunk,
48 headers={
49 'content-type': content_type,
50 'x-amz-acl': 'private'
51 }
52 )
53
54 if response.status_code != 200:
55 print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
56 print(f"Response text: {response.text}")
57 print(f"Response headers: {dict(response.headers)}")
58 return False
59 else:
60 print(f"Chunk {i+1} uploaded successfully!")
61
62 pbar.update(1)
63
64 return True
65
66 except Exception as e:
67 print(f"Error during upload: {str(e)}")
68 return False
69
70# Example usage
71if __name__ == "__main__":
72 # Replace these with your actual values
73 file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
74 upload_urls = [
75 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
76 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
77 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
78 ]
79 content_type = "image/jpeg"
80
81 print("Starting file upload...")
82 success = upload_file_in_chunks(file_path, upload_urls, content_type)
83
84 if success:
85 print("File upload completed successfully!")
86 else:
87 print("File upload failed!")

Riepilogo del flusso caricamento

1

Scegli il metodo di caricamento

Decidi tra caricamento remoto (file accessibile tramite URL) o caricamento locale (file sul sistema)

2

Crea una richiesta di file

Effettua la richiesta iniziale per creare la risorsa di file con i metadati necessari

3

Gestisci l'URL di caricamento

Per i caricamenti locali, elabora gli upload_url restituiti (singola parte o multi-parte)

4

Carica il contenuto del file

Usa richieste PUT con le intestazioni appropriate per caricare il contenuto del file sugli URL forniti

5

Verifica il caricamento

Controlla lo stato del file per confermare che il caricamento e l’elaborazione siano riusciti

Passaggi successivi: una volta caricato il file, puoi usare l’ID file restituito per aggiungere commenti, creare condivisioni o eseguire altre operazioni usando l’API Frame.io V4.