Zum Hauptinhalt springen
Dieser Leitfaden hilft Ihnen, Ihre ersten Anforderungen zum Hochladen von Medien über die X API v2 Media-Upload-endpoints zu stellen. Für diesen Leitfaden werden die gestückelten POST /2/media/upload endpoints verwendet, um ein Video hochzuladen. Dies erfordert einen anderen Ablauf als das Hochladen einzelner Bilder. Für Video- oder gestückelte Uploads müssen Sie:
  1. Den Upload mit dem Befehl INIT initialisieren
  2. Jeden Daten-Chunk mit dem Befehl APPEND hochladen
  3. Den Upload mit dem Befehl FINALIZE abschließen
Hinweis: Siehe diesen Beispielcode für ein in Python geschriebenes Beispiel.

​
Authentifizierung

Um die in diesem Leitfaden bereitgestellten Beispiele auszuführen, müssen Sie die Authentifizierung über OAuth 2 verwenden. Sie finden Ihre CONSUMER_KEY, CONSUMER_SECRET, ACCESS_KEY, ACCESS_TOKEN in der App innerhalb Ihres Project im Dashboard des Entwicklerportals.

​
Schritt 1: POST media/upload (INIT)

Die INIT-Anforderung wird verwendet, um eine Upload-Sitzung für eine Datei zu starten. Sie gibt eine media_id zurück, die für alle nachfolgenden Anforderungen verwendet werden sollte. Der nächste Schritt nach einer erfolgreichen Antwort auf den INIT-Befehl ist der APPEND-Befehl. Siehe Best Practices für Einschränkungen und Anforderungen an Mediendateien. Beispielanforderung 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <IHR_ZUGRIFFSTOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=INIT' \
    --form 'media_type=video/mp4' \
    --form 'total_bytes=1024' \
    --form 'media_category=amplify_video'
Hinweis: Bei direkten HTTP-Anfragen muss die Anfrage als POST mit dem Format multipart/form-data oder application/x-www-form-urlencoded gesendet werden.
Beispielantwort 
{
    "data":
    {
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "expires_after_secs":1295999
    }
}
Die Antwort liefert die Medienkennungen id (String) und media_key (String). Die gesamte Datei muss innerhalb von expires_after_secs Sekunden hochgeladen werden.

​
Schritt 2 : POST media/upload (APPEND)

Der Befehl APPEND wird verwendet, um einen Chunk (aufeinanderfolgender Bytebereich) der Mediendatei hochzuladen. Beispielsweise kann eine 3‑MB‑Datei in drei Chunks zu je 1 MB aufgeteilt und mit drei APPEND‑Anfragen hochgeladen werden. Nachdem die gesamte Datei hochgeladen wurde, wird im nächsten Schritt der Befehl FINALIZE aufgerufen.
Das Hochladen einer Mediendatei in kleinen Chunks bietet mehrere Vorteile:
  • Höhere Zuverlässigkeit und Erfolgsraten bei geringer Bandbreite
  • Uploads können pausiert und fortgesetzt werden
  • Datei‑Chunks können einzeln erneut übertragen werden
  • Möglichkeit, die Chunk‑Größen an wechselnde Netzwerkbedingungen anzupassen, z. B. bei Mobilfunkverbindungen
Beispielanforderung 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=APPEND' \
    --form 'media_id=1880028106020515840' \
    --form 'segment_index=0' \
    --form 'media=@/pfad/zu/ihrer/mediendatei.mp4'
segment_index ist ein geordneter Index eines Dateifragmentes. Er muss im Bereich 0–999 (einschließlich) liegen. Das erste Segment hat den Index 0, das zweite den Index 1, und so weiter. Laden Sie die Dateifragmente weiter hoch, bis alle Fragmente hochgeladen wurden.
Hinweis: Bei rohen HTTP-Anfragen sollte die Anfrage im Format multipart/form-data mit der Methode POST erfolgen.
Hinweis: Bei erfolgreichem Upload wird ein HTTP-Status 2XX mit leerem Antworttext zurückgegeben.

​
Schritt 3: POST media/upload (FINALIZE)

