TL;DR, szybka odpowiedź
8 min czytaniaMedia Transfer Guide TikToka ustala cztery zasady dotyczące fragmentów: każdy ma co najmniej 5 MB i nie więcej niż 64 MB, ostatni może mieć do 128 MB, fragmentów musi być od 1 do 1000, a total_chunk_count równa się video_size podzielonemu przez chunk_size "rounded down to the nearest integer." Zaokrąglanie w górę to błąd, który psuje większość pierwszych integracji. Własny przykład TikToka z przesłaniem całego pliku wysyła jednak fragment 4 194 304 bajtów, poniżej własnej granicy 5 MB, a dokumentacja nie mówi, czy MB to 1 000 000, czy 1 048 576 bajtów. Nie ma osobnego kodu błędu dla złych obliczeń: wywołanie init zwraca 400 invalid_param, a niezgodny PUT zwraca 400 lub 416.
Do czego służy pole chunk_size w TikTok API?
Pole chunk_size w TikTok API informuje serwery TikToka, ile bajtów przeniesie każde żądanie PUT podczas przesyłania filmu z source: "FILE_UPLOAD". Deklarujesz je raz, w treści wywołania init, zanim popłynie choćby jeden bajt filmu. Wszystko, co TikTok później sprawdza, jest porównywane z tą deklaracją.
W source_info występują razem trzy pola, które TikTok opisuje tak:
| Pole | Typ | Opis TikToka |
|---|---|---|
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." |
Przyjmują je oba endpointy init. /v2/post/publish/inbox/video/init/ to endpoint Upload, który umieszcza szkic w skrzynce twórcy. /v2/post/publish/video/init/ to endpoint Direct Post, który publikuje od razu na profilu. Dokumentacja Upload oznacza wszystkie trzy pola jako "true for FILE_UPLOAD". Dokumentacja Direct Post oznacza tak video_size ("true for FILE_UPLOAD"), a przy chunk_size i total_chunk_count zostawia kolumnę wymagalności pustą. TikTok nigdzie nie mówi, że te dwa pola są opcjonalne w Direct Post, a publikowane zasady dotyczące fragmentów są wspólne dla obu endpointów, więc traktuj puste komórki jako usterkę formatowania i wysyłaj wszystkie trzy.

