Uploads und Frontend-Integration # Transloadit in fünf Minuten integrieren Installieren Sie das Node-SDK, skalieren Sie ein Bild und prüfen Sie in etwa fünf Minuten ein reales Assembly-Ergebnis. Veröffentlicht am 26. August 2026 ## Wichtigste Erkenntnisse * Bewahren Sie das Auth Secret auf einem vertrauenswürdigen Server auf und übergeben Sie es über Umgebungsvariablen. * Erstellen Sie eine Assembly mit einem Upload-Step und einem Image-Resize-Step, der das Bild auf 400 × 400 Pixel einpasst. * Geben Sie sowohl die Ergebnis-URL als auch die Assembly-ID aus, damit sich der erste Durchlauf leicht prüfen lässt. Die kürzeste sinnvolle Transloadit-Integration ist ein serverseitiges Skript, das ein Bild hochlädt und ein Derivat erzeugt. Es beweist, dass Zugangsdaten, Dateiübertragung, Verarbeitung und Ergebnisbehandlung funktionieren, bevor ein Browser, ein Speicherziel, eine Datenbank oder ein Webhook weitere bewegliche Teile hinzufügen. ## In diesem Leitfaden 1. [Mit einem vertrauenswürdigen Serverprozess beginnen](#transloadit-five-minute-integration-section-1) 2. [Das SDK installieren und den Befehl vorbereiten](#transloadit-five-minute-integration-section-2) 3. [Die erste Assembly ausführen](#transloadit-five-minute-integration-section-3) 4. [Das Ergebnis prüfen, statt beim Erfolg stehenzubleiben](#transloadit-five-minute-integration-section-4) 5. [Den Nachweis in eine Produktionsintegration verwandeln](#transloadit-five-minute-integration-section-5) 6. [Sicheren Status bereitstellen, Diagnosen schützen und einen Smoke-Test beibehalten](#transloadit-five-minute-integration-section-6) ## Worauf es besonders ankommt * Behandeln Sie die zurückgegebene Datei als temporär, bis ein Export-Step sie dauerhaft speichert. ## Mit einem vertrauenswürdigen Serverprozess beginnen Erstellen Sie einen kostenlosen Workspace, öffnen Sie die Seite mit den Zugangsdaten und generieren Sie einen Auth Key sowie ein Auth Secret. Für diesen serverseitigen Schnelleinstieg benötigen Sie beide Werte. Fügen Sie keinen der beiden Werte in die Quelldatei ein, und senden Sie das Secret niemals an einen Browser. Das Node-SDK nutzt das Paar, um Anfragen zu authentifizieren, ohne das Auth Secret als Anfrage-Zugangsdaten zu übertragen. Wählen Sie ein kleines JPEG-, PNG-, WebP- oder AVIF-Bild, das bereits auf der Festplatte liegt. Eine bescheidene Eingabe hält den ersten Durchlauf schnell und macht die Ausgabe leicht erkennbar. Das Skript nimmt den Dateipfad als einziges Kommandozeilenargument entgegen, sodass derselbe Code mit anderen Testdaten erneut ausgeführt werden kann, ohne ihn zu bearbeiten. ### Auth Key Identifiziert die für die Assembly verwendeten Zugangsdaten und kann sicher von vertrauenswürdigem Integrationscode referenziert werden. ### Auth Secret Verbleibt in der Serverumgebung und wird vom SDK zur Authentifizierung der Anfrage verwendet. ### Eine lokale Datei Hält diesen Durchlauf auf den API-Pfad fokussiert statt auf Browser-Upload-Status oder Remote-Importe. ## Das SDK installieren und den Befehl vorbereiten Erstellen Sie ein leeres ES-Modul-Projekt und fügen Sie das aktuelle Node-SDK mit npm hinzu. Speichern Sie im nächsten Abschnitt das TypeScript-Listing als `quickstart.ts` und führen Sie es anschließend mit dem nach dem Listing gezeigten Befehl aus. Dieser Schnelleinstieg führt die TypeScript-Datei mit Nodes nativem Type Stripping direkt aus und benötigt daher weder `tsx` noch `ts-node`. Natives Type Stripping ist ab Node 22.18 und Node 23.6 standardmäßig aktiviert, verwenden Sie also Node 22.18+, Node 23.6+ oder Node 24. Das SDK und das Bild sind die einzigen Laufzeit-Eingaben. Übergeben Sie die Zugangsdaten über Umgebungsvariablen an den Prozess. Shell-Verlauf, Prozessinspektion, CI-Logs und lokale Rechnerrichtlinien beeinflussen alle, ob Inline-Umgebungszuweisungen angemessen sind, verwenden Sie also für die Produktion Ihren üblichen Secret-Manager. Der hier gezeigte Befehl ist bewusst lokal und kurzlebig. Projekt anlegen und Node-SDK installieren ``` mkdir transloadit-quickstart cd transloadit-quickstart npm init -y npm pkg set type=module npm install @transloadit/node ``` ### Eine Abhängigkeit `@transloadit/node` übernimmt Authentifizierung, Datei-Upload, Status-Polling und typisierte Antworten. ### Node 24 Führt die TypeScript-Datei direkt aus und bewahrt dabei ein kopierbares typisiertes Beispiel. ### Keine Secret-Datei erforderlich Der Schnelleinstieg liest die beiden Zugangsdaten aus der Prozessumgebung. ## Die erste Assembly ausführen Speichern Sie das folgende TypeScript-Listing als `quickstart.ts`. Der `:original`-Step nimmt den Upload entgegen. Der `resized`-Step verweist mit `use` auf `:original` und startet daher erst, nachdem der Upload eine Datei erzeugt hat. Seine `resize_strategy` ist `fit`, wodurch das Seitenverhältnis erhalten bleibt und beide Abmessungen innerhalb von 400 Pixeln bleiben, statt das Bild auf ein Quadrat zuzuschneiden. Mit aktiviertem `waitForCompletion` gibt `createAssembly` erst zurück, wenn die Assembly einen Endzustand erreicht hat. Dieses blockierende Verhalten macht das erste Ergebnis anschaulich, ist aber eine didaktische Vereinfachung und keine Standardarchitektur für langsame Videos, große Batches oder einen Request-Handler mit kurzem Timeout. Genau ein Bild hochladen und in der Größe ändern ``` import { Transloadit } from '@transloadit/node' async function main(): Promise { const authKey = process.env.TRANSLOADIT_KEY const authSecret = process.env.TRANSLOADIT_SECRET const inputPath = process.argv[2] if (authKey == null || authSecret == null || inputPath == null) { throw new Error( 'Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, then pass an image path.', ) } const transloadit = new Transloadit({ authKey, authSecret }) const assembly = await transloadit.createAssembly({ files: { image: inputPath }, params: { steps: { ':original': { robot: '/upload/handle', }, resized: { use: ':original', robot: '/image/resize', result: true, width: 400, height: 400, resize_strategy: 'fit', }, }, }, waitForCompletion: true, }) const result = assembly.results?.resized?.[0] if (result == null) { throw new Error(`Assembly ${assembly.assembly_id} produced no resized result.`) } console.log(`Result: ${result.ssl_url}`) console.log(`Assembly: ${assembly.assembly_id}`) } main().catch((error: unknown) => { if (!(error instanceof Error)) { throw new Error(`Was thrown a non-error: ${error}`) } console.error(error.message) process.exit(1) }) ``` Den Schnelleinstieg ausführen ``` env \ TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY" \ TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET" \ node quickstart.ts ./your-image.jpg ``` ### :original Der reservierte Upload-Step, der eingehende Dateien für nachfolgende Robots verfügbar macht. ### resized Ein von der Integration gewählter Name; er wird zugleich zum Schlüssel, mit dem diese Ergebnisdateien ausgelesen werden. ### fit Begrenzt die Ausgabe, ohne den Bildinhalt zu strecken oder zu entfernen. ## Das Ergebnis prüfen, statt beim Erfolg stehenzubleiben Öffnen Sie die ausgegebene HTTPS-Ergebnis-URL und prüfen Sie, ob Abmessungen und sichtbarer Inhalt der Anfrage entsprechen. Öffnen Sie dann die Assembly anhand ihrer ID in der Transloadit Console. Der Assembly Status zeigt Uploads, Step-Ergebnisse, Zeitstempel, Metadaten und etwaige Fehler und ist damit die erste Anlaufstelle, um abzugleichen, was die Anwendung angefordert hat, mit dem, was die Plattform tatsächlich ausgeführt hat. Notieren Sie die Assembly-ID zusammen mit Ihrer eigenen Auftrags- oder Asset-Kennung. Eine URL allein reicht zur Fehlersuche nicht aus, da sie nicht erklärt, welche Eingabe, welche Parameter oder welcher Step sie erzeugt hat. Speichern Sie in der Produktion die konkreten Ergebnisfelder, die Ihre Anwendung benötigt, statt eine rohe Antwort eines Drittanbieters vollständig zu speichern oder zurückzugeben. ### Visuelle Prüfung Bestätigt, dass der Workflow die beabsichtigte Variante erzeugt hat, und nicht nur einen erfolgreichen Statuscode. ### Assembly Status Liefert die Verarbeitungsspur und Metadaten für Debugging und Abgleich. ### Anwendungsdatensatz Verknüpft die externe Assembly-ID mit dem Nutzer, der Eingabe und der Geschäftsaktion, die sie ausgelöst hat. ## Den Nachweis in eine Produktionsintegration verwandeln Temporäre Assembly-Dateien werden etwa 24 Stunden lang aufbewahrt und sind für eine begrenzte Anzahl kurzfristiger Abrufe gedacht, nicht für die direkte Auslieferung an Endnutzer. Bevor ein Ergebnis dauerhaft wird, fügen Sie einen Export-Robot hinzu, etwa `/s3/store`, `/azure/store` oder das Ziel, das Ihrer Anwendung gehört. Speichern Sie Cloud-Schlüssel als Template-Zugangsdaten, nicht als literale Werte im Anwendungscode oder in den Assembly Instructions. Speichern Sie die Steps als Template, setzen Sie `allow_steps_override` auf false, wenn Aufrufer den Graphen nicht ändern dürfen, und senden Sie nur dessen `template_id` sowie validierte Felder. Browser-Uploads benötigen signierte, ablaufende Parameter, die von einem Backend erzeugt werden. Hintergrundverarbeitung sollte sofort eine Anwendungs-Auftrags-ID zurückgeben, einen verifizierten Webhook verarbeiten, doppelte Zustellungen sicher akzeptieren und den Abgleich über Assembly Status vornehmen, wenn eine Benachrichtigung ausbleibt. ### Dauerhafter Export Verschiebt Ergebnisse aus dem standardmäßigen temporären Aufbewahrungsfenster in eigenen Speicher. ### Gespeichertes Template Hält den Verarbeitungsgraphen kontrolliert, während Integrationen eine kompakte Template-ID übermitteln. ### Verifizierter Abschluss Ein signierter Webhook und regelmäßiger Abgleich machen lang laufende Aufträge wiederherstellbar. ## Sicheren Status bereitstellen, Diagnosen schützen und einen Smoke-Test beibehalten Eine Produktionsoberfläche sollte einen knappen, anwendungseigenen Status wie „in der Warteschlange“, „in Bearbeitung“, „bereit“ oder „fehlgeschlagen“ anzeigen. Betreiber benötigen weiterhin einen geschützten Pfad von diesem Datensatz zur Assembly-ID und zu bereinigten Diagnosedaten. Geben Sie Endnutzern keine rohen Anbieterfehler, Stack-Traces, Speicherantworten oder URLs mit eingebetteten Zugangsdaten zurück, nur weil der Schnelleinstieg ein Ergebnis auf einem Terminal ausgibt. Bewahren Sie ein kleines, bekanntermaßen funktionierendes Bild sowie die erwarteten Ausgabebeschränkungen als Smoke-Test auf. Führen Sie ihn nach einer Rotation der Zugangsdaten oder einer kontrollierten Workflow-Änderung aus, machen Sie aber keine kostenpflichtige externe Assembly zu einem Bestandteil jedes Unit-Test-Laufs. Unit-Tests sollten lokale Regeln und Zuordnungen prüfen, während ein expliziter Integrationstest die live gültigen Zugangsdaten, den Upload, den Robot und den Ergebnispfad gemeinsam belegt. ### Sicherer Client-Zustand Einen verwertbaren Status anzeigen, ohne eine Drittanbieter-Antwort oder interne Ausnahme preiszugeben. ### Geschützter Pfad Ermöglicht autorisierten Betreibern den Zugriff auf die Assembly-ID und die zur Untersuchung nötigen Diagnosedaten. ### Bewährte Testdaten Trennt echte Integrationsfehler von ungewöhnlichen Kundenmedien, wenn der Pfad getestet wird. ## Wissenswerte technische Details * Eine Assembly ist eine Ausführung von Assembly Instructions. Jeder Verarbeitungs-Step ruft einen Robot auf und deklariert seine vorgelagerte Eingabe über `use`; der reservierte `:original`-Upload-Step ist die Quelle und benötigt kein `use`. * Das Node-SDK generiert die Anfrage-Authentifizierung aus Auth Key und Auth Secret. Das Secret gehört ausschließlich in einen vertrauenswürdigen Serverprozess, niemals in Browser-JavaScript oder eine mobile Anwendung. * Wird `waitForCompletion` auf true gesetzt, fragt das SDK so lange ab, bis die Assembly einen Endzustand erreicht, was für einen kleinen ersten Testlauf praktisch, aber für lang laufende Request-Handler ungeeignet ist. * Das Flag `result` markiert die Dateien eines Steps zur Aufnahme in das übergeordnete `results`-Objekt der Assembly. Es macht die Dateien nicht dauerhaft. * Temporäre Assembly-Dateien sind standardmäßig etwa 24 Stunden lang und für eine begrenzte Anzahl von Abrufen verfügbar. Liefern Sie ihre URLs nicht direkt an Endnutzer aus; fügen Sie für nutzerseitig sichtbare Dateien einen Export-Robot hinzu. * Die Assembly-ID ist eine nützliche Referenz zur Fehlersuche, selbst wenn eine Anwendung ihre eigene übergeordnete Auftragskennung speichert. ## Ein praxisnaher Ansatz 1. 1\ Erstellen Sie einen Auth Key und wählen Sie ein kleines lokales Bild aus. 2. 2\ Installieren Sie das Node-SDK und führen Sie den TypeScript-Schnelleinstieg mit Zugangsdaten in der Umgebung aus. 3. 3\ Öffnen Sie die ausgegebene Ergebnis-URL und prüfen Sie die Assembly in der Konsole. 4. 4\ Verlagern Sie den Workflow in ein gespeichertes Template und fügen Sie vor dem Produktionseinsatz dauerhaften Speicher hinzu. Ein vierstufiger Medienworkflow ## Wann Transloadit hilfreich ist Verwenden Sie das Node-SDK, um eine Assembly mit /upload/handle und /image/resize zu erstellen. Das SDK signiert die Anfrage mit serverseitigen Zugangsdaten, lädt die lokale Datei hoch, wartet auf den Abschluss und gibt die Ergebnis-URL sowie die Assembly-ID zurück. ## Architekturgrenze Dieser Schnelleinstieg läuft auf einem vertrauenswürdigen Server und wartet, bis ein kleines Bild fertig verarbeitet ist. Eine Browser-Integration muss signierte, kurzlebige Parameter von einem Backend erhalten, während produktive Hintergrundarbeit einen verifizierten Webhook verwenden sollte, statt eine HTTP-Anfrage offen zu halten. ## Häufig gestellte Fragen ### Kann ich das Auth Secret für diesen Schnelleinstieg in Browser-JavaScript einbetten? Nein. Das Beispiel läuft serverseitig. Ein Browser sollte signierte, kurzlebige Assembly-Parameter von einem Backend anfordern, das das Auth Secret geheim hält. ### Warum wartet das Skript auf den Abschluss? `waitForCompletion` macht einen ersten Durchlauf leicht überprüfbar, indem es das fertige Ergebnis zurückgibt. Produktive Request-Handler sollten normalerweise Hintergrundarbeit starten und einen verifizierten Webhook oder kontrolliertes Status-Polling verwenden. ### Wo wird das skalierte Bild gespeichert? Es handelt sich um ein temporäres Assembly-Ergebnis, das standardmäßig 24 Stunden lang aufbewahrt wird. Fügen Sie einen Storage-Robot hinzu, um es dauerhaft an einem von Ihnen kontrollierten Ziel zu speichern. ### Warum `fit` statt `fillcrop` verwenden? `fit` erhält das komplette Bild und begrenzt es auf die angeforderte Box. `fillcrop` füllt exakte Abmessungen durch Zuschneiden, was eine bewusste Kompositionsentscheidung erfordert. ### Was sollte ich nach Abschluss der Assembly speichern? Speichern Sie die Assembly-ID, Ihre eigene Auftrags- oder Asset-ID, die ausgewählten Ergebnismetadaten mit dem dauerhaften Speicherort sowie einen bereinigten Endstatus. Geben Sie Clients standardmäßig nicht die gesamte Rohantwort preis. ## Erstellen Sie den Workflow Entwickeln Sie das Konzept mithilfe der Robot-Dokumentation und funktionsfähiger Demos zu einer getesteten Assembly weiter. ### Relevante Robots * [/upload/handle](/de/docs/robots/upload-handle.md) * [/image/resize](/de/docs/robots/image-resize.md) * [Auth Key erstellen](/c/credentials/) * [Node-SDK-Dokumentation lesen](/de/docs/sdks/node-sdk.md) * [Ergebnisse dauerhaft speichern](/de/docs/getting-started/saving-conversion-results.md) * [Lesen Sie die API-Dokumentation](/de/docs.md) * [Entdecken Sie funktionsfähige Demos EN (English)](/demos.md) * [Kostenlosen Workspace erstellen](/c/signup/) Uploads und Frontend-Integration ## Mit verwandten Leitfäden fortfahren * [Anpassbare Medienverarbeitungs-Workflows mit Transloadit](/de/guides/customizable-media-processing-workflows.md)\ Entwerfen Sie ein wiederverwendbares Template mit Validierung, Variablen, parallelen Derivaten, sicherem Speicher und beobachtbarem Abschluss. * [Leitfaden zur File Upload API: Architektur, Sicherheit und Anbieterauswahl](/de/guides/file-upload-api-guide.md)\ Eine File Upload API anhand von Architektur, Wiederaufnahme, direkter Cloud-Übertragung, Sicherheit, Speichergrenzen und Anbietern auswählen und implementieren. * [React-Datei-Uploads mit Uppy: fortsetzbare Uploads, Vorschauen, Validierung und Verarbeitung](/de/guides/react-file-uploads-with-uppy.md)\ React-Dateiuploader mit Uppy bauen: Vorschau, Validierung, barrierefreier Fortschritt, Abbruch, fortsetzbarer Upload und Übergabe zur Transloadit-Verarbeitung. * [Datei-Uploads, Bildoptimierung und Ihr eigener S3-Bucket](/de/guides/file-uploads-image-optimization-s3.md)\ Kombinieren Sie fortsetzbare Browser-Uploads, Bildoptimierung, kundeneigenen Amazon-S3-Speicher und On-Demand-Auslieferung ohne separate Medien-Services. * [Große Uploads trotz Verbindungsabbruch zuverlässig annehmen](/de/guides/resumable-uploads-for-large-files.md)\ Nehmen Sie Multi-Gigabyte-Uploads über tus an, setzen Sie sie nach Verbindungsabbrüchen fort und halten Sie die Assembly bis zum Abschluss aktiv. * [Sichere Datei-Uploads in Next.js mit Uppy und signierten Transloadit Templates](/de/guides/secure-file-uploads-nextjs-uppy.md)\ Sicherer Next.js-App-Router-Upload mit Uppy, Serversignierung, gesperrtem Template, verbindlicher Prüfung, fortsetzbarem Transfer und asynchronem Abschluss.