TL;DR, szybka odpowiedź
8 min czytaniaPrzesyłanie wideo we fragmentach w X v2 to cztery wywołania: POST /2/media/upload/initialize zwraca identyfikator multimediów, POST /2/media/upload/{id}/append przyjmuje każdy fragment z segment_index, POST /2/media/upload/{id}/finalize zamyka sesję, a GET /2/media/upload?command=STATUS odpytuje processing_info, aż stan będzie succeeded lub failed. Stare parametry command=INIT i command=APPEND zniknęły wszędzie poza tym żądaniem GET o status. segment_index kończy się na 999, a X zaleca fragmenty 5 MB, co nie pozwala osiągnąć 16 GB total_bytes akceptowanych przez schemat initialize.
Czym jest przesyłanie multimediów INIT APPEND FINALIZE w X API?
Proces przesyłania multimediów INIT APPEND FINALIZE w X API składa się z czterech wywołań: trzech żądań POST, które przenoszą plik, i jednego GET, które informuje, co X z nim potem zrobił. X wymienia je w tej kolejności w przewodniku po przesyłaniu we fragmentach.
- INIT,
POST /2/media/upload/initialize, które X opisuje jako "start the session and get amedia_id" - APPEND,
POST /2/media/upload/{id}/append, "upload each chunk" - FINALIZE,
POST /2/media/upload/{id}/finalize, "complete the upload" - STATUS,
GET /2/media/upload, "wait for processing whenprocessing_infois returned"
Nazwy poleceń przetrwały przejście na v2, ale sposób ich przekazywania już nie. X umieszcza ostrzeżenie tuż pod listą: "Do not send command=INIT, command=APPEND, or command=FINALIZE to POST /2/media/upload. Those command-style parameters were the previous upload protocol. The v2 flow uses the dedicated paths above. command=STATUS is still used only on the status GET."
Jedno z czterech poleceń nadal istnieje więc jako parametr zapytania, a trzy pozostałe nie. Kod napisany pod v1.1 zawodzi na trzech żądaniach POST i dalej działa przy odpytywaniu, co jest dość mylącym sposobem na awarię.
Wszystkie cztery wywołania wymagają tego samego zakresu OAuth 2.0, media.write, łącznie z GET o status. Odczyt stanu przetwarzania własnego pliku wymaga zakresu do zapisu, a X nie publikuje alternatywy tylko do odczytu.
Co wysyła i zwraca każdy krok?
Każdy krok ma inne parametry, a tylko dwa z czterech zwracają coś, co warto zachować.
| Krok | Endpoint | Co wysyłasz | Co dostajesz |
|---|---|---|---|
| INIT | POST /2/media/upload/initialize | media_type, total_bytes, media_category, opcjonalnie additional_owners i shared | id, media_key, expires_after_secs |
| APPEND | POST /2/media/upload/{id}/append | media i segment_index | expires_at |
| FINALIZE | POST /2/media/upload/{id}/finalize | nic poza id w ścieżce | id, media_key, size, expires_after_secs, processing_info |
| STATUS | GET /2/media/upload?command=STATUS&media_id= | media_id, opcjonalnie command | id, media_key, size, processing_info, video lub image |
INIT przyjmuje treść JSON, a nie pola formularza, co X podkreśla w przewodniku: "Send a JSON body, not multipart form fields." Enum media_type obejmuje video/mp4 i video/quicktime, przez text/srt i text/vtt, aż po dwa formaty 3D, których większość osób nawet nie zauważa: model/gltf-binary i model/vnd.usdz+zip. Pole total_bytes ma w schemacie sztywny limit 17179869184, czyli 16 GiB.
{
"data": {
"id": "1880028106020515840",
"media_key": "13_1880028106020515840",
"expires_after_secs": 86400
}
}Wartość expires_after_secs równa 86400 w przykładzie X to zegar sesji: jeden dzień od INIT na dołączenie gotowych multimediów do czegokolwiek. id pasuje do wzorca ^[0-9]{1,19}$, a media_key poprzedza go numerem typu i podkreśleniem, w tej samej postaci 13_, którą Ads API dokumentuje, nazywając tę wartość id wideo.
APPEND to jedyny krok, którego odpowiedź nie mówi nic przydatnego o multimediach. Jego schemat ma jedno pole, expires_at, opisane jako "Epoch seconds when the upload session expires." Każdy inny krok podaje pozostały czas sesji jako expires_after_secs, czyli wartość względną. APPEND podaje go jako bezwzględny znacznik czasu. Ten sam fakt, dwie jednostki, różne nazwy pól w czterech endpointach.
FINALIZE to najuboższe żądanie w całym procesie. Przyjmuje id w ścieżce i nic więcej, bez treści i parametrów zapytania, dlatego całe polecenie curl mieści się w dwóch wierszach:
curl -X POST "https://api.x.com/2/media/upload/1880028106020515840/finalize" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN"To w odpowiedzi na nie następuje właściwe rozgałęzienie. X ujmuje zasadę w jednym zdaniu: "If processing_info is returned, proceed to Step 4 to wait for processing. If not, the media is ready to use." Zdjęcie zwykle pomija krok czwarty. Wideo nigdy.

