ガイド

Postman Collection

このガイドでは、公式Frame.io Developer API Postman collectionの基本について説明します。これは、Frame.io V4 APIの使用を開始するために使用できる事前構築済みリクエストのセットです。

このcollectionは、V4 APIエンドポイントの全範囲をカバーし、安定版と実験版のカテゴリに分かれています。 安定版エンドポイントは本番環境対応で、実験版エンドポイントは機能的ですが、安定版に昇格する前にフィードバックに基づいて変更される可能性がある新しい追加機能です。

Postman の基本を学ぶ

このガイドでは、APIの資格情報を生成済みであることを前提としています。 まだ生成していない場合は、まずこちらから開始してください

1

Postmanアカウントの作成 + セットアップの選択

postman.comでPostmanアカウントを作成し、セットアップを選択してください。 Postmanアプリケーションはこちらからダウンロードするか、webでPostmanを使用できます。

環境のセットアップ

Frame.io Developer API Collectionには、デフォルトの 環境があります には、多数の環境変数が定義されています。 BASE_URLとIMS_BASE_URLの値は静的です。 追加の環境変数は、アカウント情報に応じて設定できます。

alt imagealt image

以下は、collectionのDefaultおよびStage環境で見つかる各変数の説明を示した表です：

変数説明取得方法環境
BASE_URLすべてのV4 APIリクエストのベースURL事前設定済み、編集しないでくださいオン
IMS_BASE_URLAdobe IMS認証ベースURL事前設定済み、編集しないでくださいデフォルト、ステージ
IMS_CLIENT_IDFrame.ioアプリケーションクライアントID**Adobe Developer Console**の資格情報ページステージ
IMS_CLIENT_SECRETFrame.ioアプリケーションクライアントシークレット**Adobe Developer Console**の資格情報ページステージ
FOLDER_ID宛先フォルダーの一意のIDフォルダー応答オブジェクトで返されるオン
WEBHOOK_ID設定されたWebhookの一意のIDWebhook応答オブジェクトで返されるオン
ASSET_IDファイルまたはフォルダーアセットの一意のIDファイルまたはフォルダー応答オブジェクトで返されるオン
SHARE_ID共有リンクの一意のID共有応答オブジェクトで返されるオン

アカウント ID の取得

account_id は、ほとんどの V4 API エンドポイントで必要なパスパラメーターであり、他のリクエストをテストするために必要なものです。 コレクションの Accounts フォルダーにある GET List accounts リクエストを使用して、account_id を取得できます。 API Reference レスポンスの例

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

複数の Frame.io アカウントがある場合、それぞれが応答内で個別のオブジェクトとして表示されます

アカウント ID を取得したら、応答から id 値をコピーして、環境変数として保存します。 account_id として参照します パスパラメーター 今後のリクエストで {{ACCOUNT_ID}} を使用します。

Workspace とプロジェクトの操作

Frame.io ファイルはフォルダーに保存され、Workspace 内のプロジェクトに整理されます。 V4 リソース階層の完全な概要については、**このガイド**を参照してください。

Workspace の一覧表示

Workspaces フォルダーの GET list workspaces リクエストは /v4/accounts/:account_id/workspaces を呼び出し、アカウントがアクセスできる Workspace のリストを返します。 一部のプロジェクト操作では workspace_id がパスパラメーターとして必要なため、プロジェクトを一覧表示または取得する予定がある場合は、まず Workspace ID を保存してください。 リクエストが成功すると、200 OK ステータスと以下の例のような応答本文が返されます。 応答例

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

ワークスペースを作成

POST create workspace リクエストは /v4/accounts/:account_id/workspaces を呼び出して、アカウント用の新しい Workspace を作成します。 リクエストエディターで Body タブを選択し、data オブジェクト内で Workspace の名前を設定します。 リクエストが成功すると、**201 Created**ステータスと以下の例のような応答本文が返されます。 応答例

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

Workspace の更新

PATCH update workspace リクエストは /v4/accounts/:account_id/workspaces/:workspace_id を呼び出して、Workspace の名前を更新します。 リクエストエディターで Body タブを選択し、data オブジェクト内で Workspace の新しい名前を設定します。 リクエストが成功すると、200 OK ステータスと以下の例のような応答本文が返されます。 応答例

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

プロジェクトの作成

POST create projectリクエストは/v4/accounts/:account_id/workspaces/:workspace_id/projectsを呼び出して、指定されたWorkspace内に新しいプロジェクトを作成します。 リクエストエディターでBodyタブを選択し、dataオブジェクト内でプロジェクトの名前を設定します。 オプションのrestrictedプロパティは、制限付きプロジェクトを作成するために使用されるブーリアンです。 リクエストが成功すると、**201 Created**ステータスと以下の例のような応答本文が返されます。 応答例

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

