Pourquoi chunk_size de l'API TikTok et total_chunk_count doivent tomber juste

À quoi sert le champ chunk_size de l'API TikTok ?

Le champ chunk_size de l'API TikTok indique aux serveurs de TikTok combien d'octets chaque requête PUT portera quand vous transférez une vidéo avec source: "FILE_UPLOAD". Vous le déclarez une fois, dans le corps de l'appel init, avant qu'un seul octet de vidéo ne bouge. Tout ce que TikTok valide ensuite est vérifié contre cette déclaration.

Trois champs voyagent ensemble dans source_info, et TikTok les décrit ainsi :

Champ	Type	Description de TikTok
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. »

Les deux points de terminaison init les acceptent. /v2/post/publish/inbox/video/init/ est le point de terminaison Upload, qui dépose un brouillon dans la boîte de réception du créateur. /v2/post/publish/video/init/ est le point de terminaison Direct Post, qui publie directement sur le profil. La référence Upload marque les trois champs « true for FILE_UPLOAD ». La référence Direct Post marque video_size « true for FILE_UPLOAD » et laisse la colonne obligatoire vide pour chunk_size et total_chunk_count. TikTok n'indique jamais que ces deux champs sont optionnels sur Direct Post, et les règles de découpage qu'il publie sont écrites une seule fois pour les deux points de terminaison, traitez donc les cellules vides comme un artefact de mise en forme et envoyez les trois.

Quelles sont la taille de morceau minimale et maximale sur TikTok ?

Chaque morceau doit faire au moins 5 Mo et pas plus de 64 Mo, avec une exception à la fin du fichier. Le Media Transfer Guide de TikTok l'énonce ainsi :

« 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. »

Trois autres phrases de la même liste complètent le jeu de règles :

Règle	Formulation de TikTok
Petits fichiers	« 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. »
Gros fichiers	« Videos with a total size greater than 64 MB must be uploaded in multiple chunks. »
Nombre de morceaux	« There must be a minimum of 1 chunk and a maximum of 1000 chunks. »
Ordre	« File chunks must be uploaded sequentially. »

La règle d'ordre est celle que l'on découvre tard. Les morceaux ne peuvent pas être répartis entre plusieurs workers, parce que TikTok suit un seul décalage d'octets par tâche d'envoi et répond 416 RequestedRangeNotSatisfiable quand un en-tête Content-Range arrive dans le désordre.

Comment calcule-t-on total_chunk_count ?

On divise et on arrondit à l'inférieur, jamais au supérieur. La phrase exacte de TikTok :

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

L'exemple travaillé de TikTok est un fichier de 50 000 123 octets avec un chunk_size de 10 000 000. Cinquante millions divisés par dix millions font cinq virgule zéro zéro zéro zéro un deux trois, total_chunk_count vaut donc 5, pas 6. Les 123 octets de queue n'obtiennent pas leur propre requête. Ils voyagent dans le cinquième morceau, qui fait donc 10 000 123 octets, un peu plus que le chunk_size déclaré :

Requête	Content-Range	Octets dans ce morceau	Statut
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

C'est là qu'une fonction plafond casse une intégration en silence. Arrondir au supérieur donne un sixième morceau de 123 octets, qui est à la fois un morceau que TikTok n'attend pas et un morceau très en dessous du plancher de 5 Mo. La même logique explique pourquoi TikTok autorise un dernier morceau allant jusqu'à 128 Mo : avec un chunk_size de 64 Mo, les octets restants fusionnent dans le dernier morceau plein et peuvent le pousser vers le double de la taille déclarée.

Le cas de l'envoi en un seul bloc est la version dégénérée de la même formule. Un fichier de 4 194 304 octets avec un chunk_size de 4 194 304 se divise en exactement 1, total_chunk_count vaut donc 1 et le PUT unique renvoie 201 Created au lieu de 206.

Arrondir vers le bas ou vers le haut

Arrondir vers le bas (la règle de TikTok)

• total_chunk_count = 5
• Le morceau 5 porte les 123 derniers octets, 10 000 123 octets au total
• Le PUT final renvoie 201 Created

Arrondir vers le haut (le bug)

• total_chunk_count = 6
• Le morceau 6 fait 123 octets, une requête que TikTok n'attend pas
• 123 octets, bien en dessous du plancher de 5 Mo

