Cómo cuadra el chunk_size de la API de TikTok con total_chunk_count

¿Qué hace el campo chunk_size de la API de TikTok?

El campo chunk_size de la API de TikTok le dice a los servidores de TikTok cuántos bytes va a llevar cada petición PUT cuando transfieres un video con source: "FILE_UPLOAD". Lo declaras una vez, en el cuerpo de la llamada de init, antes de que se mueva un solo byte de video. Todo lo que TikTok valida después se comprueba contra esa declaración.

Tres campos viajan juntos dentro de source_info, y TikTok los describe así:

Campo	Tipo	Descripción 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."

Los dos endpoints de init los aceptan. /v2/post/publish/inbox/video/init/ es el endpoint de Upload, que deja un borrador en la bandeja de entrada del creador. /v2/post/publish/video/init/ es el endpoint de Direct Post, que publica directamente en el perfil. La referencia de Upload marca los tres campos como "true for FILE_UPLOAD". La referencia de Direct Post marca video_size como "true for FILE_UPLOAD" y deja vacía la columna de obligatoriedad para chunk_size y total_chunk_count. TikTok nunca afirma que los dos campos sean opcionales en Direct Post, y las reglas de chunks que publica están escritas una sola vez para los dos endpoints, así que trata las celdas vacías como un artefacto de formato y envía los tres.

¿Cuál es el tamaño mínimo y máximo de chunk en TikTok?

Cada chunk tiene que medir al menos 5 MB y no más de 64 MB, con una excepción al final del archivo. La Media Transfer Guide de TikTok lo enuncia así:

"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."

Otras tres frases de la misma lista rematan el conjunto de reglas:

Regla	Redacción de TikTok
Archivos pequeños	"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."
Archivos grandes	"Videos with a total size greater than 64 MB must be uploaded in multiple chunks."
Número de chunks	"There must be a minimum of 1 chunk and a maximum of 1000 chunks."
Orden	"File chunks must be uploaded sequentially."

La regla del orden es la que se descubre tarde. Los chunks no se pueden repartir entre varios workers, porque TikTok sigue un único desplazamiento de bytes por tarea de subida y responde 416 RequestedRangeNotSatisfiable cuando llega una cabecera Content-Range fuera de orden.

¿Cómo se calcula total_chunk_count?

Divide y redondea hacia abajo, nunca hacia arriba. La frase exacta de TikTok:

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

El ejemplo resuelto de TikTok es un archivo de 50.000.123 bytes con un chunk_size de 10.000.000. Cincuenta millones entre diez millones son cinco coma cero cero cero cero uno dos tres, así que total_chunk_count es 5, no 6. Los 123 bytes sobrantes no tienen su propia petición. Viajan dentro del quinto chunk, que por tanto mide 10.000.123 bytes, algo más grande que el chunk_size que declaraste:

Petición	Content-Range	Bytes en este chunk	Estado
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

Aquí es donde una función de techo rompe una integración sin hacer ruido. Redondear hacia arriba da un sexto chunk de 123 bytes, que es a la vez un chunk que TikTok no espera y un chunk muy por debajo del suelo de 5 MB. La misma lógica explica por qué TikTok permite un chunk final de hasta 128 MB: con un chunk_size de 64 MB, los bytes sobrantes se funden con el último chunk completo y pueden empujarlo hacia el doble del tamaño declarado.

El caso de la subida entera es la versión degenerada de la misma fórmula. Un archivo de 4.194.304 bytes con chunk_size 4.194.304 divide a exactamente 1, así que total_chunk_count es 1 y el único PUT devuelve 201 Created en lugar de 206.

Redondear hacia abajo frente a hacia arriba

Redondear hacia abajo (la regla de TikTok)

• total_chunk_count = 5
• El chunk 5 lleva los 123 bytes finales, 10.000.123 bytes en total
• El PUT final devuelve 201 Created

Redondear hacia arriba (el error)

• total_chunk_count = 6
• El chunk 6 tiene 123 bytes, una solicitud que TikTok no espera
• 123 bytes quedan muy por debajo del mínimo de 5 MB

