Medien in Shop, CMS und Website ausliefern

Warum Medien aus footage.one heraus verteilt und nicht direkt verlinkt werden, welche Wege es dafür gibt und wofür die internen Medien-Links gedacht sind.

Der Grundsatz

Medien, die außerhalb von footage.one erscheinen sollen, werden dorthin ausgeliefert: in das Zielsystem selbst oder in einen Speicher, aus dem deine Website oder dein Auslieferungsnetz liefert. Die URLs, die die Plattform intern verwendet, sind Arbeits-URLs der Anwendung und keine Auslieferungsstrecke.

Vier Gründe, warum das kein Formalismus ist:

Vorschauen können ein Wasserzeichen tragen. Was in der Verwaltungsoberfläche richtig ist, ist im Shop falsch.
Vorschauen sind Arbeitsansichten. Auflösung, Format und Zuschnitt richten sich nach der Anwendung, nicht nach deinem Layout, und können sich mit der Plattform ändern.
Sonst wird die Plattform zum Ursprung unter Publikumslast. Ladezeit, Datenverkehr und Verfügbarkeit deiner Website hängen dann an ihr.
Veröffentlichen soll eine Entscheidung sein. Was auf einer öffentlichen Seite steht, gehört bewusst verteilt und nicht dadurch erreichbar, dass jemand eine URL kennt.

Die Wege nach draußen

Die Distribution ist der vorgesehene Weg. Du wählst Medien aus, bestimmst das Ziel, und footage.one liefert dorthin aus:

Ziel	Wofür
S3	Ablage in einen eigenen Bucket, aus dem Website, Shop oder CDN liefern. Der übliche Weg für eine eigene Website
Webhook	Das Zielsystem wird benachrichtigt und übernimmt die Medien in seinen eigenen Bestand
Media-Feed	Ein Feed, den ein angebundenes System regelmäßig ausliest
Shop	Angebot im eigenen Footage-Shop
Öffentliche Suche	Durchsuchbarer Bestand für die Such-Komponenten auf deiner Seite

Dazu kommen partnerspezifische Ziele, sofern sie für deine Instanz eingerichtet sind. Welche Ziele du tatsächlich anlegen kannst, meldet die Plattform selbst: Der Distributions-Dialog zeigt genau die Adapter, die auf deiner Instanz registriert sind. Siehe Medien verteilen.

Muster: eine Website oder einen Shop beliefern

Bestand festlegen. Album oder Auswahl zusammenstellen, die veröffentlicht werden soll.
Distribution einrichten, in der Regel auf einen eigenen S3-Bucket.
Auslieferung davorschalten. Website oder CDN liefern aus diesem Bucket, nicht aus footage.one. Damit bestimmst du Cache-Zeiten, Formate und Verfügbarkeit selbst.
Zieladresse im CMS speichern, am Produkt oder am Artikel.
Beim Ersetzen erneut verteilen und den Cache gezielt leeren. Die Datei im Bucket ist die Fassung, die dein Publikum sieht.

Der Vorteil dieser Trennung: Ein Ausfall oder eine Wartung der Plattform berührt deine Website nicht, und die veröffentlichte Fassung bleibt genau die, die du freigegeben hast.

Wofür die internen Medien-Links gedacht sind

Jedes Asset führt in seinem _links-Objekt eigene Medien-URLs. Sie sind für eigene Werkzeuge im geschützten Bereich gedacht: Verwaltungsoberflächen, Prüfansichten hinter der Anmeldung, Auswertungen, Skripte.

curl -H "apiKey: DEIN_API_TOKEN" \
  https://app.footage.one/api/asset/assets/DEINE_ASSET_ID \
  | jq '._links | {kframe, preview, master, download, actionToken}'

Link	Inhalt
`kframe`	Standbild des Mediums, bei Videos der Keyframe
`preview`	Vorschau-Fassung, bei Videos die Proxy-Datei
`master`	die Originaldatei, nur mit Token abrufbar
`download`	Download der Datei über die angemeldete Sitzung
`actionToken`	liefert das kurzlebige Token für den Zugriff auf `master`

Baue diese URLs nie selbst zusammen, sondern lies sie am Asset aus, siehe HATEOAS verstehen.

Vorschauen sind ohne Token abrufbar. Das ist technisch nötig, weil ein img- oder video-Element keinen Authorization-Header senden kann und die Anwendung sonst kein einziges Bild darstellen könnte. Es heißt aber auch: Wer eine solche URL kennt, kann sie abrufen. Genau deshalb gehören diese Adressen nicht in öffentliche Seiten, Newsletter oder Exportdateien.

Originaldatei herunterladen

Der Master-Download ist zweistufig. Erst holst du mit deinem API-Token ein kurzlebiges Zugriffs-Token, dann rufst du damit die Datei ab:

JWT=$(curl -s -H "apiKey: DEIN_API_TOKEN" \
  https://app.footage.one/api/asset/assets/DEINE_ASSET_ID/action-token | jq -r '.jwt')

curl -L -o original.jpg \
  "https://app.footage.one/api/asset/assets/DEINE_ASSET_ID/master?token=$JWT"

Das Zugriffs-Token ist kurzlebig und für genau diesen Zweck gedacht. Schreibe es nicht in eine öffentliche Seite, in einen Cache oder in ein Repository.

Wenn du doch direkt einbindest

Für ein internes Portal hinter der Anmeldung oder einen schnellen Prototyp kannst du die Vorschau-Links direkt verwenden. Dann solltest du wissen, worauf du dich einlässt:

Prüfe, ob für den Bestand ein Wasserzeichen gesetzt ist.
Verlasse dich nicht auf ein bestimmtes Format oder eine bestimmte Kantenlänge.
Rechne die entstehende Last am Ursprung mit, sobald mehr als eine Handvoll Menschen die Seite aufruft.

Für alles, was öffentlich sichtbar ist, bleibt die Distribution der richtige Weg.