OpenTweet X 发布器

您可以使用 OpenTweet REST API 向 X（原 Twitter）发布内容。所有请求均发送至 https://opentweet.io，并需提供用户的 API 密钥。

认证

每个请求都需要以下头部信息：

Authorization: Bearer $OPENTWEET_API_KEY
Content-Type: application/json

上传文件时，请使用 Content-Type: multipart/form-data。

开始前准备

请始终先验证连接状态：

GET https://opentweet.io/api/v1/me

该接口返回订阅状态、每日发布限额、已发布数量以及已绑定的 X 账号信息。在安排或发布前，请确认 subscription.has_access 为 true，且 limits.remaining_posts_today 大于 0。

多账号支持

• Pro 用户：支持 1 个 X 账号
• Advanced 用户：支持 3 个 X 账号
• Agency 用户：支持 10 个 X 账号

通过 x_account_id 参数可指定具体目标账号。

查看已绑定的账号列表

GET https://opentweet.io/api/v1/accounts

返回结果示例：

{
  "accounts": [
    {
      "id": "...",
      "x_handle": "@handle",
      "x_name": "显示名称",
      "is_primary": true,
      "nickname": null
    }
  ]
}

使用 x_account_id 指定账号

将 x_account_id 添加到任意 POST/PUT 请求体或 GET 查询参数中，以指定目标账号：

• 创建帖子：{ "text": "...", "x_account_id": "account_id_here" }
• 列出帖子：GET /api/v1/posts?x_account_id=account_id_here
• 批量排期：{ "schedules": [...], "x_account_id": "account_id_here" }
• 数据分析：GET /api/v1/analytics/overview?x_account_id=account_id_here
• 永续发布：GET /api/v1/evergreen/posts?x_account_id=account_id_here
• 最佳发布时间分析：POST /api/v1/analytics/best-times/analyze 请求体 { "x_account_id": "..." }

若未指定 x_account_id，则默认使用主账号。单账号用户无需手动设置。

帖子管理

创建一条推文

POST https://opentweet.io/api/v1/posts
Body: { "text": "您的推文内容" }

可选地添加 "scheduled_date": "2026-05-01T10:00:00Z" 来设定发布时间（需有效订阅，日期必须为未来时间）。

创建并立即发布（一步完成）

POST https://opentweet.io/api/v1/posts
Body: { "text": "Hello from the API!", "publish_now": true }

此操作会在一次请求中完成创建与发布。不能与 scheduled_date 或批量发布同时使用。成功响应包含 status: "posted"、x_post_id 和 url（真实 X 推文链接）。

创建带媒体的推文

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "查看这张截图！",
  "media_urls": ["https://从上传接口获取的URL"]
}

需先通过 POST /api/v1/upload 上传媒体，再将返回的 URL 填入 media_urls。

创建一条推文线程

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "线程的第一条推文",
  "is_thread": true,
  "thread_tweets": ["第二条推文", "第三条推文"]
}

创建带每条推文独立媒体的线程

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "带图片的线程引言",
  "is_thread": true,
  "thread_tweets": ["第二条推文", "第三条推文"],
  "media_urls": ["https://引言图片URL"],
  "thread_media": [["https://第二条推文图片URL"], []]
}

thread_media 是一个数组，每个子数组对应 thread_tweets 中相应推文的媒体 URL 列表。无媒体的推文使用空数组 []。

发布到 X 社区

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "与社区分享的内容！",
  "community_id": "1234567890",
  "share_with_followers": true
}

自动转发（自动重推）

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "这条推文会获得助推。",
  "scheduled_date": "2026-05-01T10:00:00Z",
  "auto_retweet_enabled": true,
  "auto_retweet_offset_minutes": 240
}

推文发布后，OpenTweet 将在指定分钟数后自动从同一账号进行转发。该功能也适用于 PUT 请求。范围：1–10080 分钟（最多 7 天）。两个字段也可通过 PUT /api/v1/posts/{id} 设置。

自动引流（病毒式传播时自动回复）

