Wie chunk_size der TikTok API und total_chunk_count zusammenpassen müssen

Was macht das Feld chunk_size der TikTok API?

Das Feld chunk_size der TikTok API sagt TikToks Servern, wie viele Bytes jede PUT-Anfrage trägt, wenn du ein Video mit source: "FILE_UPLOAD" überträgst. Du deklarierst es einmal, im Body des init-Aufrufs, bevor sich ein einziges Byte Video bewegt. Alles, was TikTok danach prüft, wird gegen diese Deklaration geprüft.

Drei Felder reisen zusammen in source_info, und TikTok beschreibt sie so:

Feld	Typ	TikToks Beschreibung
video_size	int64	„The size of the video to be uploaded in bytes.“
chunk_size	int64	„The size of the chunk in bytes.“
total_chunk_count	int64	„The total number of chunks.“

Beide init-Endpunkte nehmen sie an. /v2/post/publish/inbox/video/init/ ist der Upload-Endpunkt, der einen Entwurf in den Posteingang des Creators legt. /v2/post/publish/video/init/ ist der Direct-Post-Endpunkt, der direkt auf das Profil veröffentlicht. Die Upload-Referenz markiert alle drei Felder mit „true for FILE_UPLOAD“. Die Direct-Post-Referenz markiert video_size mit „true for FILE_UPLOAD“ und lässt die Pflichtspalte bei chunk_size und total_chunk_count leer. TikTok sagt nirgends, dass die beiden Felder bei Direct Post optional sind, und die veröffentlichten Chunk-Regeln sind einmal für beide Endpunkte geschrieben, also behandle die leeren Zellen als Formatierungsartefakt und sende alle drei.

Was ist die minimale und maximale Chunk-Größe bei TikTok?

Jeder Chunk muss mindestens 5 MB und darf höchstens 64 MB groß sein, mit einer Ausnahme am Ende der Datei. TikToks Media Transfer Guide formuliert es so:

„Each chunk must be at least 5 MB but no greater than 64 MB, except for the final chunk, which can be greater than chunk_size (up to 128 MB) to accommodate any trailing bytes.“

Drei weitere Sätze in derselben Liste vervollständigen das Regelwerk:

Regel	TikToks Wortlaut
Kleine Dateien	„Videos with a total size less than 5 MB must be uploaded as a whole, with chunk_size equal to the entire video's byte size.“
Große Dateien	„Videos with a total size greater than 64 MB must be uploaded in multiple chunks.“
Chunk-Anzahl	„There must be a minimum of 1 chunk and a maximum of 1000 chunks.“
Reihenfolge	„File chunks must be uploaded sequentially.“

Die Regel zur Reihenfolge entdecken die meisten spät. Chunks lassen sich nicht auf mehrere Worker verteilen, weil TikTok einen einzigen Byte-Offset pro Upload-Task führt und mit 416 RequestedRangeNotSatisfiable antwortet, wenn ein Content-Range-Header außer der Reihe ankommt.

Wie wird total_chunk_count berechnet?

Teilen und abrunden, nie aufrunden. TikToks genauer Satz:

„The value of total_chunk_count should be equal to video_size divided by chunk_size, rounded down to the nearest integer.“

TikToks durchgerechnetes Beispiel ist eine 50.000.123 Byte große Datei mit einer chunk_size von 10.000.000. Fünfzig Millionen geteilt durch zehn Millionen ist fünf Komma null null null null eins zwei drei, also ist total_chunk_count 5, nicht 6. Die 123 übrigen Bytes bekommen keine eigene Anfrage. Sie fahren im fünften Chunk mit, der damit 10.000.123 Byte groß ist, etwas größer als die deklarierte chunk_size:

Anfrage	Content-Range	Bytes in diesem Chunk	Status
1	bytes 0-9999999/50000123	10.000.000	206
2	bytes 10000000-19999999/50000123	10.000.000	206
3	bytes 20000000-29999999/50000123	10.000.000	206
4	bytes 30000000-39999999/50000123	10.000.000	206
5	bytes 40000000-50000122/50000123	10.000.123	201

Hier zerlegt eine Aufrundungsfunktion still eine Integration. Aufrunden ergibt einen sechsten Chunk von 123 Byte, der sowohl ein Chunk ist, den TikTok nicht erwartet, als auch einer weit unter der 5-MB-Untergrenze. Dieselbe Logik erklärt, warum TikTok einen letzten Chunk von bis zu 128 MB erlaubt: Bei einer chunk_size von 64 MB gehen die übrigen Bytes im letzten vollen Chunk auf und können ihn auf fast das Doppelte der deklarierten Größe treiben.

Der Upload am Stück ist der Grenzfall derselben Formel. Eine 4.194.304 Byte große Datei mit chunk_size 4.194.304 teilt sich auf genau 1, also ist total_chunk_count 1 und das einzige PUT gibt 201 Created statt 206 zurück.

Abrunden vs. Aufrunden

Abrunden (TikToks Regel)

• total_chunk_count = 5
• Chunk 5 trägt die letzten 123 Byte, insgesamt 10.000.123 Byte
• Der letzte PUT liefert 201 Created