Jak działa segment_index?
segment_index to zwykły licznik, którym zarządzasz sam, zaczynający się od zera, a schemat określa oba jego końce: "minimum: 0, maximum: 999."
Wskazówki dotyczące rozmiaru fragmentu X umieszcza w przewodniku, a nie w schemacie: "Keep each segment at or below 5 MB (the server maximum is 8 MB). Segments are indexed from 0." Przykład w Pythonie z tego samego przewodnika czyta plik blokami po 4 MB i zwiększa indeks po każdym udanym wywołaniu.
curl -X POST "https://api.x.com/2/media/upload/1880028106020515840/append" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
-F "segment_index=0" \
-F "media=@/path/to/chunk0.mp4"Treść może być danymi formularza multipart, jak wyżej, albo JSON-em, ponieważ schemat żądania jest zarejestrowany dla obu typów. W JSON-ie pole media przyjmuje base64, a w multipart surowe bajty.
Teraz pomnóż oba opublikowane limity. Tysiąc segmentów przy serwerowym maksimum 8 MB to 8 GB. Tysiąc segmentów przy zalecanych 5 MB to 5 GB. Tymczasem POST /2/media/upload/initialize akceptuje total_bytes do 16 GiB, a X wprost stwierdza, że konto X Premium lub zweryfikowane może przesłać w poście wideo o rozmiarze 16 GB. Tych dwóch faktów nie da się pogodzić przez APPEND w udokumentowanej postaci, a X nie publikuje większego rozmiaru segmentu, alternatywnej ścieżki ani informacji, że limit 999 zmienia się dla dużych plików. Dla wszystkiego powyżej 8 GB nie ma udokumentowanej drogi przez ten proces.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Przesyłanie nie musi też być sekwencyjne w żadnym opublikowanym sensie. X wymienia wśród zalet dzielenia na fragmenty "Failed chunks can be retried individually" oraz "Uploads can be paused and resumed", ale nigdy nie mówi, czy ponownie wysłany segment nadpisuje wcześniejszy, czy indeksy mogą przychodzić w innej kolejności ani co się stanie, gdy pominiesz numer. To samo pytanie pojawia się w innych sieciach: sesja wznawianego przesyłania na Instagramie ma nagłówek offsetu, który każdy opublikowany przykład ustawia na zero, a LinkedIn rozwiązuje to, podając listę adresów przesyłania, po jednym na część.

