Postman 컬렉션 | Frame.io API Documentation

이 가이드는 Frame.io V4 API를 바로 시작할 수 있도록 사전 구성된 요청 세트인 공식 Frame.io Developer API Postman 컬렉션의 기본 사항을 다룹니다.

이 컬렉션은 V4 API 엔드포인트의 전체 영역을 포괄하며 안정화 버전과 실험적 버전의 두 가지 범주로 나뉩니다. 안정화 엔드포인트는 프로덕션 환경에 바로 사용할 수 있으며, 실험적 엔드포인트는 정상 작동하지만 안정화 버전으로 승격되기 전에 피드백에 따라 변경될 수 있는 새로운 추가 기능입니다.

Postman 시작하기

이 가이드는 이미 API 자격 증명을 생성했다고 가정합니다. 아직 생성하지 않았다면 여기서부터 시작하세요.

Postman 계정 생성 및 개발 환경 선택

postman.com에서 Postman 계정을 생성하고 환경을 선택합니다. 여기에서 Postman 앱을 다운로드하거나 웹 환경에서 Postman을 바로 사용할 수 있습니다.

Frame.io Developer API Postman 컬렉션 가져오기

Frame.io Developer API 컬렉션

여기에서 포크하거나 다운로드하세요.

환경 설정

Frame.io Developer API 컬렉션에는 다수의 환경 변수가 정의된 기본 환경 이 포함되어 있습니다. BASE_URL 및 IMS_BASE_URL 값은 고정되어 있습니다. 추가 환경 변수는 귀하의 계정 정보에 맞게 구성할 수 있습니다.

아래 표는 컬렉션의 Default 및 Stage 환경에 포함된 각 변수에 대한 설명입니다.

변수	설명	가져오는 방법	환경
`BASE_URL`	모든 V4 API 요청을 위한 기본 URL	사전 구성됨, 편집하지 마세요.	Default
`IMS_BASE_URL`	Adobe IMS 인증 기본 URL	사전 구성됨, 편집하지 마세요.	Default, Stage
`IMS_CLIENT_ID`	Frame.io 앱 클라이언트 ID	Adobe Developer Console의 자격 증명 페이지	Stage
`IMS_CLIENT_SECRET`	Frame.io 앱 클라이언트 시크릿	Adobe Developer Console의 자격 증명 페이지	Stage
`FOLDER_ID`	대상 폴더의 고유 ID	폴더 응답 오브젝트로 반환됨	Default
`WEBHOOK_ID`	구성된 웹훅의 고유 ID	웹훅 응답 오브젝트로 반환됨	Default
`ASSET_ID`	파일 또는 폴더 에셋의 고유 ID	파일 또는 폴더 응답 오브젝트로 반환됨	Default
`SHARE_ID`	공유 링크의 고유 ID	공유 응답 오브젝트로 반환됨	Default

인증 설정

이 안내서는 OAuth 2.0을 사용하여 Frame.io V4 API로 인증합니다. 서버 간 인증(S2S) 등 다른 인증 방법에 대한 정보는 인증 안내서를 참조하세요.

IMS_CLIENT_ID 및 IMS_CLIENT_SECRET 환경 변수는 Adobe Developer Console에서 프로젝트의 자격 증명 세부 정보에서 가져온 값으로 설정해야 합니다.

프로젝트의 자격 증명 세부 정보 섹션에서 URI 리디렉션 및 URL 패턴 리디렉션을 Postman의 공용 콜백 엔드포인트로 설정하세요. URI 리디렉션

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

URI 패턴 리디렉션

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

환경 변수를 설정하고 저장했으면 다음 단계는 인증 설정을 구성하는 것입니다. 이를 위해 왼쪽 사이드바 상단의 컬렉션 아이콘을 클릭하여 컬렉션 브라우저를 엽니다. 컬렉션 브라우저에서 Frame.io V4 Developer API 컬렉션의 루트(일반적으로 ‘Frame.io Developer API Collection’ 뒤에 포크 이름이 표시됨)를 선택하고 인증 탭을 선택합니다. alt image OAuth 범위 은 컬렉션에서 사전 구성되어 있습니다. 환경 변수를 설정한 후 <strong>새 액세스 토큰 가져오기** 버튼을 사용하여 OAuth 2.0 흐름을 시작하세요. 브라우저 창이 열려 인증 프로세스를 완료하고 토큰을 Postman으로 반환합니다. 인증 구성을 확인하려면 Users 폴더에서 GET 사용자 세부 정보 요청을 선택하고 보내기를 클릭하세요. 200 OK 응답은 컬렉션이 올바르게 구성되었고 올바른 계정으로 인증되었음을 확인해 줍니다. 오류가 발생하면 오류 및 경고에 대한 정보는 시작 안내서의 ****](</span)**이 섹션**을 참조하세요. 응답 예시

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

계정 ID 가져오기

