Pular para o conteúdo principal
Este guia ajudará você a fazer suas primeiras solicitações para enviar mídia usando os endpoints de upload de mídia da X API v2. Neste guia, os endpoints segmentados POST /2/media/upload são usados para enviar um vídeo, o que exige um fluxo de trabalho diferente do de uploads de imagem única. Para vídeos ou uploads segmentados, você deve:
  1. Inicializar o upload usando o comando INIT
  2. Enviar cada segmento de bytes usando o comando APPEND
  3. Concluir o upload usando o comando FINALIZE
Observação: Consulte este exemplo de código escrito em Python.

​
Autenticação

Para executar os exemplos fornecidos neste guia, você precisará usar a autenticação OAuth 2. Você pode encontrar CONSUMER_KEY, CONSUMER_SECRET, ACCESS_KEY e ACCESS_TOKEN na sua App dentro do seu Projeto no dashboard do portal do desenvolvedor.

​
Etapa 1: POST media/upload (INIT)

A solicitação do comando INIT é usada para iniciar uma sessão de upload de arquivo. Ela retorna um media_id, que deve ser usado para executar todas as solicitações subsequentes. A próxima etapa após um retorno bem-sucedido do comando INIT é o comando APPEND. Consulte as Boas práticas para conhecer as restrições e os requisitos de arquivos de mídia. Exemplo de solicitação 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <SEU_TOKEN_DE_ACESSO>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=INIT' \
    --form 'media_type=video/mp4' \
    --form 'total_bytes=1024' \
    --form 'media_category=amplify_video'
Observação: Ao fazer solicitações HTTP diretas, a requisição deve usar o método POST nos formatos multipart/form-data ou application/x-www-form-urlencoded.
Exemplo de resposta 
{
    "data":
    {
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "expires_after_secs":1295999
    }
}
A resposta fornece os identificadores de mídia id (string) e media_key (string). O arquivo completo deve ser carregado antes de expires_after_secs segundos.

​
Etapa 2 : POST media/upload (APPEND)

O comando APPEND é usado para enviar um bloco (intervalo consecutivo de bytes) do arquivo de mídia. Por exemplo, um arquivo de 3 MB pode ser dividido em 3 blocos de 1 MB e enviado usando 3 solicitações do comando APPEND. Após o envio do arquivo inteiro, a próxima etapa é chamar o comando FINALIZE.
Há várias vantagens em enviar um arquivo de mídia em pequenos blocos:
  • Maior confiabilidade e taxa de sucesso em condições de rede com baixa largura de banda
  • Os uploads podem ser pausados e retomados
  • Blocos do arquivo podem ser reenviados individualmente
  • Capacidade de ajustar o tamanho dos blocos para acompanhar mudanças nas condições da rede, por exemplo, em clientes móveis
Exemplo de requisição 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=APPEND' \
    --form 'media_id=1880028106020515840' \
    --form 'segment_index=0' \
    --form 'media=@/caminho/para/seu/arquivo/de/midia/arquivo.mp4'
segment_index é um índice ordenado do chunk do arquivo. Ele deve estar entre 0 e 999, inclusive. O primeiro segmento tem índice 0, o segundo tem índice 1 e assim por diante. Continue enviando os chunks do arquivo até que todos sejam enviados.
Observação: Ao fazer solicitações HTTP brutas, a requisição deve estar no formato POST multipart/form-data.
Observação: Um código HTTP 2XX será retornado com um corpo de resposta vazio em caso de upload bem-sucedido.

​
Etapa 3: POST media/upload (FINALIZE)

O comando FINALIZE deve ser chamado após o envio de todo o arquivo de mídia usando comandos APPEND. Se, e somente se, a resposta do comando FINALIZE contiver um campo processing_info, também pode ser necessário usar um comando STATUS e aguardar que ele retorne sucesso antes de prosseguir para a criação do Post. Exemplo de requisição 
curl --location --request POST 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <SEU_TOKEN_DE_ACESSO>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=FINALIZE' \
    --form 'media_id=1880028106020515840'
Nota: Ao fazer solicitações HTTP brutas, a requisição deve usar o método POST nos formatos multipart/form-data ou application/x-www-form-urlencoded.
Exemplo de resposta 
{
    "data": {
        "id": "1880028106020515840",
        "media_key": "13_1880028106020515840",
        "size": 1024,
        "expires_after_secs": 86400,
        "processing_info": {
            "state": "pending",
            "check_after_secs": 1
        }
    }
}
A resposta fornece um identificador de mídia nos campos media_id (inteiro de 64 bits) e media_id_string (string). Use o media_id_string retornado na resposta da API em JavaScript e em outras linguagens que não conseguem representar com precisão um inteiro longo. O media_id retornado é válido apenas por expires_after_secs segundos. Qualquer tentativa de usar o mediaId após esse período em outras chamadas à API resultará em uma resposta Bad Request (HTTP 4xx). Se a resposta contiver o campo processing_info, use o comando STATUS para verificar o status da operação FINALIZE. A finalização assíncrona é usada quando o processamento de mídia exige mais tempo. No futuro, todo o processamento de vídeos e GIFs animados será compatível apenas por meio de finalização assíncrona. Esse comportamento é ativado se uma sessão de upload tiver sido inicializada com o parâmetro media_category e quando o tipo de mídia for vídeo ou GIF animado.
Observação: Se o campo processing_info NÃO for retornado na resposta, então media_id está pronto para uso em outros endpoints da API.

​
Etapa 4 : GET media/upload (STATUS)

O comando STATUS é usado para consultar periodicamente as atualizações da operação de processamento de mídia. Depois que a resposta do comando STATUS retornar succeeded, você pode avançar para a próxima etapa, que geralmente é criar um Post com media_id.
Observação: O comando STATUS deve ser usado se e somente se a resposta do comando FINALIZE ou de um comando STATUS anterior contiver o campo processing_info.

​
Exemplo de requisição

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

​
Exemplo de resposta

{
    "data":{
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "processing_info":{
            "state":"uploading" // fluxo de transição de estado é pending -> in_progress -> [failed|succeeded]
        }
    }
}
O corpo da resposta contém o campo processing_info, que fornece informações sobre o estado atual da operação de processamento de mídia. Esse campo inclui state, que segue o fluxo de transição: pending -> in_progress -> [failed | succeeded]. Você não pode usar o media_id para criar um Post ou outras entidades antes de o campo state estar definido como succeeded.

​
Etapa 5 : Publicar Tweet com mídia

Cria um Post usando o endpoint POST /2/tweets, incluindo o media_id em nome de um usuário autenticado. Exemplo de requisição 
curl --location 'https://api.x.com/2/tweets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
--data '{
    "text": "Criei um Post com mídia!",
     "media": {
       "media_ids": [
            "1880028106020515840"
        ]
    }
}'
Exemplo de resposta 
{
    "data": {
        "edit_history_tweet_ids": [
            "1880028106020515840"
        ],
        "id": "1880028106020515840",
        "text": "Eu fiz um post com mídia! https://t.co/DqNyXX"
    }
}

​
Solução de problemas

Para problemas com as APIs de mídia, consulte a categoria Media API nos fóruns de desenvolvedores em busca de uma resposta.
⌘I