> This page is for Plataforma, version Herdado. > 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. # Fazer upload de ativos # Visão geral Este tutorial aborda como fazer upload de ativos no Frame.io.O Frame.io pode lidar com todos os tipos de arquivo, não apenas vídeos, mas também scripts, imagens, mapas e arquivos de referência.Em termos mais técnicos, um ativo no Frame.io é uma representação robusta de um arquivo no S3 e seu contexto no Frame.io, incluindo transcodificações, contexto de usuário/equipe/projeto e metadados.Para obter mais informações sobre ativos, consulte a definição de recursos. ## Hierarquias principais Também é útil saber como o Frame.io estrutura seus modelos principais. **Contas**, às quais **Usuários** pertencem, têm muitos **Projetos**, que contêm **Ativos**.**Equipes** estão disponíveis apenas para contas corporativas e fornecem um nível adicional de separação lógica.Os ativos não "sabem" a qual equipe pertencem, apenas a qual projeto e conta, mas os projetos são estritamente de propriedade de equipes, não de contas, tornando as equipes parte integral do processo de upload de ativos. ## Pré-requisitos Para este tutorial, você precisará de: * Uma conta Frame.io com um token de desenvolvedor (tokens são explicados abaixo) * [Frame.io Python SDK](https://github.com/Frameio/python-frameio-client) ## Fazer upload de um ativo Esta seção orienta você pelas etapas para fazer upload de um ativo. 1. Crie um token de desenvolvedor em [developer.frame.io](/) com os seguintes escopos: | Escopo | Motivo | | ---------- | ---------- | | **Contas:** Leitura | Buscar a lista de contas para o usuário solicitante. | | **Equipes:** Leitura | Buscar equipes disponíveis para a conta desejada. | | **Projetos:** Leitura | Buscar projetos disponíveis para a equipe desejada. | | **Ativos:** Criação, leitura | Criar o novo registro de ativo e buscar ativos disponíveis para navegar pela estrutura de pastas no projeto. | Consulte as instruções [**aqui**](doc:get-a-developer-token). 2. Localize um destino para o ativo.No mínimo, os ativos precisam ser colocados em um **Projeto**.Você precisa recuperar o ID do ativo raiz (`root_asset_id`) de um projeto ou um ID de ativo de uma pasta para especificar a localização na hierarquia de arquivos para a qual deseja fazer upload. Não é possível fazer upload apenas com um ID de projeto.Para fazer upload na raiz do projeto, especifique o `root_asset_id` na solicitação. Em geral, você precisa recuperar (na ordem especificada): * ID(s) de conta e escolher uma conta * ID(s) de equipe e escolher uma equipe * projetos associados a uma equipe * o ID do projeto para o projeto com o qual você quer trabalhar * o ID do ativo raiz ou um ID de pasta Você pode fazer upload diretamente na raiz de um projeto usando o `root_asset_id`. ### Listar ativos Para escolher onde você quer fazer upload do novo ativo, você pode usar a API para listar todos os ativos em um projeto ou pasta dentro de um projeto.Se um ativo é uma *pasta*, ele contém ativos filhos, que também podem ser arquivos e pastas.Ao listar informações de ativos, você pode usar qualquer ID de ativo, mas se quiser revisar tudo associado a um projeto, use o `root_asset_id`. ``` ``` python-sdk from frameioclient import FrameioClient import os ASSET_ID = "" TOKEN = "" client = FrameioClient(TOKEN) response_list = client.assets.get_children(ASSET_ID) assets = response_list.results for item in assets: print(item['id'], item['name']) ``` ``` ```python-sdk # Code sample uses the Python SDK: https://github.com/Frameio/python-frameio-client from frameioclient import FrameioClient client = frameioclient("FRAMEIO_TOKEN) asset = client.assets.upload( destination_id="PARENT_ASSET_ID", filepath="./my_file.mov" ) # Create a folder: asset = client.assets.create_folder( parent_asset_id=PARENT_ASSET_ID, name="My Awesome Folder" ) ``` Na lista de ativos retornada, você pode usar um ID para qualquer ativo que seja uma pasta, ou o ID do ativo raiz.Você vai usar este ID para marcar onde quer fazer upload do novo ativo. ### Fazer upload de ativo Neste exemplo, vamos fazer upload de um novo arquivo.Você envia a solicitação com as seguintes informações: | Parâmetro | Descrição | | ---------- | ---------- | | `filesize` | Insira o tamanho do arquivo que deseja fazer upload | | `filetype` | Escolha o tipo de arquivo que está fazendo upload.As opções incluem vídeo e imagem.Exemplos: `video/mp4`, `image/png`. | | `name` | Insira um string que representa o nome do arquivo, sem espaços. | | `type` | Representa se você está usando um `file` ou uma `folder`.Uma pilha de versões é quando você empilha vários arquivos uns sobre os outros. | Se quiser criar uma nova pasta, não precisa incluir `filesize` ou `filetype` na solicitação.Para uma solicitação `cURL`, você pode fazer upload rapidamente de um ativo no Frame.io incluindo um link para o arquivo usando o parâmetro `"source": { "url":"URL_FOR_VIDEO" }`.O link deve ser publicamente acessível.Caso contrário, você pode usar o Python SDK, que quebra o arquivo em um fragmento para cada link de upload. ```cURL curl --request POST \ --url https://api.frame.io/v2/assets/<asset_id>/children \ --header 'authorization: Bearer<dev_token>' \ --header 'content-type: application/json' \ --data '{"filesize":200000,"filetype":"video/mp4","name":"test","source":{"url":"URL_FOR_VIDEO"},"type":"file"}' ``` **`Python`** ```python title="Python" filesize = 30000000 upload_urls = ["https://...", "https://...", "https://..."] chunk_size = filesize / len(upload_urls) start_byte = 0 # Set to 0 to start for i, url in enumerate(upload_urls): end_byte = chunk_size * (i + 1) upload_chunk(url=url, start_byte, end_byte) start_byte = start_byte + chunk_size ``` Os URLs retornadas da chamada de API de criação de ativos são pré-assinadas para autorizar o upload, mas expiram após 24 horas. # Criar seu próprio carregador de arquivos Se quiser criar seu próprio carregador, para melhor desempenho, recomenda-se fazer upload de blocos em paralelo.Cada bloco deve ser `PUT` diretamente para os URLs do Amazon S3 fornecidos na resposta da API do Frame.io.Os blocos de arquivo devem corresponder à ordem dos `upload_urls` fornecidos, pois eles *determinam a sequência do ativo final concatenado e transcodificado.* Isso significa que o 1º URL recebe o 1º bloco, o 2º URL recebe o 2º bloco, e assim por diante. #### Exemplo de pseudocódigo **`title="Python"`** ```python title="Python" filesize = 30000000 upload_urls = ["https://...", "https://...", "https://..."] chunk_size = filesize / len(upload_urls) start_byte = 0 # Set to 0 to start for i, url in enumerate(upload_urls): end_byte = chunk_size * (i + 1) upload_chunk(url=url, start_byte, end_byte) start_byte = start_byte + chunk_size ``` Os cabeçalhos para cada solicitação ao S3 devem incluir o `filetype` do novo ativo exatamente como foi retornado da chamada inicial para a API do Frame.io, bem como um cabeçalho de privacidade adicional: ```text PUT https://frameio-uploads-production.s3/etc/etc Content-Type: video/mp4 x-amz-acl: private ``` Você pode ver um exemplo de como isso é tratado em nosso SDK Python [aqui](https://github.com/Frameio/python-frameio-client/blob/master/examples/upload_asset.py). Note que quaisquer erros neste estágio virão diretamente da AWS e, portanto, serão formatados como XML, e não no tratamento de erro JSON padrão do Frame.io.Geralmente recomendamos criar lógica de repetição para esses uploads em qualquer uso de produção, pois arquivos com upload incompleto (ou seja, arquivos com fragmentos ausentes) falharão na transcodificação e exibição no Frame.io Pronto!Depois de concluir as chamadas `PUT` para os `upload_url`s, você terá um novo ativo no Frame.io.