> This page is for 플랫폼, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 실험적: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - 레거시: 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. # Postman 컬렉션 이 가이드는 Frame.io V4 API를 바로 시작할 수 있도록 사전 구성된 요청 세트인 공식 Frame.io Developer API Postman 컬렉션의 기본 사항을 다룹니다. 이 컬렉션은 V4 API 엔드포인트의 전체 영역을 포괄하며 안정화 버전과 실험적 버전의 두 가지 범주로 나뉩니다. 안정화 엔드포인트는 프로덕션 환경에 바로 사용할 수 있으며, 실험적 엔드포인트는 정상 작동하지만 안정화 버전으로 승격되기 전에 피드백에 따라 변경될 수 있는 새로운 추가 기능입니다. ## Postman 시작하기 > **Tip** > > 이 가이드는 이미 API 자격 증명을 생성했다고 가정합니다. 아직 생성하지 않았다면 [여기](/platform/docs/quick-start)서부터 시작하세요. #### Postman 계정 생성 및 개발 환경 선택 [postman.com](http://auth.postman.com/__redirect/login)에서 Postman 계정을 생성하고 환경을 선택합니다. [여기](https://www.postman.com/downloads/)에서 Postman 앱을 다운로드하거나 웹 환경에서 Postman을 바로 사용할 수 있습니다. #### Frame.io Developer API Postman 컬렉션 가져오기 #### [Frame.io Developer API 컬렉션](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) 여기에서 포크하거나 다운로드하세요. ### 환경 설정 Frame.io Developer API 컬렉션에는 다수의 환경 변수가 정의된 기본 환경 이 포함되어 있습니다. `BASE_URL` 및 `IMS_BASE_URL` 값은 고정되어 있습니다. 추가 환경 변수는 귀하의 계정 정보에 맞게 구성할 수 있습니다. ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp) ![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) 아래 표는 컬렉션의 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](https://developer.adobe.com/developer-console/)\*\*의 자격 증명 페이지 | Stage | | `IMS_CLIENT_SECRET` | Frame.io 앱 클라이언트 시크릿 | \*\*[Adobe Developer Console](https://developer.adobe.com/developer-console/)\*\*의 자격 증명 페이지 | Stage | | `FOLDER_ID` | 대상 폴더의 고유 ID | 폴더 응답 오브젝트로 반환됨 | Default | | `WEBHOOK_ID` | 구성된 웹훅의 고유 ID | 웹훅 응답 오브젝트로 반환됨 | Default | | `ASSET_ID` | 파일 또는 폴더 에셋의 고유 ID | 파일 또는 폴더 응답 오브젝트로 반환됨 | Default | | `SHARE_ID` | 공유 링크의 고유 ID | 공유 응답 오브젝트로 반환됨 | Default | --- ### 인증 설정 > **Tip** > > [ 이 안내서는 OAuth 2.0을 사용하여 Frame.io V4 API로 인증합니다. 서버 간 인증(S2S) 등 다른 인증 방법에 대한 정보는 ](\새 액세스 토큰 가져오기\*\* 버튼을 사용하여 OAuth 2.0 흐름을 시작하세요. 브라우저 창이 열려 인증 프로세스를 완료하고 토큰을 Postman으로 반환합니다. 인증 구성을 확인하려면 Users 폴더에서 **`GET 사용자 세부 정보`** 요청을 선택하고 **보내기**를 클릭하세요. **`200 OK`** 응답은 컬렉션이 올바르게 구성되었고 올바른 계정으로 인증되었음을 확인해 줍니다. 오류가 발생하면 오류 및 경고에 대한 정보는 시작 안내서의 \*\*\*\*]\(\ **Tip** > > 여러 Frame.io 계정이 있는 경우, 각 계정은 응답에서 별도의 오브젝트로 나타납니다. 계정 ID를 얻었으면 응답에서 `id` 값을 복사하여 환경 변수로 저장하세요. 이를 `account_id` 경로 매개변수 (으)로 참조하며, 향후 요청에서는 `{{ACCOUNT_ID}}`를 사용하게 됩니다. --- ## 작업 영역 및 프로젝트 작업 Frame.io 파일은 작업 영역 내의 프로젝트 안에 구성된 폴더에 저장됩니다. V4 리소스 계층 구조에 대한 전체 개요는 \**]\(\ **Tip** > > **Project Permissions** 폴더에 있는 후속 요청인 **`PATCH Update user role in a Project`** 요청을 사용하면 새로 생성된 제한된 프로젝트에 사용자를 추가할 수 있습니다. (**[API 참조](/platform/docs/guides/postman-collection)**) --- ## 폴더 및 파일 작업 ### 하위 폴더 나열하기 **`GET list folder children`** 요청은 \*\*[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)\*\*을 호출하여 지정된 폴더의 하위 항목을 나열합니다. 이 경우 **`FOLDER_ID`** 환경 변수에 설정된 프로젝트 루트 폴더를 사용합니다. 다음과 같은 선택적 쿼리 매개변수를 사용하여 응답을 세부적으로 필터링할 수 있습니다. | 매개 변수 | 문자 | 설명 | | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`page_size`** | Integer | 반환되는 폴더 수를 **1에서 100 사이로 제한합니다. 기본값은 50**입니다. | | **`type`** | 문자열 | 리소스 유형(**`file`** 또는 **`folder`**)별로 폴더 하위 항목을 필터링합니다. | | **`after`** | 문자열 | 페이지가 매겨진 결과를 반환하는 요청을 위한 불투명 커서입니다. **이 값은 자동으로 생성되며 이전 응답의 `links` 오브젝트에 포함되어 반환됩니다.** 사람이 읽을 수 있는 형태로 설계되지 않았습니다. | | **`include_total_count`** | 부울 | 모든 엔터티의 총 개수를 반환합니다. **기본값은 False입니다.** | | **`include`** | Enum | `creator`, `project`, `media_links`와 같은 추가 데이터를 반환되는 각 오브젝트에 추가합니다. 지원되는 매개변수의 전체 목록은 \*\*[API 참조](/platform/api-reference/folders/index#request.query.include)\*\*를 확인하세요. | 성공적인 요청은 **`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`](/platform/v4/api-reference/files/create-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](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) 요청 에디터에서 **Body** 탭을 선택하고 **binary** 옵션을 클릭하여 업로드할 파일을 선택합니다. 선택이 완료되면 **Send**를 클릭하여 요청을 마무리합니다. 성공적인 요청은 **`200 OK`** 상태 코드를 반환하며 파일 업로드가 완료되었음을 확인해 줍니다. 파일 업로드가 완료되면 Frame.io 미디어 파이프라인이 트랜스코딩과 썸네일 생성을 자동으로 처리합니다. 파일 크기가 큰 경우 파일이 **`생성됨`** 상태에서 **`준비됨`** 상태로 변경되기까지 잠시 시간이 소요될 수 있습니다. --- ### 파일 생성하기 - 원격 업로드 **`POST create file - remote upload`** 요청은 \*\*[`/v4/accounts/:account_id/folders/:folder_id/files/remote_upload`](/platform/v4/api-reference/files/create-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" } } ```