Aufrunden (der Fehler)

• total_chunk_count = 6
• Chunk 6 ist 123 Byte groß, eine Anfrage, die TikTok nicht erwartet
• 123 Byte liegen weit unter der 5-MB-Untergrenze

Wo widersprechen sich TikToks eigene Chunk-Regeln?

Drei Lücken sitzen auf derselben Dokumentationsseite, und jede kostet eine Debugging-Sitzung.

Die Untergrenze widerspricht dem Beispiel. TikTok schreibt, dass „each chunk must be at least 5 MB“, und veröffentlicht dann ein Beispiel für einen Upload am Stück, in dem der einzige Chunk 4.194.304 Byte groß ist, also 4 MB. Die Ausnahme ist echt, denn Videos unter 5 MB „must be uploaded as a whole“, aber die Untergrenze steht wenige Zeilen über dem Beispiel, das sie verletzt, als absolute Regel da. Die brauchbare Lesart: Die 5-MB-Untergrenze gilt für jeden Chunk eines Uploads mit mehreren Chunks, und ein Upload mit einem einzigen Chunk ist ausgenommen.

MB wird nie definiert. TikTok verwendet MB für die Untergrenze, die Obergrenze und die Zugabe beim letzten Chunk, ohne zu sagen, ob 1.000.000 oder 1.048.576 Byte gemeint sind. Die beiden Beispiele sind sich ebenfalls uneinig. Das Beispiel mit mehreren Chunks nutzt einen dezimalen Chunk von 10.000.000 Byte, das Beispiel für den Upload am Stück eine binäre Datei von 4.194.304 Byte. Ein Chunk von 5.000.000 Byte ist 5 MB nach der dezimalen Lesart und 4,77 MiB nach der binären. TikTok veröffentlicht keine Antwort, also ist der sichere Zug, beide Hürden auf einmal zu nehmen und nie einen nicht-letzten Chunk unter 5.242.880 Byte zu senden.

Die Obergrenze von 1000 Chunks ist nie erreichbar. TikTok begrenzt Videodateien auf „Maximum of 4GB“ und Chunk-Anzahlen auf 1000, bei einer Untergrenze von 5 MB pro Chunk. Eine 4-GB-Datei in 5-MB-Chunks sind 800 Anfragen nach der dezimalen Lesart und 819 nach der binären. Beides liegt bequem unter 1000, also ist die Obergrenze für die Chunk-Anzahl totes Gewicht, solange TikTok das Dateigrößenlimit nicht anhebt. Was deine Schleife wirklich bindet, ist die Lebensdauer der upload_url von einer Stunde, genau wie bei Instagrams Protokoll für fortsetzbare Uploads.

Welche Fehler kommen zurück, wenn die Chunk-Arithmetik falsch ist?

TikTok veröffentlicht keinen eigenen Fehlercode für Chunk-Rechnerei. Der init-Aufruf antwortet mit 400 und dem Fehlercode invalid_param samt der Beschreibung „Check error message for details.“, was die Diagnose in das Freitextfeld message und die log_id schiebt. Alles Genauere passiert zur Übertragungszeit, beim PUT auf upload_url:

HTTP-Code	Status	TikToks Beschreibung
201	Created	„All parts are uploaded. TikTok will start the posting process.“
206	PartialContent	„The current chunk has been successfully processed. There are additional chunks yet to be uploaded.“
400	BadRequest	„Malformated request headers, or BYTE_SIZE_OF_THIS_CHUNK does not reflect the true byte size of the binary in the request body.“
403	Forbidden	„The upload_url has expired.“
404	NotFound	„TikTok cannot find a valid upload task given the upload_url.“
416	RequestedRangeNotSatisfiable	„Content-Range does not reflect the actual upload progress.“
5xx	InternalServerError	„Gateway connection error or TikTok Internal error. You should retry submitting this chunk.“

Lies diese beiden Client-Fehler genau, denn sie trennen sauber. Ein 400 heißt, dass die Bytes im Body nicht zu dem passen, was Content-Length über diesen einen Chunk behauptet. Ein 416 heißt, dass der Chunk der falsche Chunk ist: Die Offsets in Content-Range liegen nicht dort, wo TikToks Cursor gerade steht. Falsche total_chunk_count-Arithmetik zeigt sich fast immer als 416 bei der Anfrage nach der, die die letzte hätte sein sollen.

Die Wiederherstellung verlangt keinen Neustart der Datei. TikTok gibt den Fortschritts-Cursor in jedem Antwort-Header als Content-Range: bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH} zurück, und /v2/post/publish/status/fetch/ liefert dieselbe Zahl als uploaded_bytes. Setze ab diesem Offset fort, solange die upload_url noch in ihrem Ein-Stunden-Fenster ist, und frage dann auf PUBLISH_COMPLETE ab.

