Transloadit
Preise
  • Datei-Uploads
  • Dateiimport
  • Stapelverarbeitung (English)
  • Video-Encoding
  • Audio-Encoding
  • Bildverarbeitung
  • Dokumentenverarbeitung
  • Künstliche Intelligenz
  • Dateifilterung & Sicherheit
  • Medienkatalogisierung
  • Dateikomprimierung
  • Codeauswertung
  • Dateiexport
  • Smart CDN
  • Alle Services anzeigen
  • Integrationen entdecken (English)
  • Live-Demos entdecken (English)
  • Uppy
  • TransloaditKit
  • Android-SDK
  • Node.js-SDK
  • 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 (English)
  • Forschung (English)
  • Fallstudien
  • Lösungen
  • Leitfäden
  • Glossar (English)
  • 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)
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
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ügen Sie bei mehrteiligen Anfragen zur Erstellung einer Assembly, die mit einem Auth Key authentifiziert werden, ein auth-Objekt in das JSON-kodierte Formularfeld params ein. Der kleinstmögliche params-Wert dafür ist unten dargestellt.

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

Das Feld key verweist auf den Auth Key, der Ihrem Transloadit-Workspace zugeordnet ist und den Sie auf der Seite Zugangsdaten finden. Das obige Beispiel zeigt das minimale Authentifizierungsobjekt für eine Assembly-Anfrage, die einen Auth Key verwendet. Andere Endpunkte und Authentifizierungsmethoden können andere 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 zukünftigen Zeitstempel in 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 Signature und keinen separaten Ablaufzeitpunkt.

Signature Authentication

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

Warnung

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

Wenn Signature Authentication aktiviert ist, wird das Auth Secret Ihres Workspaces (zu finden neben Ihrem Auth Key auf der Seite Zugangsdaten) als Schlüssel für einen HMAC verwendet, der aus dem exakt serialisierten params-Wert generiert wird. Dieser Wert enthält sowohl einen key (Ihren Auth Key, wie zuvor erwähnt) als auch einen Parameter expires, einen Zeitstempel in der nahen Zukunft, der als Ablaufdatum für die Anfrage dient.

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

So legen Sie fest, dass Signature Authentication für API-Anfragen erforderlich ist, 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 Eine korrekte Signature verlangen.
  3. Klicken Sie auf die Schaltfläche „Speichern“.

Gültige Bearer-Tokens umgehen die Anforderungen an Signatures, einschließlich der Workspace- und Template-Einstellungen; Scope- und Audience-Beschränkungen gelten weiterhin. Diese Einstellungen ergänzen keine Authentifizierung für Capability-basierten Zugriff, etwa über 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 Back-End-SDKs verwenden automatisch Signature Authentication, wenn Sie Ihr Auth Secret angeben. Möglicherweise enthält diese Einführung also bereits alles, was Sie wissen müssen. Wenn Sie Transloadit jedoch in nicht vertrauenswürdige Umgebungen wie Browser integrieren (Uppy!), sollten Sie weiterlesen, um zu erfahren, wie Ihr Back-End dafür Signatures bereitstellen kann.

So generieren Sie Signatures

Wie sieht das Ganze nun aus?

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

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

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

Um diese Anfrage zu signieren, muss das zusätzliche Feld auth.expires hinzugefügt werden. Dadurch wird es Teil unserer Nutzlast, die durch unsere Signature geschützt ist. Würde jemand es ändern, würde Transloadit die Anfrage ablehnen, da die Signature nicht mehr übereinstimmt. Sie haben dann eine andere Nutzlast signiert als die, die wir erhalten haben. Wenn die Signature übereinstimmt, prüfen wir natürlich das Datum und lehnen die Anfrage entsprechend der Vorgabe ab. Dadurch wird es für Dritte, die in den Besitz dieser Nutzlast gelangt sind, sehr schwierig, Anfragen unbegrenzt zu wiederholen. Denn obwohl unser mit A+ bewertetes HTTPS bereits viel dazu beitragen sollte, dies zu verhindern, lässt sich der Browser-Cache möglicherweise 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 stellen Sie sicher, dass UTC als Zeitzone verwendet wird. Zum Beispiel:

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

