Best practices

Ci sono alcuni concetti importanti da comprendere quando si usa l’endpoint POST /2/media/upload. Il caricamento dei contenuti multimediali con OAuth può essere un po’ complesso, quindi qui abbiamo evidenziato alcuni aspetti da tenere presenti e fornito un esempio funzionante su come utilizzare questo endpoint.

​

Da tenere a mente

• È possibile allegare fino a 4 foto, 1 GIF animata o 1 video a un Post.
• L’immagine inviata deve essere il binario grezzo dell’immagine oppure il binario codificato in base64; non è necessario codificare o effettuare l’escape dei contenuti purché l’intestazione Content-Type sia impostata correttamente (in caso di dubbio: application/octet-stream).
• Quando si inviano immagini codificate in base64, assicurarsi di impostare “Content-Transfer-Encoding: base64” sulla parte dell’immagine del messaggio.
• I boundary dei messaggi multipart devono trovarsi su una riga dedicata e terminare con CRLF.
• Per esempi pratici su come effettuare una richiesta POST utilizzando questo endpoint, consigliamo di testare con xurl. Inoltre, consulta le X Libraries disponibili.
• Utilizzare il valore media_id_string fornito nella risposta dell’API per JavaScript e per qualsiasi altro linguaggio che non possa rappresentare accuratamente un intero long.

​

Categorie multimediali

Il parametro Media Category definisce il caso d’uso del file multimediale da caricare e può influire sui limiti di dimensione del file o su altri vincoli applicati ai caricamenti di contenuti multimediali. È importante utilizzare la categoria multimediale corretta quando si caricano i contenuti per evitare problemi durante il loro utilizzo. Si tratta di un valore opzionale passato nella richiesta INIT come parte del flusso di upload. Se la categoria multimediale non è specificata, il contenuto caricato viene considerato come media per un Post (tweet_image, tweet_video o tweet_gif), a seconda del content type.

Le categorie multimediali più comuni sono le seguenti:

• tweet_image
• tweet_video
• tweet_gif
• dm_image
• dm_video
• dm_gif
• subtitles

Se sei un partner della X Ads API, fai riferimento a questa documentazione per ulteriori informazioni sulla categoria multimediale consigliata per i video promossi.

​

Specifiche e consigli per le immagini

I file immagine devono soddisfare tutti i seguenti criteri:

• Tipi di file immagine supportati: JPG, PNG, GIF, WEBP
• Dimensione dell’immagine: <= 5 MB
• Dimensione della GIF animata: <= 15 MB

Il limite di dimensione del file indicato sopra è applicato dall’endpoint di caricamento dei media. Inoltre, esiste un limite di dimensione del file specifico per l’entità di prodotto, applicato quando si chiamano gli endpoint di creazione di Post (o simili) con media_id. Il limite di dimensione del file e altri vincoli possono variare in base al parametro media_category.

​

Raccomandazioni per GIF animate

Una GIF può non riuscire a essere creata come Post anche se rientra nel limite di dimensione del file. Attenetevi ai seguenti vincoli per aumentare il tasso di successo.

• Risoluzione: <= 1280x1080 (width x height)
• Numero di fotogrammi: <= 350
• Numero di pixel: <= 300 million (width * height * num_frames)
• Dimensione del file: <= 15MB

Per elaborare GIF più grandi, utilizzate l’endpoint chunked upload con il parametro media_category. Questo consente al server di elaborare la GIF in modo asincrono, requisito necessario per gestire file di dimensioni maggiori. Passate media_category=tweet_gif per abilitare il caricamento asincrono dei Post con una GIF animata.

​

Specifiche e raccomandazioni per i video

Usa il percorso Async per il caricamento dei media.

​

Consigliati

• Codec video: H264 High Profile
• Frame rate: 30 FPS, 60 FPS
• Risoluzione video: 1280x720 (orizzontale), 720x1280 (verticale), 720x720 (quadrato). Gli utenti abbonati possono caricare video in 1080p e ottenere la riproduzione in 1080p. Gli utenti non abbonati possono caricare video in 720p e ottenere la riproduzione in 720p.
• Bitrate video minimo: 5.000 kbps
• Bitrate audio minimo: 128 kbps
• Codec audio: AAC LC
• Proporzioni: 16:9 (orizzontale o verticale), 1:1 (quadrato)

​

Avanzate

• Frame rate: deve essere pari o inferiore a 60 FPS
• Dimensioni: devono essere comprese tra 32x32 e 1280x1024
• Dimensione del file: non deve superare 512 MB
• Durata: deve essere compresa tra 0,5 secondi e 140 secondi
• Rapporto d’aspetto: deve essere compreso tra 1:3 e 3:1
• Rapporto d’aspetto dei pixel: deve essere 1:1
• Formato dei pixel: è supportato solo YUV 4:2:0
• L’audio deve essere AAC con profilo Low Complexity. (AAC High-Efficiency non è supportato)
• L’audio deve essere mono o stereo, non 5.1 o superiore
• Non deve avere open GOP
• Deve usare la scansione progressiva

​

Informazioni aggiuntive

Nella tabella seguente, ogni riga rappresenta una raccomandazione di caricamento, ma non un requisito. Tutti i caricamenti vengono elaborati per l’ottimizzazione su più piattaforme.

Orientamento	Larghezza	Altezza	Bitrate video	Bitrate audio
Orizzontale	1280	720	2048K	128K
Orizzontale	640	360	768K	64K
Orizzontale	320	180	256K	64K
Verticale	720	1280	2048K	128K
Verticale	360	640	768K	64K
Verticale	180	320	256K	64K
Quadrato	720	720	2048K	128K
Quadrato	480	480	768K	64K
Quadrato	240	240	256K	32K

Per un esempio di come caricare contenuti multimediali, consulta la documentazione sul caricamento a blocchi dei contenuti multimediali.

​

Risoluzione dei problemi

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