Słownik

Jak w TikTok API muszą się zgadzać chunk_size i total_chunk_count

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •8 min czytania
Plik wideo podzielony na ponumerowane fragmenty do przesłania przez TikTok APIPlik wideo podzielony na ponumerowane fragmenty do przesłania przez TikTok API

TL;DR, szybka odpowiedź

8 min czytania

Media 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:

PoleTypOpis TikToka
video_sizeint64"The size of the video to be uploaded in bytes."
chunk_sizeint64"The size of the chunk in bytes."
total_chunk_countint64"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.

Ekran laptopa pokazuje plik wideo w trakcie przesyłania, podzielony na małe części.

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:

ZasadaSformuł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_count should be equal to video_size divided by chunk_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:

ŻądanieContent-RangeBajty w tym fragmencieStatus
1bytes 0-9999999/5000012310 000 000206
2bytes 10000000-19999999/5000012310 000 000206
3bytes 20000000-29999999/5000012310 000 000206
4bytes 30000000-39999999/5000012310 000 000206
5bytes 40000000-50000122/5000012310 000 123201

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.

Zaokrąglanie w dół a w górę
W dół (zasada TikToka)
  • total_chunk_count = 5
  • Fragment 5 zawiera końcowe 123 bajty, łącznie 10 000 123 bajty
  • Ostatni PUT zwraca 201 Created
W górę (błąd)
  • 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
Ten sam plik o wielkości 50 000 123 bajtów z chunk_size równym 10 000 000 bajtów, podzielony tak, jak wymaga TikTok, i tak, jak zrobiłaby to funkcja ceil.

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

Programista wpatruje się w komunikat o błędzie na ekranie, taki jak po złej liczbie fragmentów.

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 HTTPStatusOpis TikToka
201Created"All parts are uploaded. TikTok will start the posting process."
206PartialContent"The current chunk has been successfully processed. There are additional chunks yet to be uploaded."
400BadRequest"Malformated request headers, or BYTE_SIZE_OF_THIS_CHUNK does not reflect the true byte size of the binary in the request body."
403Forbidden"The upload_url has expired."
404NotFound"TikTok cannot find a valid upload task given the upload_url."
416RequestedRangeNotSatisfiable"Content-Range does not reflect the actual upload progress."
5xxInternalServerError"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
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.

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

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

Powiązane artykuły