Où les règles de découpage de TikTok se contredisent-elles ?

Trois failles siègent sur la même page de documentation, et chacune coûte une séance de débogage.

Le plancher contredit l'exemple. TikTok écrit que « each chunk must be at least 5 MB » puis publie un exemple d'envoi en un seul bloc dans lequel l'unique morceau fait 4 194 304 octets, soit 4 Mo. La dérogation est réelle, puisque les vidéos de moins de 5 Mo « must be uploaded as a whole », mais le plancher est écrit comme un absolu quelques lignes au-dessus de l'exemple qui le viole. La lecture praticable : le plancher de 5 Mo s'applique à chaque morceau d'un envoi multi-morceaux, et un envoi à morceau unique en est dispensé.

MB n'est jamais défini. TikTok utilise MB pour le plancher, le plafond et la tolérance du dernier morceau sans dire s'il veut dire 1 000 000 ou 1 048 576 octets. Ses deux exemples ne s'accordent pas davantage. L'exemple découpé utilise un morceau décimal de 10 000 000 octets ; l'exemple d'envoi en un seul bloc utilise un fichier binaire de 4 194 304 octets. Un morceau de 5 000 000 octets fait 5 Mo en lecture décimale et 4,77 Mio en lecture binaire. TikTok ne publie aucune réponse, le geste prudent est donc de franchir les deux barres à la fois et de ne jamais envoyer un morceau non final sous 5 242 880 octets.

Le plafond de 1000 morceaux est inatteignable. TikTok plafonne les fichiers vidéo à « Maximum of 4GB » et plafonne le nombre de morceaux à 1000, tout en fixant leur plancher à 5 Mo. Un fichier de 4 Go découpé en morceaux de 5 Mo fait 800 requêtes en lecture décimale et 819 en lecture binaire. Les deux restent confortablement sous 1000, le plafond du nombre de morceaux est donc du poids mort tant que TikTok ne relève pas la limite de taille de fichier. La limite qui contraint réellement votre boucle est la durée de vie d'une heure de l'upload_url, exactement comme avec le protocole d'envoi reprenable d'Instagram.

Quelles erreurs reviennent quand l'arithmétique des morceaux est fausse ?

TikTok ne publie aucun code d'erreur dédié au calcul des morceaux. L'appel init répond 400 avec le code d'erreur invalid_param et la description « Check error message for details. », ce qui repousse le diagnostic dans le champ texte libre message et dans le log_id. Tout ce qui est plus précis se passe au moment du transfert, sur le PUT vers upload_url :

Code HTTP	Statut	Description de TikTok
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. »

Lisez ces deux erreurs client attentivement, car elles se séparent nettement. Un 400 veut dire que les octets du corps ne correspondent pas à ce que Content-Length annonce pour ce morceau précis. Un 416 veut dire que le morceau est le mauvais morceau : les décalages de Content-Range ne sont pas là où se trouve le curseur de TikTok. Une mauvaise arithmétique de total_chunk_count se manifeste presque toujours par un 416 sur la requête suivant celle qui aurait dû être la dernière.

La reprise n'oblige pas à recommencer le fichier. TikTok renvoie le curseur de progression dans chaque en-tête de réponse sous la forme Content-Range: bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH}, et /v2/post/publish/status/fetch/ renvoie le même nombre dans uploaded_bytes. Reprenez depuis ce décalage tant que l'upload_url est encore dans sa fenêtre d'une heure, puis interrogez jusqu'à PUBLISH_COMPLETE.

Trois limites encadrent tout l'exercice et méritent d'être vérifiées avant de calculer le moindre morceau. Les vidéos plafonnent à 4 Go et 10 minutes via l'API, ce qui compte plus qu'il n'y paraît vu le chemin parcouru par la durée maximale d'une vidéo TikTok dans l'app. Les légendes plafonnent à 2200 runes UTF-16 dans post_info.title, le même nombre que celui traité dans la limite de caractères des légendes TikTok. Et PULL_FROM_URL saute toute cette danse du découpage, ce qui explique pourquoi TikTok dit aux développeurs que les fichiers côté serveur ne devraient jamais passer par FILE_UPLOAD.

Questions fréquentes

chunk_size doit-il être identique pour chaque morceau ?

