Transloadit
Preise
  • Datei-Uploads
  • Dateiimport
  • Stapelverarbeitung
  • Video-Encoding
  • Audio-Encoding
  • Bildverarbeitung
  • Dokumentenverarbeitung
  • Künstliche Intelligenz
  • Dateifilterung & Sicherheit
  • Medienkatalogisierung
  • Dateikomprimierung
  • Codeauswertung
  • Dateiexport
  • Smart CDN
  • Alle Services anzeigen
  • Integrationen entdecken
  • Live-Demos entdecken (English)
  • Uppy
  • TransloaditKit
  • Android-SDK
  • Node.js-SDK
  • Viewer für Next.js
  • Python-SDK
  • Ruby-SDK
  • Go-SDK
  • Java-SDK
  • PHP-SDK
  • Zapier
  • MCP-Server
  • Transloadit CLI
  • Terraform
  • Grundlagen
  • Bewährte Verfahren
  • Häufige Fragen
  • Robots
  • API-Endpunkte
  • Formate
  • Erstellen Sie Ihre erste App
  • Über Transloadit
  • Vergleiche
  • Open Source
  • Referenzen
  • Stellen (English)
  • Sicherheit
  • Beiträge
  • Aktuelles für Entwickler (English)
  • Tipps für Entwickler
  • Presse
  • Forschung (English)
  • Fallstudien
  • Lösungen
  • Leitfäden
  • Glossar
  • Rechtliches (English)
  • Werkzeuge
  • Wie wir Coursera helfen, Bildung für Millionen Menschen weltweit zugänglich zu machen
  • Transloadit-Support
  • Open-Source-Support
  • Service Level Agreement (English)
  • Buchen Sie eine Demo mit unseren Ingenieuren (English)
GrundlagenRobotsHäufige FragenAPI-EndpunkteFormateBewährte Verfahren
Themen
  • Endpunkte
  • Antwortcodes
  • Authentifizierung
  • Webhooks
  • Metadaten
  • API-Sicherheit
  • Ratenbegrenzung
  • Warteschlangen
  • Fortsetzbare Uploads
Authentifizierung
  • Bearer-Token erstellen
  • Neuen Auth Key erstellen
  • Liste der Auth Keys abrufen
  • Auth-Key-Scopes abrufen
  • Auth Key bearbeiten
  • Auth Key löschen
  • Secret für einen Auth Key abrufen
Assemblies
  • Neue Assembly erstellen
  • Assembly Status abrufen
  • Eine Assembly mit einer vorgegebenen ID erstellen
  • Änderungen einer Assembly live streamen
  • Laufende Assembly abbrechen
  • Eine Assembly erneut ausführen
  • Liste der Assemblies abrufen
  • Assembly-Status-Antwort
  • Assembly-Statistiken abrufen
Webhooks
  • Assembly Notifications abrufen
  • Assembly Notification erneut senden
Abrechnung
  • Monatsrechnung abrufen
Warteschlangen
  • Derzeit genutzte Priority Job Slots abrufen
  • Statistiken zu Priority Job Slots abrufen
Fortsetzbare Uploads
  • Funktionen des tus-Protokolls ermitteln
  • Neuen tus-Upload erstellen
  • Offset eines tus-Uploads abrufen
  • tus-Dateidaten hochladen
  • tus-Upload beenden
  • tus-Upload herunterladen
Template-Zugangsdaten
  • Neue Template-Zugangsdaten erstellen
  • Template-Zugangsdaten abrufen
  • Template-Zugangsdaten bearbeiten
  • Template-Zugangsdaten löschen
  • Liste der Template-Zugangsdaten abrufen
  • Typen von Template-Zugangsdaten abrufen
Templates
  • Neues Template erstellen
  • Template abrufen
  • Template bearbeiten
  • Template löschen
  • Liste der Templates abrufen
  • Ausführungsverlauf des Cron-Templates abrufen alpha
Verwaltung digitaler Assets
  • DAM-Asset verschieben oder umbenennen alpha
  • DAM-Asset löschen alpha
  • Mehrere DAM-Assets verschieben alpha
  • Mehrere DAM-Assets löschen alpha
  • Eine Datei oder einen Ordner im Speicher verschieben alpha
  • Ein Asset aus dem Speicher abrufen
  • Gespeicherte Assets auflisten

Authentifizierung

Auth Keys

Für Multipart-Anfragen zur Erstellung einer Assembly, die mit einem Auth Key authentifiziert werden, fügen Sie ein auth-Objekt in das als JSON codierte Formularfeld params ein. Der kleinstmögliche solche params-Wert ist unten dargestellt.

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

Das Feld key bezieht sich auf den Auth Key, der Ihrem Transloadit Workspace zugeordnet ist und den Sie auf der Seite Zugangsdaten finden. Das obige Objekt ist das minimale Authentifizierungsobjekt für eine Assembly-Anfrage, die einen Auth Key verwendet. Andere Endpunkte und Authentifizierungsmethoden können abweichende Anfrageformate verwenden, wie in der jeweiligen Endpunktdokumentation und weiter unten beschrieben.

