Todos los valores de media_category de la API de Twitter y qué permiten

¿Qué es el parámetro media_category de la API de Twitter?

Existen ocho valores para el parámetro media_category de la API de Twitter, y X define su función en una línea: "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."

Caso de uso, no tipo de archivo. media_type ya le dice a X que los bytes son un MP4. media_category le dice si ese MP4 va a un Post, a un Direct Message o a un anuncio, y X elige un techo distinto para cada respuesta.

El parámetro es opcional en POST /2/media/upload/initialize y X documenta el valor de reserva: "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."

Ese valor por defecto cubre los Posts y nada más. Todo lo que vaya a un DM, a un anuncio o a una pista de subtítulos tiene que declararlo, porque X no puede deducirlo de un MP4.

¿Qué permite cada valor de media_category de la API de Twitter?

Cada valor corresponde a una superficie, y X publica el enum completo en el esquema del endpoint initialize.

La duración mínima de vídeo es la misma en todas las categorías de vídeo. X la fija en "0.5 seconds" y la repite como suelo, no como recomendación.

Dos valores llevan una instrucción más allá de sus límites. amplify_video es obligatorio, no opcional, para cualquier cosa promocionada, y la Ads API lo dice desde 2015: "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." tweet_gif es el interruptor que activa el procesamiento asíncrono para los GIFs animados grandes, algo que X detalla en la página de buenas prácticas: "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."

¿Cómo cambia media_category los topes de tamaño y duración?

La categoría selecciona qué fila de la tabla de límites de X se aplica, y la suscripción de la cuenta selecciona qué columna. X nombra las dos entradas: los límites dependen de "the authenticated user's X Premium / verified status, not your developer API plan" y de "the media_category you pass when initializing the upload."

La diferencia entre categorías es grande. Un vídeo que cabe en tweet_video con 20 minutos tiene que bajar de 140 segundos para salir como dm_video en la misma cuenta, y de 10 minutos incluso con Premium. Mismo archivo, misma cuenta, mismo endpoint, y un factor de ocho entre los dos techos.

total_bytes también se comprueba contra la categoría. X escribe que "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." Se nombran dos puntos de fallo y X no dice cuál lo atrapa, así que trata tanto INIT como FINALIZE como sitios donde puede aparecer un rechazo por tamaño.

La categoría no cambia las reglas de imagen. Las imágenes se quedan en 5 MB y los GIFs animados en 15 MB, vayan a un Post o a un DM, y Premium no mueve ninguna de las dos cifras. Solo la duración y el tamaño de archivo del vídeo responden a la suscripción, un efecto más estrecho de lo que sugiere el conjunto completo de ventajas de X Premium.

¿Por qué X publica dos límites distintos para amplify_video?

Porque la página de creatives de la Ads API y la documentación de medios no coinciden, y las dos están publicadas.

Las páginas de medios tratan amplify_video como igual de tweet_video. La página de buenas prácticas lo dice sin rodeos: "For Posts, Premium and default duration/size caps are the same for tweet_video and amplify_video." Su tabla da a ambos 20 minutos y 8 GB por defecto, y 125 minutos y 16 GB con Premium.

La página de creatives de la Ads API, en la sección Promoted Video, da otro par de números en una sola viñeta: "The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less." Y añade una restricción de formato que las páginas de medios tampoco mencionan: "Uploaded video should be either mp4 or mov."

Diez minutos frente a 125. Quinientos megabytes frente a 16 gigabytes. Ninguna de las dos páginas reconoce a la otra, y ninguna lleva fecha más allá de la nota de 2015 pegada a la viñeta de encima. Construye para el par más pequeño si el vídeo va a una campaña, porque el canal de anuncios es el que lo rechazaría.

Un segundo desajuste aparece una capa más allá. Los endpoints de subida aceptan valores en minúsculas. La media library de la Ads API los acepta en mayúsculas: "There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO." Los mismos cuatro conceptos, dos grafías, y la lista de la media library omite por completo las categorías de DM y de subtítulos.

¿Qué pasa cuando eliges el media_category equivocado?

La subida funciona y falla la llamada siguiente. X lo señala como el caso habitual: "Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails."

Esa es la forma de casi todos los errores con media_category. INIT acepta el valor, APPEND mueve los bytes, FINALIZE devuelve un processing_info limpio, y el rechazo llega en POST /2/tweets con un 403 porque la subida y la publicación se controlan por separado. Un 403 que dice "This user is not allowed to post a video longer than N minutes" en un vídeo muy por debajo del límite del Post suele ser una categoría dm_video haciendo exactamente lo que se le pidió.