Jaki jest minimalny i maksymalny rozmiar fragmentu w TikToku?
Każdy fragment musi mieć co najmniej 5 MB i nie więcej niż 64 MB, z jednym wyjątkiem na końcu pliku. Media Transfer Guide TikToka podaje to tak:
"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."
Trzy kolejne zdania z tej samej listy dopełniają zestaw zasad:
| Zasada | Sformułowanie TikToka |
|---|---|
| Małe pliki | "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." |
| Duże pliki | "Videos with a total size greater than 64 MB must be uploaded in multiple chunks." |
| Liczba fragmentów | "There must be a minimum of 1 chunk and a maximum of 1000 chunks." |
| Kolejność | "File chunks must be uploaded sequentially." |
Zasadę kolejności programiści odkrywają zwykle najpóźniej. Fragmentów nie da się rozdzielić między równoległe procesy, bo TikTok śledzi jedno przesunięcie w bajtach na zadanie przesyłania i odpowiada 416 RequestedRangeNotSatisfiable, gdy nagłówek Content-Range przychodzi w złej kolejności.
Jak obliczyć total_chunk_count?
Podziel i zaokrąglij w dół, nigdy w górę. Dokładne zdanie TikToka:
"The value of
total_chunk_countshould be equal tovideo_sizedivided bychunk_size, rounded down to the nearest integer."
Przykład TikToka to plik o wielkości 50 000 123 bajtów z chunk_size równym 10 000 000. Wynik dzielenia to pięć przecinek zero zero zero zero jeden dwa trzy, więc total_chunk_count wynosi 5, a nie 6. Końcowe 123 bajty nie dostają własnego żądania. Trafiają do piątego fragmentu, który ma przez to 10 000 123 bajty, czyli nieco więcej niż zadeklarowany chunk_size:
| Żądanie | Content-Range | Bajty w tym fragmencie | 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 |
W tym miejscu funkcja ceil po cichu psuje integrację. Zaokrąglenie w górę daje szósty fragment o wielkości 123 bajtów, którego TikTok się nie spodziewa i który jest daleko poniżej granicy 5 MB. Ta sama logika tłumaczy, dlaczego TikTok dopuszcza ostatni fragment do 128 MB: przy chunk_size równym 64 MB pozostałe bajty łączą się z ostatnim pełnym fragmentem i mogą zbliżyć go do dwukrotności zadeklarowanego rozmiaru.
Przesłanie całego pliku to skrajny przypadek tego samego wzoru. Plik o wielkości 4 194 304 bajtów z chunk_size 4 194 304 dzieli się dokładnie na 1, więc total_chunk_count wynosi 1, a pojedynczy PUT zwraca 201 Created zamiast 206.
- total_chunk_count = 5
- Fragment 5 zawiera końcowe 123 bajty, łącznie 10 000 123 bajty
- Ostatni PUT zwraca 201 Created
- total_chunk_count = 6
- Fragment 6 ma 123 bajty, a TikTok nie spodziewa się takiego żądania
- 123 bajty to daleko poniżej granicy 5 MB
Gdzie zasady TikToka dotyczące fragmentów sobie przeczą?
Na tej samej stronie dokumentacji są trzy luki, a każda kosztuje sesję debugowania.
Dolna granica przeczy przykładowi. TikTok pisze, że "each chunk must be at least 5 MB", a potem publikuje przykład przesłania całego pliku, w którym jedyny fragment ma 4 194 304 bajty, czyli 4 MB. Wyjątek istnieje, bo filmy poniżej 5 MB "must be uploaded as a whole", ale granica jest zapisana jako bezwzględna kilka wierszy nad przykładem, który ją łamie. Praktyczna interpretacja: granica 5 MB dotyczy każdego fragmentu przesyłania wieloczęściowego, a przesyłanie jednym fragmentem jest z niej zwolnione.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
MB nigdzie nie zdefiniowano. TikTok używa MB dla dolnej granicy, górnej granicy i limitu ostatniego fragmentu, nie mówiąc, czy chodzi o 1 000 000, czy 1 048 576 bajtów. Jego dwa przykłady też się nie zgadzają. Przykład z podziałem używa dziesiętnego fragmentu 10 000 000 bajtów, a przykład z całym plikiem binarnego pliku 4 194 304 bajtów. Fragment 5 000 000 bajtów to 5 MB w ujęciu dziesiętnym i 4,77 MiB w binarnym. TikTok nie daje odpowiedzi, więc bezpiecznie jest spełnić oba warunki naraz i nigdy nie wysyłać fragmentu innego niż ostatni poniżej 5 242 880 bajtów.
Limitu 1000 fragmentów nie da się osiągnąć. TikTok ogranicza pliki wideo do "Maximum of 4GB", a liczbę fragmentów do 1000, ustalając jednocześnie minimum 5 MB na fragment. Plik 4 GB podzielony na fragmenty 5 MB to 800 żądań w ujęciu dziesiętnym i 819 w binarnym. Obie wartości są wyraźnie poniżej 1000, więc limit liczby fragmentów jest martwy, dopóki TikTok nie podniesie limitu rozmiaru pliku. Pętlę faktycznie ogranicza godzinny czas ważności upload_url, tak samo jak w protokole wznawianego przesyłania na Instagramie.

