Uploads und Frontend-Integration # Große Uploads trotz Verbindungsabbruch zuverlässig annehmen Nehmen Sie Multi-Gigabyte-Uploads über tus an, setzen Sie sie nach Verbindungsabbrüchen fort und halten Sie die Assembly bis zum Abschluss aktiv. Veröffentlicht am 13. August 2026 ## Wichtigste Erkenntnisse * Dateien, die in der Multipart-Anfrage zum Erstellen der Assembly enthalten sind, können nicht fortgesetzt werden. Daher lässt jede Unterbrechung die gesamte Assembly fehlschlagen. * Beim Hochladen über tus kann ein Client die Übertragung an dem Byte-Offset fortsetzen, bis zu dem die Daten bereits auf dem Server vorliegen, statt von vorn zu beginnen. * Erstellen Sie zuerst die Assembly mit num\_expected\_upload\_files und laden Sie die Dateien dann an die zurückgegebene tus\_url hoch. Ein großer Upload ist keine Anfrage, die gelegentlich fehlschlägt. Er ist eine Übertragung, die unterbrochen werden wird. Entscheidend ist nur, ob eine Unterbrechung den Nutzer die verbleibenden Bytes oder sämtliche Bytes kostet. Alles Weitere im Design ergibt sich aus dieser Entscheidung. ## In diesem Leitfaden 1. [Zwei Upload-Pfade, von denen nur einer fortgesetzt werden kann](#resumable-uploads-for-large-files-section-1) 2. [Die Anzahl der eingehenden Dateien angeben](#resumable-uploads-for-large-files-section-2) 3. [Wiederaufnahme als Offset, nicht als Wiederholungsversuch](#resumable-uploads-for-large-files-section-3) 4. [Die Übertragung wird fortgesetzt, die Assembly läuft trotzdem ab](#resumable-uploads-for-large-files-section-4) 5. [Die benötigten Metadaten an jede Datei anhängen](#resumable-uploads-for-large-files-section-5) 6. [Die Anfrage signieren, wenn der Browser der Client ist](#resumable-uploads-for-large-files-section-6) ## Worauf es besonders ankommt * Uploads, die über die angegebene Anzahl hinausgehen, werden ohne Meldung verworfen. Eine Abweichung um eins bei dieser Zahl führt daher ohne Fehlermeldung zum Verlust von Dateien. * Dateien dürfen bis zu 200 GB groß sein, die Assembly läuft jedoch weiterhin acht Stunden nach ihrer Erstellung ab. ## Zwei Upload-Pfade, von denen nur einer fortgesetzt werden kann Transloadit nimmt Dateien auf zwei Arten an, und der Unterschied zeigt sich erst bei einer schlechten Verbindung. Dateien können an den `multipart/form-data`-POST angehängt werden, mit dem die Assembly erstellt wird. Das ist einfach und für ein Profilbild gut geeignet. Jede Unterbrechung dieser Anfrage lässt den Upload und damit auch die Assembly fehlschlagen. Der Client kann die Übertragung nicht fortsetzen, sondern nur alles erneut senden. Der andere Weg verwendet [tus⁠](https://tus.io/), ein offenes Protokoll für fortsetzbare Uploads über HTTP mit Client-Implementierungen für die meisten Programmiersprachen. Transloadit betreibt einen tus-Server. Ein Client, der das Protokoll unterstützt, kann pausieren, seine Verbindung verlieren und die Übertragung ab dem zuletzt vom Server bestätigten Byte fortsetzen. Bei Dateien mit Hunderten von Megabyte entscheidet das darüber, ob ein Upload schließlich abgeschlossen wird oder nie zum Abschluss kommt. ### Multipart Eine einzige Anfrage überträgt die Dateien. Bei einer Unterbrechung schlagen sowohl der Upload als auch die Assembly fehl. ### tus Eine separate Übertragung pro Datei, die ab dem letzten bestätigten Byte fortgesetzt werden kann. ### Vom Client bereits übernommen Uppy und die Backend-SDKs nutzen intern tus, sodass die meisten Integrationen dies ohne zusätzlichen Aufwand erhalten. ## Die Anzahl der eingehenden Dateien angeben Ein fortsetzbarer Upload kehrt die übliche Reihenfolge um: Die Assembly wird erstellt, bevor Bytes vorhanden sind. Die Erstellungsanfrage enthält wie gewohnt `params` sowie das Feld `num_expected_upload_files`, das angibt, wie viele Dateien folgen werden, jedoch keinerlei Dateiinhalt. Die Antwort ist ein gewöhnlicher Assembly Status mit zwei hier relevanten Ergänzungen: `tus_url` gibt an, wohin die Uploads übertragen werden, und das Trio aus `expected_tus_uploads`, `started_tus_uploads` und `finished_tus_uploads` dient zu ihrer Nachverfolgung. Diese angegebene Anzahl wird strenger durchgesetzt, als es zunächst den Anschein hat. Die Assembly bleibt in `ASSEMBLY_UPLOADING`, bis jeder erwartete Upload abgeschlossen ist, selbst wenn früh eingegangene Dateien bereits verarbeitet wurden. Uploads, die über die angegebene Anzahl hinaus bereitgestellt werden, werden ohne Fehlermeldung verworfen. Dadurch ist eine falsche Anzahl einer der schwerer zu bemerkenden Fehler: Die Assembly wird erfolgreich abgeschlossen, doch in den Ergebnissen fehlt einfach eine Datei. Die Assembly erstellen, bevor Bytes gesendet werden ``` POST /assemblies HTTP/1.1 Host: api2.transloadit.com Content-Type: multipart/form-data; boundary=---xyz -----xyz Content-Disposition: form-data; name="params" {"auth":{"key":"YOUR_KEY"}, "template_id":"YOUR_TEMPLATE_ID"} -----xyz Content-Disposition: form-data; name="num_expected_upload_files" 2 -----xyz-- ``` ### num\_expected\_upload\_files Legen Sie als Wert die genaue Anzahl der Dateien fest, die der Client senden wird, und zählen Sie die Dateien, bevor Sie die Assembly erstellen. ### tus\_url Der Upload-Endpunkt für diese Assembly, der im Assembly Status zurückgegeben wird, statt fest im Code hinterlegt zu sein. ### Verwerfen zusätzlicher Dateien Alle Dateien, die über die angegebene Anzahl hinausgehen, werden ohne Hinweis verworfen. Daher lohnt es sich, die Anzahl mit einer Assertion zu prüfen. ## Wiederaufnahme als Offset, nicht als Wiederholungsversuch Jeder Upload beginnt mit einer POST-Anfrage an `tus_url`, mit der eine Ressource erstellt wird, statt Daten zu senden. Die Anfrage enthält drei Metadatenwerte: `assembly_url`, `filename` und `fieldname`. Der Server antwortet mit einer Upload-URL im Header `Location`. Anschließend werden die Bytes in einer oder mehreren PATCH-Anfragen an diese URL gesendet. Sobald die letzte Anfrage eingegangen ist, wird die Datei ohne weiteren Aufruf der Assembly zugeführt. Für die Wiederaufnahme wird dieselbe URL verwendet. Eine HEAD-Anfrage gibt im Header `Upload-Offset` die Anzahl der Bytes zurück, die der Server tatsächlich gespeichert hat. Der Client setzt den Upload dann mit einer PATCH-Anfrage fort, die genau an diesem Offset beginnt. Deshalb sind ein erneuter Versuch und eine Wiederaufnahme nicht derselbe Vorgang: Bei einem erneuten Versuch wird die Datei nochmals ab Byte null gesendet. Bei einer Wiederaufnahme fragt der Client den Server, welche Daten bereits vorhanden sind, und sendet nur die Differenz. Offset abfragen und dann nur den Rest senden ``` HEAD /resumable/files/136058f2ef4d HTTP/1.1 Host: api2-freja.transloadit.com Tus-Resumable: 1.0.0 HTTP/1.1 204 No Content Upload-Offset: 3000 Upload-Length: 10000 PATCH /resumable/files/136058f2ef4d HTTP/1.1 Host: api2-freja.transloadit.com Tus-Resumable: 1.0.0 Upload-Offset: 3000 Content-Length: 7000 Content-Type: application/offset+octet-stream ``` ### Erstellen, dann übertragen Die erste POST-Anfrage legt die Upload-URL fest. Die PATCH-Anfragen übertragen den eigentlichen Inhalt. ### Upload-Offset Der Server gibt an, wie viele Daten er empfangen hat. Der Client muss daher nie erraten, an welcher Stelle er fortfahren soll. ### Upload-URL speichern Um den Upload nach dem Neuladen einer Seite fortzusetzen, ist diese URL erforderlich. Speichern Sie sie daher dauerhaft, statt sie nur im Arbeitsspeicher vorzuhalten. ## Die Übertragung wird fortgesetzt, die Assembly läuft trotzdem ab Die Möglichkeit, einen Upload fortzusetzen, wird oft als unbegrenzte Schonfrist verstanden, doch das ist sie nicht. Die Assembly wurde zu Beginn erstellt und ihre Zeit läuft bereits: Für das Hochladen stehen höchstens acht Stunden zur Verfügung, für die Verarbeitung weitere acht Stunden. Zusammen sind beide Vorgänge auf sechzehn Stunden ab der Erstellung begrenzt. Überschreitet eine Assembly diese Grenzen, gibt sie `ASSEMBLY_EXPIRED` zurück und der zugehörige unvollständige Upload ist nicht mehr nutzbar. Das ist besonders bei den Workloads wichtig, für die eine Fortsetzung überhaupt erforderlich ist. Pausiert ein Nutzer einen großen Upload über Nacht, existiert die Assembly bei seiner Rückkehr nicht mehr. Der Client muss diesen Fall daher erkennen und eine neue Assembly erstellen, statt den Upload über eine nicht mehr gültige URL erneut zu versuchen. Wenn der Ablauf als erwartetes Ergebnis statt als zu protokollierender Fehler behandelt wird, bildet dieser Wiederherstellungspfad die tatsächlichen Bedingungen korrekt ab. ### Acht Stunden für den Upload Gemessen ab der Erstellung der Assembly, nicht ab dem Zeitpunkt, zu dem die Übertragung zuletzt Fortschritte machte. ### Höchstgrenze von sechzehn Stunden Upload und Verarbeitung dürfen zusammen ab der Erstellung höchstens sechzehn Stunden dauern. ### Neustart einplanen Erkennen Sie eine abgelaufene Assembly und erstellen Sie eine neue, statt den Upload über die alte URL erneut zu versuchen. ## Die benötigten Metadaten an jede Datei anhängen Neben den drei erforderlichen Werten sind alle zusätzlichen Metadaten, die mit einem Upload gesendet werden, als Assembly Variable unter `file.user_meta` verfügbar. Ein als `owner` gesendeter Schlüssel wird daher als `${file.user_meta.owner}` ausgelesen. Diese Unterscheidung sollten Sie früh verinnerlichen, denn `fields` gilt gemeinsam für jede Datei in der Assembly, während Nutzermetadaten jeweils zu einer Datei gehören. Wenn in einem Batch jede Datei einen eigenen Zielpfad, Eigentümer oder eine eigene Kategorie benötigt, sind Nutzermetadaten die richtige Wahl. Der Versuch, diese Angaben über gemeinsame Felder auszudrücken, führt zu einem Template, das die Dateien nicht voneinander unterscheiden kann. Wenn Sie anhand des Inhalts statt anhand der Angaben des Clients verzweigen, verwenden Sie vorzugsweise `${file.mime}` und gleichen Sie Familien wie `image/*` oder `video/*` ab. Ein vom Client bereitgestellter Dateiname oder eine Kategorie ist nur ein Hinweis. Wird diese Angabe als Tatsache behandelt, kann eine ausführbare Datei in einem Pfad landen, der Bilder voraussetzt. Die allgemeine Kategorie `${file.type}` ist ebenfalls verfügbar, doch der MIME-Abgleich ist die präzisere der beiden Möglichkeiten. ### Drei Pflichtangaben Jeder Upload benötigt assembly\_url, filename und fieldname in seinen tus-Metadaten. ### Pro Datei oder pro Assembly Nutzermetadaten gehören zu einer Datei, während Felder im selben Durchlauf für alle Dateien gemeinsam gelten. ### Nach MIME verzweigen Gleichen Sie ${file.mime} ab, statt einer Dateiendung oder einer vom Client bereitgestellten Kategorie zu vertrauen. ## Die Anfrage signieren, wenn der Browser der Client ist Wenn ein Upload in einem Browser startet, werden die Assembly Instructions aus einer Umgebung übermittelt, die Sie nicht kontrollieren. Signature Authentication schließt diese Lücke: Ihr Backend signiert die Parameter mit dem Auth Secret, fügt einen Zeitstempel `auth.expires` für die nahe Zukunft hinzu und übergibt das Ergebnis an das Frontend. Wenn Sie die Anforderung in den Einstellungen für den Workspace aktivieren, weist die API alle nicht signierten Anfragen für das Konto zurück. Entscheidend ist, dass Ihr Server festlegt, was er signiert. Mit gewöhnlicher Anwendungslogik kann er anonyme Nutzer ablehnen, einschränken, welches Template eine Anfrage aufrufen darf, oder die Parameter vor dem Signieren begrenzen. Das Auth Secret verlässt das Backend nie, und eine abgefangene Signatur kann nur bis zu dem Ablaufzeitpunkt verwendet werden, mit dem sie ausgestellt wurde. Signatur vom eigenen Backend abrufen ``` const uppy = new Uppy().use(Transloadit, { waitForEncoding: true, assemblyOptions: async () => { // Your back end signs with the Auth Secret const res = await fetch('/api/tl-signature') const { params, signature } = await res.json() return { params, signature } }, }) ``` ### Serverseitig signieren Das Auth Secret bleibt im Backend und gelangt nie in ein Browser-Bundle. ### auth.expires Ein zeitnaher Zeitstempel, der begrenzt, wie lange eine ausgestellte Signatur verwendbar bleibt. ### Signatur voraussetzen In den Einstellungen für den Workspace können Sie alle nicht signierten Anfragen für das Konto ausnahmslos ablehnen lassen. ## Wissenswerte technische Details * Die Assembly wird durch einen Multipart-POST erstellt, der params und num\_expected\_upload\_files, aber keine Dateiinhalte überträgt. Die Antwort enthält tus\_url, expected\_tus\_uploads, started\_tus\_uploads und finished\_tus\_uploads. * Eine Assembly bleibt im Zustand ASSEMBLY\_UPLOADING, bis jeder deklarierte tus-Upload abgeschlossen ist, selbst wenn einige der bereits empfangenen Dateien verarbeitet wurden. * Jeder tus-Upload beginnt mit einem POST an tus\_url, der assembly\_url, filename und fieldname als Metadaten überträgt. Der Server antwortet mit der Upload-URL im Location-Header. * Das Fortsetzen beginnt mit einer HEAD-Anfrage an diese Upload-URL, die im Header Upload-Offset die Anzahl der empfangenen Bytes meldet. Anschließend sendet eine PATCH-Anfrage die verbleibenden Bytes exakt ab diesem Offset. * Zusätzliche Metadaten, die mit einem Upload gesendet werden, werden unter file.user\_meta als Assembly Variable verfügbar und gelten jeweils für eine Datei. Im Gegensatz dazu gilt fields gemeinsam für jede Datei derselben Assembly. * Der Upload ist auf acht Stunden und die Verarbeitung auf weitere acht Stunden begrenzt. Insgesamt gilt ab der Erstellung eine Höchstgrenze von sechzehn Stunden. Danach gibt die Assembly ASSEMBLY\_EXPIRED zurück. ## Ein praxisnaher Ansatz 1. 1\ Erstellen Sie die Assembly und setzen Sie num\_expected\_upload\_files auf die exakte Anzahl der Dateien, die der Client senden wird. 2. 2\ Laden Sie jede Datei mit einem tus-Client statt mit einem einfachen POST an die tus\_url aus dem Assembly Status hoch. 3. 3\ Speichern Sie die Upload-URL dauerhaft auf dem Client, damit der Upload nach einem erneuten Laden oder Absturz fortgesetzt wird, statt neu zu beginnen. 4. 4\ Signieren Sie die Anfrage zum Erstellen der Assembly in Ihrem Backend, wenn der Browser als Client dient. Ein vierstufiger Medienworkflow ## Wann Transloadit hilfreich ist Verwenden Sie Uppy mit dem Transloadit-Plugin im Browser oder andernorts einen beliebigen tus-Client und lassen Sie /upload/handle die Dateien empfangen. Erstellen Sie zuerst die Assembly mit num\_expected\_upload\_files und senden Sie dann jede Datei an die tus\_url, die im Assembly Status zurückgegeben wird. ## Architekturgrenze Mit der Wiederaufnahme lässt sich eine unterbrochene Übertragung fortsetzen, eine vergessene jedoch nicht. Uploads müssen innerhalb von acht Stunden nach Erstellung der Assembly abgeschlossen sein und die Verarbeitung innerhalb weiterer acht Stunden; insgesamt gilt eine Obergrenze von sechzehn Stunden ab der Erstellung. Danach gibt die Assembly ASSEMBLY\_EXPIRED zurück, und die bereits empfangenen Bytes können nicht mehr verwendet werden. ## Häufig gestellte Fragen ### Muss ich das tus-Protokoll selbst implementieren? Normalerweise nicht. Uppy und die Backend-SDKs verwenden standardmäßig tus, sodass eine normale Integration bereits fortsetzbare Uploads ermöglicht. Das Protokoll müssen Sie nur direkt implementieren, wenn Sie ein SDK entwickeln oder eine Sprache verwenden, für die kein Transloadit-SDK verfügbar ist. ### Warum sind einige meiner Dateien nie in den Ergebnissen erschienen? Die wahrscheinliche Ursache ist ein Wert für `num_expected_upload_files`, der unter der Anzahl der tatsächlich gesendeten Dateien liegt. Uploads, die über die angegebene Anzahl hinausgehen, werden ohne Meldung verworfen. Daher wird die Assembly erfolgreich abgeschlossen, obwohl Dateien fehlen. Zählen Sie die Dateien, bevor Sie die Assembly erstellen. ### Was passiert, wenn der Nutzer während eines Uploads den Tab schließt? Die Übertragung kann fortgesetzt werden, solange der Client die Upload-URL gespeichert hat und die Assembly noch nicht abgelaufen ist. Speichern Sie diese URL außerhalb des Seitenspeichers. Senden Sie bei der Rückkehr eine HEAD-Anfrage, um den Byte-Offset zu ermitteln und die Übertragung dort fortzusetzen. ### Wie groß darf eine Datei sein, die ich hochlade? Dateien bis zu 200 GB werden unterstützt, und höhere Limits können vereinbart werden. In der Praxis ist meist die Zeit statt der Größe die Einschränkung: Für den Upload stehen ab Erstellung der Assembly acht Stunden zur Verfügung. Bei einer langsamen Verbindung kann diese Frist ablaufen, bevor eine sehr große Datei vollständig hochgeladen wurde. ### Gehören dateispezifische Informationen in Felder oder in Metadaten? Verwenden Sie tus-Upload-Metadaten, wenn der Wert zu einer einzelnen Datei gehört, da er unter `file.user_meta` als Assembly Variable eingeht. Verwenden Sie `fields` nur für Werte, die für jede Datei in der Assembly gelten, etwa eine Kundenkennung für den gesamten Batch. ## 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) * [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 * [Responsive Bilder über eine einzige URL ausliefern](/de/guides/serve-responsive-images-from-one-url.md)\ Leiten Sie jede Bildgröße aus einer kanonischen URL ab, cachen Sie die Ergebnisse am Edge und halten Sie die Encoding-Kosten trotz wachsendem Traffic stabil. * [Medienautomatisierung: vom Upload zur zuverlässigen Ausgabe](/de/guides/media-automation.md)\ Automatisieren Sie wiederholbare Medienaufnahme, Transformation, Validierung und Export, ohne Beobachtbarkeit und Kontrolle einzuschränken. * [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. * [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. * [Die besten JavaScript-Bibliotheken für Datei-Uploads: Uppy vs. FilePond vs. Dropzone](/de/guides/best-javascript-file-upload-libraries.md)\ Vergleichen Sie Uppy, FilePond und Dropzone nach Protokoll, Schnittstellenmodell, Wiederherstellung, Integration und langfristiger Verantwortung. * [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.