Assemblies, die /transloadit/import direkt oder über ein Template verwenden, erfordern entweder ein Bearer-Token oder signierte params mit einem in der Zukunft liegenden Zeitstempel params.auth.expires. Dies gilt auch dann, wenn Signature Authentication für den Workspace deaktiviert ist. Ein Auth Key allein reicht nicht aus; mit einem Bearer-Token authentifizierte Anfragen benötigen keine separate Signatur und keinen separaten Ablaufzeitpunkt. Öffentliche Storage Builtin Templates bilden die Ausnahme: Sie können unsignierte Anfragen nur dann bedienen, wenn jeder Storage-Import innerhalb eines deklarierten öffentlichen Präfixes bleibt. Dies autorisiert weder unsignierte Assemblies mit beliebigen Steps noch den Zugriff auf private Storage-Pfade.

Signature Authentication

Wir empfehlen, Signature Authentication für Ihr Konto zu aktivieren, insbesondere wenn Sie Transloadit aus einer nicht vertrauenswürdigen Umgebung heraus integrieren (etwa aus dem Browser mit Uppy⁠). Sie können Signature Authentication in Ihren Workspace-Einstellungen aktivieren.

Warnung

Wir empfehlen dringend, Signature Authentication zu aktivieren, wenn Sie mit unserer API arbeiten, insbesondere in nicht vertrauenswürdigen Umgebungen, in denen Benutzer möglicherweise auf Ihren Auth Key zugreifen können.

Ist Signature Authentication aktiviert, wird das Auth Secret Ihres Workspaces (das Sie neben Ihrem Auth Key auf der Seite Zugangsdaten finden) als Schlüssel für einen HMAC verwendet, der über die exakte Serialisierung des params-Werts berechnet wird. Dieser Wert enthält sowohl einen key (Ihren Auth Key, wie bereits erwähnt) als auch einen expires-Parameter, einen Zeitstempel in naher Zukunft, der als Ablaufdatum der Anfrage dient.

Für das Erstellen von Assemblies mit Transloadit könnte Ihr Back-End eine Signatur berechnen, die nur bestimmte Parameter, authentifizierte Benutzer und einen Zeitraum abdeckt, den es als legitime Nutzung ansieht. Beispielsweise würde es sich weigern, eine Signatur für Benutzer zu erzeugen, die nicht angemeldet sind. Sie können hier beliebige Geschäftslogik auf der Serverseite einsetzen, um zu entscheiden, ob Sie eine Signatur ausgeben oder nicht. Transloadit kann eine korrekte Signatur für die Nutzlast verlangen, wenn sich eine API-Anfrage mit Ihrem Auth Key authentifiziert.

So verlangen Sie Signature Authentication für API-Anfragen, die mit Ihrem Auth Key authentifiziert werden:

  1. Öffnen Sie die Workspace-Einstellungen in Ihrem Konto.
  2. Aktivieren Sie im Abschnitt API-Einstellungen die Option Korrekte Signature verlangen.
  3. Warten Sie, bis das automatische Speichern abgeschlossen ist.

Gültige Bearer-Tokens umgehen Signaturanforderungen, einschließlich der Einstellungen für Workspace und Template; Token-Scopes und Audience-Beschränkungen gelten weiterhin. Diese Einstellungen fügen keine Authentifizierung für Capability-basierten Zugriff hinzu, etwa für URLs für den Assembly Status, den Abbruch oder fortsetzbare Uploads. Halten Sie Assembly IDs und Capability-URLs geheim und befolgen Sie die Authentifizierungshinweise des jeweiligen Endpunkts.

Hinweis

Die meisten SDKs für das Back-End verwenden automatisch Signature Authentication, wenn Sie Ihr Auth Secret angeben. Vielleicht ist diese Einführung also schon alles, was Sie wissen müssen. Wenn Sie Transloadit jedoch in nicht vertrauenswürdige Umgebungen integrieren, etwa in Browser (Uppy!), sollten Sie weiterlesen, um zu erfahren, wie Ihr Back-End diesen Signaturen bereitstellen kann.

So generieren Sie Signaturen

Wie sieht das Ganze also aus?

Das typische params-Feld beim Erstellen einer Assembly ohne Signature Authentication sieht wie folgt aus:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  },
  "steps": {
    // …
  }
}

Der auth.key in diesem Beispiel ist der Auth Key aus den API-Zugangsdaten in Ihrem Konto.

Um diese Anfrage zu signieren, muss zusätzlich das Feld auth.expires hinzugefügt werden. Dadurch wird es Teil unserer Nutzlast, die durch unsere Signatur geschützt ist. Würde jemand es ändern, würde Transloadit die Anfrage ablehnen, da die Signatur nicht mehr übereinstimmt. Sie haben dann eine andere Nutzlast signiert als die, die wir erhalten haben. Stimmt die Signatur überein, vergleichen wir selbstverständlich das Datum und lehnen gegebenenfalls ab, wie angewiesen. So wird es für Dritte, die in den Besitz dieser Nutzlast gelangt sind, sehr schwer, Anfragen unbegrenzt zu wiederholen. Denn auch wenn unser mit A+ bewertetes HTTPS dies bereits weitgehend verhindern sollte, ließe sich der Browser-Cache womöglich leichter ausspähen.