POST https://opentweet.io/api/v1/posts
Body: {
  "text": "关于 AI 代理的热门观点。",
  "scheduled_date": "2026-05-01T10:00:00Z",
  "auto_plug_enabled": true,
  "auto_plug_threshold": 50,
  "auto_plug_text": "喜欢这个内容？我每周都会分享更多 → link.com/newsletter"
}

推文发布后，OpenTweet 每 5 分钟检查一次点赞数。当 like_count >= auto_plug_threshold 时，将自动以 auto_plug_text 作为回复发布到原始推文下，实现流量转化。

• auto_plug_threshold：触发条件的点赞数（默认值：20，无上限）
• auto_plug_text：回复内容，最大 280 字符（启用时必填）
• 每条推文仅触发一次；发送后设置 auto_plug_done: true 与 auto_plug_tweet_id
• 仅检查过去 30 天内发布的推文
• 也支持 PUT /api/v1/posts/{id}（可在发布前或发布后设置）

批量创建（最多 50 条）

POST https://opentweet.io/api/v1/posts
Body: {
  "posts": [
    { "text": "推文 1", "scheduled_date": "2026-05-01T10:00:00Z" },
    { "text": "推文 2", "scheduled_date": "2026-05-01T14:00:00Z" }
  ]
}

排期某条推文

POST https://opentweet.io/api/v1/posts/{id}/schedule
Body: { "scheduled_date": "2026-05-01T10:00:00Z" }

日期必须为未来时间，使用 ISO 8601 格式。

立即发布

POST https://opentweet.io/api/v1/posts/{id}/publish

无需请求体。立即发布至 X。响应包含 status: "posted"、x_post_id 和 url（真实 X 推文链接）。

批量排期（最多 50 条）

POST https://opentweet.io/api/v1/posts/batch-schedule
Body: {
  "schedules": [
    { "post_id": "id1", "scheduled_date": "2026-05-02T09:00:00Z" },
    { "post_id": "id2", "scheduled_date": "2026-05-03T14:00:00Z" }
  ],
  "community_id": "可选的社区ID",
  "share_with_followers": true,
  "x_account_id": "可选的账号ID"
}

获取帖子列表

GET https://opentweet.io/api/v1/posts?status=scheduled&page=1&limit=20

状态选项：scheduled（已排程）、posted（已发布）、draft（草稿）、failed（失败）、evergreen（返回永续池中的源帖）。

获取单个帖子

GET https://opentweet.io/api/v1/posts/{id}

更新帖子

PUT https://opentweet.io/api/v1/posts/{id}
Body: {
  "text": "更新后的文本",
  "media_urls": ["https://..."],
  "scheduled_date": "2026-05-01T10:00:00Z",
  "auto_retweet_enabled": true,
  "auto_retweet_offset_minutes": 120
}

所有字段均为可选。无法更新已发布的帖子。将 scheduled_date 设置为 null 可取消排程（恢复为草稿）。

删除帖子

DELETE https://opentweet.io/api/v1/posts/{id}

默认行为：如果帖子已发布，OpenTweet 会同时从 X 平台删除。若仅需本地删除而保留 X 上的帖子，请在 URL 后添加 ?delete_from_x=false。响应中包含 x_deleted 字段，若删除失败则附带 x_delete_error。

媒体上传

上传图片或视频

POST https://opentweet.io/api/v1/upload
Content-Type: multipart/form-data
Body: file=@your-image.png

返回结果：{ "url": "https://..." }

支持格式：JPG、PNG、GIF、WebP（最大 5MB），MP4、MOV（最大 20MB）。

操作流程：先上传媒体，再将返回的 URL 用于创建或更新帖子时的 media_urls 或 thread_media 字段。

AI 媒体生成

通过 Grok Imagine（xAI）直接根据提示词生成图像和视频。生成的文件将永久存储，其 URL 可用于创建推文时的 media_urls。需要在服务器上配置 XAI_API_KEY 才可使用。

生成图像

POST https://opentweet.io/api/v1/generate/image
Body: {
  "prompt": "一个充满活力的产品发布宣传图",
  "aspect_ratio": "16:9",
  "resolution": "1k"
}

