> This page is for Piattaforma, version V4 (default). > 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. # Raccolta Postman Questa guida illustra le nozioni di base della raccolta Postman ufficiale per l'API Frame.io Developer, un insieme di richieste precostruite che puoi utilizzare per iniziare con l'API Frame.io V4. La raccolta copre l'intera gamma di endpoint dell'API V4, suddivisi in categorie stabili e sperimentali. Gli endpoint stabili sono pronti per la produzione, mentre quelli sperimentali sono stati aggiunti recentemente e funzionano, ma potrebbero cambiare in base al feedback prima di essere promossi a stabili. ## Guida introduttiva a Postman > **Tip** > > Questa guida presuppone che tu abbia generato le credenziali per l'API. Se non l'hai ancora fatto, vai [qui](/platform/docs/quick-start) #### Crea un account Postman e scegli la configurazione Crea il tuo account Postman su [postman.com](http://auth.postman.com/__redirect/login) e scegli la configurazione. Puoi scaricare l'app Postman [qui](https://www.postman.com/downloads/) o utilizzare Postman sul web. #### Importa la raccolta Postman dell'API Frame.io Developer #### [Raccolta dell'API Frame.io Developer](https://www.postman.com/adobe/workspace/frame-io-v4-public-api/collection/33150877-924315f2-cc62-45f5-8153-77ff2aaa9067?action=share\&creator=33150877\&active-environment=33150877-cffd66a8-23bd-4c50-8891-29157ead1185) Crea un fork o scarica qui ### Configurazione dell'ambiente La raccolta dell'API Frame.io Developer ha un environment con una serie di variabili d'ambiente definite. I valori `BASE_URL` e `IMS_BASE_URL` sono statici. È possibile configurare altre variabili d'ambiente in base alle informazioni del tuo account. ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp) ![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) Di seguito è riportata una tabella con la descrizione di ogni variabile presente negli ambienti predefiniti e temporanei della raccolta: | Variabile | Descrizione | Modalità di recupero | Ambiente | | ------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------- | | `URL_BASE` | URL di base per tutte le richieste dell'API V4 | Preconfigurata, non modificare | Predefinito | | `URL_BASE_IMS` | URL di base per l'autenticazione Adobe IMS | Preconfigurata, non modificare | Predefinito, temporaneo | | `IMS_CLIENT_ID` | ID client della tua app Frame.io | Pagina delle credenziali in **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Temporaneo | | `IMS_CLIENT_SECRET` | Secret del client della tua app Frame.io | Pagina delle credenziali in **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Temporaneo | | `FOLDER_ID` | ID univoco della cartella di destinazione | Restituita nell'oggetto di risposta della cartella | Predefinito | | `WEBHOOK_ID` | ID univoco di un webhook configurato | Restituita nell'oggetto di risposta del webhook | Predefinito | | `ASSET_ID` | ID univoco di una risorsa file o cartella | Restituita nell'oggetto di risposta del file o della cartella | Predefinito | | `SHARE_ID` | ID univoco di un link di condivisione | Restituita nell'oggetto di risposta della condivisione | Predefinito | --- ### Impostazione dell'autorizzazione > **Tip** > > [ Questa Guida utilizza OAuth 2.0 per l'autenticazione con l'API V4 di Frame.io. Per informazioni su altri metodi di autenticazione, come Server-to-Server (S2S), consulta la ](\Get New Access Token\*\* (Ottieni nuovo token di accesso) per avviare il flusso OAuth 2.0. Si aprirà una finestra del browser per completare il processo di autenticazione e restituire il token a Postman. Per verificare la configurazione dell'autorizzazione, seleziona la richiesta **`GET user details`** (Recupera dettagli utente) nella cartella Users e fai clic su **Send** (Invia). Una risposta **`200 OK`** conferma sia che la raccolta è configurata correttamente sia che ti sei autenticato sull'account corretto. Se riscontri un errore, consulta \*\*\*\*]\(\ **Tip** > > Se hai più account Frame.io, ognuno apparirà come oggetto separato nella risposta Una volta ottenuto l'ID account, copia il valore dell'`id` dalla risposta e salvalo come variabile d'ambiente. Devi farvi riferimento come parametro di percorso `account_id` parametro di percorso utilizzando `{{ACCOUNT_ID}}` nelle richieste future. --- ## Operazioni su aree di lavoro e progetti I file Frame.io sono archiviati in cartelle, organizzate in progetti all'interno delle aree di lavoro. Per una panoramica completa della gerarchia delle risorse V4, consulta \**]\(\ **Tip** > > Puoi aggiungere un utente a un progetto limitato appena creato con una successiva richiesta **`PATCH Update user role in a Project`** che si trova nella cartella **Project Permissions**. (**[Riferimento API](/platform/docs/guides/postman-collection)**) --- ## Operazioni su cartelle e file ### Elenco degli elementi figlio della cartella La richiesta **`GET list folder children`** chiama **[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)** per visualizzare gli elementi figlio in una cartella specifica. In questo caso, la cartella principale del progetto impostata come variabile di ambiente **`FOLDER_ID`**. Puoi utilizzare i seguenti parametri di richiesta opzionali per perfezionare la risposta: | Parametro | Tipo | Descrizione | | ------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`page_size`** | Numero intero | Limita il numero di cartelle restituite: **1-100. Valore predefinito: 50** | | **`type`** | Stringa | Filtra gli elementi figlio delle cartelle per tipo di risorsa: **`file`** o **`folder`** | | **`after`** | Stringa | Cursore opaco per le richieste che restituiscono risultati impaginati. **Viene generato automaticamente e restituito nell'oggetto `links` della risposta precedente.** Non è destinato a essere leggibile. | | **`include_total_count`** | Booleano | Restituisce il numero totale di tutte le entità **Valore predefinito: false** | | **`include`** | Enum | Aggiunge dati aggiuntivi a ogni oggetto restituito, ad esempio `creator`, `project`, `media_links`. Per un elenco completo dei parametri supportati, consulta il **[Riferimento API](/platform/api-reference/folders/index#request.query.include)** | Una richiesta riuscita restituirà uno stato **`200 OK`** e un corpo della risposta simile all'esempio seguente. **Risposta di esempio** ``` { "data": [ { "type": "file", "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "media_type": "image/png", "name": "asset.png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "creator": { "active": true, "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "email": "user_email@example.com", "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e", "name": "Jon Doe" }, "media_links": { "high_quality": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN" }, "original": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "inline_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=inline%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragSDFXDFh&1Key-Pair-Id=KKI497NESTHMN" }, "thumbnail": { "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "url": "https://picture2.frame.io/image/s3://frameio-assets-development/image/cd58cb8e-24b3-4498-8d0f-9532fcd04d11/image_full.png?alg=HS256&sig=0_u7w_wz2MwQHOXp000ibbQSMRijujyaUu8V3YYPxu4&exp=1729857600" } }, "metadata": [ { "field_type": "select", "field_definition_id": "b859ccec-9536-4bf2-bc6f-5e9206e26606", "field_definition_name": "Fields definition name", "mutable": true, "value": [ { "display_name": "Display name", "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8" } ], "field_options": [ { "display_name": "Display name", "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8" }, { "display_name": "Display name 2", "id": "c6eb873f-125b-4317-b857-1a22eb3dbf22" } ] } ], "project": { "created_at": "2024-01-25T19:18:29.614189Z", "description": "Project Description", "id": "e0e30b1d-c3aa-44ee-926e-c6c326fb10dc", "name": "My Project", "root_folder_id": "be733511-6f15-4d97-8ee7-bc23b2fb0bd7", "status": "active", "storage": 15000, "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/", "workspace_id": "91b10e83-5874-44de-9b57-41c937b87256", "owner": { "active": true, "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN", "email": "user_email@example.com", "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e", "name": "Jon Doe" }, "restricted": false } } ], "links": { "next": "/v4/accounts/123/folders/123/folders" }, "total_count": 10 } ``` > **Test del parametro \\after\\** > > Se stai testando i risultati paginati, individua l'oggetto **`links`** nella risposta: > > * Dall'URL della proprietà **`next`**, copia solo il valore di stringa che segue **`after=`** > > * Imposta questo valore come parametro di richiesta **`after`** nella richiesta successiva. > > * **Attenzione alla doppia codifica!** Se l'URL contiene caratteri codificati (ad esempio: %3D%3D), sostituiscili con la versione non codificata (**==**). Postman interpreta l'input letteralmente e potrebbe applicare una doppia codifica, causando un errore **`422`** --- ### Creazione di un file - Caricamento locale La richiesta **`POST create file - local upload`** chiama **[`/v4/accounts/:account_id/folders/:folder_id/files/local_upload`](/platform/v4/api-reference/files/create-local-upload)** per caricare un file locale in una cartella specifica. I caricamenti locali richiedono due o più richieste a seconda delle dimensioni del file. Per il primo test, usa un file piccolo (meno di 10 MB) per limitare il processo a un singolo URL di caricamento. #### Crea una risorsa di file segnaposto Nell'editor delle richieste, seleziona la scheda **Body** per impostare il nome e le dimensioni del file (specificate in **byte**) all'interno dell'oggetto `data`. Una richiesta riuscita restituirà uno stato **`201 Created`** e un corpo della risposta simile all'esempio seguente. **Risposta di esempio** ``` { "data": { "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "media_type": "image/png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "type": "file", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "name": "asset.png", "upload_urls": [ { "size": 20000000, "url": "https://my.fileupload.url.dev" } ] } } ``` Questa chiamata ha creato una risorsa di file segnaposto nella cartella specificata. Usa l'URL di caricamento pre-firmato nell'array `upload_urls` all'interno della risposta per completare il caricamento nel passaggio successivo. #### Carica il contenuto del file Fai clic sull'URL nell'array `upload_urls` nella risposta per aprire una nuova scheda di richiesta in Postman. Cambia il metodo di richiesta in **`PUT`**. Nell'editor delle richieste, seleziona la scheda **Headers** per aggiungere le seguenti intestazioni alla richiesta: * **`x-amz-acl`:`private`*** **`Content-Type`**: deve corrispondere esattamente al tipo di estensione specificato nel nome del file (ad esempio, un file denominato **`IMG.png`** deve utilizzare **`image/png`**) ![alt image](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) Nell'editor delle richieste, seleziona la scheda **Body** e fai clic sull'opzione **binary** per selezionare il file. Una volta selezionato, fai clic su **Send** per completare la richiesta. Una richiesta riuscita restituirà uno stato **`200 OK`**, confermando che il file è stato caricato. Una volta caricato il file, la pipeline dei media di Frame.io gestisce automaticamente la transcodifica e la generazione delle miniature. Per i file più grandi, potrebbero essere necessari alcuni istanti prima che il file passi dallo stato **`created`** allo stato **`ready`**. --- ### Creazione di un file - Caricamento remoto La richiesta **`POST create file - remote upload`** chiama **[`/v4/accounts/:account_id/folders/:folder_id/files/remote_upload`](/platform/v4/api-reference/files/create-remote-upload)** per richiamare un file esterno in una cartella specifica utilizzando un URL di origine fornito. Nell'editor delle richieste, seleziona la scheda **Body** per impostare il nome e l'URL di origine del file all'interno dell'oggetto `data`. Una richiesta riuscita restituirà uno stato **`202 Accepted`** e un corpo della risposta simile all'esempio seguente. **Risposta di esempio** ``` { "data": { "created_at": "2023-09-25T19:18:29.614189Z", "file_size": 1137444, "media_type": "image/png", "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4", "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b", "status": "created", "type": "file", "updated_at": "2024-02-07T16:44:41.986478Z", "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c", "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d", "name": "asset.png" }, "links": { "status": "/v4/accounts/fb4dd62f-8a89-4e98-8fa1-ad4b29a0094f/files/eab70952-966c-4d99-949b-f0a947ca5754/status" } } ```