> This page is for Plattform, 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 > - Vorgängerversion: 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. # Medien-Links In Frame.io werden Dateien gespeichert und verarbeitet, die in Ihre Projekte hochgeladen werden – Bilder, Videos, PDFs und mehr.Wenn Sie eine Datei über die API abrufen, enthält die Grundantwort zentrale Metadaten wie den Dateinamen, Status und eine `view_url`, um sie in der Frame.io-App zu öffnen.Mit **Einbindungen** greifen Sie auf den tatsächlichen Dateiinhalt zu: das Original, eine Vorschau oder Ausgabedarstellungen in verschiedenen Qualitäten.In diesem Leitfaden werden die Medien-Link-Einbindungen erklärt, die an den Endpunkten **Dateien auflisten** und **Datei abrufen** verfügbar sind, was von diesen zurückgegeben wird und wann Sie sie verwenden. ## Was sind Einbindungen? Einbindungen sind optionale Felder, die Sie zusammen mit einer Dateiantwort anfordern können.Standardmäßig werden von der API nur zentrale Datei-Metadaten zurückgegeben: Name, Status, Typ, Zeitstempel und `view_url`.Mit Einbindungen können Sie zusätzliche Daten anfordern und dabei Antworten schlank halten, wenn Sie nicht alles benötigen. ### So fügen Sie Einbindungen hinzu Übergeben Sie bei jeder **Datei abrufen**- oder **Dateien auflisten**-Anfrage eine durch Kommas getrennte Liste der Namen von Einbindungen als `include`-Abfrageparameter: **`Einzelne Einbindung`** ```bash title="Einzelne Einbindung" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` **`Mehrere Einbindungen`** ```bash title="Mehrere Einbindungen" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` **`Einbindungen bei „Dateien auflisten“`** ```bash title="Einbindungen bei „Dateien auflisten“" GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail ``` Einbindungen funktionieren bei beiden Endpunkten, also einzelnen Dateien sowie Listen, gleichermaßen.Bei der Verwendung mit „Dateien auflisten“ werden die Einbindungen für die einzelnen Dateien in der Antwort aufgelöst. ### SDK-Beispiele **`Python SDK`** ```python title="Python SDK" 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) ``` **`TypeScript SDK`** ```typescript title="TypeScript SDK" 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); ``` Einbindungen, die nicht angefordert werden, werden vollständig aus der Antwort weggelassen. ## Übersicht über Einbindungen für Medien-Links #### media\_links.original Die ursprünglich hochgeladene Datei, wie sie hochgeladen wurde #### media\_links.thumbnail Ein PNG-Vorschaubild zu Anzeigezwecken #### media\_links.high\_quality Die beste verfügbare verarbeitete Ausgabedarstellung #### media\_links.efficient Die kleinste verfügbare Ausgabedarstellung für Anwendungsszenarien mit geringer Bandbreite #### media\_links.video\_h264\_180 Eine Videotranskodierung mit niedriger Auflösung (180p H264) für Streaming und Wiedergabe #### media\_links.scrub\_sheet Ein WebP Sprite Sheet mit Miniaturansichten von Videobildern zum Erstellen einer Bedienoberfläche zum Hin- und Herspringen ## media\_links.original Gibt signierte URLs zurück, die auf die **ursprüngliche Datei verweisen, wie sie hochgeladen wurde**, ohne Verarbeitung oder Konversion. ### Felder | Feld | Typ | Beschreibung | | | -------------- | --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL, die einen Datei-Download erzwingt (`Content-Disposition: attachment`) | | `inline_url` | Zeichenfolge \\ | null | Signierte URL, durch die die Datei direkt im Browser geöffnet wird (`Content-Disposition: inline; filename=`) | ### Wann verwenden Bei der Verwendung von `media_links.original` erhalten Sie die Quelldatei, etwa um Benutzenden das Herunterladen der ursprünglichen MOV-, MP4-, MXF-, AVI-, PSD-, PNG- oder TIFF-Datei zu ermöglichen oder um die ursprünglichen Bytes an ein anderes System zu übergeben. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original ``` ### Beispielantwort ```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** > > Diese URLs sind **temporäre signierte S3-URLs**, sie laufen ab.Speichern Sie sie nicht, auch nicht im Zwischenspeicher. Fordern Sie jedes Mal eine neue URL an, wenn Sie eine benötigen. ## media\_links.thumbnail Gibt ein **PNG-Vorschaubild** des Assets zurück, begrenzt auf 540 px Höhe.Dies ist eine verarbeitete Ausgabedarstellung, nicht die Originaldatei. Wasserzeichen können in Abhängigkeit von den Kontoeinstellungen angewendet werden. ### Felder | Feld | Typ | Beschreibung | | | -------------- | --------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL, die einen Download der PNG-Miniaturansicht erzwingt | | `url` | Zeichenfolge \\ | null | Signierte URL, durch die die PNG-Miniaturansicht inline ohne `Content-Disposition`-Header bereitgestellt wird | ### Wann verwenden Mit `media_links.thumbnail` können Sie **eine visuelle Vorschau** des Assets anzeigen, zum Beispiel in einer Rasteransicht, einer Galerie oder einer Dateiauswahl.Sie wird schneller geladen als das Original und liegt immer in einem websicheren PNG-Format vor. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` ### Beispielantwort ```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 Gibt eine Download-URL für die **beste verfügbare verarbeitete Ausgabedarstellung** des Assets zurück.In Frame.io werden Uploads über eine Auflösungsleiter verarbeitet, die bei 2160p ihr Maximum erreicht.Von der API wird die höchste verfügbare Ausgabedarstellung **zum Zeitpunkt der Anfrage** zurückgegeben. Wenn zum Zeitpunkt der Anfrage also nur eine 540p-Ausgabedarstellung fertig verarbeitet wurde, wird von der API 540p zurückgegeben, bis höhere Ausgabedarstellungen bereit sind. ### Felder | Feld | Typ | Beschreibung | | | -------------- | --------------- | ------------ | -------------------------------------------------------------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL für die Ausgabedarstellung in der höchsten zum Zeitpunkt der Anfrage vorliegenden Qualität | ### Wann verwenden Mit `media_links.high_quality` erhalten Sie die **Version in der bestmöglichen Qualität ohne das Original**, zum Beispiel beim Export einer hochauflösenden Ausgabedarstellung für die nachgelagerte Verarbeitung oder bei der Präsentation einer Vorschau in voller Auflösung.Wenn Sie die höchstmögliche Qualität benötigen, überprüfen Sie das Feld `status` der Datei und fordern Sie diese Einbindung an, sobald die Datei `ready` ist, um zu gewährleisten, dass die vollständige Auflösungsleiter verarbeitet wurde. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality ``` ### Beispielantwort ```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 Gibt eine Download-URL für die **kleinste verfügbare verarbeitete Ausgabedarstellung** zurück.Das ist das Gegenteil von `high_quality`; in Frame.io wird die Ausgabedarstellung in der niedrigsten verfügbaren Auflösung ausgewählt. ### Felder | Feld | Typ | Beschreibung | | | -------------- | --------------- | ------------ | --------------------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL für die kleinste/effizienteste Ausgabedarstellung | ### Wann verwenden Verwenden Sie `media_links.efficient`, wenn **Bandbreite oder Dateigröße wichtiger sind als Qualität**, zum Beispiel beim Generieren schneller Vorschauen in einer Umgebung mit geringer Bandbreite oder beim Einspeisen in eine Miniaturansichts-Pipeline, bei der keine volle Auflösung erforderlich ist. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient ``` ### Beispielantwort ```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 Gibt Streaming- und Download-URLs für eine **niedrigauflösende 180p-H264-Videotranskodierung** des Assets zurück. > **Warning** > > Das ist eine ältere Einbindung.Der Wert wird `null` sein, wenn für das Asset keine 180p-Transkodierung generiert wurde.Bevorzugen Sie für die meisten Anwendungsfälle `media_links.efficient`. Hier wird die beste verfügbare Ausgabedarstellung in geringer Qualität ausgewählt, anstatt sich darauf zu verlassen, dass eine spezifische Transkodierung existiert. ### Felder | Feld | Typ | Beschreibung | | | -------------- | --------------- | ------------ | ---------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL zum Herunterladen des 180p-H264-Videos | | `url` | Zeichenfolge \\ | null | Signierte URL zum Streamen des 180p-H264-Videos | ### Wann verwenden Mit `media_links.video_h264_180` erhalten Sie eine garantierte 180p-H264-Transkodierung, zum Beispiel bei der Integration mit einem älteren Player oder einer älteren Pipeline, der bzw. die genau dieses Format erfordert.Wenn die Transkodierung für ein gegebenes Asset nicht existiert, sind beide URLs `null`. > **Warning** > > In der Datei video\_h264\_180 ist keine Audiospur enthalten.Sie ist für sehr effiziente Vorschauen gedacht, wenn diese benötigt werden. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180 ``` ### Beispielantwort ```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 Gibt ein **WebP Sprite Sheet** zurück, ein einzelnes Bild, das ein Raster von Miniaturansichten von Videobildern enthält, die gleichmäßig über die Dauer des Videos gesampelt wurden.Damit wird eine Bedienoberfläche zum Hin- und Herspringen in dem Video erstellt. In dem Player wird ein Vorschaubild angezeigt, während Benutzende über die Timeline ziehen. > **Info** > > Scrub-Sheets werden **nur für Video-Assets** generiert.Für Bilder, PDFs und andere Nichtvideodateien werden von der Einbindung `null`-URLs zurückgegeben. ### Felder | Feld | Typ | Beschreibung | | | ---------------------- | --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | `download_url` | Zeichenfolge \\ | null | Signierte URL zum Herunterladen des WebP Sprite Sheets | | `url` | Zeichenfolge \\ | null | Signierte URL zum Inline-Laden des WebP Sprite Sheets | | `metadata` | object \\ | null | Informationen zum Kachel-Layout zum Extrahieren einzelner Bilder (nur experimentelle API) | | **`metadata`-Felder:** | | | | | Feld | Typ | Beschreibung | | | --- | --- | --- | | | `tile_x` | Ganzzahl | Anzahl der Spalten für Miniaturansichten im Raster | | | `tile_y` | Ganzzahl | Anzahl der Zeilen für Miniaturansichten im Raster | | | `thumb_width` | Ganzzahl | Breite der einzelnen Miniaturansichten in Pixel | | | `thumb_height` | Ganzzahl | Höhe der einzelnen Miniaturansichten in Pixel | | | `padding` | Ganzzahl | Abstand zwischen Miniaturansichten in Pixel | | | `frames` | Ganzzahl | Gesamtanzahl der Bilder, die im Sheet gesampelt wurden | | ### Wann verwenden Verwenden Sie `media_links.scrub_sheet` beim Erstellen eines selbstdefinierten Video-Players oder einer Timeline-Bedienoberfläche, in der eine Vorschau-Miniaturansicht angezeigt werden muss, während Benutzende hin- und herspringen.Anstatt für jedes Bild eine separate Anfrage zu stellen, werden im Sprite Sheet alle Vorschaubilder in einem einzigen Bild-Download gebündelt. ### Beispielanfrage ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet ``` ### Beispielantwort ```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 } } } } } ``` ### Extrahieren eines Bildes aus dem Sprite Sheet Das Sprite Sheet ist ein Raster aus `tile_x`-Spalten × `tile_y`-Zeilen.Wenn Sie die Miniaturansicht für einen gegebenen Bildindex (nullbasiert) anzeigen möchten, berechnen Sie dessen Position innerhalb des Bildes: ```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, }; } ``` Mit dem CSS `background-position` können Sie dann die richtige Kachel aus dem Sprite Sheet zeigen: ```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`; } ``` Wenn Sie einem Bildindex eine Wiedergabeposition (in Sekunden) zuordnen möchten, verwenden Sie die Gesamtdauer des Videos und die Anzahl der Bilder im Sheet: ```javascript function positionToFrameIndex(currentSeconds, durationSeconds, metadata) { const progress = currentSeconds / durationSeconds; return Math.min( Math.floor(progress * metadata.frames), metadata.frames - 1 ); } ``` > **Info** > > Das Feld `metadata` ist nur in der experimentellen Version der API verfügbar.In der stabilen V4-API wird durch `scrub_sheet` nur `download_url` und `url` zurückgegeben. ## Kombinieren mehrerer Einbindungen Sie können mehrere Einbindungen in einem einzigen API-Aufruf anfordern: ```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/..." } } } } ``` ## Auswählen der richtigen Einbindung | Ziel | Zu verwendende Einbindung | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | Vorschaubild in der Bedienoberfläche anzeigen | `media_links.thumbnail` | | Benutzenden das Herunterladen der Originaldatei ermöglichen | `media_links.original` | | Originaldatei direkt im Browser öffnen | `media_links.original` → `inline_url` | | Ausgabedarstellung in der besten Qualität für den Export abrufen | `media_links.high_quality` | | Kleine Ausgabedarstellung für die Nutzung bei geringer Bandbreite abrufen | `media_links.efficient` | | Video in niedriger Auflösung streamen oder herunterladen (Vorgängerversion) | `media_links.video_h264_180` | | Bedienoberfläche zum Hin- und Herspringen in Videos mit Einzelbildvorschau erstellen | `media_links.scrub_sheet` | | Benutzende zu der Datei in Frame.io navigieren | Verwenden Sie `view_url` aus der grundlegenden Dateiantwort. | > **Info** > > `view_url` ist bei jeder Dateiantwort verfügbar, keine Einbindung erforderlich. Dies ist ein permanenter Deep-Link in die Web-Anwendung von Frame.io.Es ist **keine** Medien-URL; mit dem Link wird die Bedienoberfläche von Frame.io geöffnet, und er läuft nicht ab.Damit können Sie Benutzende anweisen, ein Asset direkt in Frame.io zu prüfen oder zu kommentieren, aber nicht, wenn Sie die Datei programmatisch bereitstellen oder herunterladen müssen. ## Verfügbarkeit von Einbindungen Medien-Link-Einbindungen werden erst ausgefüllt, wenn die Verarbeitung der hochgeladenen Datei in Frame.io abgeschlossen ist.Wenn Sie unmittelbar nach dem Hochladen eine Einbindung anfordern, sind die URLs möglicherweise `null`, während die Transkodierung ausgeführt wird.Überprüfen Sie das Feld `status` des Dateiobjekts. Einbindungen sind verfügbar, sobald der Status `ready` lautet.