Drei Limits rahmen die ganze Übung ein und lohnen einen Blick, bevor du einen einzigen Chunk berechnest. Videos enden über die API bei 4 GB und 10 Minuten, was mehr ausmacht, als es klingt, wenn man sieht, wie weit sich TikToks Obergrenze für die Videolänge in der App bewegt hat. Beschreibungen enden bei 2200 UTF-16-Runen in post_info.title, dieselbe Zahl wie im TikTok Zeichenlimit für Beschreibungen. Und PULL_FROM_URL überspringt diesen ganzen Chunk-Tanz, weshalb TikTok Entwicklern sagt, dass serverseitige Dateien überhaupt nie FILE_UPLOAD nutzen sollten.

Häufig gestellte Fragen

Muss chunk_size für jeden Chunk identisch sein?

Ja für jeden Chunk außer dem letzten. Nach TikToks Chunk-Regeln darf nur der letzte Chunk über die chunk_size hinauslaufen, die du beim init deklariert hast, „up to 128 MB“, um übrige Bytes aufzunehmen, die nicht glatt aufgehen.

Was passiert, wenn total_chunk_count um eins höher ist, als TikTok erwartet?

Der Upload scheitert an der zusätzlichen Anfrage, nicht am init. TikTok hat die volle TOTAL_BYTE_LENGTH bis dahin bereits erhalten, also kommt das überzählige PUT mit Offsets hinter dem Dateiende an und gibt 416 RequestedRangeNotSatisfiable zurück, mit der Beschreibung „Content-Range does not reflect the actual upload progress.“

Sind TikToks 5 MB Minimum 5.000.000 oder 5.242.880 Byte?

TikTok sagt es nicht. Der Media Transfer Guide schreibt „5 MB“ ohne Byte-Angabe, und die beiden Beispiele nutzen dezimale beziehungsweise binäre Größen. Mindestens 5.242.880 Byte pro nicht-letztem Chunk zu senden erfüllt beide Auslegungen.

Können Chunks parallel hochgeladen werden?

Nein. TikTok hält fest, dass „File chunks must be uploaded sequentially“, und der Server führt einen Upload-Offset pro Task, also wird ein Chunk, der vor seinem Vorgänger ankommt, mit 416 abgewiesen statt gepuffert.

Braucht PULL_FROM_URL chunk_size und total_chunk_count?

Nein. Diese drei Felder sind nur mit „true for FILE_UPLOAD“ markiert. Mit source: "PULL_FROM_URL" sendest du stattdessen video_url, TikTok lädt die Datei selbst herunter, und die init-Antwort enthält überhaupt keine upload_url.

Wie lange ist die upload_url gültig?

Eine Stunde. TikToks Notiz an beiden init-Endpunkten lautet: „The upload_url is valid for one hour after issuance. The upload must be completed in this time range.“ Danach geben weitere Chunks 403 Forbidden zurück, und der Fix ist ein frischer init-Aufruf statt eines Retrys, genauso wie eine abgelaufene LinkedIn-Upload-URN eine neue Registrierung erzwingt.

Muss ein Video zwischen 5 MB und 64 MB in mehrere Chunks aufgeteilt werden?

TikToks Mehrfach-Chunk-Regel greift erst oberhalb von 64 MB, und die Einzel-Chunk-Regel gilt nur für Dateien unter 5 MB. Eine Datei dazwischen passt in einen einzigen Chunk, ohne eine der beiden Grenzen zu verletzen, ein einzelner PUT mit chunk_size gleich der Dateigröße erfüllt also beide Regeln. Im Media Transfer Guide steht nichts, was eine Aufteilung erzwingt, bevor die Datei die 64-MB-Grenze überschreitet.

Ist chunk_size beim Direct-Post-Endpunkt von TikTok Pflicht?

TikToks Direct-Post-Referenz lässt die Spalte für Pflichtfelder bei chunk_size und total_chunk_count leer, anders als der Upload-Endpunkt, der alle drei Felder als "true for FILE_UPLOAD" kennzeichnet. TikTok schreibt nirgends, dass die beiden Felder bei Direct Post optional sind, und veröffentlicht die Chunk-Regeln nur einmal für beide Endpunkte. Behandle die leeren Zellen als Lücke in der Dokumentation und sende alle drei Felder, unabhängig davon, welchen Init-Endpunkt du aufrufst.

Wie lang darf ein Video für die TikTok-API maximal sein?

4 GB und 10 Minuten, die beiden Obergrenzen, die TikTok noch vor jeder Chunk-Rechnung nennt. Diese Grenze zählt, weil TikToks Limit für Videos in der App inzwischen weit darüber hinausgewachsen ist, ein Video, das in der App passt, kann über die API trotzdem abgelehnt werden. Prüfe beide Grenzen, bevor du einen einzigen chunk_size-Wert berechnest.

Was tun, wenn ein Chunk-Upload einen 5xx-Fehler zurückgibt?

Denselben Chunk erneut senden. TikToks eigene Beschreibung für den 5xx-Status lautet "Gateway connection error or TikTok Internal error. You should retry submitting this chunk.", und die upload_url bleibt für den erneuten Versuch gültig, solange sie noch innerhalb ihres Einstunden-Fensters liegt. Es besteht keine Notwendigkeit, chunk_size neu zu berechnen oder die Datei neu zu starten, nur weil der Fehler serverseitig lag.