Słownik

Wszystkie wartości media_category w API Twittera i co umożliwiają

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •7 min czytania
Wartości media_category w API Twittera dla postów, DM i reklamWartości media_category w API Twittera dla postów, DM i reklam

TL;DR, szybka odpowiedź

7 min czytania

media_category mówi X, do czego służy plik. Endpoint initialize przyjmuje osiem wartości: tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif i subtitles, a X na ich podstawie wybiera limit rozmiaru i długości. tweet_video i amplify_video mają w poście te same limity: domyślnie 20 minut i 8 GB, a w Premium 125 minut i 16 GB, choć strona Ads API nadal podaje dla wideo promowanego maksimum 10 minut i 500 MB. Bez tej wartości X zgaduje kategorię na podstawie typu treści.

Czym jest parametr media_category w API Twittera?

Parametr media_category w API Twittera ma osiem wartości, a X opisuje jego zadanie jednym zdaniem: "The Media Category parameter defines the use case of the media file to be uploaded, and can affect file size limits or other constraints enforced for media uploads."

Chodzi o zastosowanie, a nie typ pliku. media_type informuje już X, że przesyłane bajty to MP4. media_category mówi, czy ten plik MP4 trafi do posta, wiadomości prywatnej czy reklamy, a X dla każdej z tych odpowiedzi stosuje inny limit.

Parametr jest opcjonalny w POST /2/media/upload/initialize, a X dokumentuje wartość domyślną: "If media category is not specified, the uploaded media is assumed to be media for a Post (tweet_image, tweet_video, or tweet_gif), depending on the content type."

To ustawienie domyślne obejmuje tylko posty. Wszystko, co ma trafić do wiadomości prywatnej, reklamy lub ścieżki napisów, musi to jawnie zadeklarować, bo X nie wywnioskuje tego z pliku MP4.

Co umożliwia każda wartość media_category w API Twittera?

Każda wartość odpowiada jednemu miejscu publikacji, a pełną listę X podaje w schemacie endpointu initialize.

WartośćDo czego służyLimit domyślnyLimit X Premium
tweet_imageObraz w poście5 MB5 MB
tweet_gifAnimowany GIF w poście15 MB15 MB
tweet_videoWideo w poście20 min, 8 GB125 min, 16 GB
amplify_videoReklamy i wideo promowane20 min, 8 GB125 min, 16 GB
dm_imageObraz w wiadomości prywatnej5 MB5 MB
dm_gifAnimowany GIF w wiadomości prywatnej15 MB15 MB
dm_videoWideo w wiadomości prywatnej140 s, 512 MB10 min, 1 GB
subtitlesPlik z napisami1 MB1 MB

Minimalna długość wideo jest taka sama we wszystkich kategoriach wideo. X podaje ją jako "0.5 seconds" i traktuje jako dolną granicę, a nie zalecenie.

Dwie wartości niosą dodatkową instrukcję poza limitami. amplify_video jest obowiązkowe przy wszystkim, co promowane, i Ads API mówi o tym od 2015 roku: "When uploading videos to be used in promoted content, the media_category parameter must be set with a value of amplify_video for all INIT command requests." Z kolei tweet_gif włącza asynchroniczne przetwarzanie dużych animowanych GIF-ów, co X wyjaśnia na stronie z dobrymi praktykami: "In order to process larger GIFs, use the chunked upload endpoint with the media_category parameter. This allows the server to process the GIF file asynchronously, which is a requirement for processing larger files."

Telefon z plikiem wideo w trakcie przesyłania, co ilustruje kontrolę rozmiaru i długości uruchamianą przez media_category.

Jak media_category zmienia limity rozmiaru i długości?

Kategoria wybiera wiersz tabeli limitów X, a subskrypcja konta wybiera kolumnę. X wskazuje oba czynniki: limity zależą od "the authenticated user's X Premium / verified status, not your developer API plan" oraz od "the media_category you pass when initializing the upload."

Rozpiętość między kategoriami jest duża. Wideo, które mieści się w tweet_video przy 20 minutach, musi mieć mniej niż 140 sekund, aby wyjść jako dm_video z tego samego konta, a nawet z Premium mniej niż 10 minut. Ten sam plik, to samo konto, ten sam endpoint, a między limitami ośmiokrotna różnica.

