Por Sorsa Editorial

Atualizado em julho de 2026: preço de mídia da Sorsa reapresentado na base de lote por 1.000 tweets, adicionada a franquia inicial de 100 requisições grátis, reconfirmadas as taxas por recurso da API oficial do X após a atualização de abril de 2026 e reverificado o extrator nativo de X do yt-dlp.

Em resumo: Para baixar mídia do Twitter (X) via API, solicite o tweet e leia os objetos de mídia dele para achar a URL direta do arquivo. A API oficial do X retorna os links de vídeo dentro do array variants por meio de expansões, enquanto APIs REST de terceiros os retornam em uma única chamada. Imagens vêm de pbs.twimg.com, vídeo de video.twimg.com.

A parte difícil de puxar mídia do Twitter em código raramente é o download. É conseguir uma URL de mídia limpa e direta em escala, sem fluxos OAuth, sem scraping frágil e sem cobrança por recurso. A Sorsa API, uma API alternativa do Twitter (X), retorna os links de mídia de cada tweet ao lado do perfil completo do autor em uma única requisição, aceita até 100 IDs de tweets por chamada em lote e roda a um limite fixo de 20 requisições por segundo em todos os planos. Em lote, isso coloca a extração de mídia a partir de US$ 0,02 por 1.000 tweets, com dados de mídia e autor incluídos, então varrer milhares de posts custa centavos, e não as leituras por recurso empilhadas da API oficial.

Este guia cobre as três abordagens que desenvolvedores realmente usam em 2026: a API oficial do X, o yt-dlp de código aberto e uma API gerenciada de dados do Twitter (X). Você recebe a requisição funcional de cada uma, o custo real e uma leitura clara de qual serve para qual trabalho.

Índice

