> 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. # Links de mídia O Frame.io armazena e processa arquivos enviados para seus projetos — imagens, vídeos, PDFs e muito mais. Ao recuperar um arquivo via API, a resposta base inclui metadados principais como nome do arquivo, status e um `view_url` para abri-lo no aplicativo Frame.io. Para acessar o conteúdo real do arquivo — o original, uma visualização ou diferentes renderizações de qualidade — você usa **includes**. Este guia explica os includes de link de mídia disponíveis nos pontos de acesso **List Files** e **Get File**, o que cada um retorna e quando usar cada um. ## O que são includes? Includes são campos opcionais que você pode solicitar junto com uma resposta de arquivo. Por padrão, a API retorna apenas metadados principais do arquivo — nome, status, tipo, carimbos de data e hora e `view_url`. Os includes permitem optar por dados adicionais, mantendo as respostas leves quando você não precisa de tudo. ### Como adicionar includes Passe uma lista separada por vírgulas de nomes de include como o parâmetro de consulta `include` em qualquer solicitação **Get File** ou **List Files**: **`Include único`** ```bash title="Include único" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` **`Vários includes`** ```bash title="Vários includes" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` **`Includes em List Files`** ```bash title="Includes em List Files" GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail ``` Os includes funcionam da mesma forma nos pontos de acesso de arquivo único e de lista. Quando usados em List Files, os includes são resolvidos para todos os arquivos na resposta. ### Exemplos de SDK **`SDK para Python`** ```python title="SDK para Python" import frameio client = frameio.Frameio(auth="") file = client.files.get( file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", include=["media_links.thumbnail", "media_links.original"] ) print(file.media_links.thumbnail.url) ``` **`SDK para TypeScript`** ```typescript title="SDK para TypeScript" import Frameio from "frameio"; const client = new Frameio({ auth: "" }); const file = await client.files.get("93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", { include: ["media_links.thumbnail", "media_links.original"], }); console.log(file.media_links?.thumbnail?.url); ``` Includes que não são solicitados são omitidos completamente da resposta. ## Visão geral dos includes de link de mídia #### media\_links.original O arquivo original carregado, exatamente como foi carregado #### media\_links.thumbnail Uma imagem de visualização PNG para fins de exibição #### media\_links.high\_quality A melhor representação processada disponível #### media\_links.efficient A menor representação disponível para casos de uso com pouca largura de banda #### media\_links.video\_h264\_180 Uma transcodificação de vídeo H264 180p de baixa resolução para streaming e reprodução #### media\_links.scrub\_sheet Uma folha de sprite WebP de miniaturas de quadros de vídeo para criar interface de busca ## media\_links.original Retorna URLs assinadas que apontam para o **arquivo original exatamente como foi feito upload** — sem processamento, sem conversão. ### Campos | Campo | Tipo | Descrição | | | -------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL assinada que força o download de um arquivo (`Content-Disposition: attachment`) | | `inline_url` | string \\ | null | URL assinada que abre o arquivo diretamente no navegador (`Content-Disposition: inline; filename=`) | ### Quando usar Use `media_links.original` quando precisar do arquivo de origem — por exemplo, para permitir que um usuário baixe o MOV, MP4, MXF, AVI, PSD, PNG ou TIFF original, ou para passar os bytes originais para outro sistema. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "original": { "download_url": "https://s3.amazonaws.com/...", "inline_url": "https://s3.amazonaws.com/..." } } } } ``` > **Warning** > > Essas URLs são **URLs S3 assinadas temporárias** — elas expiram. Não armazene essas URLs em cache nem salve-as; solicite uma nova URL sempre que precisar. ## media\_links.thumbnail Retorna uma **imagem de visualização PNG** do ativo, limitada a 540 px de altura. Esta é uma representação processada, não o arquivo original, e marcas-d’água podem ser aplicadas dependendo das configurações da sua conta. ### Campos | Campo | Tipo | Descrição | | | -------------- | --------- | --------- | --------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL assinada que força o download da miniatura PNG | | `url` | string \\ | null | URL assinada que serve a miniatura PNG inline sem cabeçalho `Content-Disposition` | ### Quando usar Use `media_links.thumbnail` quando precisar **exibir uma visualização visual** do ativo. Por exemplo, em uma visualização em grade, uma galeria ou um seletor de arquivos. Ela carrega mais rápido do que o original e sempre está em um formato PNG seguro para a Web. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "thumbnail": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.high\_quality Retorna uma URL de download para a **melhor renderização processada disponível** do ativo. O Frame.io processa uploads por meio de uma escala de resolução que chega a até 2160p. A API retorna a renderização mais alta disponível **no momento da solicitação**. Portanto, se apenas uma representação 540p tiver terminado de ser processada quando você fizer a solicitação, a API retornará 540p até que as representações superiores estejam prontas. ### Campos | Campo | Tipo | Descrição | | | -------------- | --------- | --------- | ----------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL assinada para a representação de maior qualidade disponível no momento da solicitação | ### Quando usar Use `media_links.high_quality` quando quiser a **versão de melhor qualidade sem precisar do original**. Por exemplo, para exportar uma representação em alta resolução para processamento posterior ou apresentar uma visualização em resolução total. Se precisar da mais alta qualidade possível, verifique o campo `status` do arquivo e solicite essa inclusão quando o arquivo estiver `pronto` para garantir que a escala de resolução completa foi processada. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "high_quality": { "download_url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.efficient Retorna uma URL de download para a **menor renderização processada disponível**. Este é o oposto de `high_quality`. O Frame.io escolhe a renderização de menor resolução disponível. ### Campos | Campo | Tipo | Descrição | | | -------------- | --------- | --------- | ------------------------------------------------------ | | `download_url` | string \\ | null | URL assinada para a menor/mais eficiente representação | ### Quando usar Use `media_links.efficient` quando **largura de banda ou tamanho do arquivo importam mais que qualidade**. Por exemplo, ao gerar visualizações rápidas em um ambiente com baixa largura de banda ou alimentar um pipeline de miniaturas que não precisa de resolução total. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "efficient": { "download_url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.video\_h264\_180 Retorna URLs de streaming e download para uma **transcodificação de vídeo H264 em baixa resolução, 180p**, do ativo. > **Warning** > > Este é um include legado. Ele será `null` se uma transcodificação 180p não tiver sido gerada para o ativo. Para a maioria dos casos de uso, prefira `media_links.efficient`, que seleciona a melhor representação de baixa qualidade disponível em vez de depender da existência de uma transcodificação específica. ### Campos | Campo | Tipo | Descrição | | | -------------- | --------- | --------- | ---------------------------------------------- | | `download_url` | string \\ | null | URL assinada para baixar o vídeo H264 180p | | `url` | string \\ | null | URL assinada para streaming do vídeo H264 180p | ### Quando usar Use `media_links.video_h264_180` quando precisar especificamente de uma transcodificação H264 180p garantida. Por exemplo, ao integrar com um player legado ou um pipeline que exija exatamente esse formato. Se a transcodificação não existir para determinado ativo, ambas as URLs serão `null`. > **Warning** > > Não há áudio incluído no arquivo video\_h264\_180. Ele foi projetado para ser usado em visualizações muito eficientes quando necessário. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180 ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "interview-clip.mp4", "type": "file", "media_links": { "video_h264_180": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.scrub\_sheet Retorna uma **folha de sprites WebP**, uma única imagem contendo uma grade de miniaturas de quadros de vídeo amostrados uniformemente ao longo da duração do vídeo. Isso é usado para criar uma interface de scrubbing de vídeo, em que o player mostra um quadro de visualização conforme o usuário arrasta pela linha do tempo. > **Info** > > Planilhas de scrub são geradas **apenas para ativos de vídeo**. O include retornará URLs `null` para imagens, PDF e outros arquivos que não sejam vídeos. ### Campos | Campo | Tipo | Descrição | | | -------------------------- | --------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL assinada para baixar a folha de sprites WebP | | `url` | string \\ | null | URL assinada para carregar a folha de sprites WebP inline | | `metadados` | object \\ | null | Informações de layout dos blocos para extrair quadros individuais (somente API experimental) | | Campos de **`metadados`:** | | | | | Campo | Tipo | Descrição | | | --- | --- | --- | | | `tile_x` | integer | Número de colunas de miniaturas na grade | | | `tile_y` | integer | Número de linhas de miniaturas na grade | | | `thumb_width` | integer | Largura de cada miniatura em pixels | | | `thumb_height` | integer | Altura de cada miniatura em pixels | | | `padding` | integer | Espaço em pixels entre miniaturas | | | `frames` | integer | Número total de quadros amostrados na folha | | ### Quando usar Use `media_links.scrub_sheet` ao criar um player de vídeo personalizado ou uma interface de linha do tempo que precise mostrar uma miniatura de visualização conforme o usuário faz scrubbing. Em vez de fazer uma solicitação separada para cada quadro, a folha de sprites agrupa todos os quadros de visualização em um único download de imagem. ### Exemplo de solicitação ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet ``` ### Exemplo de resposta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "interview-clip.mp4", "type": "file", "media_links": { "scrub_sheet": { "download_url": "https://assets.frame.io/...", "url": "https://assets.frame.io/...", "metadata": { "tile_x": 10, "tile_y": 10, "thumb_width": 160, "thumb_height": 90, "padding": 1, "frames": 100 } } } } } ``` ### Como extrair um quadro da folha de sprites A folha de sprites é uma grade de `tile_x` colunas × `tile_y` linhas. Para exibir a miniatura de determinado índice de quadro (base zero), calcule sua posição dentro da imagem: ```javascript function getFrameOffset(frameIndex, metadata) { const { tile_x, thumb_width, thumb_height, padding } = metadata; const col = frameIndex % tile_x; const row = Math.floor(frameIndex / tile_x); return { x: col * (thumb_width + padding), y: row * (thumb_height + padding), width: thumb_width, height: thumb_height, }; } ``` Em seguida, você pode usar CSS `background-position` para mostrar o bloco correto da folha de sprites: ```javascript function applyFrameToElement(el, frameIndex, scrubSheet) { const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata); el.style.backgroundImage = `url(${scrubSheet.url})`; el.style.backgroundPosition = `-${x}px -${y}px`; el.style.width = `${width}px`; el.style.height = `${height}px`; } ``` Para mapear uma posição de reprodução (em segundos) para um índice de quadro, use a duração total do vídeo e o número de quadros na folha: ```javascript function positionToFrameIndex(currentSeconds, durationSeconds, metadata) { const progress = currentSeconds / durationSeconds; return Math.min( Math.floor(progress * metadata.frames), metadata.frames - 1 ); } ``` > **Info** > > O campo `metadata` está disponível apenas na versão experimental da API. Na API v4 estável, `scrub_sheet` retorna apenas `download_url` e `url`. ## Como combinar vários includes Você pode solicitar vários includes em uma única chamada de API: ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "thumbnail": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." }, "original": { "download_url": "https://s3.amazonaws.com/...", "inline_url": "https://s3.amazonaws.com/..." } } } } ``` ## Como escolher o include certo | Objetivo | Include a ser usado | | ---------------------------------------------------------------------- | ------------------------------------------ | | Mostrar uma imagem de visualização na sua interface | `media_links.thumbnail` | | Permitir que um usuário baixe o arquivo original | `media_links.original` | | Abrir o arquivo original diretamente no navegador | `media_links.original` → `inline_url` | | Obter a representação de melhor qualidade para exportação | `media_links.high_quality` | | Obter uma representação pequena para uso com baixa largura de banda | `media_links.efficient` | | Fazer streaming ou baixar um vídeo em baixa resolução (legado) | `media_links.video_h264_180` | | Criar uma interface de scrubbing de vídeo com visualizações de quadros | `media_links.scrub_sheet` | | Direcionar um usuário para o arquivo no Frame.io | Use `view_url` da resposta base do arquivo | > **Info** > > `view_url` — disponível em todas as respostas de arquivo sem precisar de um include. É um deep link permanente para o aplicativo Web do Frame.io. Não **é** uma URL de mídia; ela abre a interface do Frame.io e não expira. Use-a quando quiser direcionar um usuário para revisar ou comentar em um ativo diretamente no Frame.io, não quando precisar servir ou baixar o arquivo programaticamente. ## Disponibilidade de includes Os includes de links de mídia só são preenchidos depois que o Frame.io conclui o processamento do arquivo enviado. Se você solicitar um include imediatamente após o upload, as URLs poderão ser `null` enquanto a transcodificação estiver em andamento. Verifique o campo de `status` no objeto de arquivo. Os includes estarão disponíveis quando o status for `ready`.