X API

Навык, требующий постоянного мониторинга. Конечные точки X API, уровни доступа, квоты и права на запись часто меняются. Проверяйте актуальную документацию для разработчиков и права доступа к учетной записи прежде чем указывать ограничения по скорости или реализовывать процесс публикации/поиска.

Программное взаимодействие с X (Twitter) для публикации, чтения, поиска и аналитики.

Когда следует активировать

• Пользователь хочет программно публиковать твиты или нити
• Чтение ленты, упоминаний или данных пользователей из X
• Поиск в X контента, трендов или обсуждений
• Создание интеграций с X или ботов
• Аналитика и отслеживание вовлеченности
• Пользователь говорит «опубликовать в X», «твит», «API X» или «API Twitter»

Аутентификация

Токен Bearer по OAuth 2.0 (только для приложений)

Идеально подходит для: операций с большим объемом чтения, поиска, открытых данных.

# 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 (контекст пользователя)

Требуется для: публикации твитов, управления аккаунтом, личных сообщений и любых операций записи.

# 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"

Устаревшие псевдонимы, такие как X_API_KEY, X_API_SECRET, и X_ACCESS_SECRET могут присутствовать в устаревших конфигурациях. Предпочтительно использовать X_CONSUMER_* и X_ACCESS_TOKEN_SECRET при документировании или настройке новых потоков.

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"],
)

Основные операции

Опубликовать твит

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"]

Опубликовать ветку

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

Просмотр ленты пользователя

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",
    }
)

Поиск твитов

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",
    }
)

Извлечение последних оригинальных постов для моделирования голоса

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()

Получить пользователя по имени пользователя

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

Загрузить медиафайлы и опубликовать

# 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]}}
)

Ограничения по частоте запросов

Ограничения скорости X API варьируются в зависимости от конечной точки, метода аутентификации и уровня учетной записи, а также меняются со временем. Всегда:

• проверяйте актуальную документацию для разработчиков X, прежде чем жестко прописывать какие-либо допущения
• Читайте x-rate-limit-remaining и x-rate-limit-reset заголовки во время выполнения
• автоматически уменьшайте частоту запросов, вместо того чтобы полагаться на статические таблицы в коде

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")

Обработка ошибок

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}")

Безопасность

• Никогда не прописывайте токены в коде. Используйте переменные среды или .env файлы.
• Никогда не фиксируйте файлы с токенами (.env) в репозитории. Добавляйте в .gitignore.
• Регулярно обновляйте токены в случае их утечки. Сгенерируйте новые на developer.x.com.
• Используйте токены только для чтения, если доступ на запись не требуется.
• Храните секретные данные OAuth надежно — не в исходном коде и не в журналах.

Интеграция с Content Engine

Используйте brand-voice plus content-engine для генерации контента, адаптированного под платформу, а затем публикуйте его через X API:

1. Извлекайте последние оригинальные публикации, когда важно сопоставление голоса
2. Создайте или используйте уже готовый VOICE PROFILE
3. Генерируйте контент с помощью content-engine в формате, собственном для X
4. Проверьте длину и структуру ветки
5. Возвращайте черновик на утверждение, если пользователь явно не попросил опубликовать сообщение сейчас
6. Опубликовать через API X только после утверждения
7. Отслеживайте вовлеченность с помощью public_metrics

Связанные навыки

• brand-voice — Создание многоразового голосового профиля на основе реальных данных из X и материалов сайта/источника
• content-engine — Создание контента, адаптированного под платформу X
• crosspost — Распространять контент в X, LinkedIn и на других платформах
• connections-optimizer — Реорганизовать граф X перед разработкой стратегии взаимодействия, ориентированной на сеть