Agende tweets via API Posts, threads e mídia no X

Publique e agende posts, threads, imagens e vídeo no X (Twitter) por um único endpoint REST. Conecte sua conta do X uma vez: você não precisa de uma conta de desenvolvedor do X nem de um plano próprio da API do X.

Obter uma chave de APIReferência da API

URL base https://api.so-me.studio/v1 · Autenticação X-API-Key · socialMedia: TWITTER

O que você pode publicar em X

Envie um destes valores em postType. Todo post precisa de texto, e fotos ou vídeos são anexados por fileId a partir da sua biblioteca de mídia.

TEXT

Um post só com texto.

IMAGE

Uma imagem.

CAROUSEL

De 2 a 4 imagens em um post.

VIDEO

Um vídeo.

Agende um post em X

Envie a mídia e depois crie o post. Omita scheduledAt para publicar na hora.

  1. Reserve uma URL de upload

    POST /v1/media/presign-upload adiciona o arquivo à sua biblioteca de mídia e devolve um fileId e um uploadUrl pré-assinado.

    Reserve uma URL de upload
    curl -X POST https://api.so-me.studio/v1/media/presign-upload \
  -H "X-API-Key: $SOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"filename":"onboarding.png","mimetype":"image/png","size":412300}]}'

# → [{ "fileId": "…", "uploadUrl": "https://…", "fileSrc": "…", "s3Key": "…" }]

  2. Envie o arquivo

    Faça um PUT dos bytes em uploadUrl com exatamente o Content-Type que você declarou. A URL é válida por uma hora.

    Envie o arquivo
    curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --upload-file ./onboarding.png

  3. Crie o post

    POST /v1/posts com o fileId. A resposta é o post com status SCHEDULED, e ele é publicado em scheduledAt por uma fila que tenta de novo em caso de falha.

    Crie o post
    curl -X POST https://api.so-me.studio/v1/posts \
  -H "X-API-Key: $SOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "socialMedia": "TWITTER",
    "postType": "IMAGE",
    "text": "Reconstruímos nosso onboarding. 3 coisas que aprendemos:",
    "fileIds": ["<fileId>"],
    "threadParts": [
      { "text": "1. Peça uma coisa por tela." },
      { "text": "2. Mostre o resultado antes da configuração." },
      { "text": "3. Meça o abandono por etapa, não por funil." }
    ],
    "scheduledAt": "2026-11-06T13:00:00Z"
  }'

accountId é opcional quando o workspace tem uma conta de X. Caso contrário, passe um id de GET /v1/accounts.

Os arquivos anexados com fileIds são verificados contra os limites de X abaixo antes de qualquer coisa entrar na fila. Um arquivo que viola uma regra retorna 400 com um relatório por arquivo.

Opções de X

Os campos que mudam a forma como um post é publicado em X.

CampoO que faz
threadPartsOs posts seguintes, em ordem, publicados como uma cadeia de respostas abaixo do primeiro. Até 24 partes de 280 caracteres, cada uma com até 4 fileIds.
firstCommentUma resposta publicada abaixo do post, ou abaixo da última parte de uma thread, assim que ele vai ao ar. Até 280 caracteres, e o X conta cada link como 23.
accountIdA conta do X de onde publicar. Opcional quando o workspace tem apenas uma.

Limites de mídia de X

O Social media studio verifica cada arquivo contra estes limites antes de publicar. São os limites que configuramos, não uma promessa de X: GET /v1/media/rules devolve a tabela atual, e POST /v1/media/validate verifica um arquivo sem publicá-lo.

Tipo de post TEXT

Somente texto, sem mídia

Tipo de post IMAGE

Formatos
JPEG, PNG, GIF, WebP, HEIC
Tamanho máximo do arquivo
5 MB
Arquivos por post
1
Dimensões
≤ 8192 px por lado

Tipo de post CAROUSEL

Formatos
JPEG, PNG, GIF
Arquivos por post
2–4
Dimensões
≤ 8192 px por lado

Tipo de post VIDEO

Formatos
MP4, MOV
Tamanho máximo do arquivo
350 MB
Arquivos por post
1
Duração máxima
20 min
Dimensões
≥ 32 × 32 px
Proporção
1:3 a 3:1
Codecs de vídeo
H.264, H.265
Taxa de quadros
≤ 60 fps