So berechnen Sie die Signature für diese Anfrage:

  1. Serialisieren Sie in Ihrem Front-End das obige JavaScript-Objekt als JSON-Zeichenfolge und senden Sie diese an Ihr Back-End.
  2. Berechnen Sie in Ihrem Back-End eine RFC-6234-konforme⁠ HMAC-Signature in Hexadezimaldarstellung über die Zeichenfolge, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus, der in signature_algo Ihres Auth Keys konfiguriert ist. Neue Auth Keys verwenden standardmäßig sha384. Ältere Auth Keys ohne konfigurierten Algorithmus akzeptieren sha384, sha256 oder sha1. Stellen Sie der Zeichenfolge signature den Algorithmusnamen in Kleinbuchstaben voran. Der Standardalgorithmus verwendet beispielsweise sha384:<HMAC-signature>. Sie können diese Zeichenfolge an Ihr Front-End senden (sofern Sie die entsprechenden Prüfungen durchgeführt haben, um sicherzustellen, dass es sich um eine echte Anfrage Ihres Front-Ends handelt).
  3. Fügen Sie in Ihrem Front-End Ihrer Anfrage ein mehrteiliges POST-Feld signature hinzu, das diesen Wert enthält (z. B. mit einem versteckten Feld in einem HTML-Formular).
Hinweis

Wenn Ihre Implementierung eine template_id anstelle von steps verwendet, müssen Sie keine Signature für die Instructions generieren, die Ihr Template enthält. Wir sollten nur die bei der Kommunikation übertragenen Nutzlasten signieren.

Hinweis

Wir empfehlen dringend, für jede Anfrage einen zufällig generierten Wert params.nonce auf der obersten Ebene von params einzufügen. Dadurch unterscheiden sich unabhängig generierte Signatures voneinander, und eine versehentliche Wiederverwendung von Signatures wird vermieden. Eine nonce macht Wiederholungsversuche nicht idempotent: Das Wiederholen einer Anfrage zur Erstellung einer Assembly kann eine weitere Assembly erstellen. Sorgen Sie bei Bedarf in Ihrer Anwendung für die Deduplizierung von Wiederholungsversuchen. Verwenden Sie signierte params nicht für verschiedene Endpunkte wieder. Lesezugriffe auf Templates, das Auflisten von Auth Keys, das Auflisten von Template-Zugangsdaten und Lesezugriffe auf Abrechnungsdaten lehnen Signatures, die bereits für einen anderen Endpunkt registriert oder zum Erstellen einer Assembly verwendet wurden, mit SIGNATURE_REUSE_DETECTED ab. Generieren Sie für jede Anfrage neue signierte params.

Die vollständige Anfrage sollte ähnlich wie das folgende Beispiel aussehen:

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

Nachdem Transloadit die Anfrage erhalten hat, generieren auch wir nach demselben Verfahren eine Signature und vergleichen die beiden Signatures. Wenn sie unterschiedlich sind, antworten unsere Server mit INVALID_SIGNATURE.

Zusammengefasst läuft der Vorgang wie folgt ab:

  1. Generieren Sie eine JSON-Nutzlast, die als Feld params an Transloadit gesendet werden soll.
  2. Berechnen Sie eine Signature anhand des Inhalts der Nutzlast und verwenden Sie dabei Ihr Auth Secret als Schlüssel.
  3. Senden Sie die Anfrage an Transloadit und übergeben Sie die Signature im Feld signature
  4. Transloadit berechnet dieselbe Signature mit dem Auth Secret Ihres Kontos und dem Inhalt der Nutzlast.
  5. Wenn die Signatures übereinstimmen, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet. Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code INVALID_SIGNATURE zurückgegeben.