Również total_bytes jest sprawdzane względem kategorii. X pisze, że "POST /2/media/upload/initialize accepts total_bytes up to 16 GB. Passing a larger total_bytes than the account is allowed to upload fails at initialize or finalize." Wskazano dwa miejsca błędu, ale X nie mówi, które z nich zadziała, więc traktuj zarówno INIT, jak i FINALIZE jako etapy, na których może pojawić się odrzucenie z powodu rozmiaru.

Kategoria nie zmienia zasad dla obrazów. Obrazy pozostają przy 5 MB, a animowane GIF-y przy 15 MB niezależnie od tego, czy trafiają do posta, czy do wiadomości prywatnej, a Premium nie zmienia żadnej z tych liczb. Na subskrypcję reagują tylko długość i rozmiar pliku wideo, czyli mniej, niż sugeruje pełna lista korzyści X Premium.

Zespół omawia kampanię reklamową wideo na laptopie, co wiąże się z osobnymi limitami rozmiaru dla promowanych filmów.

Dlaczego X publikuje dwa różne limity dla amplify_video?

Bo strona kreacji Ads API i dokumentacja mediów są ze sobą sprzeczne, a obie nadal obowiązują.

Strony o mediach traktują amplify_video na równi z tweet_video. Strona z dobrymi praktykami mówi to wprost: "For Posts, Premium and default duration/size caps are the same for tweet_video and amplify_video." Jej tabela podaje dla obu 20 minut i 8 GB domyślnie oraz 125 minut i 16 GB z Premium.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Strona kreacji Ads API, w sekcji Promoted Video, podaje w jednym punkcie inną parę liczb: "The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less." Dodaje też wymóg formatu, o którym strony o mediach nie wspominają: "Uploaded video should be either mp4 or mov."

Dziesięć minut wobec 125. Pięćset megabajtów wobec 16 gigabajtów. Żadna ze stron nie odnosi się do drugiej i żadna nie ma daty poza notatką z 2015 roku przy wcześniejszym punkcie. Jeśli wideo trafia do kampanii, przygotuj je pod mniejsze limity, bo to proces reklamowy może je odrzucić.

Druga niezgodność pojawia się o warstwę dalej. Endpointy przesyłania przyjmują wartości pisane małymi literami. Biblioteka mediów Ads API przyjmuje wielkie litery: "There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO." Te same cztery pojęcia, dwa zapisy, a lista biblioteki mediów całkowicie pomija kategorie DM i napisów.

Co się stanie, gdy wybierzesz złą wartość media_category?

Przesyłanie się powiedzie, a kolejne wywołanie zakończy się błędem. X wskazuje to jako typową sytuację: "Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails."

Tak wygląda niemal każda pomyłka z media_category. INIT przyjmuje wartość, APPEND przesyła bajty, FINALIZE zwraca poprawne processing_info, a odrzucenie przychodzi przy POST /2/tweets jako błąd 403, bo przesyłanie i publikowanie są egzekwowane osobno. Błąd 403 o treści "This user is not allowed to post a video longer than N minutes" przy filmie wyraźnie krótszym od limitu posta zwykle oznacza kategorię dm_video, która robi dokładnie to, co jej kazano.

W tym samym parametrze kryją się trzy mniejsze pułapki.

Dwa endpointy przesyłania różnią się co do tego, czy parametr jest opcjonalny. W POST /2/media/upload/initialize jest opcjonalny, a lista ma osiem wartości. W prostym endpoincie POST /2/media/upload schemat wymienia media i media_category jako wymagane, a lista ma siedem wartości, bez amplify_video. Wideo promowane nie może więc w ogóle przejść prostą ścieżką przesyłania, co zgadza się z osobnym zaleceniem X, by każde wideo przesyłać fragmentami.

Pominięcie wartości przy dużym GIF-ie oznacza rezygnację z przetwarzania asynchronicznego, którego taki plik potrzebuje, bo X wiąże je z przekazaniem tweet_gif, a nie z samym plikiem.

Wreszcie subtitles wyróżnia się na tle pozostałych. To jedyna wartość na liście, która nie jest obrazem, GIF-em ani wideo, ma limit 1 MB, a jej wartości media_type to text/srt i text/vtt. Plik z napisami przesłany bez niej dziedziczy domyślne ustawienie dla posta i jest oceniany według zasad dla obrazów, których nigdy nie spełni.