Die Eigenschaft expires muss einen Zeitstempel in der (nahen) Zukunft enthalten. Verwenden Sie für das Datum das ISO-8601-Format (YYYY-MM-DDTHH:mm:ss.sssZ) und achten Sie darauf, dass UTC als Zeitzone verwendet wird. Zum Beispiel:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211",
    "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP"
  },
  "steps": {
    // …
  }
}

So berechnen Sie die Signatur für diese Anfrage:

  1. Wandeln Sie im Front-End das obige JavaScript-Objekt in einen JSON-String um und senden Sie ihn an Ihr Back-End.
  2. Berechnen Sie im Back-End eine RFC-6234-konforme⁠ HMAC-Signatur in Hexadezimaldarstellung über den String, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus, der im signature_algo Ihres Auth Keys konfiguriert ist, oder einem stärkeren Algorithmus. Neue Auth Keys verwenden standardmäßig sha384. Eine explizite Einstellung ist ein Minimum für Signaturen von API-Anfragen, vom schwächsten zum stärksten: sha1 → sha256 → sha384 → sha512. Ein Schlüssel mit sha256 akzeptiert sha256, sha384 und sha512 mit Präfix, lehnt aber sha1 und Digests ohne Präfix ab. Legacy-Signaturen ohne Präfix behalten ihre bestehenden Einschränkungen auf exakt einen Algorithmus; die Akzeptanz stärkerer Algorithmen erfordert ein Präfix. Ältere Auth Keys (Legacy) ohne konfigurierten Algorithmus akzeptieren sha384, sha256 oder sha1. Dieses nicht festgelegte Verhalten bleibt unverändert und umfasst sha512 nicht. Stellen Sie dem signature-String den Namen des Algorithmus in Kleinbuchstaben voran. Der Standardalgorithmus verwendet zum Beispiel sha384:<HMAC-signature>. Diesen String können Sie an Ihr Front-End senden (sofern Sie die entsprechenden Prüfungen vorgenommen haben, um sicherzustellen, dass es sich um eine echte Anfrage Ihres Front-Ends handelt).
  3. Fügen Sie im Front-End Ihrer Anfrage ein Multipart-POST-Feld signature mit diesem Wert hinzu (z. B. über ein verstecktes Feld in einem HTML-Formular).
Hinweis

Wenn Ihre Implementierung eine template_id statt steps verwendet, müssen Sie keine Signatur für die Instructions generieren, die Ihr Template enthält. Wir sollten nur Kommunikationsnutzlasten signieren.

Hinweis

Wir empfehlen dringend, für jede Anfrage einen zufällig generierten Wert params.nonce auf der obersten Ebene von params anzugeben. Dadurch unterscheiden sich unabhängig voneinander generierte Signaturen, und eine versehentliche Wiederverwendung von Signaturen wird vermieden. Eine nonce macht Wiederholungsversuche nicht idempotent: Ein wiederholter Versuch einer Anfrage zur Erstellung einer Assembly kann eine weitere Assembly erstellen. Kümmern Sie sich bei Bedarf in Ihrer Anwendung um die Deduplizierung von Wiederholungsversuchen. Verwenden Sie signierte params nicht endpunktübergreifend wieder. Template-Lesezugriffe, das Auflisten von Auth Keys, das Auflisten von Template-Zugangsdaten und Lesezugriffe auf Abrechnungsdaten lehnen Signaturen, die bereits für einen anderen Endpunkt erfasst oder zur Erstellung einer Assembly verwendet wurden, mit SIGNATURE_REUSE_DETECTED ab. Generieren Sie für jede Anfrage neue signierte params.

Die vollständige Anfrage sollte etwa so aussehen:

{
  "params": {
    "auth": {
      "key": "23c96d084c744219a2ce156772ec3211",
      "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
    },
    "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
    "steps": {
      // …
    },
  },
  "signature": "sha384:YOUR_SIGNATURE",
}

Sobald Transloadit die Anfrage erhalten hat, erzeugen auch wir eine Signatur nach demselben Verfahren und vergleichen die beiden Signaturen. Unterscheiden sich die Signaturen, antworten unsere Server mit INVALID_SIGNATURE.

Zusammengefasst läuft der Prozess wie folgt ab:

  1. Erzeugen Sie eine JSON-Nutzlast, die als Feld params an Transloadit gesendet wird.
  2. Berechnen Sie anhand des Inhalts der Nutzlast eine Signatur und verwenden Sie dabei Ihr Auth Secret als Schlüssel.
  3. Senden Sie die Anfrage an Transloadit und übergeben Sie die Signatur im Feld signature
  4. Transloadit berechnet dieselbe Signatur mithilfe des Auth Secrets Ihres Kontos und des Inhalts der Nutzlast.
  5. Stimmen die Signaturen überein, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet. Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code INVALID_SIGNATURE zurückgegeben.