Jakie błędy pojawiają się przy złych obliczeniach fragmentów?
TikTok nie publikuje osobnego kodu błędu dla obliczeń dotyczących fragmentów. Wywołanie init odpowiada 400 z kodem błędu invalid_param i opisem "Check error message for details.", co przenosi diagnozę do tekstowego pola message i log_id. Wszystko bardziej szczegółowe dzieje się podczas transferu, przy PUT na upload_url:
| Kod HTTP | Status | Opis TikToka |
|---|---|---|
| 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." |
Przeczytaj uważnie te dwa błędy klienta, bo wyraźnie się różnią. 400 oznacza, że bajty w treści nie zgadzają się z tym, co Content-Length deklaruje dla tego jednego fragmentu. 416 oznacza, że to niewłaściwy fragment: przesunięcia w Content-Range nie odpowiadają bieżącej pozycji kursora TikToka. Błędne obliczenie total_chunk_count niemal zawsze ujawnia się jako 416 w żądaniu następującym po tym, które powinno być ostatnie.
Naprawa nie wymaga przesyłania pliku od nowa. TikTok zwraca kursor postępu w nagłówku każdej odpowiedzi jako Content-Range: bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH}, a /v2/post/publish/status/fetch/ zwraca tę samą liczbę jako uploaded_bytes. Wznów od tego przesunięcia, dopóki upload_url mieści się w godzinnym oknie, a potem odpytuj o PUBLISH_COMPLETE.
Całość obejmują trzy limity, które warto sprawdzić, zanim obliczysz choćby jeden fragment. Filmy przez API mogą mieć do 4 GB i 10 minut, co ma większe znaczenie, niż się wydaje, biorąc pod uwagę, jak bardzo przesunął się limit długości filmu w aplikacji TikTok. Opisy mają limit 2200 runów UTF-16 w post_info.title, czyli tę samą liczbę, którą omawia artykuł o limicie znaków w opisie na TikToku. A PULL_FROM_URL pomija cały ten podział na fragmenty, dlatego TikTok radzi deweloperom, by pliki po stronie serwera nigdy nie korzystały z FILE_UPLOAD.
Najczęściej zadawane pytania
Czy chunk_size musi być identyczny dla każdego fragmentu?
Tak, dla każdego z wyjątkiem ostatniego. Zasady TikToka pozwalają tylko ostatniemu fragmentowi przekroczyć chunk_size zadeklarowany przy init, "up to 128 MB", aby pomieścić końcowe bajty, które nie dzielą się równo.
Co się stanie, gdy total_chunk_count jest o jeden większy, niż oczekuje TikTok?
Przesyłanie nie powiedzie się przy dodatkowym żądaniu, a nie przy init. TikTok ma już wtedy całe TOTAL_BYTE_LENGTH, więc nadmiarowy PUT przychodzi z przesunięciami poza końcem pliku i zwraca 416 RequestedRangeNotSatisfiable z opisem "Content-Range does not reflect the actual upload progress."
Czy minimum 5 MB w TikToku to 5 000 000, czy 5 242 880 bajtów?
TikTok tego nie podaje. Media Transfer Guide pisze "5 MB" bez liczby bajtów, a jego dwa przykłady używają odpowiednio rozmiarów dziesiętnych i binarnych. Wysyłanie co najmniej 5 242 880 bajtów w każdym fragmencie oprócz ostatniego spełnia obie interpretacje.
Czy fragmenty można przesyłać równolegle?
Nie. TikTok podaje, że "File chunks must be uploaded sequentially", a serwer śledzi jedno przesunięcie na zadanie, więc fragment przychodzący przed poprzednim zostaje odrzucony z kodem 416, a nie zbuforowany.
Czy PULL_FROM_URL wymaga chunk_size i total_chunk_count?
Nie. Te trzy pola są oznaczone jako "true for FILE_UPLOAD" i tylko wtedy obowiązują. Przy source: "PULL_FROM_URL" wysyłasz zamiast nich video_url, TikTok sam pobiera plik, a odpowiedź init w ogóle nie zawiera upload_url.
Jak długo ważny jest upload_url?
Godzinę. Uwaga TikToka przy obu endpointach init brzmi: "The upload_url is valid for one hour after issuance. The upload must be completed in this time range." Później kolejne fragmenty zwracają 403 Forbidden, a rozwiązaniem jest nowe wywołanie init, a nie ponowienie, podobnie jak nieaktualny URN przesyłania na LinkedInie wymusza nową rejestrację.
Czy film o wielkości od 5 MB do 64 MB trzeba dzielić na fragmenty?
Zasada wielu fragmentów zaczyna obowiązywać dopiero powyżej 64 MB, a zasada jednego fragmentu obejmuje tylko pliki poniżej 5 MB. Plik z tego środkowego zakresu mieści się w jednym fragmencie bez łamania żadnego limitu, więc pojedynczy PUT z chunk_size równym rozmiarowi pliku spełnia obie zasady. Nic w Media Transfer Guide nie wymusza podziału, dopóki plik nie przekroczy 64 MB.
Czy chunk_size jest wymagany w endpoincie Direct Post TikToka?
Dokumentacja Direct Post zostawia kolumnę wymagalności pustą dla chunk_size i total_chunk_count, w przeciwieństwie do endpointu Upload, który oznacza wszystkie trzy pola jako true for FILE_UPLOAD. TikTok nigdzie nie mówi, że te dwa pola są opcjonalne w Direct Post, i publikuje jeden zestaw zasad dla obu endpointów. Traktuj puste komórki jako lukę w dokumentacji i wysyłaj wszystkie trzy pola, niezależnie od wywoływanego endpointu init.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Jaki najdłuższy film przyjmuje API TikToka?
4 GB i 10 minut, czyli dwa limity, które TikTok wymienia jeszcze przed obliczeniami fragmentów. Ten pułap ma znaczenie, bo limit przesyłania w aplikacji TikTok znacznie go przekroczył, więc film mieszczący się w aplikacji może zostać odrzucony przez API. Sprawdź oba limity, zanim obliczysz choćby jedną wartość chunk_size.
Co zrobić, gdy przesyłanie fragmentu zwraca błąd 5xx?
Ponów ten sam fragment. Opis TikToka dla statusu 5xx brzmi "Gateway connection error or TikTok Internal error. You should retry submitting this chunk," a upload_url pozostaje ważny na czas ponowienia, dopóki mieści się w godzinnym oknie. Przy błędzie po stronie serwera nie trzeba ponownie obliczać chunk_size ani przesyłać pliku od nowa.
Wykorzystaj to w praktyce z AdaptlyPost
Czy ten artykuł był pomocny?
Chętnie poznamy opinię!
Więcej naszych treści w Google
Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.
Jeszcze chwila...
AdaptlyPost
Planowanie treści na wszystkich platformach
Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Powiązane hasła ze słownika