account_id는 대부분의 V4 API 엔드포인트에 필수적인 경로 매개변수이며, 다른 요청들을 테스트하는 데 반드시 필요합니다. 컬렉션 내 Accounts 폴더에 있는 GET List accounts 요청을 통해 account_id를 가져올 수 있습니다. **API 참조**응답 예시

{
  "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}}를 사용하게 됩니다.

작업 영역 및 프로젝트 작업

Frame.io 파일은 작업 영역 내의 프로젝트 안에 구성된 폴더에 저장됩니다. V4 리소스 계층 구조에 대한 전체 개요는 <strong>](</span)이 안내서**에서 확인할 수 있습니다.

작업 영역 나열하기

Workspaces 폴더의 GET list workspaces 요청은 **/v4/accounts/:account_id/workspaces**를 호출하여 계정에 접근 권한이 있는 작업 영역 목록을 반환합니다. 일부 프로젝트 작업의 경우 경로 매개변수로 workspace_id가 필요하므로, 프로젝트를 나열하거나 검색할 계획이라면 먼저 작업 영역 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**를 호출하여 계정에 새 작업 영역을 생성합니다. 요청 에디터에서 Body 탭을 선택하고 data 오브젝트 내에서 새 작업 영역의 이름을 설정합니다. 성공적인 요청은 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"
  }
}

작업 영역 업데이트하기

PATCH update workspace 요청은 **/v4/accounts/:account_id/workspaces/:workspace_id**를 호출하여 작업 영역의 이름을 업데이트합니다. 요청 에디터에서 Body 탭을 선택하고 data 오브젝트 내에 작업 영역의 새 이름을 설정합니다. 성공적인 요청은 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**를 호출하여 특정 작업 영역에 새 프로젝트를 생성합니다. 요청 에디터에서 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`	Integer	반환되는 폴더 수를 1에서 100 사이로 제한합니다. 기본값은 50입니다.
`type`	문자열	리소스 유형(`file` 또는 `folder`)별로 폴더 하위 항목을 필터링합니다.
`after`	문자열	페이지가 매겨진 결과를 반환하는 요청을 위한 불투명 커서입니다. 이 값은 자동으로 생성되며 이전 응답의 `links` 오브젝트에 포함되어 반환됩니다. 사람이 읽을 수 있는 형태로 설계되지 않았습니다.
`include_total_count`	부울	모든 엔터티의 총 개수를 반환합니다. 기본값은 False입니다.
`include`	Enum	`creator`, `project`, `media_links`와 같은 추가 데이터를 반환되는 각 오브젝트에 추가합니다. 지원되는 매개변수의 전체 목록은 API 참조를 확인하세요.

성공적인 요청은 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
}

after 매개변수 테스트

페이지 매김 결과를 테스트하는 경우 응답에서 links 오브젝트를 찾으세요.

next 속성의 URL에서 after= 뒤에 오는 문자열 값만 복사합니다.

복사한 값을 다음 요청의 after 쿼리 매개변수 값으로 설정하세요.

이중 인코딩 주의! URL에 인코딩된 문자(예: %3D%3D)가 포함되어 있다면 원시 형태(raw version, 즉 ==)로 변경하세요. Postman은 입력을 있는 그대로 받아들이기 때문에 이를 다시 한 번 인코딩하여 422 오류를 발생시킬 수 있습니다.

파일 생성하기 - 로컬 업로드

POST create file - local upload 요청은 **/v4/accounts/:account_id/folders/:folder_id/files/local_upload**를 호출하여 지정된 폴더에 로컬 파일을 업로드합니다.

로컬 업로드의 경우 파일 크기에 따라 두 개 이상의 요청이 필요할 수 있습니다. 첫 번째 테스트에서는 단일 업로드 URL로 전체 프로세스를 진행할 수 있도록 작은 크기(10MB 미만)의 파일을 사용하세요.

자리 표시자 파일 리소스 생성

요청 에디터에서 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을 사용하세요.

파일 콘텐츠 업로드

응답의 upload_urls 배열에 있는 URL을 클릭하여 Postman에 새로운 요청 탭을 엽니다. 요청 메서드를 **PUT**으로 변경합니다. 요청 에디터의 Headers 탭에서 다음 헤더를 추가합니다.

x-amz-acl:private

Content-Type: 파일 이름에 명시된 확장자 유형과 정확히 일치해야 합니다(예: **IMG.png**라는 파일은 **image/png**를 사용해야 함).

alt image 요청 에디터에서 Body 탭을 선택하고 binary 옵션을 클릭하여 업로드할 파일을 선택합니다. 선택이 완료되면 Send를 클릭하여 요청을 마무리합니다. 성공적인 요청은 200 OK 상태 코드를 반환하며 파일 업로드가 완료되었음을 확인해 줍니다.

파일 업로드가 완료되면 Frame.io 미디어 파이프라인이 트랜스코딩과 썸네일 생성을 자동으로 처리합니다. 파일 크기가 큰 경우 파일이 생성됨 상태에서 준비됨 상태로 변경되기까지 잠시 시간이 소요될 수 있습니다.

파일 생성하기 - 원격 업로드

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