• prompt — 必填，最长 1000 字符
• aspect_ratio — 可选："1:1"（默认）、"16:9"、"9:16"、"4:3"、"3:4"
• resolution — 可选："1k"（默认）或 "2k"

返回结果：{ "url": "https://...", "prompt": "...", "aspect_ratio": "16:9", "resolution": "1k" }

响应为同步，URL 可立即使用。

生成视频

POST https://opentweet.io/api/v1/generate/video
Body: {
  "prompt": "产品在底座上旋转，搭配戏剧性灯光",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}

• prompt — 必填，最长 1000 字符
• aspect_ratio — 可选："16:9"（默认）、"9:16"、"1:1"、"4:3"、"3:4"
• resolution — 可选："480p"（默认）或 "720p"
• duration — 可选：5（默认）至 10 秒

返回（状态码 202）：{ "job_id": "...", "status": "processing", "message": "..." }

视频生成为异步操作，需轮询状态接口直至完成。

查询视频生成状态

GET https://opentweet.io/api/v1/generate/video/{job_id}

返回结果之一：

• { "job_id": "...", "status": "processing" } — 正在生成，建议 10 秒后再次轮询
• { "job_id": "...", "status": "completed", "url": "https://..." } — 已完成，可使用该 URL
• { "job_id": "...", "status": "failed", "error": "..." } — 生成失败

典型生成时间：1–3 分钟。建议每 10 秒轮询一次。

永续队列（Evergreen Queue）

永续队列用于维护一批具有长期价值的推文，并按设定时间周期性重新发布，同时设置冷却间隔以避免重复发布同一内容。源帖作为模板保留，调度器会在指定时间克隆为普通帖子。需付费订阅（试用版不可用）。

• Pro 计划：最多 10 个源帖 / 每日发布 2 条
• Advanced 计划：最多 999 个源帖 / 每日发布 10 条

获取队列设置与池统计信息

GET https://opentweet.io/api/v1/evergreen/settings

返回：enabled（是否启用）、posts_per_day（每日发布数量）、posting_times（如 ["09:00","17:00"]）、default_cooldown_days（默认冷却天数），以及池中数量和当前计划限制。

更新队列设置

PUT https://opentweet.io/api/v1/evergreen/settings
Body: {
  "enabled": true,
  "posts_per_day": 2,
  "posting_times": ["09:00", "17:00"],
  "default_cooldown_days": 14
}

所有字段均可选。posting_times 必须为 "HH:mm" 格式字符串。default_cooldown_days 范围为 1–90 天。posts_per_day 不得超过计划允许的每日上限。

列出永续池中的帖子

GET https://opentweet.io/api/v1/evergreen/posts?page=1&limit=20&paused=false

可通过 paused=true 或 paused=false 进行过滤。每个条目包含：cooldown_days（冷却天数）、last_posted_at（上次发布时间）、times_posted（已发布次数）、paused（是否暂停）。

向永续池中添加内容

模式 1：将现有帖子转换为永续池条目

POST https://opentweet.io/api/v1/evergreen/posts
Body: { "post_id": "507f1f77bcf86cd799439011", "cooldown_days": 14 }

模式 2：直接创建新的永续池帖子

POST https://opentweet.io/api/v1/evergreen/posts
Body: {
  "text": "一条永不过时的推文内容",
  "category": "技巧",
  "cooldown_days": 21,
  "is_thread": false,
  "media_urls": ["https://..."]
}

获取、更新或移除永续池中的帖子

GET    https://opentweet.io/api/v1/evergreen/posts/{id}
PUT    https://opentweet.io/api/v1/evergreen/posts/{id}    # body: { "cooldown_days": 30, "paused": true }
DELETE https://opentweet.io/api/v1/evergreen/posts/{id}    # 转换回草稿（不会彻底删除）

GET 请求还返回 recent_posts 字段，包含最近 5 次发布的克隆副本及其对应的 X 推文链接。

永续发布历史记录

GET https://opentweet.io/api/v1/evergreen/history?page=1&limit=20&source_id=optional

列出已发布的克隆副本。可通过 source_id 筛选，查看某一条永续帖的历史发布记录。

