API X

Habilidad propensa a cambios. Los puntos finales de la API de X, los niveles de acceso, las cuotas y los permisos de escritura cambian con frecuencia. Comprueba la documentación actual para desarrolladores y el acceso a la cuenta antes de establecer límites de frecuencia o implementar un flujo de publicación o búsqueda.

Interacción programática con X (Twitter) para publicar, leer, buscar y realizar análisis.

Cuándo activarla

• El usuario desea publicar tuits o hilos de forma programada
• Leer la cronología, las menciones o los datos de los usuarios de X
• Buscar en X contenido, tendencias o conversaciones
• Crear integraciones o bots para X
• Análisis y seguimiento de la interacción
• El usuario dice «publicar en X», «tuitear», «API de X» o «API de Twitter»

Autenticación

Token de portador OAuth 2.0 (solo para aplicaciones)

Ideal para: operaciones con gran volumen de lectura, búsquedas y datos públicos.

# Environment setup
export X_BEARER_TOKEN="your-bearer-token"

import os
import requests

bearer = os.environ["X_BEARER_TOKEN"]
headers = {"Authorization": f"Bearer {bearer}"}

# Search recent tweets
resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={"query": "claude code", "max_results": 10}
)
tweets = resp.json()

OAuth 1.0a (contexto de usuario)

Requerido para: publicar tuits, gestionar la cuenta, mensajes directos y cualquier flujo de escritura.

# Environment setup — source before use
export X_CONSUMER_KEY="your-consumer-key"
export X_CONSUMER_SECRET="your-consumer-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"

Alias heredados como X_API_KEY, X_API_SECRET, y X_ACCESS_SECRET pueden existir en configuraciones más antiguas. Es preferible utilizar el X_CONSUMER_* y X_ACCESS_TOKEN_SECRET a la hora de documentar o configurar nuevos flujos.

import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_CONSUMER_KEY"],
    client_secret=os.environ["X_CONSUMER_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_TOKEN_SECRET"],
)

Operaciones básicas

Publicar un tuit

resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Hello from Claude Code"}
)
resp.raise_for_status()
tweet_id = resp.json()["data"]["id"]

Publicar un hilo

def post_thread(oauth, tweets: list[str]) -> list[str]:
    ids = []
    reply_to = None
    for text in tweets:
        payload = {"text": text}
        if reply_to:
            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
        tweet_id = resp.json()["data"]["id"]
        ids.append(tweet_id)
        reply_to = tweet_id
    return ids

Leer la cronología de un usuario

resp = requests.get(
    f"https://api.x.com/2/users/{user_id}/tweets",
    headers=headers,
    params={
        "max_results": 10,
        "tweet.fields": "created_at,public_metrics",
    }
)

Buscar tuits

resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet",
        "max_results": 10,
        "tweet.fields": "public_metrics,created_at",
    }
)

Recopilar publicaciones originales recientes para el modelado de voz

resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet -is:reply",
        "max_results": 25,
        "tweet.fields": "created_at,public_metrics",
    }
)
voice_samples = resp.json()

Obtener usuario por nombre de usuario

resp = requests.get(
    "https://api.x.com/2/users/by/username/affaanmustafa",
    headers=headers,
    params={"user.fields": "public_metrics,description,created_at"}
)

Subir contenido multimedia y publicar

# Media upload uses v1.1 endpoint

# Step 1: Upload media
media_resp = oauth.post(
    "https://upload.twitter.com/1.1/media/upload.json",
    files={"media": open("image.png", "rb")}
)
media_id = media_resp.json()["media_id_string"]

# Step 2: Post with media
resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Check this out", "media": {"media_ids": [media_id]}}
)

Límites de rate

Los límites de frecuencia de la API de X varían según el punto final, el método de autenticación y el nivel de la cuenta, y cambian con el tiempo. Siempre:

• Consulta la documentación actual para desarrolladores de X antes de codificar suposiciones de forma rígida
• Lee x-rate-limit-remaining y x-rate-limit-reset los encabezados en tiempo de ejecución
• Aplique el retroceso automáticamente en lugar de basarse en tablas estáticas en el código

import time

remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
if remaining < 5:
    reset = int(resp.headers.get("x-rate-limit-reset", 0))
    wait = max(0, reset - int(time.time()))
    print(f"Rate limit approaching. Resets in {wait}s")

Gestión de errores

resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
if resp.status_code == 201:
    return resp.json()["data"]["id"]
elif resp.status_code == 429:
    reset = int(resp.headers["x-rate-limit-reset"])
    raise Exception(f"Rate limited. Resets at {reset}")
elif resp.status_code == 403:
    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
else:
    raise Exception(f"X API error {resp.status_code}: {resp.text}")

Seguridad

• Nunca codifiques tokens de forma rígida. Utiliza variables de entorno o .env archivos.
• Nunca incluyas archivos «.env» en el control de versiones. Añádelos a .gitignore.
• Rota los tokens si se han visto expuestos. Regénéralos en developer.x.com.
• Utiliza tokens de solo lectura cuando no se necesite acceso de escritura.
• Almacena los secretos de OAuth de forma segura, no en el código fuente ni en los registros.

Integración con Content Engine

Utiliza brand-voice plus content-engine para generar contenido nativo de la plataforma y, a continuación, publícalo a través de la API X:

1. Recupera publicaciones originales recientes cuando la coincidencia de voz sea importante
2. Crea o reutiliza un VOICE PROFILE
3. Genera contenido con content-engine en formato nativo de X
4. Valida la longitud y la estructura del hilo
5. Devuelve el borrador para su aprobación, a menos que el usuario haya solicitado explícitamente publicarlo ahora
6. Publicar a través de la API de X solo tras la aprobación
7. Realizar un seguimiento de la interacción a través de public_metrics

Habilidades relacionadas

• brand-voice — Crear un perfil de voz reutilizable a partir de contenido real de X y de material del sitio web o de la fuente
• content-engine — Generar contenido nativo de la plataforma para X
• crosspost — Distribuir contenido en X, LinkedIn y otras plataformas
• connections-optimizer — Reorganizar el grafo de X antes de planificar campañas de divulgación impulsadas por la red