Todos os valores de media_category da API do Twitter e o que cada um libera

O que é o parâmetro media_category da API do Twitter?

Existem oito valores para o parâmetro media_category da API do Twitter, e o X define em uma linha o trabalho que ele faz: "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, não tipo de arquivo. O media_type já diz ao X que os bytes são um MP4. O media_category diz ao X se esse MP4 vai para um Post, para uma mensagem direta ou para um anúncio, e o X escolhe um teto diferente para cada resposta.

O parâmetro é opcional em POST /2/media/upload/initialize e o X documenta o que acontece na ausência dele: "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."

Esse padrão cobre Posts e mais nada. Qualquer coisa destinada a uma DM, a um anúncio ou a uma faixa de legendas precisa dizer isso, porque o X não tem como deduzir a partir de um MP4.

O que cada valor de media_category da API do Twitter libera?

Cada valor mapeia para uma superfície, e o X publica o enum completo no schema do endpoint de inicialização.

Valor	Superfície que libera	Teto padrão	Teto no X Premium
tweet_image	Imagem em um Post	5 MB	5 MB
tweet_gif	GIF animado em um Post	15 MB	15 MB
tweet_video	Vídeo em um Post	20 min, 8 GB	125 min, 16 GB
amplify_video	Anúncios e vídeo promovido	20 min, 8 GB	125 min, 16 GB
dm_image	Imagem em uma mensagem direta	5 MB	5 MB
dm_gif	GIF animado em uma mensagem direta	15 MB	15 MB
dm_video	Vídeo em uma mensagem direta	140 s, 512 MB	10 min, 1 GB
subtitles	Arquivo de legendas	1 MB	1 MB

A duração mínima de vídeo é a mesma em todas as categorias de vídeo. O X declara "0.5 seconds" e repete isso como piso, não como recomendação.

Dois valores carregam uma instrução além dos seus limites. amplify_video é obrigatório e não opcional para qualquer coisa promovida, e a Ads API diz isso 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 é o botão que liga o processamento assíncrono para GIFs animados grandes, o que o X detalha na página de boas práticas: "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."

Como o media_category muda os tetos de tamanho e duração?

A categoria seleciona qual linha da tabela de limites do X se aplica, e a assinatura da conta seleciona qual coluna. O X nomeia as duas entradas: os limites dependem do "the authenticated user's X Premium / verified status, not your developer API plan" e do "the media_category you pass when initializing the upload."

A distância entre as categorias é grande. Um vídeo que cabe em tweet_video com 20 minutos precisa ter menos de 140 segundos para sair como dm_video na mesma conta, e menos de 10 minutos mesmo com Premium. Mesmo arquivo, mesma conta, mesmo endpoint, e um fator de oito entre os dois tetos.

O total_bytes também é conferido contra a categoria. O X escreve 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." Dois pontos de falha são nomeados e o X não diz qual dos dois pega o problema, então trate INIT e FINALIZE como lugares onde uma recusa por tamanho pode aparecer.

A categoria não muda as regras de imagem. Imagens ficam em 5 MB e GIFs animados em 15 MB, vão eles para um Post ou para uma DM, e o Premium não mexe em nenhum dos dois números. Só duração de vídeo e tamanho de arquivo de vídeo respondem à assinatura, um efeito mais estreito do que o conjunto completo de benefícios do X Premium sugere.

Por que o X publica dois limites diferentes para amplify_video?

Porque a página de criativos da Ads API e a documentação de mídia se contradizem, e as duas estão no ar.

As páginas de mídia tratam amplify_video como igual de tweet_video. A página de boas práticas diz isso sem meias palavras: "For Posts, Premium and default duration/size caps are the same for tweet_video and amplify_video." A tabela dela dá aos dois 20 minutos e 8 GB no padrão, 125 minutos e 16 GB com Premium.

A página de criativos da Ads API, na seção Promoted Video, dá outro par de números em um único item: "The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less." E acrescenta uma restrição de formato que as páginas de mídia também não mencionam: "Uploaded video should be either mp4 or mov."

Dez minutos contra 125. Quinhentos megabytes contra 16 gigabytes. Nenhuma das páginas reconhece a outra, e nenhuma traz data além da nota de 2015 anexada ao item acima. Construa para o par menor se o vídeo vai entrar numa campanha, porque é o pipeline de anúncios que recusaria o arquivo.

Uma segunda divergência aparece uma camada adiante. Os endpoints de upload recebem valores em minúsculas. A biblioteca de mídia da Ads API recebe em maiúsculas: "There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO." Os mesmos quatro conceitos, duas grafias, e a lista da biblioteca de mídia omite por completo as categorias de DM e de legendas.

O que acontece quando você escolhe o media_category errado?

O upload dá certo e a chamada seguinte falha. O X aponta isso como o caso comum: "Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails."