So kann Transloadit den Aufrufer authentifizieren und die Integrität von params überprüfen, da Dritte ohne Zugriff auf Ihr Auth Secret keine passende Signatur berechnen könnten. TLS authentifiziert Transloadit gegenüber Ihrem Client und schützt die Verbindung. Das Signieren von Webhooks ist ein separater Ablauf für Anfragen, die Transloadit an Ihre Server sendet.

Nachfolgend finden Sie einige Beispiele dafür, wie Sie eine POST-Anfrage zum Erstellen einer Assembly ausführen. Wir empfehlen dringend, eines unserer SDKs zu verwenden, die die Signaturerzeugung automatisch übernehmen und gut getestet sind.

Hinweis

Webhooks werden anders signiert als API-Anfragen. Transloadit signiert den JSON-String im Formularfeld transloadit byte-genau mit HMAC-SHA1 und dem jeweils zutreffenden Auth Secret. Das Feld signature enthält den hexadezimalen Digest ohne Algorithmus-Präfix. Befolgen Sie die Anleitung zur Webhook-Verifizierung, einschließlich der Auswahl des Auth Secrets, statt die unten stehenden Signaturbeispiele für API-Anfragen zu verwenden.

Beispielcode für verschiedene Sprachen

Die folgenden Beispiele zeigen, wie Sie Assemblies mit unseren offiziellen SDKs erstellen. Die SDKs übernehmen die gesamte Signaturerzeugung intern, was die Integration einfacher und sicherer macht.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const response = await transloadit.createAssembly({
  params: {
    template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
    // your other params like notify_url, fields, etc.
  },
  waitForCompletion: true,
})

console.log(response)

Wenn Sie eine Signatur separat berechnen müssen (z. B. für die Verwendung im Front-End), können Sie calcSignature verwenden:

const { signature, params } = transloadit.calcSignature({
  template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})

console.log(signature, params)

Quellcode der Signaturimplementierung ansehen⁠

Hinweis

Wenn Sie die Details der Signaturimplementierung im Rohformat sehen möchten (z. B. um das Signieren in einer Sprache zu implementieren, für die wir kein SDK haben), sehen Sie sich die oben verlinkten Quellcodes an. Die Signatur ist ein RFC-6234-konformer⁠ HMAC-Hex-Digest, der über den als JSON codierten params-String berechnet wird, mit Ihrem Auth Secret als Schlüssel und einem Algorithmus, der mindestens so stark ist wie das im signature_algo Ihres Auth Keys konfigurierte Minimum. Neue Auth Keys verwenden standardmäßig sha384. Stellen Sie der Signatur den Namen ihres Algorithmus in Kleinbuchstaben voran (z. B. sha384:...).

curl --fail-with-body -sS --location 'https://api2.transloadit.com/assemblies' \
  --form 'params={"auth":{"key":"23c96d084c744219a2ce156772ec3211","expires":"YOUR_FUTURE_ISO_8601_TIMESTAMP"},"template_id":"9cf67cbba601e37ee10c442b037e0"}' \
  --form 'signature=sha384:YOUR_SIGNATURE' \
  --form 'files=@/path/to/your/file.jpg'

Signierte Smart-CDN-URLs

Zum Signieren einer Smart-CDN-URL wird ein ähnliches Verfahren wie bei regulären API-Signaturen verwendet. Ein HMAC-Digest wird über einen String berechnet, der aus der Smart-CDN-URL abgeleitet wird, mit dem Auth Secret als Schlüssel. Damit die Signatur gültig ist, muss der verwendete Auth Key für die Nutzung von Smart CDN aktiviert sein.

Wichtig

Um eine signierte Smart-CDN-URL zu generieren, verwenden Sie den für die Nutzung von Smart CDN vorgesehenen Auth Key von Ihrer Seite „Zugangsdaten“. Smart-CDN-URLs erfordern sha256. Signaturen regulärer API-Anfragen können einen Algorithmus mit Präfix verwenden, der mindestens so stark ist wie der signature_algo des Auth Keys; neue Auth Keys verwenden standardmäßig sha384.

Hinweis

Legacy-Signaturen für Smart CDN auf Basis von s= und expires= sind veraltet. Neue Integrationen sollten immer sig= mit exp= verwenden.

Die Erzeugung einer Smart-CDN-Signatur muss im Back-End erfolgen. Das Verfahren verwendet das Auth Secret, das vertraulich ist und Ihren Benutzern im Front-End nicht offengelegt werden darf.

Eine typische Smart-CDN-URL hat folgende Struktur:

https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]
  • [your-workspace] ist der Name Ihres Transloadit Workspaces
  • [template-name] ist der Name Ihres Templates
  • [file-path] ist der Pfad zu der Datei, die Sie transformieren möchten
  • [parameters] sind die gewünschten Transformationsparameter (z. B. h=100)