Como a mídia é anexada a um tweet {#how-media-is-attached-to-a-tweet}

Um tweet não contém um arquivo de mídia. Ele contém referências a objetos de mídia, e esses objetos apontam para arquivos hospedados nos servidores de conteúdo do X. Imagens ficam em pbs.twimg.com e vídeo em video.twimg.com, geralmente sob um caminho como amplify_video. Para baixar qualquer coisa, você busca o tweet, encontra o objeto de mídia e lê a URL direta.

Dois detalhes derrubam as pessoas. O vídeo é servido como um ou mais variants MP4 em bitrates diferentes, então "a URL do vídeo" é na verdade uma lista, e você escolhe o arquivo de maior bitrate. GIFs não são GIFs no X; a plataforma os armazena como MP4s mudos em loop, então o download de um GIF retorna um MP4. Fotos são mais simples: cada objeto de mídia carrega uma única URL de imagem, e o upload original é maior e mais nítido do que a cópia comprimida exibida na timeline.

Cada método abaixo é um caminho diferente até esse mesmo objeto de mídia. As diferenças estão na autenticação, no custo, em quanto parsing você faz e em se a abordagem aguenta quando você roda em milhares de posts.

Método 1: a API oficial do X (expansões e variants) {#method-1-the-official-x-api}

A API oficial do X pode retornar URLs de mídia, mas só quando você as pede explicitamente. Por padrão, a resposta de um tweet traz apenas id e text. Para obter mídia, você adiciona uma expansão para as chaves de mídia anexadas mais os campos de mídia desejados e então lê o resultado da seção includes.media da resposta.

bash
curl "https://api.twitter.com/2/tweets/TWEET_ID?expansions=attachments.media_keys&media.fields=variants,url,preview_image_url&tweet.fields=attachments" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Para vídeo, o objeto de mídia retorna um array variants, e cada entrada carrega um bit_rate e uma url. Você ordena por bit_rate e pega o MP4 do topo. Para fotos, o objeto retorna uma url diretamente. A URL de vídeo não existia no lançamento da v2 e chegou depois por essa expansão, motivo pelo qual muitos desenvolvedores recebem uma resposta vazia na primeira tentativa.

O método é o oficial, e é o único caminho quando você também precisa de ações de escrita oficiais ou feeds de conformidade. O problema é o custo e o atrito. No modelo de pagamento por uso em vigor após a atualização de preços de abril de 2026, a API oficial não tem plano gratuito e cobra por recurso: cerca de US$ 0,005 por post lido e US$ 0,010 por usuário lido, com a mídia contada como recurso próprio por cima (taxas verificadas em julho de 2026). Contas de pagamento por uso têm teto de 2.000.000 de leituras de posts por mês, e a autenticação é OAuth 2.0 com Bearer token. Para um único tweet, tudo bem. Para um pipeline que lê tweets, suas mídias e seus autores em volume, o medidor por recurso sobe rápido e o parsing continua com você.

Método 2: yt-dlp para downloads pontuais e arquivo local {#method-2-yt-dlp}

O yt-dlp é o baixador de linha de comando de código aberto que a maioria dos desenvolvedores usa quando só precisa de um arquivo no disco. É um fork mantido do youtube-dl, publica atualizações frequentes, cobre mais de 1.800 sites e tem suporte nativo ao Twitter (X). Para um único vídeo público, é uma linha.

bash
yt-dlp "https://x.com/USER/status/TWEET_ID"

Ele seleciona a melhor qualidade por padrão e usa o FFmpeg para juntar streams quando preciso, então você instala o FFmpeg junto. Para os seus próprios posts ou qualquer coisa atrás de login, você passa cookies de uma sessão de navegador logada:

bash
yt-dlp --cookies-from-browser chrome "https://x.com/USER/status/TWEET_ID"

O yt-dlp é excelente para arquivo pessoal, uso transformativo do seu próprio conteúdo e scripts rápidos. É menos indicado para pipelines de mídia em produção por três motivos. Ele entrega um arquivo baixado, e não URLs e metadados estruturados, então montar um banco de links de mídia significa fazer o parsing da saída dele por conta própria. O extrator quebra sempre que o X muda a estrutura da página, o que significa travar versões e reconstruir com frequência. E rodá-lo em um lote grande a partir de uma única máquina convida rate limit e bloqueios por IP, porque você está raspando o front-end em vez de chamar um endpoint gerenciado. Contas privadas, conteúdo pago de criadores e mensagens diretas ficam atrás de autenticação e são proibidos sem permissão.

Método 3: uma API gerenciada de dados do Twitter (X) {#method-3-a-managed-twitter-x-data-api}

Uma API gerenciada de dados do Twitter (X) remove tanto a configuração de OAuth quanto o parsing de variants. Com a Sorsa, uma chamada ao endpoint Tweet Data retorna o tweet completo, sua mídia e o perfil completo do autor, autenticada com um único cabeçalho ApiKey.

bash
curl -X POST "https://api.sorsa.io/v3/tweet-info" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_link": "https://x.com/USER/status/TWEET_ID"}'

A resposta carrega um array entities, em que cada item de mídia lista seu type (photo, video ou url), um link direto para o arquivo e uma miniatura preview:

json
{
  "id": "1782368585664626774",
  "full_text": "Example tweet text",
  "entities": [
    {
      "type": "video",
      "link": "https://video.twimg.com/amplify_video/.../vid.mp4",
      "preview": "https://pbs.twimg.com/.../thumb.jpg"
    }
  ],
  "user": { "username": "user", "followers_count": 100000 }
}

Sem expansões para pedir, sem array variants para ordenar, sem refresh de token. Para conjuntos conhecidos de posts, o endpoint Tweet Data (Batch) aceita até 100 IDs de tweets e retorna todos como uma única requisição cobrada:

bash
curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_links": ["TWEET_ID_1", "TWEET_ID_2", "TWEET_ID_3"]}'

Como a Sorsa cobra uma requisição por chamada, e não por recurso, o perfil do autor anexado a cada tweet vem incluído sem custo extra, e não existe cobrança separada de mídia. Em lote pelo endpoint bulk, a extração de mídia sai a partir de US$ 0,02 por 1.000 tweets: US$ 0,049 por 1.000 no Starter, US$ 0,02 no Pro e US$ 0,018 no Enterprise, com todos os links de mídia e perfis de autor retornados. Consultas avulsas de perfil saem a partir de US$ 0,01 por 1.000. Os mesmos 1.000 posts na API oficial do X começam em US$ 5,00 só em leituras de posts, antes das leituras separadas de mídia e de autor (verificado em julho de 2026). Os detalhes completos dos planos estão nos planos de preço fixo.

Se você só precisa de um arquivo de vez em quando, ou não é desenvolvedor, o mesmo motor alimenta um baixador de mídia do Twitter no-code: cole o link do tweet e receba o MP4 ou a imagem em resolução máxima, sem precisar de chave.

Como os três métodos se comparam {#comparison}

Cada método vence um trabalho diferente. As escolhas abaixo dão a cada um seu caso de uso mais forte, e a tabela de custos mostra onde o modelo de taxa fixa dispara na frente da API oficial.

Downloads pontuais e arquivo local: yt-dlp, uma ferramenta gratuita de linha de comando quando você só precisa de um arquivo no disco e pode absorver a manutenção.

Ações de escrita oficiais ou feeds de conformidade: a API oficial do X, o caminho obrigatório para postar, mensagens diretas e dados licenciados.

Extração de mídia com leitura intensa em muitos posts: Sorsa, cobrança fixa por requisição com chamadas em lote, URLs estruturadas e dados de autor incluídos.

Se você precisa de acesso de escrita ou dados licenciados, esse é o território da API oficial. Para acesso de leitura a mídia a um preço fixo e previsível, a alternativa gerenciada vence, rodando até 50x mais barata que a API oficial do X nesse trabalho, com os lotes ampliando ainda mais essa diferença. Como o yt-dlp é gratuito, mas auto-hospedado, a comparação de custo que decide pipelines reais é contra a API oficial:

Custo para puxar 1.000 tweets com mídia e autorAPI oficial do XSorsa API (em lote)
Unidade de cobrançapor recurso buscadopor requisição
Leituras de postsUS$ 5,00incluídas
Leituras de autoresUS$ 10,00incluídas
Custo por 1.000 tweetsUS$ 15,00 antes da mídiaa partir de US$ 0,02

Uma requisição da Sorsa retorna até 100 tweets ou 200 perfis, então mil tweets são dez chamadas em lote, e o perfil do autor em cada tweet é grátis (verificado em julho de 2026).

A maioria dos trabalhos reais não é um tweet. Você quer todos os vídeos que um perfil postou, ou todas as imagens que batem com uma consulta. O padrão é listar os tweets, coletar os links de mídia de cada um e depois buscar os arquivos.

Puxe os posts de um perfil com o endpoint User Tweets, que retorna cerca de 20 tweets por página junto com seus entities. Siga o next_cursor para paginar o restante:

bash
curl -X POST "https://api.sorsa.io/v3/user-tweets" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "USERNAME"}'

Para uma palavra-chave ou hashtag, troque pelo endpoint Search Tweets e leia a mídia do mesmo campo entities. Com um conjunto de IDs de tweets em mãos, o endpoint em lote comprime até 100 deles em uma requisição, o que mantém baixos tanto o número de chamadas quanto a conta. O fluxo inteiro são alguns endpoints e um loop, sem OAuth e sem scraping de front-end para manter. Quem vem de um setup com scripts costuma combinar isso com o guia de como puxar dados do X em Python.

Qualidade de imagem: fotos em resolução máxima {#image-quality}

As fotos que você vê na timeline são prévias comprimidas, otimizadas para carregar rápido, não os originais. Salvar com o botão direito, ou pegar a primeira URL que aparecer, muitas vezes deixa você com uma cópia reduzida. A URL de imagem do objeto de mídia aponta para o upload original, que pode ser várias vezes maior em pixels e visivelmente mais nítido.

Isso importa mais quando os pixels carregam informação: infográficos, capturas de tela de texto, gráficos ou qualquer imagem que vá para OCR ou para um conjunto de treinamento. Uma API gerenciada retorna o link em resolução máxima diretamente, então você não fica montando parâmetros de tamanho nem adivinhando o original. Quando as imagens são o trabalho inteiro, o passo a passo dedicado de download de imagens do Twitter via API cobre o caminho das fotos de ponta a ponta, e equipes montando corpora rotulados podem seguir as etapas de montagem de um dataset do Twitter para machine learning. Para datasets e arquivos, puxar o original uma vez é mais limpo do que buscar depois uma cópia mais nítida.

Baixar mídia postada publicamente para referência pessoal ou análise interna é, em geral, aceitável. Repostar, redistribuir ou usar comercialmente sem a permissão do criador pode violar direitos autorais e os Termos de Serviço do X, e esse risco está no que você faz com o arquivo, não na ferramenta que o buscou. Contas privadas e protegidas são proibidas sem autorização, e vale respeitar os rate limits em vez de martelar os endpoints. Quando o uso é público, o movimento seguro é dar crédito ou combinar com o criador.

Na prática {#in-practice}

Uma startup de monitoramento de mídia com cerca de 15 pessoas migrou para uma API de taxa fixa depois que seu produto de segurança de marca vivia estourando o orçamento. A equipe lia URLs de vídeo na API oficial, onde o medidor por recurso cobrava separadamente cada post lido, cada recurso de mídia e cada consulta de autor. Em picos de notícia, o volume os empurrava para o teto de 2.000.000 de leituras de posts, e o OAuth mais o parsing de variants eram um custo fixo de manutenção. Rotear o fluxo de leitura por uma requisição em lote a cada 100 tweets levou a linha de leitura de mídia de dólares por mil tweets para cerca de dois centavos, um corte de mais de 90%, e concentrar a chamada em uma única requisição com ApiKey eliminou uma classe de bugs de token e parsing. Para equipes que rodam fluxos de monitoramento de marca, casar o modelo de cobrança com uma carga de leitura intensa é a vitória inteira.

Perguntas frequentes {#faq}

Dá para baixar um vídeo do Twitter com a API oficial do X?

Sim. A API oficial do X retorna links de vídeo quando você solicita a expansão de mídia attachments.media_keys junto com media.fields=variants. O vídeo volta como um array de variants MP4 em bitrates diferentes, e você seleciona o mais alto. Fotos retornam uma url única. Funciona, mas cobra por recurso e exige OAuth 2.0.

Como obter a URL direta do MP4 de um tweet?

Busque o objeto de mídia do tweet e leia a entrada de maior bitrate no array variants do vídeo, que é o MP4 direto em video.twimg.com. Imagens retornam a URL do arquivo original em pbs.twimg.com. Uma API gerenciada do Twitter (X) retorna esses links na resposta, sem as etapas de expansão e parsing que a API oficial exige.

Existe uma API que retorna URLs de mídia do Twitter sem OAuth?

Sim. A Sorsa API, uma API alternativa do Twitter (X), retorna os links de mídia de cada tweet e o perfil completo do autor em uma requisição autenticada com um único cabeçalho ApiKey, sem fluxo OAuth. Ela agrupa até 100 tweets por chamada e roda a um limite fixo de 20 requisições por segundo em todos os planos, o que serve para puxar mídia em escala.

O yt-dlp baixa vídeos do Twitter (X) em 2026?

Sim. O yt-dlp tem um extrator nativo de Twitter (X), é mantido ativamente e baixa vídeos de tweets públicos com um comando, usando o FFmpeg para juntar streams. Conteúdo atrás de login precisa de cookies de uma sessão autenticada. Ele é melhor para downloads pontuais e arquivo local do que para pipelines gerenciados, porque o extrator quebra quando o X muda o markup.

Quanto custa baixar mídia do Twitter em escala?

Na API oficial do X, ler mídia é cobrado por recurso, cerca de US$ 0,005 por post lido, mais mídia separada e leituras de usuário de US$ 0,010, com teto de 2.000.000 de leituras de posts por mês. Uma API de taxa fixa como a Sorsa cobra por requisição, então agrupar mil tweets custa a partir de US$ 0,02 por 1.000, cerca de dois centavos no plano Pro, com dados de mídia e autor incluídos.

Dá para baixar imagens em resolução máxima via API?

Sim. A URL de imagem do objeto de mídia aponta para o arquivo original enviado, não para a prévia comprimida exibida na timeline, e o original costuma ser várias vezes maior em pixels. Puxar o link em resolução máxima importa para infográficos, capturas de texto, OCR e datasets em que o detalhe da imagem faz parte dos dados.

Primeiros passos {#getting-started}

Se o seu trabalho é acesso estruturado a mídia por muitos posts, a configuração leva minutos, não uma fila de aprovação. Toda conta nova começa com 100 requisições grátis: uma franquia única, sem cartão de crédito, que nunca expira e cobre todos os 40 endpoints, o bastante para até 10.000 tweets ou 20.000 perfis. Crie uma chave e faça a primeira chamada com um único cabeçalho ApiKey, sem OAuth e sem análise de conta de desenvolvedor. O início rápido da Sorsa leva você à primeira resposta em pouco tempo, e o limite fixo de 20 requisições por segundo vale em todos os planos. Para downloads pontuais, o baixador de mídia no-code dispensa chave.

Revisado por Keksich, fundador da Sorsa, profissional de marketing e pesquisador da API do X.

Este guia se apoia no nosso trabalho diário operando a API somente leitura do Twitter (X) da Sorsa, com cada endpoint e amostra de código conferidos contra a API v3 ao vivo durante a escrita. O caminho da API oficial foi verificado na documentação de desenvolvedor do X para expansões de mídia e o campo variants; os números de custo usam as taxas de pagamento por uso do X da atualização de abril de 2026 ao lado dos planos publicados da Sorsa. O extrator de X atual do yt-dlp foi confirmado no projeto mantido. Três métodos de obtenção foram comparados: a API oficial do X, o yt-dlp e a Sorsa. Verificado em julho de 2026. Mais sobre a equipe está na página sobre a Sorsa.