---

name: X-Publisher description: Publish tweets to X (Twitter) using the official Tweepy library. Supports text-only tweets, tweets with images or videos, and returns detailed publish results including tweet ID and URL. Requires X API credentials (API Key, API Secret, Access Token, Access Token Secret). env:

• X_API_KEY
• X_API_SECRET
• X_ACCESS_TOKEN
• X_ACCESS_TOKEN_SECRET
• X_BEARER_TOKEN

---

X (Twitter) 推文发布工具

使用官方 Tweepy 库发布推文，支持纯文本、图片、视频等多种媒体类型。

功能特性

• 📝 纯文本推文 - 快速发布文字内容
• 🖼️ 图片支持 - 支持 JPG、PNG、GIF、WebP 格式（最多4张）
• 🎬 视频支持 - 支持 MP4、MOV、AVI、WebM 格式
• 📊 返回结果 - 返回推文 ID、链接、发布时间等详细信息
• ✅ 认证验证 - 支持验证 API 凭证是否有效

前提条件

1. 安装依赖

pip3 install tweepy --user

2. 获取 X API 凭证

1. 访问 https://developer.twitter.com/en/portal/dashboard
2. 创建项目并生成 API 密钥
3. 获取以下凭证：
   • API Key
   • API Secret
   • Access Token
   • Access Token Secret

3. 配置环境变量

# 添加到 ~/.zshrc
export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"
export X_BEARER_TOKEN="your-bearer-token"  # 可选

然后执行：

source ~/.zshrc

使用方法

验证认证信息

首次使用前，建议先验证凭证：

python3 scripts/x_publisher.py verify

输出示例：

✅ 认证成功!
👤 用户名: @your_username
📛 显示名: Your Name
👥 粉丝: 1,234
📝 推文: 5,678

发布纯文本推文

python3 scripts/x_publisher.py tweet "Hello, X! This is my first tweet."

发布带图片的推文

# 单张图片
python3 scripts/x_publisher.py tweet "Check out this photo!" --media /path/to/image.jpg

# 多张图片（最多4张）
python3 scripts/x_publisher.py tweet "My photo collection:" \
  --media /path/to/photo1.jpg \
  --media /path/to/photo2.png \
  --media /path/to/photo3.gif

发布带视频的推文

python3 scripts/x_publisher.py tweet "Watch this video!" --media /path/to/video.mp4

输出结果

发布成功后会返回：

============================================================
✅ 推文发布成功!
============================================================
📝 推文 ID: 1234567890123456789
🔗 链接: https://twitter.com/user/status/1234567890123456789
⏰ 发布时间: 2024-02-03T15:30:45.123456
📄 内容预览: Hello, X! This is my first tweet.
============================================================

📋 JSON 输出:
{
  "success": true,
  "tweet_id": "1234567890123456789",
  "text": "Hello, X! This is my first tweet.",
  "created_at": "2024-02-03T15:30:45.123456",
  "url": "https://twitter.com/user/status/1234567890123456789"
}

命令参考

命令	功能	示例
verify	验证认证	x_publisher.py verify
tweet	发布推文	x_publisher.py tweet "Hello" --media photo.jpg

tweet 命令参数

参数	简写	说明	必填
text	-	推文内容	是
--media	-m	媒体文件路径	否

支持的媒体格式

图片

• JPG/JPEG - 推荐格式
• PNG - 支持透明背景
• GIF - 支持动画
• WebP - 现代格式

限制：

• 最多 4 张图片
• 单张图片最大 5MB

视频

• MP4 - 推荐格式
• MOV - QuickTime 格式
• AVI - 常见格式
• WebM - 现代格式

限制：

• 单个视频最大 512MB
• 最长 2 分 20 秒

错误处理

认证失败

❌ 认证失败: 无法获取用户信息

解决方法：

• 检查 API 密钥和令牌是否正确
• 确认令牌未过期
• 检查网络连接

权限不足

❌ 推文发布失败
错误类型: 权限不足
错误信息: You are not allowed to create a Tweet with these settings

解决方法：

• 确认应用有 "Write" 权限
• 检查是否违反 X 平台规则

请求过于频繁

❌ 推文发布失败
错误类型: 请求过于频繁
错误信息: Rate limit exceeded

解决方法：

• 等待几分钟后重试
• X API 有速率限制（每15分钟300条推文）

媒体上传失败

❌ 媒体文件不存在: /path/to/image.jpg

解决方法：

• 检查文件路径是否正确
• 确认文件格式支持
• 检查文件大小是否超限

使用场景

场景1：自动化发布

# 发布每日摘要
python3 scripts/x_publisher.py tweet "📊 今日市场摘要：BTC $43,250 (+2.3%)" 

场景2：带图发布

# 发布截图或图表
python3 scripts/x_publisher.py tweet "📈 今日走势图" --media ~/charts/btc_today.png

场景3：批量发布脚本

#!/bin/bash
# publish_news.sh

CONTENT="🚀 重大新闻：..."
IMAGE="/path/to/news_image.jpg"

python3 scripts/x_publisher.py tweet "$CONTENT" --media "$IMAGE"

场景4：集成到其他工具

import subprocess
import json

result = subprocess.run(
    ['python3', 'scripts/x_publisher.py', 'tweet', 'Hello!', '--media', 'photo.jpg'],
    capture_output=True,
    text=True
)

# 解析 JSON 输出
output_lines = result.stdout.split('\n')
for line in output_lines:
    if line.strip().startswith('{'):
        tweet_info = json.loads(line)
        print(f"Tweet ID: {tweet_info['tweet_id']}")
        print(f"URL: {tweet_info['url']}")

API 限制

限制类型	数值	说明
推文长度	280 字符	超过将自动截断
媒体数量	4 个	图片或视频混合
图片大小	5 MB	单张图片
视频大小	512 MB	单个视频
视频时长	2分20秒	最大时长
发布频率	300条/15分钟	速率限制

注意事项

1. 凭证安全 - 不要泄露 API 密钥，使用环境变量存储
2. 内容合规 - 遵守 X 平台规则，避免发布违规内容
3. 频率控制 - 注意 API 速率限制，避免频繁发布
4. 媒体版权 - 确保上传的媒体文件有版权或使用授权

参考

• Tweepy 文档: https://docs.tweepy.org/
• X API 文档: https://developer.twitter.com/en/docs/twitter-api
• X Developer Portal: https://developer.twitter.com/en/portal/dashboard