¿Dónde se contradicen las propias reglas de chunks de TikTok?

Tres huecos conviven en la misma página de documentación, y cada uno cuesta una sesión de depuración.

El suelo contradice al ejemplo. TikTok escribe que "each chunk must be at least 5 MB" y luego publica un ejemplo de subida entera en el que el único chunk es de 4.194.304 bytes, es decir, 4 MB. La excepción es real, ya que los videos de menos de 5 MB "must be uploaded as a whole", pero el suelo está escrito como algo absoluto unas líneas por encima del ejemplo que lo incumple. La lectura viable: el suelo de 5 MB se aplica a cada chunk de una subida multichunk, y una subida de un solo chunk queda exenta.

MB nunca se define. TikTok usa MB para el suelo, el techo y el margen del chunk final sin decir si significa 1.000.000 o 1.048.576 bytes. Sus dos ejemplos tampoco coinciden. El ejemplo por chunks usa un chunk decimal de 10.000.000 bytes; el ejemplo de subida entera usa un archivo binario de 4.194.304 bytes. Un chunk de 5.000.000 bytes son 5 MB según la lectura decimal y 4,77 MiB según la binaria. TikTok no publica ninguna respuesta, así que lo seguro es superar los dos listones a la vez y no enviar nunca un chunk no final por debajo de 5.242.880 bytes.

El tope de 1000 chunks nunca se puede alcanzar. TikTok limita los archivos de video a "Maximum of 4GB" y el número de chunks a 1000, mientras pone un suelo de 5 MB por chunk. Un archivo de 4 GB partido en chunks de 5 MB son 800 peticiones según la lectura decimal y 819 según la binaria. Las dos se quedan cómodamente por debajo de 1000, así que el tope de número de chunks es peso muerto mientras TikTok no suba el límite de tamaño de archivo. El límite que de verdad aprieta tu bucle es la vida de una hora del upload_url, exactamente igual que pasa con el protocolo de subida reanudable de Instagram.

¿Qué errores llegan cuando la aritmética de los chunks está mal?

TikTok no publica ningún código de error dedicado a las cuentas de los chunks. La llamada de init responde 400 con el código de error invalid_param y la descripción "Check error message for details.", lo que empuja el diagnóstico al campo de texto libre message y al log_id. Todo lo más específico ocurre en el momento de la transferencia, en el PUT a upload_url:

Código HTTP	Estado	Descripción 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."

Lee con atención esos dos errores de cliente, porque se separan limpiamente. Un 400 significa que los bytes del cuerpo no coinciden con lo que Content-Length afirma sobre este chunk concreto. Un 416 significa que el chunk es el chunk equivocado: los desplazamientos de Content-Range no están donde está ahora mismo el cursor de TikTok. Una aritmética mala de total_chunk_count casi siempre asoma como un 416 en la petición siguiente a la que debería haber sido la última.

Recuperarse no exige reiniciar el archivo. TikTok devuelve el cursor de progreso en la cabecera de cada respuesta como Content-Range: bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH}, y /v2/post/publish/status/fetch/ devuelve el mismo número como uploaded_bytes. Reanuda desde ese desplazamiento mientras el upload_url siga dentro de su ventana de una hora, y luego consulta hasta ver PUBLISH_COMPLETE.

Tres límites enmarcan todo el ejercicio y conviene comprobarlos antes de calcular un solo chunk. Los videos topan en 4 GB y 10 minutos a través de la API, lo que importa más de lo que parece dado lo lejos que ha llegado el techo de duración de video dentro de la app de TikTok. Los captions topan en 2200 runas UTF-16 en post_info.title, el mismo número cubierto en el límite de caracteres de los captions de TikTok. Y PULL_FROM_URL se salta todo este baile de chunks, que es la razón por la que TikTok dice a los desarrolladores que los archivos que ya están en un servidor no deberían usar FILE_UPLOAD en absoluto.

Preguntas frecuentes