灵感获取（搜索与重用）

在 X 平台上搜索推文，并由 AI 以用户风格进行改写。两个接口均需有效订阅。搜索功能有每日限额（Pro：50 条/天，Advanced：200 条/天，试用版：2 条/天）。重用功能计入 AI 生成每日配额。

搜索灵感推文

GET https://opentweet.io/api/v1/inspiration/search?q=AI%20agents&max_results=20&sort_order=relevancy&lang=en&has_media=true&min_likes=100&min_retweets=10

必需参数：q。可选过滤条件：max_results、sort_order（可选值：relevancy 或 recency）、lang、has_media、min_likes、min_retweets。响应包含 data（推文列表）、meta.result_count 和 usage（已使用次数 / 剩余次数 / 每日上限）。

使用 AI 重制推文

POST https://opentweet.io/api/v1/inspiration/repurpose
Body: {
  "tweet_text": "需要重制的原始推文内容",
  "tweet_author": "@someone",
  "instructions": "让内容更有力，并添加行动号召",
  "tone": "随意",
  "save_as_draft": true
}

返回字段包括 repurposed.text、category、key_topics，当 save_as_draft 为 true（默认）时还会返回 draft.id。系统会自动遵循用户的语言风格和内容主题。可选参数 x_account_id 用于标记已保存草稿。

分析功能

账号概览

GET https://opentweet.io/api/v1/analytics/overview

返回发布统计数据（总发文数、发布频率、活跃天数、每周平均发文数、最活跃时段/日期、长文帖数量、带媒体发文数）、连续发布记录（当前持续天数、最长持续天数）、趋势分析（本周 vs 上周、本月 vs 上月、最佳月份）、内容类别分布以及近期活动（最近7天和30天每日发文量）。

推文互动指标（高级计划专属）

GET https://opentweet.io/api/v1/analytics/tweets?period=30

返回每条推文的互动数据：点赞数、转发数、回复数、引用数、曝光量、收藏数、互动率。同时提供表现最佳/最差的推文、内容类型统计、互动时间线以及最佳发布时段/日期。period 参数支持 7-365 天或 "all"。

最佳发布时间分析

GET https://opentweet.io/api/v1/analytics/best-times

支持两种分析模式：

• **engagement_weighted** — 基于真实每条推文的互动数据计算每小时×每日组合得分。返回 heatmap、confidence、top_windows、best_day、best_hour、worst_day、worst_hour、insights。仅在完成分析后可用。
• **frequency_only** — 仅基于用户历史发布频率的降级方案。当尚未建立互动数据档案时返回（需至少发布3条推文）。

两种模式均保留兼容性字段：hour_distribution、day_distribution、best_hours、best_days。

触发新的最佳发布时间分析

POST https://opentweet.io/api/v1/analytics/best-times/analyze
Body: {}    # 可选：{ "x_account_id": "..." }

从 X 平台拉取用户近期发布的推文，计算加权互动窗口并存储分析结果。内置冷却机制：若最近分析仍有效，返回 429 状态码及 next_available_at 时间。返回 success 与 profile（状态为 ready / analyzing / insufficient_posts）。

常用工作流程

第一步：验证连接是否正常

1. GET /api/v1/me — 检查 authenticated 是否为 true，subscription.has_access 是否为 true

立即发布一条推文（一步操作）

1. GET /api/v1/me — 检查 limits.can_post 是否为 true
2. POST /api/v1/posts 传入 { "text": "...", "publish_now": true }

带图片发布推文

1. GET /api/v1/me — 检查发布限制
2. 上传文件：POST /api/v1/upload 附带图片文件 — 获取返回的 URL
3. 创建并发布：POST /api/v1/posts 传入 { "text": "...", "media_urls": ["<url>"], "publish_now": true }

定时发布推文

1. GET /api/v1/me — 检查 limits.remaining_posts_today 是否大于 0
2. POST /api/v1/posts 传入 { "text": "...", "scheduled_date": "2026-05-01T10:00:00Z" } — 必须执行此 HTTP 请求
3. 读取响应 JSON — 确认 posts[0].status === "scheduled"，并向用户展示响应中的 id 和 scheduled_date