Dadurch kann Transloadit den Aufrufer authentifizieren und die Integrität von params überprüfen, da Dritte keine passende Signature ohne Zugriff auf Ihr Auth Secret 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 für POST-Anfragen zum Erstellen einer Assembly. Wir empfehlen dringend, eines unserer SDKs zu verwenden, die die Generierung von Signatures automatisch übernehmen und gründlich getestet sind.

Hinweis

Webhooks werden anders signiert als API-Anfragen. Transloadit signiert die exakte JSON-Zeichenfolge im Formularfeld transloadit mit HMAC-SHA1 und dem zutreffenden Auth Secret. Das Feld signature enthält den hexadezimalen Digest ohne Algorithmuspräfix. Befolgen Sie die Anleitung zur Webhook-Verifizierung, einschließlich der Hinweise zur Auswahl des Auth Secrets, anstatt die folgenden Beispiele zum Signieren von API-Anfragen zu verwenden.

Beispielcode für verschiedene Sprachen

Die folgenden Beispiele zeigen, wie Sie mit unseren offiziellen SDKs Assemblies erstellen. Die SDKs übernehmen die gesamte Generierung von Signatures 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 Signature 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 Signature-Implementierung ansehen⁠

Hinweis

Wenn Sie sich die direkten Implementierungsdetails für Signatures ansehen möchten (z. B. um das Signieren in einer Sprache zu implementieren, für die wir kein SDK anbieten), folgen Sie den obigen Quellcode-Links. Die Signature ist ein RFC-6234-konformer⁠ HMAC-Digest in Hexadezimaldarstellung, der über die JSON-kodierte params-Zeichenfolge berechnet wird. Dabei werden Ihr Auth Secret als Schlüssel und der in signature_algo Ihres Auth Keys konfigurierte Algorithmus verwendet. Neue Auth Keys verwenden standardmäßig sha384. Stellen Sie der Signature den Algorithmusnamen 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 für reguläre API-Signatures verwendet. Ein HMAC-Digest wird über eine Zeichenfolge berechnet, die aus der Smart CDN-URL abgeleitet wird, mit dem Auth Secret als Schlüssel. Damit die Signature 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 Auth Key, der auf Ihrer Zugangsdaten-Seite für die Nutzung von Smart CDN vorgesehen ist. Smart CDN-URLs erfordern sha256. Signatures für reguläre API-Anfragen verwenden den in signature_algo des Auth Keys konfigurierten Algorithmus; neue Auth Keys verwenden standardmäßig sha384.

Hinweis

Ältere Smart CDN-Signatures auf Basis von s= und expires= sind veraltet. Neue Integrationen sollten immer sig= mit exp= verwenden.

