> This page is for Piattaforma, version Versione precedente. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: 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. # Caricamento delle risorse # Panoramica Questa esercitazione spiega come caricare le risorse in Frame.io. Frame.io gestisce tutti i tipi di file, non solo video, ma anche script, immagini, mappe e file di riferimento. In termini più tecnici, una risorsa in Frame.io è una rappresentazione completa di un file in S3 e del relativo contesto in Frame.io, inclusi transcodifiche, contesto di utente/team/progetto e metadati. Per ulteriori informazioni sulle risorse, consulta la rispettiva definizione.​ ## Gerarchie principali È utile anche sapere in che modo Frame.io struttura i suoi modelli principali. Gli **account**, ai quali appartengono gli **utenti**, hanno molti **progetti** che contengono **risorse**. I **team** sono disponibili solo per gli account Enterprise e forniscono un livello aggiuntivo di separazione logica. Le risorse non "sanno" a quale team appartengono, ma solo a quale progetto e account. I progetti, però, sono di proprietà esclusiva dei team e non degli account, di conseguenza i team sono parte integrante del processo di caricamento delle risorse. ## Prerequisiti Per questa esercitazione ti serve: * Un account Frame.io con un token per sviluppatori (i token sono spiegati di seguito) * [SDK Python di Frame.io](https://github.com/Frameio/python-frameio-client) ## Carica una risorsa Questa sezione illustra i passaggi per caricare una risorsa. 1. Crea un token per sviluppatori in [developer.frame.io](/) con i seguenti ambiti: | Ambito | Motivo | | ---------- | ---------- | | **Account:** lettura | Recupera l'elenco di account per l'utente richiedente. | | **Team:** lettura | Recupera i team disponibili per l'account desiderato. | | **Progetti:** lettura | Recupera i progetti disponibili per il team desiderato. | | **Risorse:** creazione, lettura | Crea il nuovo record di risorsa e recupera le risorse disponibili nella struttura delle cartelle all'interno del progetto. | Consulta le istruzioni [**qui**](doc:get-a-developer-token). 2. Individua una destinazione per la risorsa. Come minimo, le risorse devono essere inserite all'interno di un **progetto**. Devi recuperare l'ID della risorsa radice (`root_asset_id`) per un progetto o l'ID di una risorsa per una cartella per specificare la posizione nella gerarchia dei file in cui vuoi caricare. Non puoi eseguire il caricamento usando solo l'ID del progetto. Per eseguire il caricamento nella root del progetto, specifica il `root_asset_id` nella richiesta. In generale, devi recuperare (nell'ordine specificato): * ID account e scegliere un account * ID team e scegliere un team * Progetti associati a un team * ID del progetto su cui lavorare * ID della risorsa root o ID di una cartella Puoi eseguire il caricamento direttamente nella root di un progetto usando il `root_asset_id`. ### Elenca le risorse Per scegliere dove caricare la nuova risorsa, puoi usare l'API in modo da elencare tutte le risorse in un progetto o in una cartella all'interno di un progetto. Se una risorsa è una *cartella*, conterrà risorse figlio che possono essere file e cartelle. Quando elenchi le informazioni delle risorse, puoi usare qualsiasi ID risorsa, ma se vuoi rivedere tutto ciò che è associato a un progetto, usa il `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" ) ``` Dall'elenco restituito delle risorse, puoi usare un ID per qualsiasi risorsa che sia una cartella oppure l'ID della risorsa root. Userai questo ID per contrassegnare dove vuoi caricare la nuova risorsa. ### Carica la risorsa In questo esempio, caricheremo un nuovo file. Devi inviare la richiesta con le seguenti informazioni: | Parametro | Descrizione | | ---------- | ---------- | | `filesize` | Inserisci la dimensione del file che desideri caricare | | `filetype` | Scegli il tipo di file che stai caricando. Le opzioni includono video e immagine. Esempi: `video/mp4`, `image/png`. | | `name` | Inserisci una stringa che rappresenti il nome del file, senza spazi. | | `type` | Indica se stai utilizzando un `file` o una cartella (`folder`). Viene creato uno stack di versioni quando si sovrappongono diversi file. | Per una nuova cartella, non devi includere `filesize` o `filetype` nella richiesta. Per una richiesta `cURL`, puoi caricare rapidamente una risorsa in Frame.io includendo un link al file utilizzando il parametro `"source": { "url":"URL_FOR_VIDEO" }`. Il link deve essere accessibile pubblicamente. In alternativa, puoi utilizzare l'SDK Python, che gestisce automaticamente la suddivisione del file in un chunk per ogni link di caricamento. ```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 ``` Gli URL restituiti dalla chiamata API per la creazione delle risorse sono pre-firmati in modo da autorizzare il caricamento, ma scadono dopo 24 ore. # Crea il tuo programma di caricamento dei file Se vuoi creare un programma di caricamento personalizzato, si consiglia di caricare i chunk in parallelo per avere delle prestazioni ottimali. Ogni chunk deve essere inserito (`PUT`) direttamente negli URL di Amazon S3 forniti nella risposta dall'API di Frame.io. I chunk dei file devono corrispondere all'ordine di `upload_url` forniti, poiché *determinano la sequenza della risorsa finale concatenata e transcodificata.* Questo significa che il primo URL prende il primo chunk, il secondo URL prende il secondo chunk e così via. #### Esempio di pseudocodice **`title="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 ``` Le intestazioni per ogni richiesta a S3 devono includere il `filetype` della nuova risorsa esattamente come è stato restituito dalla chiamata iniziale all'API Frame.io, oltre a un'intestazione di privacy aggiuntiva: ```text PUT https://frameio-uploads-production.s3/etc/etc Content-Type: video/mp4 x-amz-acl: private ``` Puoi vedere un esempio di come tutto questo viene gestito nel nostro SDK Python [qui](https://github.com/Frameio/python-frameio-client/blob/master/examples/upload_asset.py). Tieni presente che eventuali errori che ricevi in questa fase arriveranno direttamente da AWS e, pertanto, saranno formattati come XML, non secondo la gestione standard degli errori JSON di Frame.io. In generale, consigliamo di creare logiche di nuovi tentativi di questi caricamenti per qualsiasi utilizzo in produzione, poiché i file caricati in modo incompleto (ossia file con chunk mancanti) non riescono a essere transcodificati e visualizzati in Frame.io Ecco fatto! Una volta completate le chiamate `PUT` agli `upload_url, avrai una nuova risorsa in Frame.io.