¿chunk_size tiene que ser idéntico para todos los chunks?

Sí para todos salvo el último. Las reglas de fragmentación de TikTok solo dejan que el chunk final supere el chunk_size que declaraste en el init, "up to 128 MB", para absorber los bytes sobrantes que no dividen de forma exacta.

¿Qué pasa si total_chunk_count es uno más de lo que TikTok espera?

La subida falla en la petición extra, no en el init. Para entonces TikTok ya ha recibido el TOTAL_BYTE_LENGTH completo, así que el PUT sobrante llega con desplazamientos más allá del final del archivo y devuelve 416 RequestedRangeNotSatisfiable con la descripción "Content-Range does not reflect the actual upload progress."

¿El mínimo de 5 MB de TikTok son 5.000.000 o 5.242.880 bytes?

TikTok no lo dice. La Media Transfer Guide escribe "5 MB" sin cifra en bytes, y sus dos ejemplos usan tamaños decimales y binarios respectivamente. Enviar al menos 5.242.880 bytes por chunk no final satisface cualquiera de las dos interpretaciones.

¿Se pueden subir los chunks en paralelo?

No. TikTok afirma que "File chunks must be uploaded sequentially", y el servidor sigue un único desplazamiento de subida por tarea, así que un chunk que llega antes que su predecesor se rechaza con 416 en lugar de guardarse en un buffer.

¿PULL_FROM_URL necesita chunk_size y total_chunk_count?

No. Esos tres campos están marcados como "true for FILE_UPLOAD" y nada más. Con source: "PULL_FROM_URL" envías video_url en su lugar, TikTok descarga el archivo por su cuenta, y la respuesta del init no contiene ningún upload_url.

¿Cuánto tiempo es válido el upload_url?

Una hora. La nota de TikTok en los dos endpoints de init dice: "The upload_url is valid for one hour after issuance. The upload must be completed in this time range." Pasado ese plazo, los chunks siguientes devuelven 403 Forbidden, y el arreglo es una llamada de init nueva y no un reintento, igual que un URN de subida de LinkedIn caducado obliga a un registro nuevo.

¿Un vídeo de entre 5 MB y 64 MB tiene que dividirse en varios chunks?

La regla de varios chunks de TikTok solo se activa por encima de 64 MB, y la regla de un solo chunk cubre solo los archivos de menos de 5 MB. Un archivo en ese rango intermedio cabe en un único chunk sin romper ninguno de los dos límites, así que un solo PUT con chunk_size igual al tamaño del archivo cumple ambas reglas. La Media Transfer Guide no dice nada que obligue a dividir el archivo antes de que supere los 64 MB.

¿chunk_size es obligatorio en el endpoint Direct Post de TikTok?

La referencia de Direct Post de TikTok deja en blanco la columna de obligatoriedad para chunk_size y total_chunk_count, a diferencia del endpoint de Upload, que marca los tres campos como "true for FILE_UPLOAD". TikTok nunca dice que esos dos campos sean opcionales en Direct Post, y publica las reglas de chunks una sola vez para ambos endpoints. Trata las celdas en blanco como un vacío de documentación y envía los tres campos sin importar qué endpoint de init uses.

¿Cuál es la duración máxima de vídeo que acepta la API de TikTok?

4 GB y 10 minutos, los dos límites que TikTok fija antes de que entre en juego cualquier cálculo de chunks. Ese tope importa porque el límite de TikTok para vídeos dentro de la app ha crecido muy por encima de esa cifra, así que un vídeo que cabe en la app puede rechazarse igualmente por la API. Revisa ambos límites antes de calcular un solo valor de chunk_size.

¿Qué hacer cuando una subida de chunk devuelve un error 5xx?

Reenviar el mismo chunk. La propia descripción de TikTok para el estado 5xx dice "Gateway connection error or TikTok Internal error. You should retry submitting this chunk.", y la upload_url sigue siendo válida para ese reintento mientras siga dentro de su ventana de una hora. No hace falta recalcular chunk_size ni reiniciar el archivo por un error del lado del servidor.