Vai al contenuto principale
Questa guida ti aiuterà a inviare le prime richieste per caricare contenuti multimediali utilizzando gli endpoint di caricamento dei media della X API v2. In questa guida vengono utilizzati gli endpoint segmentati (chunked) POST /2/media/upload per caricare un video, il che richiede un flusso di lavoro diverso rispetto al caricamento di una singola immagine. Per i caricamenti di video o segmentati, è necessario:
  1. Inizializzare il caricamento con il comando INIT
  2. Caricare ogni segmento di byte con il comando APPEND
  3. Completare il caricamento con il comando FINALIZE
Nota: Consulta questo esempio di codice per un esempio scritto in Python.

​
Autenticazione

Per eseguire gli esempi forniti in questa guida è necessario utilizzare l’autenticazione OAuth 2. Potete trovare CONSUMER_KEY, CONSUMER_SECRET, ACCESS_KEY e ACCESS_TOKEN nella vostra App all’interno del vostro Project, nella dashboard del developer portal.

​
Passaggio 1: POST media/upload (INIT)

La richiesta del comando INIT avvia una sessione di caricamento del file. Restituisce un media_id che deve essere utilizzato per tutte le richieste successive. Il passo successivo dopo una risposta positiva al comando INIT è il comando APPEND. Consulta le Best Practices per i vincoli e i requisiti sui file multimediali. Esempio di richiesta 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <IL_TUO_ACCESS_TOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=INIT' \
    --form 'media_type=video/mp4' \
    --form 'total_bytes=1024' \
    --form 'media_category=amplify_video'
Nota: Quando si inviano richieste HTTP raw, la richiesta deve utilizzare il metodo POST con formato multipart/form-data o application/x-www-form-urlencoded.
Esempio di risposta 
{
    "data":
    {
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "expires_after_secs":1295999
    }
}
La risposta fornisce gli identificatori dei media id (stringa) e media_key (stringa). L’intero file deve essere caricato entro expires_after_secs secondi.

​
Passaggio 2: POST media/upload (APPEND)

Il comando APPEND viene utilizzato per caricare un blocco (intervallo consecutivo di byte) del file multimediale. Ad esempio, un file da 3 MB può essere suddiviso in 3 blocchi da 1 MB ciascuno e caricato tramite 3 richieste del comando APPEND. Dopo che l’intero file è stato caricato, il passo successivo è chiamare il comando FINALIZE.
Caricare un file multimediale in piccoli blocchi offre numerosi vantaggi:
  • Maggiore affidabilità e percentuali di successo in condizioni di rete a bassa larghezza di banda
  • I caricamenti possono essere messi in pausa e ripresi
  • I singoli blocchi possono essere ritentati
  • Possibilità di regolare le dimensioni dei blocchi in base alle condizioni di rete variabili, ad esempio su client mobili
Esempio di richiesta 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <IL_TUO_ACCESS_TOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=APPEND' \
    --form 'media_id=1880028106020515840' \
    --form 'segment_index=0' \
    --form 'media=@/percorso/al/tuo/file/media.mp4'
segment_index è l’indice ordinato del chunk del file. Deve essere compreso tra 0 e 999 inclusi. Il primo segmento ha indice 0, il secondo ha indice 1 e così via. Continua a caricare i chunk del file finché tutti i chunk non sono stati caricati.
Nota: Quando si effettuano richieste HTTP grezze, la richiesta deve essere in formato POST multipart/form-data.
Nota: In caso di caricamento riuscito, verrà restituito un codice HTTP 2XX con un corpo della risposta vuoto.

​
Passaggio 3: POST media/upload (FINALIZE)

Il comando FINALIZE va eseguito dopo che l’intero file multimediale è stato caricato tramite i comandi APPEND. Se e solo se la risposta del comando FINALIZE contiene un campo processing_info, potrebbe essere necessario usare anche il comando STATUS e attendere che restituisca esito positivo prima di procedere alla creazione del Post. Esempio di richiesta 
curl --location --request POST 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <IL_TUO_ACCESS_TOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=FINALIZE' \
    --form 'media_id=1880028106020515840'
Nota: Quando si inviano richieste HTTP raw, la richiesta deve utilizzare il formato POST multipart/form-data oppure application/x-www-form-urlencoded.
Esempio di risposta 
{
    "data": {
        "id": "1880028106020515840",
        "media_key": "13_1880028106020515840",
        "size": 1024,
        "expires_after_secs": 86400,
        "processing_info": {
            "state": "pending",
            "check_after_secs": 1
        }
    }
}
La risposta fornisce un identificatore multimediale nei campi media_id (intero a 64 bit) e media_id_string (stringa). Usa media_id_string fornito nella risposta dell’API da JavaScript e da altri linguaggi che non possono rappresentare con precisione un intero lungo. Il media_id restituito è valido solo per expires_after_secs secondi. Qualsiasi tentativo di usare mediaId dopo questo intervallo nelle altre chiamate API comporterà una risposta Bad Request (HTTP 4xx). Se la risposta contiene un campo processing_info, usa il comando STATUS per effettuare il polling dello stato dell’operazione FINALIZE. L’approccio di finalizzazione asincrona viene utilizzato nei casi in cui l’elaborazione dei media richiede più tempo. In futuro, l’elaborazione di video e GIF animate sarà supportata esclusivamente tramite finalizzazione asincrona. Questo comportamento è abilitato se una sessione di upload è stata initialized con il parametro media_category, e quando il tipo di media è video o GIF animata.
Nota: Se nella risposta NON è presente un campo processing_info, allora media_id è pronto per essere utilizzato negli altri endpoint API.

​
Passaggio 4: GET media/upload (STATUS)

Il comando STATUS viene usato per verificare periodicamente l’avanzamento dell’elaborazione dei media. Una volta che la risposta del comando STATUS restituisce succeeded, puoi passare al passaggio successivo, che di solito consiste nel creare un Post con media_id.
Nota: Il comando STATUS va utilizzato se e (solo se) la risposta del comando FINALIZE o di un precedente comando STATUS contiene un campo processing_info.

​
Esempio di richiesta

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

​
Esempio di risposta

{
    "data":{
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "processing_info":{
            "state":"uploading" // il flusso di transizione degli stati è pending -> in_progress -> [failed|succeeded]
        }
    }
}
Il corpo della risposta include il campo processing_info, che fornisce informazioni sullo stato corrente dell’operazione di elaborazione dei media. Include un campo state che segue il flusso di transizione: pending -> in_progress -> [failed | succeeded]. Non è possibile utilizzare il media_id per creare Post o altre entità finché il campo state non è impostato su succeeded.

​
Passaggio 5: Pubblicare un Tweet con contenuti multimediali

Crea un Post utilizzando l’endpoint POST /2/tweets, includendo il media_id per conto di un utente autenticato. Esempio di richiesta 
curl --location 'https://api.x.com/2/tweets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
--data '{
    "text": "Ho pubblicato un post con contenuti multimediali!",
     "media": {
       "media_ids": [
            "1880028106020515840"
        ]
    }
}'
Esempio di risposta 
{
    "data": {
        "edit_history_tweet_ids": [
            "1880028106020515840"
        ],
        "id": "1880028106020515840",
        "text": "Ho pubblicato un post con contenuti multimediali! https://t.co/DqNyXX"
    }
}

​
Risoluzione dei problemi

Per problemi con le API Media, consulta la categoria Media API nei forum per sviluppatori per trovare una risposta.
⌘I