Die Generierung einer Smart CDN-Signature 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 die 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 zur 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 generiert:

  1. Fügen Sie den Abfrageparameter exp hinzu, um einen zukünftigen Zeitpunkt festzulegen, nach dem die Signature von Smart CDN nicht mehr akzeptiert wird. Dies ist nützlich, um den Zugriff auf eine Datei zeitlich zu begrenzen. Der Ablaufzeitpunkt wird als Anzahl der Millisekunden seit der UNIX-Epoche dargestellt (Mitternacht zu Beginn des 1. Januar 1970, UTC). Dieser Parameter ist zwar optional, wir empfehlen jedoch dringend, immer einen Ablaufzeitpunkt festzulegen. Eine Signature mit exp=1722517200000 ist beispielsweise bis Do, 01 Aug 2024 13:00:00 GMT gültig.
  2. Fügen Sie den Abfrageparameter auth_key hinzu, um den Auth Key festzulegen, der zu dem Auth Secret gehört, das zum Erstellen der Signature verwendet wird. Wenn dieser Parameter nicht gesetzt ist, geht die API von Transloadit davon aus, dass das älteste für Smart CDN aktivierte Auth Key-Paar für die Signature verwendet wurde. Durch das Setzen des Parameters auth_key können Sie Ihren Auth Key rotieren, ohne die Nutzung durch Ihre Benutzer zu unterbrechen. Daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel: auth_key=23c96d084c744219a2ce156772ec3211
  3. Sortieren Sie die Abfrageparameter anhand ihrer Schlüssel in aufsteigender Reihenfolge nach UTF-16-Codeeinheiten, entsprechend URLSearchParams.sort(). Die Sortierung sollte stabil sein, d. h., wenn ein Schlüssel mehrfach in der Abfragezeichenfolge vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Beispielsweise wird h=100&f=png&f=jpg&auth_key=hello&exp=123 zu auth_key=hello&exp=123&f=png&f=jpg&h=100 sortiert.
  4. Erstellen Sie die zu signierende Zeichenfolge, 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-kodiert sein, damit sie nur URL-sichere Zeichen enthalten. Beachten Sie, dass die Zeichenfolge 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-Signature in Hexadezimaldarstellung über die zu signierende Zeichenfolge, mit Ihrem Auth Secret als Schlüssel und SHA256 als Hash-Algorithmus. Stellen Sie der hexadezimalen Signature den Algorithmusnamen in Kleinbuchstaben und einen Doppelpunkt voran, also sha256:. Verwenden Sie für SHA256 beispielsweise sha256:[hmac-signature].
  6. Hängen Sie die hexadezimale Signature mit Präfix unter dem Abfrageparameter sig an die URL an. So erhalten Sie die signierte Smart CDN-URL:
    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-kodiert 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 dienen nicht nur der Zugriffskontrolle. Ihr Ablaufzeitpunkt bestimmt auch, wie lange ein neu generiertes Ergebnis cachebar bleiben darf.

  • Kürzere exp-Werte reduzieren das Replay-Zeitfenster und verschärfen die Zugriffskontrolle.
  • Längere exp-Werte erhöhen die Wiederverwendung des Caches, reduzieren den Aufwand am Origin und verringern im Allgemeinen die Latenz und das Kodierungsvolumen.
  • In der Praxis wird die effektive Cache-Lebensdauer einer signierten Smart CDN-Antwort durch die verbleibende Gültigkeitsdauer der Signature begrenzt.

Daraus ergibt sich eine klare Abwägung:

  • Höhere Sicherheitsanforderungen: Verwenden Sie einen kürzeren exp-Wert, was auch eine kürzere effektive Cache-TTL bedeutet.
  • Mehr Wiederverwendung des Caches und geringere Kosten: Verwenden Sie einen längeren exp-Wert, wodurch auch 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 ein gutes Gleichgewicht. Verwenden Sie für hochsensible Inhalte ein deutlich kürzeres.

Beispielcode

Nachfolgend finden Sie Beispiele in verschiedenen Sprachen zur Generierung 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 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 bestehenden aktiven Auth Key und dessen Auth Secret; der Auth Key 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 das SDK in einem vertrauenswürdigen serverseitigen Node.js-Projekt 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 Endpunktseite angegeben ist. Ersetzen Sie dabei alle Pfadparameter durch die Werte Ihrer Ressourcen. Halten Sie beide Zugangsdaten, die signierte URL und die Antwort geheim. Führen Sie diese Einrichtung 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 Signatures zu vermeiden. Wenn Ihr Auth Key einen anderen Signature-Algorithmus verwendet, übergeben Sie ihn als zweites Argument an calcSignature. Fügen Sie alle Endpunktfilter neben der Nonce in das Objekt ein, das als erstes Argument übergeben wird. Das SDK ruft für diese Anleitung /token nicht 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))

Bearer-Tokens (Client-Zugangsdaten)

