Postman-Sammlung | Frame.io API Documentation

In diesem Leitfaden geht es um die Grundlagen der offiziellen Frame.io Developer-API Postman-Sammlung, eine Sammlung vorgefertigter Anfragen, mit denen Sie in die Frame.io V4-API einsteigen können.

Die Sammlung deckt das gesamte Spektrum der V4-API-Endpunkte ab, aufgeteilt in stabile und experimentelle Kategorien.Stabile Endpunkte sind produktionsreif, und experimentelle Endpunkte sind neuere Ergänzungen, die funktional sind, sich aber basierend auf Feedback ändern können, bevor sie als stabil eingestuft werden.

Erste Schritte mit Postman

In diesem Leitfaden wird davon ausgegangen, dass Sie Anmeldedaten für die API generiert haben.Falls nicht, beginnen Sie hier.

Postman-Konto erstellen und Setup wählen

Erstellen Sie unter postman.com Ihr Postman-Konto und wählen Sie Ihr Setup.Sie können die Postman-App hier herunterladen oder Postman im Web verwenden.

Frame.io Developer API Postman-Sammlung importieren

Frame.io Developer API-Sammlung

Hier abbiegen oder herunterladen

Einrichten Ihrer Umgebung

In der Frame.io Developer API-Sammlung gibt es eine standardmäßige Umgebung mit einer Reihe definierter Umgebungsvariablen. Die Werte BASE_URL und IMS_BASE_URL sind statisch.Entsprechend Ihren Kontoinformationen können zusätzliche Umgebungsvariablen konfiguriert werden.

Unten finden Sie eine Tabelle mit einer Beschreibung der einzelnen Variablen, die in den Standard- und Staging-Umgebungen der Sammlung zu finden sind:

Variable	Beschreibung	So rufen Sie sie ab	Umgebung
`BASE_URL`	Basis-URL für alle V4-API-Anfragen	Vorkonfiguriert, nicht bearbeiten	Standard
`IMS_BASE_URL`	Basis-URL von Adobe IMS zur Authentifizierung	Vorkonfiguriert, nicht bearbeiten	Standard, Staging
`IMS_CLIENT_ID`	Ihre Client-ID für die Frame.io-App	Seite mit Anmeldedaten in Adobe Developer Console	Staging
`IMS_CLIENT_SECRET`	Ihr Clientschlüssel für die Frame.io-App	Seite mit Anmeldedaten in Adobe Developer Console	Staging
`FOLDER_ID`	Eindeutige ID für den Zielordner	Im Rückmeldeobjekt des Ordners zurückgegeben	Standard
`WEBHOOK_ID`	Eindeutige ID für einen konfigurierten Webhook	Im Rückmeldeobjekt des Webhooks zurückgegeben	Standard
`ASSET_ID`	Eindeutige ID für ein Datei- oder Ordner-Asset	Im Rückmeldeobjekt der Datei oder des Ordners zurückgegeben	Standard
`SHARE_ID`	Eindeutige ID für einen Freigabe-Link	Im Rückmeldeobjekt der Freigabe zurückgegeben	Standard

Einrichten der Autorisierung

In dieser Anleitung wird OAuth 2.0 zur Authentifizierung mit der Frame.io V4-API verwendet. Informationen zu anderen Authentifizierungsmethoden wie Server-zu-Server (S2S) finden Sie im Authentifizierungsleitfaden.

Die Umgebungsvariablen IMS_CLIENT_ID und IMS_CLIENT_SECRET sollten auf die Werte eingestellt werden, die in der Adobe Developer Console aus den Anmeldedaten Ihres Projekts abgerufen wurden.

Stellen Sie im Bereich Anmeldedaten Ihres Projekts den Umleitungs-URI und das Muster für Umleitungs-URIs auf den öffentlichen Rückrufendpunkt von Postman ein: Umleitungs-URI

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

Muster für Umleitungs-URIs

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

Sobald die Umgebungsvariablen eingestellt und gespeichert wurden, besteht der nächste Schritt in der Konfiguration der Autorisierungseinstellungen. Klicken Sie dazu oben in der linken Seitenleiste auf das Symbol Sammlungen, um Ihren Sammlungsbrowser zu öffnen. Wählen Sie im Sammlungsbrowser den Stamm der Frame.io V4-Developer-API-Sammlung aus (trägt in der Regel den Titel Frame.io Developer-API-Sammlung, gefolgt von Ihrem Fork-Namen), und wählen Sie dann die Registerkarte Autorisierung aus. alt image OAuth Geltungsbereiche sind in der Sammlung vorkonfiguriert. Wenn Ihre Umgebungsvariablen eingestellt sind, starten Sie mit der Schaltfläche <strong>Neuen Zugriffstoken abrufen** den OAuth 2.0-Fluss. Dadurch wird ein Browserfenster geöffnet, um den Authentifizierungsprozess abzuschließen und den Token an Postman zurückzugeben. Wählen Sie zum Überprüfen Ihrer Autorisierungskonfiguration im Ordner „Benutzende“ die Anfrage GET Benutzendendetails aus und klicken Sie auf Senden. Mit der Antwort 200 OK wird sowohl bestätigt, dass Ihre Sammlung korrekt konfiguriert ist, als auch, dass Sie sich bei dem richtigen Konto authentifiziert haben. Informationen zu Fehlern und Warnungen finden Sie im Leitfaden „Erste Schritte“ in ****](</span)diesem Abschnitt. Beispielantwort

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

