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，再进行发布或排期操作。

多账号支持

• 普通用户：1 个 X 账号
• 高级用户：3 个 X 账号
• 机构用户：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 指定账号

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

• 创建推文：{ "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": "来自 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 将在 auto_retweet_offset_minutes 分钟后自动从同一账号进行转发。该功能也适用于 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 上内容，可在请求末尾添加 ?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：可选，1–10 秒（默认 5 秒）

返回（状态码 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 秒轮询一次。

X 文章（长文发布）

从 Markdown 写作并发布长文文章（X Articles）。OpenTweet 在发布时将 Markdown 转换为 X 的富文本格式，支持：

• #/##/### 标题
• 加粗、*斜体*、~~删除线~~
• 链接、项目列表、编号列表
• > 引用块
• 内联图片：![caption](url)（自动上传至 X）
• 封面图
• 嵌入推文：在单独一行输入 x.com 推文链接

需有效付费订阅（非试用版）。绑定的 X 账号必须拥有 X Premium（自 2026 年 1 月起任意等级），否则发布失败，failed_reason 会返回 X 的具体错误。

文章状态：draft（草稿）、scheduled（已排期）、publishing（发布中）、published（已发布）、failed（失败）。

创建文章（草稿、排期或立即发布）

POST https://opentweet.io/api/v1/articles
Body: {
  "title": "我们如何增长到 1 万用户",
  "content_markdown": "# 简要版本\n\n我们每周都上线...",
  "cover_image_url": "https://上传接口返回的URL",
  "scheduled_date": "2026-07-15T14:00:00Z"
}

• title 和 content_markdown 为必填项
• scheduled_date 用于排期；"publish_now": true 可立即发布（与 scheduled_date 互斥）
• 两者均省略则保存为草稿
• 多账号用户可选传入 x_account_id

返回 201 状态码，包含文章对象。已发布的文章包含 article_url（实际链接）和 x_post_id。

列出文章

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

状态过滤选项：draft、scheduled、publishing、published、failed。

获取、更新或删除文章

GET    https://opentweet.io/api/v1/articles/{id}
PUT    https://opentweet.io/api/v1/articles/{id}    # 可更新 title、content_markdown、cover_image_url、scheduled_date、x_account_id
DELETE https://opentweet.io/api/v1/articles/{id}

已发布的文章无法编辑。将 scheduled_date 设为 null 可取消排期，恢复为草稿。更新失败的文章将重置为草稿或排期状态。

立即发布文章

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

无需请求体。返回状态为 published 且含 article_url，或返回 502 错误并附带 code: "publish_failed" 及 X 的错误信息 failed_reason。

私信推广活动（AI 客户开发）

运行基于 AI 的精准私信推广活动：自动发现目标用户、AI 评估资质、生成个性化私信草稿，仅在人工审核后发送。非群发工具：发送过程由人工介入、按滴答节奏、限速，并遵守用户退订规则。仅高级版和机构版可用（普通版返回 403）。需付费 API 密钥（非免费试用密钥）。

活动流程：创建活动时提供理想客户画像和一个或多个线索来源 → 系统发现并 AI 评估候选人 → 你审查并批准草稿消息 → 发送器按设定限制从绑定账号逐条发送 → 回复被追踪并标记，退订者自动屏蔽 → 实际发送受服务端控制并按节奏执行，批准即排队，不会立即发送。

创建推广活动

POST https://opentweet.io/api/v1/dm-campaigns
Body: {
  "name": "Shopify 创始人 Q3",
  "x_account_id": "account_id_here",
  "sources": [
    { "type": "search", "value": "shopify analytics", "max_candidates": 500 },
    { "type": "followers_of", "value": "somecompetitor", "max_candidates": 500 },
    { "type": "tweet_engagers", "value": "https://x.com/user/status/123", "max_candidates": 300 },
    { "type": "own_followers", "value": "", "max_candidates": 500 }
  ],
  "icp_prompt": "Shopify 店铺主或电商创始人，粉丝数 200–20,000，英语用户，最近两周活跃，抱怨广告成本或分析问题。非代理机构。",
  "score_threshold": 60,
  "message_brief": {
    "offer": "每月 29 美元的 Shopify 分析工具",
    "tone": "随意",
    "cta": "值得一看吗？",
    "follow_up_enabled": false
  },
  "limits": {
    "dms_per_day": 25,
    "active_hours_start": 9,
    "active_hours_end": 18,
    "timezone": "America/New_York"
  },
  "accept_policy": true
}

accept_policy 必须为 true（表示接受 X 的使用条款，相关账号承担推广风险）。返回 { "campaign": {...} }。支持的来源类型：

• search：关键词搜索
• followers_of：关注某个账号
• tweet_engagers：互动某条推文的用户
• own_followers：自己的关注者

列出推广活动

GET https://opentweet.io/api/v1/dm-campaigns

返回 { "campaigns": [...] }，每个活动包含 stats 流程（发现、合格、批准、发送、回复）。

获取活动详情（含统计数据）

GET https://opentweet.io/api/v1/dm-campaigns/{id}

启动发现流程

POST https://opentweet.io/api/v1/dm-campaigns/{id}/discover

将活动状态设为 discovering，立即返回。后台执行发现与 AI 评估，完成后状态变为 reviewing。需轮询直到状态为 reviewing。

列出候选人（待审队列）

GET https://opentweet.io/api/v1/dm-campaigns/{id}/leads?state=qualified&page=1

状态过滤包括：qualified（待审批）、approved（已批准）、sent（已发送）、replied（已回复）、skipped（跳过）。每条候选人包含评分、理由、切入点、草稿消息。

批准或跳过候选人

PATCH https://opentweet.io/api/v1/dm-campaigns/{id}/leads/{leadId}
Body: { "action": "approve", "final_message": "可选编辑后的消息" }

action 可为：

• approve：将草稿或自定义消息加入滴答发送队列
• skip：跳过
• edit：修改草稿但不批准

批准不会立即发送，发送器将在活动日限额和活跃时段内按节奏推送。

查看回复（收件箱）

GET https://opentweet.io/api/v1/dm-campaigns/{id}/inbox

返回：

{
  "conversations": [
    {
      "lead": {...},
      "reply_tag": "interested|question|not_interested|opt_out",
      "events": [...]
    }
  ]
}

退订者将自动加入禁止联系名单。

永续队列

永续队列维护一组永不过时的推文，按设定时间周期性重新发布，中间设有冷却间隔，防止同一推文重复过多。源推文作为模板保留，调度器会在指定时间将其克隆为常规推文发布。