Raccolta Postman | Frame.io API Documentation

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

Questa guida presuppone che tu abbia generato le credenziali per l’API. Se non l’hai ancora fatto, vai qui

Crea un account Postman e scegli la configurazione

Crea il tuo account Postman su postman.com e scegli la configurazione. Puoi scaricare l’app Postman qui o utilizzare Postman sul web.

Importa la raccolta Postman dell'API Frame.io Developer

Raccolta dell'API Frame.io Developer

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.

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	Temporaneo
`IMS_CLIENT_SECRET`	Secret del client della tua app Frame.io	Pagina delle credenziali in Adobe 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

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 guida all’autenticazione.

Le variabili d’ambiente IMS_CLIENT_ID e IMS_CLIENT_SECRET devono essere impostate sui valori recuperati dai dettagli delle credenziali del tuo progetto in Adobe Developer Console.

Nella sezione Credential details (Dettagli delle credenziali) del progetto, imposta l’URI di reindirizzamento e il pattern per l’URI di reindirizzamento sull’endpoint di callback pubblico di Postman: URI di reindirizzamento

https://oauth/pstmn.io/v1/callback

Pattern per l’URI di reindirizzamento

https://oauth\\.pstmn\\.io

Una volta impostate e salvate le variabili d’ambiente, il passaggio successivo consiste nel configurare le impostazioni di autorizzazione. Per farlo, fai clic sull’icona delle Raccolte nella parte superiore della barra laterale sinistra per aprire il browser delle raccolte. Dal browser delle raccolte, seleziona la radice della raccolta API Frame.io V4 Developer (che di solito si chiama “Frame.io Developer API Collection” seguita dal nome del tuo fork) e seleziona la scheda Authorization (Autorizzazione). alt image OAuth scopes sono preconfigurati nella raccolta. Una volta impostate le variabili d’ambiente, usa il pulsante <strong>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 ****](</span)questa sezione della guida introduttiva per informazioni su errori e avvertenze. Risposta di esempio

{
  "data": {
    "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": "00000000-1111-2222-3333-444444444444",
    "name": "Name"
  }
}

Come ottenere l’ID dell’account

L’account_id è un parametro del percorso obbligatorio per la maggior parte degli endpoint dell’API V4 e serve per testare altre richieste. Puoi ottenere il tuo account_id con la richiesta GET List accounts, che si trova nella cartella Accounts della raccolta. Riferimento API Risposta di esempio

{
  "data": [
    {
      "created_at": "2023-09-25T19:18:29.614189Z",
      "display_name": "Integration Account",
      "id": "11111111-2222-3333-4444-555555555555",
      "roles": [
        "admin"
      ],
      "storage_limit": 300,
      "storage_usage": 300,
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "image": null
    }
  ],
  "links": {
    "next": "/v4/accounts"
  }
}

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 <strong>](</span)questa guida**.

Elenca le aree di lavoro

La richiesta GET list workspaces nella cartella Workspaces chiama /v4/accounts/:account_id/workspaces e restituisce un elenco delle aree di lavoro a cui il tuo account ha accesso. Alcune operazioni sui progetti richiedono workspace_id come parametro del percorso, quindi salva prima l’ID area di lavoro se prevedi di elencare o recuperare i progetti. Una richiesta riuscita restituirà uno stato 200 OK e un corpo della risposta simile all’esempio seguente. Risposta di esempio

{
  "data": [
    {
      "account_id": "11111111-2222-3333-4444-555555555555",
      "created_at": "2024-01-25T19:18:29.614189Z",
      "id": "88888888-bbbb-4444-aaaa-ffffffffffff",
      "name": "My Workspace",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "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": "196C1A5777BF4CV00A49411B@176719f5667d82g5594324.e",
        "name": "Name"
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/workspaces"
  }
}

Creazione di un’area di lavoro

La richiesta POST create workspace chiama /v4/accounts/:account_id/workspaces per creare una nuova area di lavoro per l’account. Nell’editor delle richieste, seleziona la scheda Body per impostare il nome dell’area di lavoro nell’oggetto data. Una richiesta riuscita restituirà uno stato 201 Created e un corpo della risposta simile all’esempio seguente. Risposta di esempio

{
  "data": {
    "account_id": "11111111-2222-3333-4444-555555555555",
    "created_at": "2024-01-25T19:18:29.614189Z",
    "id": "77777777-999-4444-8888-000000000000",
    "name": "My New Workspace",
    "updated_at": "2024-02-07T16:44:41.986478Z"
  }
}

Aggiornamento di un’area di lavoro

La richiesta PATCH update workspace chiama /v4/accounts/:account_id/workspaces/:workspace_id per aggiornare il nome di un’area di lavoro. Nell’editor delle richieste, seleziona la scheda Body per impostare il nuovo nome dell’area di lavoro nell’oggetto data. Una richiesta riuscita restituirà uno stato 200 OK e un corpo della risposta simile all’esempio seguente. Risposta di esempio

{
    "data": {
        "id": "77777777-9999-4444-8888-000000000000",
        "name": "New Workspace Name",
        "updated_at": "2026-05-01T02:42:00.462467Z",
        "account_id": "11111111-2222-3333-4444-555555555555",
        "created_at": "2025-09-22T19:17:02.565496Z"
    }
}

Creare un progetto

La richiesta POST create project chiama /v4/accounts/:account_id/workspaces/:workspace_id/projects per creare un nuovo progetto in un’area di lavoro specifica. Nell’editor delle richieste, seleziona la scheda Body per impostare il nome del progetto nell’oggetto data. La proprietà opzionale restricted è un valore booleano che permette di creare un progetto limitato. Una richiesta riuscita restituirà uno stato 201 Created e un corpo della risposta simile all’esempio seguente. Risposta di esempio

{
    "data": {
        "id": "fd26defb-8bdf-5c39-9746-24d38f109cc3",
        "name": "test",
        "status": "active",
        "restricted": true,
        "updated_at": "2026-05-01T03:39:58.910884Z",
        "storage": 0,
        "workspace_id": "77777777-999-4444-8888-000000000000",
        "created_at": "2026-05-01T03:39:58.853797Z",
        "root_folder_id": "d4fca8b4-5fd8-4a94-90aa-de13de4b2021",
        "view_url": "https://next.frame.io/project/fd26defb-8bdg-5c39-9746-24d38f109cc3"
    }
}

Copia il root_folder_id dalla risposta e impostalo come valore per la variabile di ambiente FOLDER_ID. Sarà necessario per le restanti sezioni di questa guida.

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)

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

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