Co zwraca polecenie STATUS?
STATUS zwraca obiekt processing_info z trzema polami, a decydujące jest state.
| Pole | Co mówi schemat |
|---|---|
state | "Processing state (pending, in_progress, failed, succeeded)" |
check_after_secs | "Seconds to wait before polling status again" |
progress_percent | "Processing completion percentage" |
Przewodnik przedstawia poprawny przebieg jako ciąg: "pending to in_progress to succeeded or failed." Dwa z tych czterech stanów są końcowe. Przykład odpytywania od X przerywa pętlę przy succeeded i failed, a w pozostałych przypadkach czeka check_after_secs, co jest poprawnym podejściem, bo odstęp ustala serwer, a nie twoja polityka ponawiania. Przykład FINALIZE zwraca "check_after_secs": 1, więc pierwsze odpytanie następuje szybko.
curl "https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN"Zanim zbudujesz pętlę, warto znać dwie luki.
Cztery wartości stanu istnieją tylko w opisie, a nie w enumie. Schemat definiuje state jako zwykły ciąg znaków bez listy dozwolonych wartości, więc cztery nazwy podane przez X są dokumentacją, a nie zamkniętym zbiorem. Nieznany stan traktuj jako „odpytuj dalej”, a nie jako błąd.
Ważniejsze jest to, że processing_info nie ma gdzie umieścić przyczyny niepowodzenia. Schemat deklaruje dokładnie trzy właściwości, a potem additionalProperties: false, więc odpowiedź z "state": "failed" nie zawiera kodu, komunikatu ani podkodu. Protokół v1.1 zwracał wewnątrz processing_info obiekt błędu z nazwą i komunikatem. Opublikowany schemat v2 nie ma na to pola, więc samo „failed” jest całą diagnozą.
progress_percent jest udokumentowane w każdym schemacie processing_info w dokumentacji multimediów, ale nie pojawia się w żadnej przykładowej odpowiedzi X, więc licz się z jego brakiem, a nie z wartością zero.
Dlaczego ukończone przesyłanie nadal zawodzi na POST /2/tweets?
Bo X sprawdza plik dwukrotnie względem dwóch różnych osób i dwukrotnie o tym mówi. Wprowadzenie do multimediów zaczyna się od tego: "Upload and posting are separately enforced. A file that uploads successfully can still be rejected when you attach it to a Post."
Pierwsza kontrola dotyczy użytkownika przesyłającego plik na etapach INIT i FINALIZE. Druga dotyczy użytkownika publikującego, gdy media_id trafia do POST /2/tweets. X dokładnie nazywa ten błąd:
{
"title": "Forbidden",
"detail": "This user is not allowed to post a video longer than 20 minutes.",
"type": "about:blank",
"status": 403
}Dwadzieścia minut to domyślna wartość w tym komunikacie. X zaznacza, że liczba się zmienia: "N is the posting user's duration cap (20 minutes by default, 125 minutes for Premium / verified)." Oznacza to, że to samo media_id, sfinalizowane raz i przetworzone do succeeded, da się dołączyć na jednym koncie, a na innym zwróci 403. Uprawnienia zależą od konta, a o długości wideo decydują te same poziomy X Premium, a nie twój plan deweloperski.
W tym samym momencie obowiązują limity składu posta. X pozwala na "up to 4 photos, 1 animated GIF, or 1 video" w poście, a media_id łamiące ten układ zawodzi przy dołączaniu, nawet jeśli samo przesyłanie przebiegło bez błędów. Praktyczną kolejność dla dłuższych materiałów opisuje pełny przewodnik po publikowaniu wideo wysokiej jakości na X, w którym 403 jest zwykłym wynikiem, a nie wyjątkiem.
Najczęściej zadawane pytania
Które endpointy zastępują command=INIT i command=APPEND w X API v2?
POST /2/media/upload/initialize oraz POST /2/media/upload/{id}/append. X podaje, że parametry w stylu poleceń "were the previous upload protocol" i nie wolno już wysyłać ich do POST /2/media/upload.
Czy command=STATUS jest nadal poprawne w X API v2?
Tak, i tylko ono. X pisze, że "command=STATUS is still used only on the status GET", czyli GET /2/media/upload?command=STATUS&media_id=. Schemat oznacza parametr command jako opcjonalny, choć każdy opublikowany przykład go przekazuje.
Jaka jest maksymalna wartość segment_index w endpoincie append X API?
- Schemat żądania append ustawia
segment_indexna minimum 0 i maksimum 999, więc plik może mieć najwyżej 1000 fragmentów.
Jak duży może być każdy fragment APPEND?
X zaleca 5 MB, a jako maksimum serwera podaje 8 MB. Jego własny przykład w Pythonie czyta plik blokami po 4 MB.
AdaptlyPost
Rozpocznij 7-dniowy bezpłatny okres próbny
Analityka wszystkich platform
Skrzynka społecznościowa
Asystent oparty na AI
Jakie są stany przetwarzania przy przesyłaniu multimediów na X?
pending, in_progress, succeeded i failed. X przedstawia przejście od pending przez in_progress do succeeded lub failed, choć schemat definiuje state jako otwarty ciąg znaków, a nie enum.
Dlaczego media_id po udanym FINALIZE zawodzi na POST /2/tweets?
Przesyłanie i publikowanie są egzekwowane osobno, według różnych uprawnień. Jeśli publikujący użytkownik nie może dołączyć tak długiego wideo, żądanie posta zwraca 403 Forbidden ze szczegółem "This user is not allowed to post a video longer than N minutes."
Jak długo sesja przesyłania multimediów na X pozostaje ważna?
Przykład INIT od X zwraca expires_after_secs równe 86400, czyli jeden dzień od INIT na dołączenie gotowych multimediów do czegokolwiek. FINALIZE również podaje pozostały czas jako expires_after_secs. APPEND łamie ten schemat i zwraca expires_at, czyli bezwzględny znacznik czasu zamiast odliczania, więc ten sam zegar sesji występuje w dwóch różnych jednostkach.
Czy przesłanie zdjęcia na X wymaga odpytywania endpointu STATUS?
Zwykle nie. Zgodnie z zasadą X, jeśli FINALIZE nie zwróci bloku processing_info, multimedia są gotowe do użycia, a przesłane zdjęcie zazwyczaj wraca bez niego. Wideo nigdy, więc krok czwarty to w praktyce oczekiwanie dotyczące tylko wideo.
Czy endpoint STATUS używa innego zakresu OAuth niż kroki przesyłania?
Wszystkie cztery wywołania, INIT, APPEND, FINALIZE i STATUS, wymagają tego samego zakresu media.write. Odczyt stanu przetwarzania własnego pliku wymaga zakresu do zapisu, a X nie publikuje alternatywy tylko do odczytu.
Jakie typy multimediów można przesłać przez endpoint initialize w X API?
Enum media_type w INIT obejmuje video/mp4 i video/quicktime, przez text/srt i text/vtt, aż po dwa formaty 3D, model/gltf-binary i model/vnd.usdz+zip. Ten zakres mieści wideo, pliki napisów i zasoby 3D w jednym endpoincie przesyłania.
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


Wszystkie wartości media_category w API Twittera i co umożliwiają
Parametr media_category w API Twittera ma osiem wartości, wyznacza limity rozmiaru i długości, a zła wartość wywołuje błąd dopiero przy publikacji posta.


Sesja wznawianego przesyłania na Instagramie i host rupload
Wznawiane przesyłanie na Instagramie zaczyna się od upload_type=resumable w /media, po czym następuje POST na rupload.facebook.com z nagłówkami offset i file_size.


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.
Powiązane artykuły


Jak długi może być film na X przy każdym rodzaju konta
Jak długi może być film na X? Trzy oficjalne odpowiedzi: 140 sekund za darmo, do 4 godzin w Premium oraz 20 lub 125 minut przez API.


Jaki jest limit długości wideo na Pintereście dla Pinów i reklam
Limit długości wideo na Pintereście to od 4 sekund do 15 minut dla Pina wideo, przy pliku do 2 GB. Reklamy Idea kończą się na 5 minutach, a quizy na 60 s.


Jaki jest limit długości filmu w Threads w aplikacji i w API
Limit długości filmu w Threads to 5 minut w aplikacji i 300 sekund w API, przy pliku do 1 GB. Oto jak Meta sprawdza każdy film.