Beziehen Ihrer Konto-ID

Die account_id ist für die meisten V4-API-Endpunkte ein erforderlicher Pfad-Parameter und etwas, das Sie zum Testen anderer Anfragen benötigen.Sie können Ihre account_id mit der Anfrage GET List accounts abrufen. Diese befindet sich im Ordner Konten der Sammlung.**API-Referenz**Beispielantwort

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

Falls Sie mehrere Frame.io-Konten haben, werden diese in der Antwort als separate Objekte angezeigt.

Sobald Sie Ihre Konto-ID erhalten haben, kopieren Sie den id-Wert aus der Antwort und speichern Sie ihn als Umgebungsvariable.Sie werden sie in künftigen Anfragen als account_id Pfad-Parameter mit {{ACCOUNT_ID}} referenzieren.

Arbeitsbereiche und Projektvorgänge

Ihre Frame.io-Dateien werden in Ordnern gespeichert, die innerhalb von Arbeitsbereichen in Projekten organisiert sind.Eine vollständige Übersicht der V4-Ressourcenhierarchie finden Sie <strong>](</span)in diesem Leitfaden**.

Auflisten von Arbeitsbereichen

Mit der Anfrage GET list workspaces im Ordner Arbeitsbereiche wird /v4/accounts/:account_id/workspaces aufgerufen und eine Liste der Arbeitsbereiche zurückgegeben, auf die Ihr Konto Zugriff hat.Einige Projektoperationen erfordern workspace_id als Pfad-Parameter. Speichern Sie also zunächst Ihre Arbeitsbereichs-ID, falls Sie Projekte auflisten oder abrufen möchten.Bei einer erfolgreichen Anfrage wird der Status 200 OK und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Erstellen eines Arbeitsbereichs

Durch die Anfrage POST create workspace wird /v4/accounts/:account_id/workspaces aufgerufen, um einen neuen Arbeitsbereich für Ihr Konto zu erstellen.Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus, um den Namen Ihres Arbeitsbereichs in dem data-Objekt festzulegen.Bei einer erfolgreichen Anfrage wird der Status 201 Created und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Aktualisieren eines Arbeitsbereichs

Mit der Anfrage PATCH update workspace wird /v4/accounts/:account_id/workspaces/:workspace_id aufgerufen, um den Namen eines Arbeitsbereiche zu aktualisieren.Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus, um den neuen Namen Ihres Arbeitsbereichs im data-Objekt festzulegen.Bei einer erfolgreichen Anfrage wird der Status 200 OK und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Erstellen eines Projekts

Mit der Anfrage POST create project wird /v4/accounts/:account_id/workspaces/:workspace_id/projects aufgerufen, um in einem gegebenen Arbeitsbereich ein neues Projekt zu erstellen.Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus, um den Namen Ihres Projekts im data-Objekt festzulegen.Die optionale Eigenschaft restricted ist ein Boolescher Wert, mit dem ein eingeschränktes Projekt erstellt wird.Bei einer erfolgreichen Anfrage wird der Status 201 Created und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Kopieren Sie die root_folder_id aus der Antwort und legen Sie sie als Wert für Ihre Umgebungsvariable FOLDER_ID fest.Diese benötigen Sie für die verbleibenden Abschnitte in diesem Leitfaden.

Mit der nachfolgenden Anfrage PATCH Update user role in a Project, die sich im Ordner Project Permissions befindet, können Sie einem neu erstellten eingeschränkten Projekt Benutzende hinzufügen.(API-Referenz)

Vorgänge in Ordnern und Dateien

Auflisten untergeordneter Elemente in Ordnern

Mit der Anfrage GET list folder children wird /v4/accounts/:account_id/folders/:folder_id/children aufgerufen, um die untergeordneten Elemente in einem gegebenen Ordner aufzulisten.Legen Sie in diesem Fall den Stammordner des Projekts als Umgebungsvariable FOLDER_ID fest.

Mit den folgenden optionalen Abfrageparametern können Sie Ihre Rückmeldung verfeinern:

Parameter	Typ	Beschreibung
`page_size`	Ganzzahl	Begrenzt die Anzahl der zurückgegebenen Ordner auf 1-100.Standardwert ist 50
`type`	Zeichenfolge	Filtert untergeordnete Elemente von Ordnern anhand des Ressourcentyps: `file` oder `folder`.
`after`	Zeichenfolge	Intransparenter Cursor für Anfragen, bei denen paginierte Ergebnisse zurückgegeben werden. Dieser wird automatisch generiert und im Objekt `links` der vorherigen Antwort zurückgegeben.Er ist nicht dafür vorgesehen, für Menschen lesbar zu sein.
`include_total_count`	Boolescher Wert	Gibt die Gesamtanzahl aller Entitäten zurück Standardwert ist „False“.
`include`	Enum	Hängt an jedes zurückgegebene Objekt zusätzliche Daten an, etwa `creator`, `project`, `media_links`. Eine vollständige Liste der unterstützten Parameter finden Sie in der API-Referenz.

Bei einer erfolgreichen Anfrage wird der Status **200 OK**und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Testen des Parameters after

Wenn Sie paginierte Ergebnisse testen, suchen Sie in Ihrer Antwort nach dem Objekt links:

Kopieren Sie aus der Eigenschafts-URL next nur den Zeichenfolgenwert, der auf after= folgt.

Legen Sie diesen in Ihrer nächsten Anfrage als Wert des Abfrageparameters**after** fest.

Achten Sie auf doppelte Codierung!Wenn die URL codierte Zeichen enthält (z. B.: %3D%3D), ersetzen Sie sie durch die Rohversion (==).Ihre Eingabe wird wörtlich von Postman interpretiert, wodurch die Zeichen möglicherweise doppelt codiert werden, was wiederum zu dem Fehler 422 führt.

Dateien erstellen – Lokaler Upload

Mit der Anfrage POST create file - local upload wird /v4/accounts/:account_id/folders/:folder_id/files/local_upload aufgerufen, um eine lokale Datei in einem bestimmten Ordner hochzuladen.

Lokale Uploads erfordern zwei oder mehr Anfragen, je nach Dateigröße.Verwenden Sie für Ihren ersten Test eine kleine Datei (weniger als 10 MB), um den Prozess auf eine einzige Upload-URL zu begrenzen.

Platzhalter-Dateiressource erstellen

Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus, um den Namen und die Dateigröße (angegeben in Bytes) im data-Objekt festzulegen.Bei einer erfolgreichen Anfrage wird der Status 201 Created und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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

Durch diesen Aufruf wird im angegebenen Ordner eine Platzhalter-Dateiressource erstellt.Verwenden Sie in der Antwort die vorsignierte Upload-URL im upload_urls-Array, um den Upload im nächsten Schritt abzuschließen.

Dateiinhalt hochladen

Klicken Sie in Ihrer Antwort auf die URL im upload_urls-Array, um in Postman eine neue Registerkarte „Anfrage“ zu öffnen.Ändern Sie die Anfragemethode in PUT.Wählen Sie im Anfrageneditor die Registerkarte Headers aus, um der Anfrage die folgenden Header hinzuzufügen:

x-amz-acl:private

Content-Type: Dieser muss exakt mit dem im Dateinamen angegebenen Erweiterungstyp übereinstimmen (für eine Datei namens IMG.png zum Beispiel muss image/png verwendet werden).

alt image Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus und klicken Sie auf die Option binär, um Ihre Datei auszuwählen.Klicken Sie nach der Auswahl auf Senden, um Ihre Anfrage abzuschließen.Bei einer erfolgreichen Anfrage wird der Status **200 OK**zurückgegeben und bestätigt, dass Ihre Datei hochgeladen wurde.

Sobald Ihre Datei hochgeladen wurde, wird sie in der Frame.io-Medien-Pipeline automatisch transkodiert und eine Miniaturansicht wird erstellt.Bei größeren Dateien kann es einen Moment dauern, bis die Datei vom Status created in den Status ready wechselt.

Datei erstellen – Remote-Upload

Mit der Anfrage POST create file - remote upload wird /v4/accounts/:account_id/folders/:folder_id/files/remote_upload aufgerufen, um eine externe Datei mittels einer bereitgestellten Quell-URL in einen angegebenen Ordner zu ziehen. Wählen Sie im Anfrageneditor die Registerkarte Fließtext aus, um den Namen und die Quell-URL Ihrer Datei im data-Objekt festzulegen.Bei einer erfolgreichen Anfrage wird der Status 202 Accepted und ein Antwortfließtext zurückgegeben, ähnlich dem unten stehenden Beispiel.Beispielantwort

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