Co pole creator_info max_video_post_duration_sec na TikToku mówi przed publikacją
Pole creator_info max_video_post_duration_sec na TikToku to najdłuższy film, jaki może opublikować dany twórca. Wartość zależy od konta, więc sprawdzaj ją przed każdym postem.


Jak działa dzienny limit postów na TikToku dla aplikacji i narzędzi do planowania
Dzienny limit postów na TikToku: dokumentacja API podaje 15 postów Direct Post na twórcę, 5 oczekujących szkiców i limit wspólny dla wszystkich aplikacji.


Dlaczego deweloperzy potrzebują zatwierdzenia aplikacji, by publikować na TikToku publicznie
Bez zatwierdzenia aplikacji posty z API zostają SELF_ONLY, a publikować może dziennie tylko 5 prywatnych kont. Co sprawdza audyt i jakie błędy zobaczysz.
Powiązane artykuły


Dlaczego weryfikacja domeny pull_from_url w TikTok API odrzuca twój host
Weryfikacja domeny pull_from_url w TikTok API to kontrola DNS hosta, który podajesz. Bez niej każde wywołanie init zwraca url_ownership_unverified.


Oznaczenie treści AI na TikToku to w rzeczywistości dwa różne oznaczenia
Oznaczenie AI na TikToku pojawia się na dwa sposoby: jako etykieta twórcy ustawiana przez is_aigc i jako etykieta automatyczna z efektów AI lub C2PA, której nie usuniesz.


Trzy odpowiedzi na pytanie, jak długie mogą być Reels na Facebooku
Jak długie mogą być Reels na Facebooku? W aplikacji dowolnie długie od 2025, przez API od 3 do 90 sekund, a w grupach 30 sekund, według stron samej Meta.

