> This page is for Plataforma, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Herdado: 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. # Coleção do Postman Este guia aborda os fundamentos da coleção oficial do Postman da Frame.io Developer API, um conjunto de solicitações pré-criadas que você pode usar para começar a trabalhar com a API Frame.io V4. A coleção abrange toda a variedade de pontos de acesso da API V4, divididos em categorias estáveis e experimentais. Pontos de acesso estáveis estão prontos para produção, e pontos de acesso experimentais são adições mais recentes que funcionam, mas podem mudar com base em feedback antes de serem promovidos para estáveis. ## Introdução ao Postman > **Tip** > > Este guia pressupõe que você gerou credenciais para a API. Se não fez isso, comece por [aqui](/platform/docs/quick-start) #### Criar uma conta do Postman e escolher sua configuração Crie sua conta do Postman em [postman.com](http://auth.postman.com/__redirect/login) e escolha sua configuração. Você pode baixar o aplicativo Postman [aqui](https://www.postman.com/downloads/) ou usar o Postman na Web. #### Importar a coleção do Postman da Frame.io Developer API #### [Coleção da 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) Faça um fork ou baixe aqui ### Configuração do ambiente A coleção da Frame.io Developer API tem um ambiente padrão ambiente com várias variáveis de ambiente definidas.Os valores `BASE_URL` e `IMS_BASE_URL` são estáticos. Variáveis de ambiente adicionais podem ser configuradas de acordo com as informações da sua conta. ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp)![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) Veja abaixo uma tabela com a descrição de cada variável encontrada nos ambientes Padrão e Preparo da coleção: | Variável | Descrição | Como recuperar | Ambiente | | ------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------- | | `BASE_URL` | URL base para todas as solicitações da API V4 | Pré-configurado, não editar | Padrão | | `IMS_BASE_URL` | URL base de autenticação do Adobe IMS | Pré-configurado, não editar | Padrão, Preparo | | `IMS_CLIENT_ID` | ID do cliente do seu aplicativo Frame.io | Página de credenciais no **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Preparo | | `IMS_CLIENT_SECRET` | Segredo do cliente do seu aplicativo Frame.io | Página de credenciais no **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** | Preparo | | `FOLDER_ID` | Identificador exclusivo para a pasta de destino | Retornado no objeto de resposta da pasta | Padrão | | `WEBHOOK_ID` | Identificador exclusivo para um webhook configurado | Retornado no objeto de resposta do webhook | Padrão | | `ASSET_ID` | Identificador exclusivo para um ativo de arquivo ou pasta | retornado no objeto de resposta de arquivo ou pasta | Padrão | | `SHARE_ID` | Identificador exclusivo para um link de compartilhamento | retornado no objeto de resposta de compartilhamento | Padrão | --- ### Configurar autorização > **Tip** > > [ Este guia usa OAuth 2.0 para autenticar com a API Frame.io V4.Para obter informações sobre outros métodos de autenticação, como Server-to-Server (S2S), consulte o ](\Variáveis de ambiente token\*\* para iniciar o fluxo OAuth 2.0.Isso abrirá uma janela do navegador para concluir o processo de autenticação e retornar o token ao Postman.Para verificar a configuração de autorização, selecione a solicitação **`GET user details`** na pasta Usuários e clique em **Enviar**. Uma resposta **`200 OK`** confirma que a coleção está configurada corretamente e que você se autenticou na conta correta.Se encontrar um erro, consulte \*\*\*\*]\(\ **Tip** > > Se você tiver várias contas do Frame.io, cada uma aparecerá como um objeto separado na resposta Depois de obter o ID da Conta, copie o valor `id` da resposta e salve-o como uma variável de ambiente. Você o referenciará como `account_id` parâmetro de caminho usando `{{ACCOUNT_ID}}` em solicitações futuras. --- ## Operações de espaço de trabalho e projeto Seus arquivos do Frame.io são armazenados em pastas, organizadas em Projetos dentro de espaços de trabalho. Para obter uma visão geral completa da hierarquia de recursos da V4, consulte \**]\(\ **Tip** > > Você pode adicionar um usuário a um Projeto restrito recém-criado com uma solicitação **`PATCH Atualizar função de usuário em um Projeto subsequente`**, localizada na pasta **Permissões do Projeto**. (**[Referência da API](/platform/docs/guides/postman-collection)**) --- ## Operações de pasta e arquivo ### Listar tarefas derivadas da pasta A solicitação **`GET listar tarefas derivadas da pasta`** chama **[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)** para listar as tarefas derivadas em uma pasta especificada. Neste caso, a pasta raiz do projeto definida como sua variável de ambiente **`FOLDER_ID`**. Você pode usar os seguintes parâmetros de consulta opcionais para refinar a resposta: | Parâmetro | Tipo | Descrição | | ------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`page_size`** | Número inteiro | Limita o número de pastas retornadas de **1 a 100. O padrão é 50** | | **`type`** | String | Filtra as tarefas derivadas da pasta por tipo de recurso: **`file`** ou **`folder`** | | **`after`** | String | Cursor opaco para solicitações que retornam resultados paginados. \*\*Isso é gerado automaticamente e retornado no objeto `links` da resposta anterior.\*\*Não foi criado para ser legível por humanos. | | **`include_total_count`** | Booleano | Retorna a contagem total de todas as entidades. **O padrão é False** | | **`include`** | Enum | Anexa dados adicionais a cada objeto retornado, como `creator`, `project`, `media_links`. Para obter uma lista completa de parâmetros compatíveis, consulte a **[Referência da API](/platform/api-reference/folders/index#request.query.include)** | Uma solicitação bem-sucedida retornará um status **`200 OK`** e um corpo de resposta semelhante ao exemplo abaixo. **Exemplo de resposta** ``` { "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 } ``` > **Testar o parâmetro \\after\\** > > Se estiver testando resultados paginados, localize o objeto **`links`** na resposta: > > * Na URL da propriedade **`next`**, copie apenas o valor de string após **`after=`** > > * Defina isso como o valor do parâmetro de consulta **`after`** em sua próxima solicitação. > > * **Cuidado com a codificação dupla!**Se a URL contiver caracteres codificados (exemplo: %3D%3D), substitua-os pela versão original (**==**). O Postman interpreta sua entrada literalmente e pode codificá-la duas vezes, levando a um erro **`422`** --- ### Criar um arquivo - upload local A solicitação **`POST criar arquivo - upload local`** chama **[`/v4/accounts/:account_id/folders/:folder_id/files/local_upload`](/platform/v4/api-reference/files/create-local-upload)** para fazer upload de um arquivo local em uma pasta especificada. Uploads locais exigem duas ou mais solicitações, dependendo do tamanho do arquivo. Para seu primeiro teste, use um arquivo pequeno (menos de 10 MB) para limitar o processo a uma única URL de upload. #### Criar recurso de arquivo placeholder No editor de solicitação, selecione a guia **Corpo** para definir o nome e o tamanho do arquivo (especificado em **bytes**) dentro do objeto `dados`. Uma solicitação bem-sucedida retornará um status **`201 Criado`** e um corpo de resposta semelhante ao exemplo abaixo. **Exemplo de resposta** ``` { "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" } ] } } ``` Esta chamada criou um recurso de arquivo placeholder na pasta especificada. Use a URL de upload pré-assinada na matriz `upload_urls` na resposta para concluir o upload na próxima etapa. #### Fazer upload do conteúdo do arquivo Clique na URL na matriz `upload_urls` em sua resposta para abrir uma nova guia de solicitação no Postman. Altere o método de solicitação para **`PUT`**. No editor de solicitação, selecione a aba **Cabeçalho** para adicionar os seguintes cabeçalhos à sua solicitação: * **`x-amz-acl`:`private`*** **`Content-Type`**: deve corresponder exatamente ao tipo da extensão especificada no nome do arquivo **`IMG.png`** deve usar **`image/png`**) ![alt image](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) No editor de solicitação, selecione a aba **Corpo** e clique na opção **binário** para selecionar seu arquivo. Após selecionar, clique em **Enviar** para concluir sua solicitação. Uma solicitação bem-sucedida retornará um status **`200 OK`**, confirmando que seu arquivo foi carregado. Depois que for feito upload do arquivo, o pipeline de mídia do Frame.io processará automaticamente a transcodificação e a geração de miniatura. Para arquivos maiores, pode levar alguns instantes para o arquivo passar do estado **`created`** para **`ready`**. --- ### Criar um arquivo - upload remoto A solicitação **` POST criar arquivo - upload remot`** chama **[`/v4/accounts/:account_id/folders/:folder_id/files/remote_upload`](/platform/v4/api-reference/files/create-remote-upload)** para transferir um arquivo externo para uma pasta especificada usando uma URL de origem fornecida. No editor de solicitações, selecione a guia **Corpo** para definir o nome e a URL de origem do arquivo dentro do objeto `dados`. Uma solicitação bem-sucedida retornará um status **`202 Accepted`** e um corpo de resposta semelhante ao exemplo abaixo. **Exemplo de resposta** ``` { "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" } } ```