定时发布推文并启用自动转发增强

1. GET /api/v1/me — 检查 limits.remaining_posts_today 是否大于 0
2. POST /api/v1/posts 传入文本、scheduled_date、auto_retweet_enabled: true、auto_retweet_offset_minutes: 240
3. 向用户展示 id 和 scheduled_date

定时发布推文并启用自动引流（提升病毒式传播收益）

1. GET /api/v1/me — 检查 limits.remaining_posts_today 是否大于 0
2. POST /api/v1/posts 传入文本、scheduled_date、auto_plug_enabled: true、auto_plug_threshold: 50、auto_plug_text: "..."
3. 向用户展示 id 并确认自动引流已激活
4. 推文上线后，当点赞数达到阈值时，系统将自动触发回复 — 无需额外操作

批量安排一周内容

1. GET /api/v1/me — 检查剩余发布额度
2. 批量创建：POST /api/v1/posts 传入 "posts": [...] 数组，每个对象包含 scheduled_date
3. 向用户展示响应中所有创建的 post id 及其预定发布时间

使用 AI 生成图像发布推文

1. GET /api/v1/me — 检查发布限制
2. POST /api/v1/generate/image 传入 { "prompt": "...", "aspect_ratio": "16:9" } — 立即获取返回的图片 URL
3. POST /api/v1/posts 传入 { "text": "...", "media_urls": ["<步骤2返回的URL>"], "publish_now": true }

使用 AI 生成视频发布推文

1. GET /api/v1/me — 检查发布限制
2. POST /api/v1/generate/video 传入 { "prompt": "...", "aspect_ratio": "16:9", "duration": 5 } — 返回 job_id
3. 每隔 10 秒轮询一次 GET /api/v1/generate/video/{job_id}，直到 status 变为 "completed" — 获取 url
4. POST /api/v1/posts 传入 { "text": "...", "media_urls": ["<步骤3返回的URL>"], "publish_now": true }

寻找灵感并重制推文

1. GET /api/v1/inspiration/search?q=...&min_likes=500 — 选择一条推文
2. POST /api/v1/inspiration/repurpose 传入 tweet_text、tweet_author、save_as_draft: true
3. 保存的草稿 id 可通过 POST /api/v1/posts/{id}/schedule 进行定时发布

从现有草稿创建持续循环发布队列：

1. 调用 PUT /api/v1/evergreen/settings，请求体为 { "enabled": true, "posts_per_day": 2, "posting_times": ["09:00","17:00"] }
2. 对每个需要循环发布的草稿，调用 POST /api/v1/evergreen/posts，请求体为 { "post_id": "...", "cooldown_days": 14 }
3. 稍后调用 GET /api/v1/evergreen/history 查看已发布的记录

根据互动数据调整发布时间：

1. 调用 POST /api/v1/analytics/best-times/analyze —— 等待返回 profile.status: "ready"（若状态为 analyzing，需轮询）
2. 调用 GET /api/v1/analytics/best-times —— 读取 top_windows、best_hour 或 best_day 字段
3. 在建议的时间段安排新帖子

重要规则