Eine signierte Smart-CDN-URL wird mit den folgenden Schritten erzeugt:

  1. Fügen Sie den Query-Parameter exp hinzu, um einen Zeitpunkt in der Zukunft festzulegen, nach dem die Signatur vom Smart CDN nicht mehr akzeptiert wird. Das ist nützlich, um den Zugriff auf eine Datei zeitlich zu begrenzen. Der Ablaufzeitpunkt wird als Anzahl der Millisekunden seit der UNIX-Epoche (Mitternacht zu Beginn des 1. Januar 1970, UTC) angegeben. Dieser Parameter ist zwar optional, wir empfehlen aber dringend, immer eine Ablaufzeit festzulegen. Eine Signatur mit exp=1722517200000 ist beispielsweise gültig bis Donnerstag, 1. August 2024, 13:00:00 GMT.
  2. Fügen Sie den Query-Parameter auth_key hinzu, um den Auth Key anzugeben, der zu dem Auth Secret gehört, mit dem die Signatur erstellt wird. Ist dieser Parameter nicht gesetzt, geht die API von Transloadit davon aus, dass das älteste für Smart CDN aktivierte Auth Key-Paar für die Signatur verwendet wurde. Durch das Setzen des Parameters auth_key können Sie Ihren Auth Key rotieren, ohne dass es für Ihre Benutzer zu Unterbrechungen kommt, daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel: auth_key=23c96d084c744219a2ce156772ec3211
  3. Sortieren Sie die Query-Parameter aufsteigend nach Schlüssel anhand von UTF-16-Codeeinheiten, entsprechend URLSearchParams.sort(). Die Sortierung sollte stabil sein, d. h., wenn ein Schlüssel mehrfach im Query-String vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Zum Beispiel wird h=100&f=png&f=jpg&auth_key=hello&exp=123 sortiert zu auth_key=hello&exp=123&f=png&f=jpg&h=100.
  4. Bilden Sie den zu signierenden String, indem Sie die Werte verketten:
    [your-workspace]/[template-name]/[file-path]?[sorted-parameters]
    
    Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert sein, damit sie nur URL-sichere Zeichen enthalten. Beachten Sie, dass der String nicht mit einem führenden Schrägstrich beginnt. Das Zeichen ? muss weggelassen werden, wenn [sorted-parameters] leer ist.
  5. Berechnen Sie eine RFC-6234-konforme⁠ HMAC-Signatur in Hexadezimaldarstellung über den zu signierenden String, mit Ihrem Auth Secret als Schlüssel und SHA256 als Hash-Algorithmus. Stellen Sie der Hex-Signatur den Namen des Algorithmus in Kleinbuchstaben und einen Doppelpunkt voran, also sha256:. Für SHA256 verwenden Sie zum Beispiel sha256:[hmac-signature].
  6. Hängen Sie die Hex-Signatur mit Präfix im Query-Parameter sig an die URL an, wodurch Sie die signierte Smart-CDN-URL erhalten:
    https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature]
    
    Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert sein, damit sie nur URL-sichere Zeichen enthalten. Diese signierte URL kann dann an Ihr Front-End gesendet oder dort verwendet werden, bis das Ablaufdatum erreicht ist.

Sicherheit und Cache-Lebensdauer

Signierte Smart-CDN-URLs sind nicht nur ein Mechanismus zur Zugriffskontrolle. Ihr Ablauf bestimmt auch, wie lange ein frisch erzeugtes Ergebnis zwischengespeichert werden darf.

  • Kürzere exp-Werte verkleinern das Replay-Zeitfenster und verschärfen die Zugriffskontrolle.
  • Längere exp-Werte erhöhen die Wiederverwendung des Caches, verringern die Arbeit am Origin und senken im Allgemeinen Latenz und Encoding-Volumen.
  • In der Praxis ist die effektive Cache-Lebensdauer einer signierten Smart-CDN-Antwort durch die verbleibende Lebensdauer der Signatur begrenzt.

Der Zielkonflikt ist also einfach:

  • Höhere Sicherheitsanforderungen: Verwenden Sie ein kürzeres exp, was auch eine kürzere effektive Cache-TTL bedeutet.
  • Mehr Wiederverwendung des Caches und geringere Kosten: Verwenden Sie ein längeres exp, was auch bedeutet, dass die URL länger nutzbar bleibt.

Wählen Sie das Ablaufzeitfenster entsprechend der Sensibilität der Inhalte und dem gewünschten Maß an Wiederverwendung des Caches. Für viele Anwendungsfälle mit Bildern und Vorschauen bietet ein moderates Ablaufzeitfenster eine gute Balance. Für hochsensible Inhalte verwenden Sie ein deutlich kürzeres.

Beispielcode

Nachfolgend finden Sie Beispiele in verschiedenen Sprachen für die Erzeugung signierter Smart-CDN-URLs mit unseren SDKs.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const url = transloadit.getSignedSmartCDNUrl({
  workspace: 'YOUR_WORKSPACE',
  template: 'YOUR_TEMPLATE',
  input: 'image.png',
  urlParams: { height: 100, width: 100 },
})

console.log(url)

Lesezugriff nach einer Kündigung