Każda sieć rozwiązuje to inaczej, a koncepcja kategorii nie przenosi się między nimi. Instagram dzieli tę samą decyzję między media_type a specyfikację Reels, a TikTok ustala długość na podstawie statusu konta, a nie parametru przesyłania. Na X cała decyzja mieści się w jednym opcjonalnym ciągu znaków, który wysyłasz raz, przy INIT, i którego nie możesz już zmienić. Jeśli ustawisz go źle, całe przesyłanie trzeba zacząć od początku.

Gdzie naprawdę ujawnia się zła wartość media_category
1
INIT. Przyjmuje wartość bez względu na to, jakie miejsce publikacji wskazuje.
2
APPEND. Przesyła bajty bez sprawdzania miejsca docelowego.
3
FINALIZE. Zwraca poprawne processing_info.
4
POST /2/tweets. Odrzuca żądanie błędem 403, bo przesyłanie i publikowanie są egzekwowane osobno.
Zła wartość media_category przechodzi przez wszystkie etapy przesyłania i ujawnia się dopiero przy publikacji posta.

Najczęściej zadawane pytania

Jakie wartości przyjmuje parametr media_category w API Twittera?

Osiem: tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif i subtitles. Taką listę publikuje POST /2/media/upload/initialize.

Czy media_category jest wymagane w API X?

To zależy od endpointu. POST /2/media/upload/initialize traktuje je jako opcjonalne i zgaduje kategorię posta na podstawie typu treści. Prosty endpoint POST /2/media/upload wymienia je jako wymagane.

Czym różni się tweet_video od amplify_video?

Przeznaczeniem, a nie rozmiarem. X wymaga amplify_video przy wszystkim, co trafia do treści promowanych, i podaje, że limity długości i rozmiaru obu wartości są w poście takie same. Strona kreacji Ads API nadal wskazuje niższy limit dla wideo promowanego: 10 minut i 500 MB.

Jak długie może być dm_video w API X?

Domyślnie 140 sekund, a na koncie X Premium lub zweryfikowanym 10 minut, przy limitach rozmiaru 512 MB i 1 GB. Minimalna długość to 0,5 sekundy, tak jak w każdej innej kategorii wideo.

Jaki błąd powoduje zła wartość media_category?

Zwykle 403 Forbidden przy POST /2/tweets, a nie błąd podczas przesyłania. X zaznacza, że użycie kategorii DM w poście to częsty powód, dla którego przesyłanie się udaje, a utworzenie posta już nie.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Czy media_category wpływa na limity rozmiaru obrazów?

Nie. Obrazy pozostają przy 5 MB, a animowane GIF-y przy 15 MB zarówno w postach, jak i w wiadomościach prywatnych, a X Premium nie podnosi żadnego z tych limitów. Od kategorii i subskrypcji zależą tylko długość i rozmiar pliku wideo.

Czym różni się media_type od media_category w API X?

media_type mówi X, jaki jest format pliku, na przykład video/mp4. media_category mówi, do czego plik służy: do posta, wiadomości prywatnej, ścieżki napisów czy reklamy. To media_category, a nie media_type, decyduje o tym, który limit rozmiaru i długości obowiązuje.

Jaką minimalną długość wideo akceptuje API X?

Minimum to 0,5 sekundy, a X podaje je jako dolną granicę, a nie zalecenie. Jest ono takie samo we wszystkich kategoriach wideo: tweet_video, amplify_video, dm_video i pozostałych, więc zmiana kategorii go nie obniża.

Jakiego formatu wideo wymaga X Ads API dla wideo promowanego?

Strona kreacji Ads API wymaga plików mp4 lub mov dla wideo przesyłanego do treści promowanych. Mówi to wprost: przesłane wideo powinno być w formacie mp4 lub mov. Strony dokumentacji mediów nigdzie indziej tego wymogu nie powtarzają.

Czy prosty endpoint przesyłania mediów obsługuje wideo promowane?

Wideo promowane nie może przejść przez prosty endpoint przesyłania. Jego lista zawiera siedem wartości media_category i pomija amplify_video, a POST /2/media/upload/initialize zachowuje wszystkie osiem. Ta różnica pokrywa się z osobnym zaleceniem X, by każde wideo przesyłać fragmentami, niezależnie od kategorii.

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