Saiba quando está no ar

A publicação é assíncrona. Assine post.published e post.failed, ou consulte GET /v1/posts/:id até que postStatus seja POSTED ou FAILED.

Assine uma vez
curl -X POST https://api.so-me.studio/v1/webhooks/subscriptions \
  -H "X-API-Key: $SOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/social",
    "categories": ["post"],
    "events": ["post.published", "post.failed"]
  }'

# The response includes the secret that signs every delivery.
Como é cada entrega
POST /hooks/social
X-Webhook-Event: post.published
X-Webhook-Signature: <hex HMAC-SHA256 of the raw body>

{
  "event": "post.published",
  "category": "post",
  "timestamp": "2026-11-03T15:00:07.412Z",
  "data": { "postId": "…", "platform": "TWITTER" }
}

Toda entrega é assinada com HMAC-SHA256 em X-Webhook-Signature. post.failed é disparado após a última nova tentativa; corrija a causa e chame POST /v1/posts/:id/retry. Um primeiro comentário é reportado por conta própria, com post.first_comment_posted ou post.first_comment_failed.

Criando um agente de IA?

A mesma chave de API aciona um servidor MCP com mais de 200 ferramentas e uma CLI, para que um agente possa publicar em X sem chamadas HTTP escritas à mão.

Servidor MCP

Adicione o servidor ao Claude, ao Cursor ou a qualquer cliente MCP com a sua chave de API. OAuth também funciona. Para X, o agente chama estas ferramentas com os mesmos campos da requisição REST:

  • presign_media_upload
  • create_post
mcp.json
{
  "mcpServers": {
    "so-me-studio": {
      "url": "https://api.so-me.studio/mcp",
      "headers": { "X-API-Key": "sk_live_…" }
    }
  }
}

CLI

Instale com npm i -g @social-media-scheduler/cli. Ela envia os arquivos locais por você e imprime JSON, então um script ou um job de CI pode agendar um post em X com um único comando.

so-me
so-me posts:create --platform TWITTER --post-type IMAGE \
  -m ./onboarding.png \
  -c "Reconstruímos nosso onboarding. 3 coisas que aprendemos:" \
  --thread "1. Peça uma coisa por tela." \
  --thread "2. Mostre o resultado antes da configuração." \
  -s 2026-11-06T13:00:00Z

O acesso à API, à CLI e ao MCP está incluído em todos os planos pagos: Lite, Creator, Standard, Advanced e Lifetime. Veja os planos e limites

Continue lendo

Guias de outras plataformas

Publique no Instagram via APIAPI de publicação no LinkedInAPI de upload para o TikTokAPI de publicação no FacebookAPI de upload para o YouTubeAPI de publicação no ThreadsAPI do Pinterest para Pins

Sim. Coloque o primeiro post em text e o restante em threadParts. Cada parte pode ter seu próprio texto e seus próprios fileIds. Se uma parte posterior falhar, as partes que já estão no ar continuam lá e o post registra quantas foram publicadas.

Não. Você conecta sua conta do X ao Social media studio uma vez, e a publicação passa pela integração do Social media studio com o X. O seu código envia apenas a sua chave de API do Social media studio.

Não. Você conecta a conta de X uma única vez no painel do Social media studio, pelo login de X. Os tokens ficam armazenados criptografados e são renovados do nosso lado, e o seu código envia apenas a sua chave de API do Social media studio no cabeçalho X-API-Key.

Não. Ele retorna assim que o post entra na fila. A publicação roda em um worker que tenta de novo em caso de falha, então escute post.published e post.failed, ou consulte GET /v1/posts/:id.

A API REST, a CLI e o servidor MCP estão incluídos em todos os planos pagos: Lite, Creator, Standard, Advanced e Lifetime. Lite, Creator, Standard e Advanced começam com um teste de 7 dias (cartão obrigatório), e o Lifetime é um pagamento único.

Agende uma vez.
Publique em todo lugar.

Pare de malabarismo com abas, escreva, adapte e publique em 20 plataformas a partir de um único calendário.

Teste grátis por 7 diasTestar demo ao vivo
Agende tweets via API: posts, threads e mídia no X