미디어 링크

Frame.io는 이미지, 비디오, PDF 등 귀하의 프로젝트에 업로드된 파일들을 저장하고 처리합니다. API를 통해 파일을 가져올 때 기본 응답에는 파일 이름, 상태, 그리고 Frame.io 앱에서 열어보기 위한 view_url과 같은 핵심 메타데이터가 포함됩니다. 원본, 미리 보기 또는 다른 품질의 렌디션과 같은 실제 파일 콘텐츠에 액세스하려면 include를 사용합니다. 이 가이드에서는 파일 나열 및 파일 가져오기 엔드포인트에서 사용할 수 있는 미디어 링크 include와 각각 반환하는 내용, 그리고 사용 시기에 대해 설명합니다.

include란 무엇인가요?

include는 파일 응답과 함께 요청할 수 있는 선택적인 필드입니다. 기본적으로 API는 이름, 상태, 유형, 타임스탬프, view_url과 같은 핵심 파일 메타데이터만 반환합니다. include를 사용하면 추가 데이터를 선택적으로 받아볼 수 있어, 모든 정보가 필요하지 않을 때 응답을 가볍게 유지할 수 있습니다.

include 추가 방법

파일 가져오기 또는 파일 나열 요청에 include 쿼리 매개변수로 쉼표로 구분된 include 이름 목록을 전달합니다.

$
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

include는 단일 파일 가져오기 엔드포인트와 목록 나열 엔드포인트 모두에서 동일한 방식으로 작동합니다. 파일 나열에 사용할 경우, 응답에 포함된 모든 파일에 대해 include가 적용됩니다.

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)

요청하지 않은 include는 응답에서 완전히 생략됩니다.

미디어 링크 include 개요

media_links.original

어떠한 처리나 변환도 거치지 않고 업로드된 그대로의 원본 파일을 가리키는 서명된 URL을 반환합니다.

필드

사용 시기

사용자에게 원본 MOV, MP4, MXF, AVI, PSD, PNG 또는 TIFF를 다운로드하게 하거나, 다른 시스템에 원본 바이트를 전달하는 등 소스 파일이 필요할 때 media_links.original을 사용합니다.

요청 예시

$
GET /v4/accounts/{account_id}/files/{file_id}?include=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
      "original": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "inline_url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

media_links.thumbnail

에셋의 PNG 미리 보기 이미지를 반환하며, 높이는 540px로 제한됩니다. 이는 원본 파일이 아닌 처리된 렌디션이며, 계정 설정에 따라 워터마크가 적용될 수 있습니다.

필드

사용 시기

그리드 뷰, 갤러리 또는 파일 피커와 같이 에셋의 시각적 미리 보기를 표시해야 할 때 media_links.thumbnail을 사용합니다. 원본보다 빠르게 로드되며 항상 웹에서 안전하게 사용할 수 있는 PNG 형식입니다.

요청 예시

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

응답 예시

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

사용 가능한 최상의 화질로 처리된 에셋 렌디션의 다운로드 URL을 반환합니다. Frame.io는 최대 2160p까지 해상도를 단계별로 높여가며 업로드를 처리합니다. API는 요청 시점에 사용 가능한 가장 높은 렌디션을 반환합니다. 따라서 요청할 때 540p 렌디션만 처리가 완료된 상태라면, 더 높은 렌디션이 준비될 때까지 API는 540p를 반환합니다.

필드

사용 시기

다운스트림 처리를 위해 고해상도 렌디션을 내보내거나 전체 해상도 미리 보기를 제공하는 등 원본 파일 없이 최고의 화질 버전을 원할 때 media_links.high_quality를 사용합니다. 최고의 화질이 필요하다면 파일의 status 필드를 확인하고, 파일 처리가 완료되어(ready) 전체 해상도의 렌디션이 모두 처리된 후에 이 include를 요청하세요.

요청 예시

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

응답 예시

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

사용 가능한 처리된 렌디션 중 가장 작은 용량의 다운로드 URL을 반환합니다. 이는 high_quality와 반대로, Frame.io가 사용 가능한 가장 낮은 해상도의 렌디션을 선택합니다.

필드

사용 시기

저대역폭 환경에서 빠른 미리 보기를 생성하거나 전체 해상도가 필요 없는 썸네일 파이프라인에 제공하는 등, 품질보다 대역폭이나 파일 크기가 더 중요할 때 media_links.efficient를 사용합니다.

요청 예시

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

응답 예시

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

에셋의 저해상도 180p H264 비디오 트랜스코드에 대한 스트리밍 및 다운로드 URL을 반환합니다.

필드

사용 시기

정확히 180p H264 형식을 요구하는 기존 플레이어 또는 파이프라인과 연동하는 등 반드시 180p H264 트랜스코드가 필요할 때만 media_links.video_h264_180을 사용합니다. 특정 에셋에 대해 이 트랜스코드가 존재하지 않으면 두 URL 모두 null이 됩니다.

요청 예시

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

응답 예시

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

WebP 스프라이트 시트(비디오 재생 시간 동안 균일하게 샘플링된 비디오 프레임 썸네일 그리드가 포함된 단일 이미지)를 반환합니다. 이는 사용자가 타임라인을 드래그할 때 플레이어에 미리 보기 프레임을 보여주는 비디오 스크러빙 UI를 구축하는 데 사용됩니다.

필드

사용 시기

사용자가 스크러빙할 때 미리 보기 썸네일을 표시해야 하는 사용자 지정 비디오 플레이어 또는 타임라인 UI를 구축할 때 media_links.scrub_sheet를 사용합니다. 각 프레임에 대해 개별적인 요청을 보내는 대신, 스프라이트 시트는 모든 미리 보기 프레임을 단일 이미지 다운로드로 묶어 제공합니다.

요청 예시

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

응답 예시

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
}

스프라이트 시트에서 프레임 추출하기

스프라이트 시트는 tile_x(열) × tile_y(행)의 그리드로 구성됩니다. 특정 프레임 인덱스(0부터 시작)의 썸네일을 표시하려면 이미지 내에서의 위치를 계산하세요.

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
}

그런 다음 CSS의 background-position을 사용하여 스프라이트 시트에서 올바른 타일을 표시할 수 있습니다.

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
}

재생 위치(초 단위)를 프레임 인덱스에 매핑하려면, 총 비디오 재생 시간과 시트의 프레임 수를 사용하세요.

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
}

여러 개의 include 결합하기

단일 API 호출에서 여러 include를 한 번에 요청할 수 있습니다.

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

상황에 맞는 include 선택

include 가용성

미디어 링크 include는 Frame.io가 업로드된 파일의 처리를 완료한 후에만 정보가 채워집니다. 업로드 직후에 include를 요청하면, 트랜스코딩이 진행되는 동안 URL이 null로 표시될 수 있습니다. 파일 오브젝트의 status 필드를 확인하세요. 상태가 ready가 되면 include를 사용할 수 있습니다.