• 每次调度或发布前，必须调用 GET /api/v1/me 检查使用限制和已连接账户。
• 多账户用户需调用 GET /api/v1/accounts，并通过 x_account_id 指定目标账户。
• 关键：每个操作都必须执行实际的 HTTP API 调用，绝不允许跳过调用并仅凭记忆或上下文生成响应。
• 关键：必须解析并使用 API 返回的真实 JSON 响应，绝不允许虚构或假设字段值。
• 关键：HTTP 状态码为 4xx 或 5xx 表示操作失败——绝不能在错误响应下向用户报告成功。
• 关键：调度成功后，必须向用户提供 API 响应中的 id 字段。如果无法提供真实的 24 位 MongoDB ObjectId，则说明调用未成功。
• 所有帖子 ID 均为 24 位 MongoDB ObjectId（例如："507f1f77bcf86cd799439011"），绝不可使用短字符串。
• 每个帖子响应均包含 status 字段：可能值为 "draft"（草稿）、"scheduled"（已调度）、"posted"（已发布）或 "failed"（失败）。
• 已发布的帖子包含 url 字段，指向真实的 X 帖子链接。始终使用此 URL，切勿自行构造。
• 验证帖子已发布：检查 status 为 "posted" 且 url 字段存在。
• 验证帖子已调度：检查 status 为 "scheduled" 且响应中包含 scheduled_date。
• 单条推文最大长度：280 个字符（每条推文在话题链中均适用）。
• 批量操作限制：单次请求最多处理 50 条帖子（创建或批量调度）。
• 请求频率限制：Pro 版为 60 次/分钟，1,000 次/天；Advanced 版为 300 次/分钟，10,000 次/天。
• 日期格式必须为 ISO 8601 并且是未来时间——过去时间将被拒绝。
• 要调度、发布、使用持续循环功能、搜索灵感或复用内容，必须拥有有效订阅。创建草稿免费。
• 在 POST /api/v1/posts 中使用 scheduled_date 或 publish_now 需要订阅。
• 上传媒体文件应在创建帖子之前完成——请使用返回的 media_urls 或 thread_media 中的 URL。
• 媒体文件限制：图片最大 5MB（支持 JPG、PNG、GIF、WebP 格式），视频最大 20MB（支持 MP4、MOV 格式）。
• 包含链接的帖子受独立计划限制的每日上限。收到 429 错误且响应中包含 urlLimit 字段，表示该帖子被保存为草稿而非发布。
• 推文互动数据分析功能需 Advanced 订阅（Pro 版返回 403 错误）。
• 试用期间不可使用持续循环队列。
• 当 auto_retweet_enabled 为 true 时，auto_retweet_offset_minutes 必须在 1–10080 分钟之间（最多 7 天）。
• 403 错误表示无订阅或未连接 X 账户；429 错误表示达到速率限制、每日发帖上限、链接类帖子数量上限或持续循环池已满。
• 请始终检查响应状态码：201=已创建，200=成功，4xx=客户端错误，5xx=服务器错误。

安全防护机制

发布操作不可逆——一旦推文发布至 X，无法通过 API 撤销（DELETE 会从本地和 X 上移除，但重新发布的内容并非原帖）。

发布前确认

• 在调用 /publish 或设置 publish_now: true 之前，必须告知用户即将发布的帖子内容，并请求确认。
• 显示推文正文（过长时截断）及帖子 ID，以便用户核对。

已调度的帖子 ≠ 可立即发布

• 若帖子包含未来的 scheduled_date，则由调度器在指定时间自动发布，不应立即手动发布。
• 绝不允许在未获用户明确指令的情况下，对具有未来调度时间的帖子调用 /publish。
• 当用户要求“发布”帖子时，需明确其意图：是立即发布还是稍后调度？若提供了日期，默认选择调度。

持续循环源不是普通草稿

• isEvergreen: true 的帖子是可重复使用的模板。调度器发布的是副本，而非原始源帖。
• 绝不允许直接对持续循环源帖调用 /publish（API 将拒绝）。应通过 POST /api/v1/evergreen/posts 添加至队列，交由调度器处理。

批量操作需谨慎

• 创建或调度超过 5 条帖子时，先汇总批次信息（数量、时间范围、首尾推文预览），并请求用户确认后再执行。
• 禁止一次性批量创建并立即发布。应先以草稿或已调度状态创建，让用户审查后，再经确认才发布。
• 使用批量调度时，发送请求前需向用户展示所有调度日期列表。

不要循环调用发布

• 绝不能在未经用户明确批准的情况下，对一组帖子逐个调用 /publish。
• 若用户要求“发布我所有的草稿”等类似指令，应先列出所有草稿，获取确认后再操作。

AI 生成内容需人工审阅

• 在将 AI 复用生成的推文保存为自动调度帖子前，必须向用户展示 AI 输出结果，并允许其编辑。复用接口默认保存为草稿，除非用户已审阅，否则保持 save_as_draft: true。