Der Befehl FINALIZE sollte aufgerufen werden, nachdem die gesamte Mediendatei mithilfe von APPEND-Befehlen hochgeladen wurde. Wenn und nur wenn die Antwort des FINALIZE-Befehls ein Feld processing_info enthält, kann es außerdem notwendig sein, einen STATUS-Befehl zu verwenden und zu warten, bis dieser „success“ zurückgibt, bevor mit der Erstellung des Post fortgefahren wird. Beispielanforderung 
curl --location --request POST 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <IHR_ZUGRIFFSTOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=FINALIZE' \
    --form 'media_id=1880028106020515840'
Hinweis: Bei rohen HTTP-Anfragen muss die Anfrage als POST im Format multipart/form-data oder application/x-www-form-urlencoded gesendet werden.
Beispielantwort 
{
    "data": {
        "id": "1880028106020515840",
        "media_key": "13_1880028106020515840",
        "size": 1024,
        "expires_after_secs": 86400,
        "processing_info": {
            "state": "pending",
            "check_after_secs": 1
        }
    }
}
Die Antwort enthält eine Medienkennung in den Feldern media_id (64‑Bit‑Integer) und media_id_string (String). Verwenden Sie die in der API-Antwort bereitgestellte media_id_string in JavaScript und anderen Sprachen, die lange Ganzzahlen nicht exakt darstellen können. Die zurückgegebene media_id ist nur für expires_after_secs Sekunden gültig. Jeder Versuch, media_id nach diesem Zeitraum in anderen API-Aufrufen zu verwenden, führt zu einer Bad-Request-Antwort (HTTP 4xx). Wenn die Antwort ein processing_info-Feld enthält, verwenden Sie den Befehl STATUS, um den Status des FINALIZE-Vorgangs abzufragen. Der asynchrone Finalize-Ansatz wird in Fällen verwendet, in denen die Medienverarbeitung mehr Zeit benötigt. Künftig wird die Verarbeitung von Videos und animierten GIFs nur noch über asynchrones Finalize unterstützt. Dieses Verhalten ist aktiviert, wenn eine Upload-Sitzung mit einem media_category-Parameter initialisiert wurde und der Medientyp entweder Video oder animiertes GIF ist.
Hinweis: Wenn in der Antwort kein processing_info-Feld enthalten ist, ist media_id für die Verwendung in anderen API-endpoints bereit.

​
Schritt 4 : GET media/upload (STATUS)

Der Befehl STATUS wird verwendet, um periodisch den Fortschritt der Medienverarbeitung abzufragen. Sobald die Antwort auf den STATUS-Befehl succeeded zurückgibt, können Sie zum nächsten Schritt übergehen, der in der Regel darin besteht, einen Post mit der media_id zu erstellen.
Hinweis: Der Befehl STATUS sollte nur verwendet werden, wenn die Antwort des Befehls FINALIZE oder eines vorherigen STATUS-Befehls ein Feld processing_info enthalten hat.

​
Beispielanfrage

curl --location --request GET 'https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840' \
    --header 'Authorization: Bearer <IHR_ZUGANGSTOKEN>'

​
Beispiel-Antwort

{
    "data":{
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "processing_info":{
            "state":"uploading" // Zustandsübergänge: pending -> in_progress -> [failed|succeeded]
        }
    }
}
Der Antworttext enthält das Feld processing_info, das Informationen über den aktuellen Stand der Medienverarbeitung bereitstellt. Es enthält ein Feld state mit folgendem Übergangsablauf: pending -> in_progress -> [failed | succeeded]. Sie können die media_id nicht verwenden, um einen Post oder andere Objekte zu erstellen, bevor das Feld state auf succeeded gesetzt ist.

​
Schritt 5: Tweet mit Medien posten

Erstellt einen Post mithilfe des POST /2/tweets endpoint und gibt dabei die media_id im Namen eines authentifizierten Nutzers an. Beispielanfrage 
curl --location 'https://api.x.com/2/tweets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
--data '{
    "text": "Ich habe einen Post mit Medien veröffentlicht!",
     "media": {
       "media_ids": [
            "1880028106020515840"
        ]
    }
}'
Beispielantwort 
{
    "data": {
        "edit_history_tweet_ids": [
            "1880028106020515840"
        ],
        "id": "1880028106020515840",
        "text": "Ich habe einen Post mit Medien erstellt! https://t.co/DqNyXX"
    }
}

​
Fehlerbehebung

Bei Problemen mit den Media APIs durchsuchen Sie die Kategorie „Media APIs“ in den Entwicklerforen, um eine Antwort zu finden.
⌘I