Oui pour tous les morceaux sauf le dernier. Les règles de découpage de TikTok ne laissent que le dernier morceau dépasser le chunk_size déclaré à l'init, « up to 128 MB », pour absorber les octets de queue qui ne tombent pas rond.

Que se passe-t-il si total_chunk_count vaut un de plus que ce que TikTok attend ?

L'envoi échoue à la requête en trop, pas à l'init. TikTok a déjà reçu tout le TOTAL_BYTE_LENGTH à ce moment-là, la requête PUT excédentaire arrive donc avec des décalages au-delà de la fin du fichier et renvoie 416 RequestedRangeNotSatisfiable avec la description « Content-Range does not reflect the actual upload progress. »

Le minimum de 5 Mo de TikTok fait-il 5 000 000 ou 5 242 880 octets ?

TikTok ne le dit pas. Le Media Transfer Guide écrit « 5 MB » sans chiffre en octets, et ses deux exemples utilisent respectivement une taille décimale et une taille binaire. Envoyer au moins 5 242 880 octets par morceau non final satisfait les deux interprétations.

Les morceaux peuvent-ils être envoyés en parallèle ?

Non. TikTok indique que « File chunks must be uploaded sequentially », et le serveur suit un seul décalage d'envoi par tâche, un morceau qui arrive avant son prédécesseur est donc rejeté avec un 416 plutôt que mis en tampon.

PULL_FROM_URL a-t-il besoin de chunk_size et total_chunk_count ?

Non. Ces trois champs sont marqués « true for FILE_UPLOAD » uniquement. Avec source: "PULL_FROM_URL" vous envoyez video_url à la place, TikTok télécharge le fichier lui-même, et la réponse init ne contient aucune upload_url.

Combien de temps l'upload_url reste-t-elle valide ?

Une heure. La note de TikTok sur les deux points de terminaison init se lit : « The upload_url is valid for one hour after issuance. The upload must be completed in this time range. » Passé ce délai, les morceaux suivants renvoient 403 Forbidden, et le correctif est un nouvel appel init plutôt qu'une nouvelle tentative, de la même façon qu'une URN d'envoi LinkedIn périmée force un nouvel enregistrement.

Une vidéo entre 5 Mo et 64 Mo doit-elle être découpée en plusieurs morceaux ?

La règle des morceaux multiples de TikTok ne se déclenche qu'au-delà de 64 Mo, et la règle du morceau unique ne couvre que les fichiers de moins de 5 Mo. Un fichier entre les deux tient dans un seul morceau sans enfreindre l'une ou l'autre limite, un seul PUT avec un chunk_size égal à la taille du fichier respecte donc les deux règles. Le Media Transfer Guide ne dit rien qui impose un découpage avant que le fichier ne dépasse 64 Mo.

chunk_size est-il obligatoire sur l'endpoint Direct Post de TikTok ?

La référence Direct Post de TikTok laisse la colonne obligatoire vide pour chunk_size et total_chunk_count, contrairement à l'endpoint Upload, qui marque les trois champs "true for FILE_UPLOAD". TikTok n'écrit nulle part que ces deux champs sont facultatifs sur Direct Post, et publie les règles de découpage une seule fois pour les deux endpoints. Traite ces cellules vides comme un trou dans la documentation et envoie les trois champs quel que soit l'endpoint d'init appelé.

Quelle est la durée maximale de vidéo acceptée par l'API TikTok ?

4 Go et 10 minutes, les deux plafonds que TikTok fixe avant même le moindre calcul de morceaux. Cette limite compte parce que le plafond de TikTok pour les vidéos dans l'application a largement dépassé ce chiffre, une vidéo acceptée dans l'application peut donc quand même être rejetée par l'API. Vérifie ces deux plafonds avant de calculer la moindre valeur de chunk_size.

Que faire quand un envoi de morceau renvoie une erreur 5xx ?

Renvoyer le même morceau. La description de TikTok pour le statut 5xx est "Gateway connection error or TikTok Internal error. You should retry submitting this chunk.", et l'upload_url reste valide pour cette nouvelle tentative tant qu'elle est encore dans sa fenêtre d'une heure. Il n'y a pas besoin de recalculer chunk_size ni de relancer le fichier pour une erreur côté serveur.