Gekündigte Workspaces können keine neuen Bearer-Tokens erstellen. Endpunkte, die den Zugriff nach einer Kündigung ausdrücklich erlauben, verlinken auf diese Anleitung. Verwenden Sie einen vorhandenen aktiven Auth Key und das zugehörige Auth Secret; der Schlüssel muss weiterhin die für den Endpunkt aufgeführten Scopes gewähren. Dies stellt weder den Schreibzugriff wieder her, noch macht es andere Endpunkte nach der Kündigung verfügbar.

Installieren Sie in einem vertrauenswürdigen serverseitigen Node.js-Projekt das SDK mit yarn add @transloadit/node. Setzen Sie TRANSLOADIT_KEY und TRANSLOADIT_SECRET und anschließend TRANSLOADIT_URL auf die vollständige HTTPS-URL, die auf der Seite des Endpunkts angezeigt wird, wobei Sie alle Pfadparameter durch die Werte Ihrer Ressourcen ersetzen. Halten Sie beide Zugangsdaten, die signierte URL und die Antwort geheim. Führen Sie dieses Setup niemals in Browser-Code aus.

Das SDK signiert params mit sha384, dem Standard für neue Auth Keys, und liefert den Ablaufzeitpunkt. Das Beispiel fügt eine neue Nonce hinzu, um die Wiederverwendung von Signaturen zu vermeiden. Wenn Ihr Schlüssel einen anderen Signaturalgorithmus verwendet, übergeben Sie ihn als zweites Argument an calcSignature. Legen Sie etwaige Endpunktfilter in das Objekt, das als erstes Argument übergeben wird, neben die Nonce. Das SDK ruft für diese Anleitung nicht /token auf.

Speichern Sie dies als read-api.mjs und führen Sie node read-api.mjs aus:

import { randomUUID } from 'node:crypto'

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_URL } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_URL) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_URL')
}
const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})
const { params, signature } = transloadit.calcSignature({ nonce: randomUUID() })
const url = new URL(TRANSLOADIT_URL)
url.searchParams.set('params', params)
url.searchParams.set('signature', signature)
const response = await fetch(url, { redirect: 'error' })
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const result = await response.json()
if (result.error) throw new Error(result.error)
console.log(JSON.stringify(result, null, 2))

MCP-Client per URL verbinden

Agent-Clients wie ChatGPT, Codex, Claude.ai, Claude Desktop, Claude Code und Cursor verbinden sich mit dem gehosteten MCP-Server unter https://api2.transloadit.com/mcp allein über diese URL. Die Transloadit API ist dafür ein OAuth-2.1-Autorisierungsserver: Der Client ermittelt die Endpunkte, identifiziert sich, leitet Sie zur Console weiter, wo Sie sich anmelden und zustimmen, und erhält schließlich ein kurzlebiges Bearer-Token für die Audience mcp sowie ein Refresh-Token. Kein Auth Secret verlässt jemals Ihr Konto.

  1. Erkennung. Der MCP-Server beantwortet nicht authentifizierte Anfragen mit 401 und einem Header WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Dieses Dokument gemäß RFC 9728⁠ nennt https://api2.transloadit.com als Autorisierungsserver, dessen Metadaten gemäß RFC 8414⁠ unter https://api2.transloadit.com/.well-known/oauth-authorization-server die unten aufgeführten Endpunkte auflisten.
  2. Client-Identifizierung. Legen Sie entweder ein Client ID Metadata Document⁠ vor: eine HTTPS-URL, die die client_id ist und JSON mit derselben client_id, einem client_name und den redirect_uris ausliefert. Oder registrieren Sie den Client einmalig über Dynamic Client Registration gemäß RFC 7591⁠ unter https://api2.transloadit.com/oauth/register; Clients senden entweder nur ihre client_id (token_endpoint_auth_method: "none", auch wenn dieses Feld weggelassen wird), authentifizieren sich mit einem Client-Secret (client_secret_basic oder client_secret_post) oder authentifizieren sich mit private_key_jwt und einer jwks_uri. Die Antwort enthält eine opake client_id, bei den Secret-Methoden zusätzlich ein client_secret, das nur in dieser Antwort angezeigt wird. Redirect-URIs müssen HTTPS-URLs sein, die exakt abgeglichen werden, oder Loopback-URLs http://localhost / http://127.0.0.1, die auf jedem Port abgeglichen werden. Ein mit Secret registrierter Client sendet dieses bei jeder Token- und Widerrufsanfrage, über HTTP Basic oder als client_id und client_secret im Formular. Andere Token-Anfragen authentifizieren den Client mit none oder private_key_jwt, je nachdem, was sein Dokument auflistet (in token_endpoint_auth_methods_supported oder andernfalls als token_endpoint_auth_method) oder seine Registrierung deklariert. Die erste Token-Anfrage bindet den Grant an die von ihr verwendete Methode: Sobald eine Anfrage für einen Grant eine client_assertion gemäß RFC 7523⁠ enthält, muss auch jede spätere Token- und Widerrufsanfrage dafür eine enthalten. Diese Assertion ist ein JWT, signiert (RS256 oder ES256) mit einem Schlüssel aus der jwks_uri des Clients, mit der Client-ID als iss und sub. Ihr aud ist eine konfigurierte Token-Endpunkt-URL oder deren Origin (ohne abschließenden Schrägstrich) für dieses Deployment. Sie hat ein exp innerhalb von fünf Minuten und eine jti, die pro Client und Region einmal akzeptiert wird, solange die Assertion gültig bleibt. Verwenden Sie für jede Anfrage eine neue jti.
  3. Zustimmung. Der Client öffnet https://transloadit.com/c/oauth/authorize mit response_type=code, seiner client_id, redirect_uri, einer PKCE-code_challenge (nur S256), optional scope und state sowie resource=https://api2.transloadit.com/mcp. Sie melden sich an, wählen einen Workspace aus und stimmen zu; die Console leitet den Browser mit code, Ihrem state und iss=https://api2.transloadit.com zurück. Der Code ist an den Client, die Redirect-URI, die Challenge und den Workspace gebunden und läuft nach 120 Sekunden ab.
  4. Tokens. Der Client sendet grant_type=authorization_code mit code, code_verifier, client_id und redirect_uri per POST an https://api2.transloadit.com/token und erhält ein access_token (standardmäßig gültig für 604.800 Sekunden, also 7 Tage), dessen scope und ein refresh_token. Das Senden von grant_type=refresh_token mit refresh_token und client_id liefert ein neues Paar und setzt das vorgelegte Refresh-Token außer Kraft; Refresh-Tokens sind 30 Tage gültig, und die Wiederverwendung eines außer Kraft gesetzten Tokens widerruft die gesamte Token-Kette. Clients, die sich mit einem Client-Secret authentifizieren, erhalten stattdessen dasselbe Refresh-Token zurück, das ab dieser Aktualisierung weitere 30 Tage gültig ist.
  5. Widerruf. Senden Sie token (ein Access- oder Refresh-Token) per POST an https://api2.transloadit.com/oauth/revoke gemäß RFC 7009⁠, oder widerrufen Sie die Verbindung in der Console.