Wenn Sie ein kurzlebiges Token für Server-zu-Server- oder Headless-Clients benötigen, können Sie Ihren Auth Key und Ihr Auth Secret gegen ein Bearer-Token eintauschen. Dies entspricht einem client_credentials-Ablauf nach OAuth 2.0, wird jedoch direkt von der Transloadit-API abgewickelt. Die vollständige Endpunktreferenz finden Sie in der /token-API-Dokumentation.

Verwendung des Tokens

Übergeben Sie das Token bei API-Anfragen als Authorization: Bearer <access_token>. Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert wird, betrachtet API2 die Signature Authentication als erfüllt und überspringt die Validierung der Signature. Signature Authentication wird nur bei Anfragen mit Auth Key und Auth Secret durchgesetzt. Scope- und Audience-Prüfungen gelten weiterhin. Die Audience mcp wird vom MCP-Server akzeptiert und von regulären API2-Endpunkten abgelehnt. Sie können auth.key in params weglassen, aber die params-Hülle ist für Endpunkte, die sie 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"}'

Automatische MCP-Authentifizierung für /ai/chat

Wenn Ihre /ai/chat-Steps einen von Transloadit gehosteten MCP-Server aufrufen, kann API2 automatisch ein kurzlebiges Bearer-Token ausstellen und einfügen (automatische Authentifizierung). Dies muss für jeden MCP-Servereintrag ausdrücklich aktiviert werden:

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

Verhalten:

  • Wenn auth: "transloadit" gesetzt ist und kein Authorization-Header vorhanden ist, stellt API2 ein Token aus und fügt Authorization: Bearer <token> ein.
  • Wenn Authorization bereits in mcp_servers[].headers angegeben ist, bleibt es unverändert.
  • Die automatische Authentifizierung 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 unter /mcp/ verwenden.
  • Die URL darf keine Zugangsdaten, keine Abfragezeichenfolge und kein Fragment enthalten.
  • Der Auth Key muss mindestens einen dieser sicheren MCP-Scopes gewähren: assemblies:write, assemblies:read, templates:read.
  • Das ausgestellte Token wird auf die Schnittmenge dieser sicheren MCP-Scopes und der Scopes des Auth Keys beschränkt; es erhält niemals einen Scope, den der Auth Key nicht gewährt.

Häufig gestellte Fragen

Fügt Transloadit seinen Anfragen Signatures bei?

Transloadit signiert Webhook-Anfragen, damit Ihr Server deren Authentizität überprüfen kann. Das Signieren von Webhooks ist vom HMAC getrennt, der API-Anfragen authentifiziert, die an Transloadit gesendet werden.

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

Abgesehen vom oben beschriebenen Server-zu-Server-Tokenaustausch darf Ihr Auth Secret niemals an einen Client übertragen oder in API-Anfrageparametern enthalten sein. POST /token sendet es als HTTP-Basic-Passwort über HTTPS und darf nur von Ihrem Back-End aus aufgerufen werden. Bei signierten Anfragen bleibt das Secret in Ihrem Back-End und wird als HMAC-Schlüssel verwendet. Dadurch wird verhindert, dass ein böswilliger Akteur eine signierte Anfrage abfängt und gefälschte Anfragen an Ihr Konto stellt. Schützen Sie Ihr Auth Secret mit einem System zur Verwaltung von Secrets Ihrer Wahl. Beispiele sind: Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ und Kubernetes Secrets⁠. Es gibt jedoch viele weitere, die je nach Ihrer bevorzugten Back-End-Plattform geeignet sein könnten.

Hinweis

Sie sollten sicherstellen, 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 ist frei wählbar. Wichtig ist jedoch, dass die gewählte Reihenfolge mit der Generierung Ihrer Signature übereinstimmt. Der generierte Hash hängt vom Inhalt des JSON ab. Eine andere Reihenfolge erzeugt einen anderen Hash, was dazu führt, dass 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 EN (English)
  • 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

Datenschutz EN (English)Nutzungsbedingungen EN (English)Impressum EN (English)
EnglishDeutschEspañolFrançaisPortuguês (Brasil)