Esse é o formato de quase todo erro de media_category. O INIT aceita o valor, o APPEND move os bytes, o FINALIZE devolve um processing_info limpo, e a recusa chega em POST /2/tweets com um 403, porque upload e publicação são fiscalizados separadamente. Um 403 dizendo "This user is not allowed to post a video longer than N minutes" em um vídeo bem abaixo do limite de Post costuma ser uma categoria dm_video fazendo exatamente o que mandaram.

Três armadilhas menores moram no mesmo parâmetro.

Os dois endpoints de upload não concordam sobre o parâmetro ser opcional. Em POST /2/media/upload/initialize ele é opcional e o enum tem oito valores. No endpoint simples POST /2/media/upload o schema lista media e media_category como obrigatórios, e o enum dele tem sete valores, sem amplify_video. Vídeo promovido, portanto, não passa pelo caminho de upload simples de jeito nenhum, o que combina com o conselho separado do X de usar upload em partes para todo vídeo.

Omitir o valor em um GIF grande abre mão do processamento assíncrono de que GIFs grandes precisam, porque o X amarra esse comportamento ao envio de tweet_gif e não ao arquivo em si.

E subtitles é o valor fora da curva. É o único do enum que não é imagem, GIF nem vídeo, para em 1 MB e tem media_type text/srt e text/vtt. Um arquivo de legendas enviado sem ele herda o padrão de Post e é julgado por regras de imagem que jamais atenderia.

Cada rede resolve isso de um jeito, e o conceito de categoria não viaja. O Instagram divide a mesma decisão entre media_type e a especificação de reels e o TikTok resolve duração pelo padrão da conta, não por um parâmetro de upload. No X, a decisão inteira cabe em uma string opcional que você envia uma vez, no INIT, e nunca mais pode mudar. Se errar, o passo a passo de upload tem que recomeçar do zero.

Onde uma media_category errada realmente falha

1

INIT. Aceita o valor, não importa qual superfície ele indique.

2

APPEND. Move os bytes sem checar o destino.

3

FINALIZE. Retorna um processing_info limpo.

4

POST /2/tweets. Rejeita com um 403 porque upload e publicação são verificados separadamente.

Perguntas frequentes

Quais valores o parâmetro media_category da API do Twitter aceita?

Oito: tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif e subtitles. É esse o enum publicado em POST /2/media/upload/initialize.

O media_category é obrigatório na API do X?

Depende do endpoint. POST /2/media/upload/initialize o trata como opcional e adivinha uma categoria de Post pelo content type. O endpoint simples POST /2/media/upload o lista como obrigatório.

Qual a diferença entre tweet_video e amplify_video?

Finalidade, não tamanho. O X exige amplify_video para qualquer coisa usada em conteúdo promovido e diz que os tetos de duração e tamanho dos dois são iguais em um Post. A página de criativos da Ads API ainda declara um teto menor de vídeo promovido, de 10 minutos e 500 MB.

Quanto tempo pode ter um dm_video na API do X?

140 segundos no padrão e 10 minutos numa conta X Premium ou verificada, com tetos de arquivo de 512 MB e 1 GB. A duração mínima é de 0,5 segundo, igual a todas as outras categorias de vídeo.

Que erro o media_category errado gera?

Em geral um 403 Forbidden em POST /2/tweets, e não um erro na hora do upload. O X observa que uma categoria de DM usada em um Post é motivo comum de o upload dar certo e a criação do Post falhar em seguida.

O media_category afeta os limites de tamanho de imagem?

Não. Imagens ficam em 5 MB e GIFs animados em 15 MB tanto em Posts quanto em DMs, e o X Premium não sobe nenhum dos dois. Só duração de vídeo e tamanho de arquivo de vídeo mudam com a categoria e com a assinatura.

Qual a diferença entre media_type e media_category?

media_type diz ao X em qual formato o arquivo está, por exemplo video/mp4. media_category diz ao X para que serve esse arquivo, um Post, uma mensagem direta, uma faixa de legendas ou um anúncio. O X usa media_category, não media_type, para decidir qual teto de tamanho e duração vale.

Qual é a duração mínima de vídeo aceita pela API do X?

O mínimo é 0,5 segundo, e o X trata isso como um piso, não uma recomendação. Esse mínimo é igual em toda categoria de vídeo, tweet_video, amplify_video, dm_video e as demais, então trocar de categoria não reduz esse número.

Que formato de vídeo a API de Ads do X exige para promoted video?

A página de criativos da Ads API exige mp4 ou mov para vídeo enviado em conteúdo promovido. Ela deixa isso direto: uploaded video should be either mp4 or mov. As páginas de documentação de mídia não repetem essa exigência em nenhum outro lugar.

Dá para subir promoted video pelo endpoint simples de media upload?

Promoted video não passa pelo endpoint simples de upload. O enum dele lista sete valores de media_category e deixa amplify_video de fora, enquanto o POST /2/media/upload/initialize mantém os oito. Isso combina com a recomendação separada do X de usar chunked upload para todo vídeo, independente da categoria.