Der resource-Indikator (RFC 8707⁠) bestimmt, wofür das Token bestimmt ist. resource=https://api2.transloadit.com/mcp (der Standard, wenn der Parameter weggelassen wird) erzeugt ein mcp-Token, das höchstens die sicheren MCP-Scopes (assemblies:write, assemblies:read, templates:read) enthält, eingeschränkt auf das, was der Auth Key des Workspaces gewährt, und das nur der MCP-Server akzeptiert. resource=https://api2.transloadit.com (mit oder ohne abschließenden Schrägstrich) erzeugt ein api2-Token für Anwendungen, die die REST API direkt aufrufen, etwa Integrationen mit Vercel Connect⁠: Es enthält die angeforderten Scopes, eingeschränkt auf die Scopes des Auth Keys, oder alles, was der Schlüssel gewährt, wenn scope weggelassen wird, mit der Ausnahme, dass ein Grant niemals die Verwaltung von Auth Keys oder Template-Zugangsdaten umfasst (auth_keys:*, template_credentials:* oder das globale read/write, das diese impliziert), sodass es keine dauerhaften Zugangsdaten erstellen oder offenlegen kann. Jede andere resource wird mit invalid_target beantwortet.

OAuth-Protokollfehler bei Client-Registrierung, Autorisierung und Widerruf verwenden den Standard-Body mit error und error_description; Rate Limits können RATE_LIMIT_REACHED zurückgeben.

Unter /token verwenden OAuth-Grant-Fehler für authorization_code und refresh_token den Standard-Body mit error und error_description. Rate Limits geben RATE_LIMIT_REACHED (429) zurück, und unerwartete interne Fehler geben SERVER_500 (500) zurück. Fehlerhafte Anfragen, die abgelehnt werden, bevor der Grant identifiziert ist, können eine HTTP-Basic-Challenge (401) erhalten oder TOKEN_INVALID_REQUEST, falls Basic-Zugangsdaten mitgesendet wurden.

Bearer-Tokens (Client Credentials)

CI-Jobs, Server und andere Headless-Clients, die einen Auth Key und ein Auth Secret besitzen, tauschen diese über den OAuth-2.0-Grant client_credentials, der direkt von der Transloadit API verarbeitet wird, gegen ein kurzlebiges Bearer-Token ein. Verwenden Sie dies, wenn es keinen Browser für die Zustimmung gibt; interaktive MCP-Clients sollten sich wie oben beschrieben per URL verbinden. Die vollständige Endpunktreferenz finden Sie in der /token-API-Dokumentation.

Das Token verwenden

Übergeben Sie das Token als Authorization: Bearer <access_token> in API-Anfragen. Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert ist, betrachtet API2 Signature Authentication als erfüllt und überspringt die Signaturprüfung. Signature Authentication wird nur für Anfragen mit Key und Secret erzwungen. Scope- und Audience-Prüfungen gelten weiterhin. Die Audience mcp wird vom MCP-Server akzeptiert, der sie mit Service-Zugangsdaten an API2 weiterleitet; wird sie regulären API2-Endpunkten direkt vorgelegt, wird sie abgelehnt. Sie können auth.key in params weglassen, aber der params-Umschlag ist für Endpunkte, die ihn erwarten, weiterhin erforderlich.