応答から**root_folder_idをコピーし、FOLDER_ID**環境変数の値として設定します。 このガイドの残りのセクションで必要になります。

Project Permissionsフォルダーにある**PATCH Update user role in a Projectリクエストを使用して、新しく作成された制限付きプロジェクトにユーザーを追加できます。 (API リファレンス**)

フォルダーとファイルの操作

フォルダーの子要素の一覧表示

**GET list folder childrenリクエストは/v4/accounts/:account_id/folders/:folder_id/childrenを呼び出して、指定されたフォルダー内の子要素を一覧表示します。 この場合、FOLDER_ID**環境変数として設定されたプロジェクトルートフォルダーです。

以下のオプションのクエリパラメーターを使用して、応答を絞り込むことができます：

パラメータータイプ説明
page_size整数返されるフォルダーの数を制限します
1-100。 デフォルトは50
“文字列Filters folder children by resource type: file, or folder
after文字列ページ分割された結果を返すリクエスト用の不透明なカーソル。
これは自動生成され、前の応答のlinksオブジェクトで返されます。 人間が読めるようには意図されていません。
include_total_countBooleanすべてのエンティティの合計数を返します
デフォルトはfalseです
includeEnumcreator、project、media_linksなどの追加データを返される各オブジェクトに追加します。
サポートされているパラメーターの完全なリストについては、**API Reference**を参照してください

リクエストが成功すると、**200 OK**ステータスと以下の例のような応答本文が返されます。 応答例

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

Testing the after Parameter

ページ分割された結果をテストしている場合は、応答内の**links**オブジェクトを見つけてください：

  • **nextプロパティURLから、after=**に続く文字列値のみをコピーしてください
  • これを次のリクエストの**after**クエリパラメーターの値として設定してください。
  • 二重エンコーディングに注意してください！ URLにエンコードされた文字（例：%3D%3D）が含まれている場合は、生の版（==）に置き換えてください。 Postmanは入力を文字通りに解釈し、これらを二重エンコードする可能性があり、**422**エラーにつながります

ファイルの作成 - ローカルアップロード

**POST create file - local uploadリクエストは/v4/accounts/:account_id/folders/:folder_id/files/local_upload**を呼び出して、指定されたフォルダーにローカルファイルをアップロードします。

ローカルアップロードには、ファイルサイズに応じて2つ以上のリクエストが必要です。 最初のテストでは、小さなファイル（10 MB未満）を使用して、プロセスを単一のアップロードURLに制限してください。

1

プレースホルダーファイルリソースの作成

リクエストエディターで、Bodyタブを選択して、dataオブジェクト内で名前とファイルサイズ（bytesで指定）を設定します。 リクエストが成功すると、**201 Created**ステータスと以下の例のような応答本文が返されます。 応答例

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

この呼び出しにより、指定されたフォルダーにプレースホルダーファイルリソースが作成されました。 次のステップでアップロードを完了するには、応答のupload_urls配列内の事前署名されたアップロードURLを使用してください。

2

ファイルコンテンツをアップロード

応答のupload_urls配列のURLをクリックして、Postmanで新しいリクエストタブを開きます。 リクエストメソッドを**PUTに変更します。 リクエストエディターでHeaders**タブを選択し、以下のヘッダーをリクエストに追加します：

  • x-amz-acl:private
  • Content-Type：これはファイル名で指定された拡張機能タイプと完全に一致する必要があります（例：**IMG.pngという名前のファイルはimage/png**を使用する必要があります）

代替画像リクエストエディターでBodyタブを選択し、binaryオプションをクリックしてファイルを選択します。 選択したらSendをクリックしてリクエストを完了します。 成功したリクエストは**200 OK**ステータスを返し、ファイルがアップロードされたことを確認します。

ファイルがアップロードされると、Frame.ioメディアパイプラインが自動的にトランスコーディングとサムネイル生成を処理します。 大きなファイルの場合、ファイルが**createdからready**状態に移行するまで数分かかる場合があります。

ファイルの作成 - リモートアップロード

POST create file - remote uploadリクエストは/v4/accounts/:account_id/folders/:folder_id/files/remote_uploadを呼び出し、提供された引用元URLを使用して外部ファイルを指定されたフォルダーに取り込みます。 リクエストエディターでBodyタブを選択し、dataオブジェクト内でファイルの名前と引用元URLを設定します。 成功したリクエストは**202 Accepted**ステータスと以下の例のような応答本文を返します。 応答例

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