Guias

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

Este guia pressupõe que você gerou credenciais para a API. Se não fez isso, comece por aqui

1

Criar uma conta do Postman e escolher sua configuração

Crie sua conta do Postman em postman.com e escolha sua configuração. Você pode baixar o aplicativo Postman aqui ou usar o Postman na Web.

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 imagealt image

Veja abaixo uma tabela com a descrição de cada variável encontrada nos ambientes Padrão e Preparo da coleção:

VariávelDescriçãoComo recuperarAmbiente
BASE_URLURL base para todas as solicitações da API V4Pré-configurado, não editarPadrão
IMS_BASE_URLURL base de autenticação do Adobe IMSPré-configurado, não editarPadrão, Preparo
IMS_CLIENT_IDID do cliente do seu aplicativo Frame.ioPágina de credenciais no Adobe Developer ConsolePreparo
IMS_CLIENT_SECRETSegredo do cliente do seu aplicativo Frame.ioPágina de credenciais no Adobe Developer ConsolePreparo
FOLDER_IDIdentificador exclusivo para a pasta de destinoRetornado no objeto de resposta da pastaPadrão
WEBHOOK_IDIdentificador exclusivo para um webhook configuradoRetornado no objeto de resposta do webhookPadrão
ASSET_IDIdentificador exclusivo para um ativo de arquivo ou pastaretornado no objeto de resposta de arquivo ou pastaPadrão
SHARE_IDIdentificador exclusivo para um link de compartilhamentoretornado no objeto de resposta de compartilhamentoPadrão

Configurar autorização

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 Guia de autenticação.

As variáveis de ambiente IMS_CLIENT_ID e IMS_CLIENT_SECRET devem ser definidas com os valores recuperados dos detalhes de credenciais do seu projeto no Adobe Developer Console.

alt image
Na seção Detalhes de credenciais do projeto, defina o URI de redirecionamento e o Padrão de URL de redirecionamento para o ponto de acesso de callback público do Postman: URI de redirecionamento

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

Padrão de URI de redirecionamento

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

Depois que as variáveis de ambiente forem definidas e salvas, a próxima etapa é configurar as definições de autorização.Para isso, clique no ícone Coleções na parte superior da barra lateral esquerda para abrir o navegador de coleções.No navegador de coleções, selecione a raiz da coleção Frame.io V4 Developer API, geralmente intitulada ‘Frame.io Developer API Collection’ seguida pelo nome do fork, e selecione a guia Autorizaçãoalt image.OAuth scopes são pré-configurados na coleção.Com as variáveis de ambiente definidas, use o botão <strong>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 ****](</span)esta seção do guia de introdução para obter informações sobre erros e avisos.Exemplo de resposta

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

Obter o ID da conta

account_id é um parâmetro de caminho obrigatório para a maioria dos pontos de acesso da API V4 e será necessário para testar outras solicitações. Você pode obter account_id com a solicitação GET Listar contas, localizada na pasta Contas da coleção. **Referência da API**Resposta de exemplo

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

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 <strong>](</span)este guia**.

Listar espaços de trabalho

A solicitação GET listar espaços de trabalho na pasta Espaços de trabalho chama /v4/accounts/:account_id/workspaces e retorna uma lista de espaços de trabalho aos quais sua conta tem acesso. Algumas operações de Projeto exigem workspace_id como parâmetro de caminho, então salve primeiro seu ID de espaço de trabalho se pretende listar ou recuperar Projetos. Uma solicitação bem-sucedida retornará um status 200 OK e um corpo de resposta semelhante ao exemplo abaixo. Exemplo de resposta

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

Criar um espaço de trabalho

A solicitação POST criar workspace chama /v4/accounts/:account_id/workspaces para criar um novo espaço de trabalho para sua conta. No editor de solicitação, selecione a guia Corpo para definir o nome do espaço de trabalho 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": {
    "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"
  }
}

Atualizar um espaço de trabalho

A solicitação PATCH atualizar workspace chama /v4/accounts/:account_id/workspaces/:workspace_id para atualizar o nome de um espaço de trabalho. No editor de solicitação, selecione a guia Corpo para definir o novo nome do espaço de trabalho dentro do objeto dados. Uma solicitação bem-sucedida retornará um status 200 OK e um corpo de resposta semelhante ao exemplo abaixo. Exemplo de resposta

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

Criação de um projeto

A solicitação POST criar projeto chama /v4/accounts/:account_id/workspaces/:workspace_id/projects para criar um novo Projeto em um espaço de trabalho especificado. No editor de solicitação, selecione a guia Corpo para definir o nome do projetoo dentro do objeto dados. A propriedade opcional restricted é um booleano usado para criar um Projeto restrito. Uma solicitação bem-sucedida retornará um status 201 Criado e um corpo de resposta semelhante ao exemplo abaixo. Exemplo de resposta

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

Copie o root_folder_id da resposta e defina-o como o valor para a variável de ambiente FOLDER_ID. Você precisará disso nas seções restantes deste guia.

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)

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 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âmetroTipoDescrição
page_sizeNúmero inteiroLimita o número de pastas retornadas de
1 a 100. O padrão é 50
typeStringFiltra as tarefas derivadas da pasta por tipo de recurso: file ou folder
afterStringCursor 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_countBooleanoRetorna a contagem total de todas as entidades.
O padrão é False
includeEnumAnexa 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

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 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.

    1

    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.

    2

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