En el mismo parámetro hay tres trampas más pequeñas.

Los dos endpoints de subida no coinciden sobre si el parámetro es opcional. En POST /2/media/upload/initialize es opcional y el enum tiene ocho valores. En el endpoint simple POST /2/media/upload el esquema lista media y media_category como obligatorios, y su enum tiene siete valores porque falta amplify_video. El vídeo promocionado no puede pasar entonces por la ruta de subida simple, lo que encaja con el consejo aparte de X de usar la subida por fragmentos para todo el vídeo en cualquier caso.

Omitir el valor en un GIF grande renuncia al procesamiento asíncrono que esos GIFs necesitan, porque X ata ese comportamiento a enviar tweet_gif y no al archivo en sí.

Y subtitles es el raro del grupo. Es el único valor del enum que no es una imagen, un GIF ni un vídeo, tiene un tope de 1 MB, y sus valores de media_type son text/srt y text/vtt. Un archivo de subtítulos subido sin él hereda el valor por defecto del Post y se evalúa contra reglas de imagen que nunca iba a cumplir.

Cada red resuelve esto de otra forma, y el concepto de categoría no viaja. Instagram reparte la misma decisión entre media_type y la especificación de reels, y TikTok resuelve la duración por el estatus de la cuenta en lugar de por un parámetro de subida. En X, la decisión entera vive en una cadena opcional que envías una vez, en INIT, y que ya no puedes cambiar. Si la pones mal, el recorrido de subida tiene que empezar de cero.

Preguntas frecuentes

¿Qué valores acepta el parámetro media_category de la API de Twitter?

Ocho: tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif y subtitles. Ese es el enum publicado en POST /2/media/upload/initialize.

¿Es media_category obligatorio en la API de X?

Depende del endpoint. POST /2/media/upload/initialize lo trata como opcional y adivina una categoría de Post por el tipo de contenido. El endpoint simple POST /2/media/upload lo lista como obligatorio.

¿Cuál es la diferencia entre tweet_video y amplify_video?

El propósito, no el tamaño. X exige amplify_video para cualquier cosa usada en contenido promocionado y dice que los topes de duración y tamaño de los dos son iguales en un Post. La página de creatives de la Ads API sigue indicando un techo más bajo para el vídeo promocionado, de 10 minutos y 500 MB.

¿Cuánto puede durar un dm_video en la API de X?

140 segundos por defecto y 10 minutos en una cuenta con X Premium o verificada, con topes de tamaño de archivo de 512 MB y 1 GB. La duración mínima es de 0,5 segundos, igual que en cualquier otra categoría de vídeo.

¿Qué error da un media_category equivocado?

Normalmente un 403 Forbidden en POST /2/tweets, no un error en el momento de subir. X señala que una categoría de DM usada en un Post es un motivo habitual de que la subida funcione y la creación del Post falle después.

¿Afecta media_category a los límites de tamaño de imagen?

No. Las imágenes se quedan en 5 MB y los GIFs animados en 15 MB, tanto en Posts como en DMs, y X Premium no sube ninguno de los dos. Solo la duración y el tamaño de archivo del vídeo cambian con la categoría y la suscripción.

¿Cuál es la diferencia entre media_type y media_category?

media_type le dice a X en qué formato está el archivo, por ejemplo video/mp4. media_category le dice a X para qué es ese archivo, un Post, un mensaje directo, una pista de subtítulos o un anuncio. X usa media_category, no media_type, para decidir qué tope de tamaño y duración aplica.

¿Cuál es la duración mínima de video que acepta la API de X?

El mínimo es 0,5 segundos, y X lo plantea como un piso, no como una recomendación. Ese mínimo es igual en cada categoría de video, tweet_video, amplify_video, dm_video y el resto, así que cambiar de categoría no lo baja.

¿Qué formato de video exige la API de Ads de X para promoted video?

La página de creatividades de la Ads API exige mp4 o mov para el video subido en contenido promocionado. Lo dice de forma directa: uploaded video should be either mp4 or mov. Las páginas de documentación de media no repiten esta exigencia en ningún otro lado.

¿Se puede subir promoted video por el endpoint simple de media upload?

Promoted video no puede pasar por el endpoint simple de subida. Su enum lista siete valores de media_category y deja fuera a amplify_video, mientras que POST /2/media/upload/initialize conserva los ocho. Eso coincide con la recomendación aparte de X de usar chunked upload para todo video sin importar la categoría.