curl --fail-with-body -sS --request POST \
  --url 'https://api2.transloadit.com/assemblies' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'params={"template_id":"YOUR_TEMPLATE_ID"}'

MCP-Auto-Auth für /ai/chat

Wenn Ihre /ai/chat-Steps einen von Transloadit gehosteten MCP-Server aufrufen, kann API2 automatisch ein kurzlebiges Bearer-Token erzeugen und einfügen (Auto-Auth). Dies muss pro MCP-Server-Eintrag ausdrücklich aktiviert werden (Opt-in):

{
  "mcp_servers": [
    {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "auth": "transloadit"
    }
  ]
}

Verhalten:

  • Wenn auth: "transloadit" gesetzt ist und kein Authorization-Header vorhanden ist, erzeugt API2 ein Token und fügt Authorization: Bearer <token> ein.
  • Wenn Authorization bereits in mcp_servers[].headers angegeben ist, bleibt es unverändert.
  • Auto-Auth funktioniert nur über HTTPS für von Transloadit verwaltete Apex-Hosts und Subdomains: transloadit.com, *.transloadit.com, transloadit.dev, *.transloadit.dev, transloadit.website, *.transloadit.website, transloadit.work, *.transloadit.work.
  • Die URL muss Port 443 und exakt den Pfad /mcp oder einen Unterpfad unterhalb von /mcp/ verwenden.
  • Die URL darf keine Zugangsdaten, keinen Query-String und kein Fragment enthalten.
  • Der Auth Key muss mindestens einen dieser sicheren MCP-Scopes gewähren: assemblies:write, assemblies:read, templates:read.
  • Das erzeugte Token wird auf die Schnittmenge dieser sicheren MCP-Scopes und der Scopes des Auth Keys eingeschränkt; es erhält nie einen Scope, den der Auth Key nicht gewährt.

Häufige Fragen

Fügt Transloadit seinen Anfragen Signaturen bei?

Transloadit signiert Webhook-Anfragen, damit Ihr Server deren Echtheit überprüfen kann. Das Signieren von Webhooks ist getrennt vom HMAC, mit dem an Transloadit gesendete API-Anfragen authentifiziert werden.

Warum kann ich mein Auth Secret nicht als Bearer-Token verwenden?

Abgesehen vom oben beschriebenen Token-Austausch zwischen Servern darf Ihr Auth Secret niemals an einen Client übertragen oder in API-Anfrageparameter aufgenommen werden. POST /token sendet es als HTTP-Basic-Passwort über HTTPS und darf nur von Ihrem Back-End aus aufgerufen werden. Bei signierten Anfragen verbleibt das Secret in Ihrem Back-End und wird als HMAC-Schlüssel verwendet. Dies verhindert, dass ein böswilliger Akteur eine signierte Anfrage abfängt und gefälschte Anfragen an Ihr Konto sendet. Schützen Sie Ihr Auth Secret mit einem Secret-Management-System Ihrer Wahl. Beispiele sind: Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ und Kubernetes Secrets⁠, es gibt jedoch noch viele weitere, die je nach gewählter Back-End-Plattform geeignet sein können.

Hinweis

Stellen Sie sicher, dass Auth Secrets niemals Teil des Front-Ends Ihrer Anwendung sind oder Benutzern offengelegt werden.

In welcher Reihenfolge müssen die Schlüssel im Body stehen?

Die Reihenfolge der Schlüssel im Body können Sie beliebig wählen. Wichtig ist jedoch, dass die gewählte Reihenfolge mit Ihrer Signaturerzeugung übereinstimmt. Der erzeugte Hash hängt vom Inhalt des JSON ab, und eine andere Reihenfolge erzeugt einen anderen Hash, sodass Ihre Anfrage abgelehnt wird.

Vorherige Seite ← AntwortcodesNächste Seite Webhooks →
Support kontaktieren
TransloaditStatus wird geprüft…

Produkt

  • Dienste
  • Preise
  • Demos EN (English)
  • Werkzeuge
  • Sicherheit
  • Support

Unternehmen

  • Über Transloadit/Presse
  • Blog/Stellen EN (English)
  • Vergleiche/Compliance-Matrix
  • Forschung EN (English)
  • Open Source
  • Lösungen
  • Pioniere des Webs

Dokumentation

  • Erste Schritte
  • Transkodierung
  • Häufige Fragen
  • API-Endpunkte
  • Leitfäden/Tipps für Entwickler
  • Unterstützte Formate

Mehr

  • Plattformstatus⁠
  • Community-Forum⁠
  • Uppy
  • tus⁠

© 2009–2026 Transloadit-II GmbH

Transloadit®, tus® und Uppy® sind in den Vereinigten Staaten eingetragene Marken von Transloadit-II GmbH.

Datenschutz EN (English)Nutzungsbedingungen EN (English)Impressum EN (English)Marken EN (English)DMCA-Richtlinie EN (English)
EnglishDeutschEspañolFrançaisPortuguês (Brasil)日本語