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:

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

$
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

1
import frameio
2
3
client = frameio.Frameio(auth="<YOUR_TOKEN>")
4
5
file = client.files.get(
6
    file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
7
    include=["media_links.thumbnail", "media_links.original"]
8
)
9
10
print(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

Retorna URLs assinadas que apontam para o arquivo original exatamente como foi feito upload — sem processamento, sem conversão.

Campos

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

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "original": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "inline_url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

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

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

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "thumbnail": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

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

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

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "high_quality": {
8
        "download_url": "https://s3.amazonaws.com/..."
9
      }
10
    }
11
  }
12
}

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

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

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "efficient": {
8
        "download_url": "https://s3.amazonaws.com/..."
9
      }
10
    }
11
  }
12
}

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.

Campos

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.

Exemplo de solicitação

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "interview-clip.mp4",
5
    "type": "file",
6
    "media_links": {
7
      "video_h264_180": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

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.

Campos

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

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet

Exemplo de resposta

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "interview-clip.mp4",
5
    "type": "file",
6
    "media_links": {
7
      "scrub_sheet": {
8
        "download_url": "https://assets.frame.io/...",
9
        "url": "https://assets.frame.io/...",
10
        "metadata": {
11
          "tile_x": 10,
12
          "tile_y": 10,
13
          "thumb_width": 160,
14
          "thumb_height": 90,
15
          "padding": 1,
16
          "frames": 100
17
        }
18
      }
19
    }
20
  }
21
}

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:

1
function getFrameOffset(frameIndex, metadata) {
2
  const { tile_x, thumb_width, thumb_height, padding } = metadata;
3
4
  const col = frameIndex % tile_x;
5
  const row = Math.floor(frameIndex / tile_x);
6
7
  return {
8
    x: col * (thumb_width + padding),
9
    y: row * (thumb_height + padding),
10
    width: thumb_width,
11
    height: thumb_height,
12
  };
13
}

Em seguida, você pode usar CSS background-position para mostrar o bloco correto da folha de sprites:

1
function applyFrameToElement(el, frameIndex, scrubSheet) {
2
  const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata);
3
4
  el.style.backgroundImage = `url(${scrubSheet.url})`;
5
  el.style.backgroundPosition = `-${x}px -${y}px`;
6
  el.style.width = `${width}px`;
7
  el.style.height = `${height}px`;
8
}

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:

1
function positionToFrameIndex(currentSeconds, durationSeconds, metadata) {
2
  const progress = currentSeconds / durationSeconds;
3
  return Math.min(
4
    Math.floor(progress * metadata.frames),
5
    metadata.frames - 1
6
  );
7
}

Como combinar vários includes

Você pode solicitar vários includes em uma única chamada de API:

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "thumbnail": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      },
11
      "original": {
12
        "download_url": "https://s3.amazonaws.com/...",
13
        "inline_url": "https://s3.amazonaws.com/..."
14
      }
15
    }
16
  }
17
}

Como escolher o include certo

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.