跳转到主要内容

X BYO API 密钥

自 2026 年 3 月 31 日起,所有 X/Twitter 操作都需要你自己的 API 凭据。在通过 OAuth 关联你的 X 账户后,请在每次针对 X 的请求中包含这 2 个 header:
Header
X-Twitter-OAuth1-Api-Key你的 API Key(Consumer Key)
X-Twitter-OAuth1-Api-Secret你的 API Key Secret(Consumer Secret)
尚未关联?请参见 X BYO Key 设置指南 以连接你的 X 账户。
Ayrshare 不再对 X/Twitter 施加自己的每月或每日速率限制。由于 X 请求使用 你自己的凭据(BYO),你的使用完全由你自己的 X Developer 应用限制来管理。详情请参见 X API 速率限制 文档

发布到 X (Twitter)

使用 X API(原 Twitter API)发布带有链接和图片的基本帖子的 JSON:
X Post
  • 除非推文中包含图片或视频,否则 X 将自动预览推文中的链接。 在上面的示例中会显示图片。移除图片后,链接预览将会 显示。
  • 如果你的视频不是以已知的视频扩展名(如 mp4)结尾,请使用 isVideo 参数。详情请参见 /post 端点
  • X 还支持发送无帖子文本的媒体。如果你不希望包含帖子文本, 请发送空字符串 post: ""
  • 你可以在单条推文中上传最多 4 张图片或视频。请参见 发布 Twitter 视频 的重要指南和限制。
  • 更多信息请参见 X 媒体指南X 授权

X 选项

你可以使用 twitterOptions 参数为帖子设置额外选项。
X Options
X 选项是可选字段,可用于控制帖子。
altText
array of strings
用于无障碍和屏幕阅读器的图片替代文本。每条替代文本最多 1,000 个字符。更多信息请参见 替代文本
blockCountries
array of strings
通过阻止某些区域将媒体限制到特定国家/地区。使用 国家/地区代码不能与 allowCountries 同时使用。更多信息请参见 地理限制
allowCountries
array of strings
通过允许某些区域将媒体限制到特定国家/地区。使用 国家/地区代码不能与 blockCountries 同时使用。更多信息请参见 地理限制
longPost
boolean
默认值:false
为 Premium 用户启用长达 25,000 个字符的长帖子。更多信息请参见 长帖子
longVideo
boolean
默认值:false
允许经过批准的账户发布超过 2 分 20 秒的视频。更多信息请参见 长视频
poll
object
使用自定义选项和持续时间进行投票。必填字段:duration(分钟数)、options(字符串数组)。更多信息请参见 投票
quoteTweetId
string
通过指定推文 ID 引用另一条推文。更多信息请参见 引用推文
replySettings
string
控制谁可以回复帖子。值:followingmentionedsubscribersverified更多信息请参见 回复设置
subscribersOnly
boolean
默认值:false
仅使帖子对订阅者可见。更多信息请参见 仅订阅者
subTitleUrl
string
使用 SRT 文件为视频添加字幕/说明。必须是以 .srt 结尾的有效 SRT 文件 URL。更多信息请参见 视频字幕/说明
subTitleLanguage
string
默认值:"en"
字幕的语言。必须是有效的 语言代码
subTitleName
string
字幕轨道的名称。最多 150 个字符。
thumbNail
string
为视频设置缩略图(封面图)。必须是 JPEG、PNG、BMP 或 WebP 图片文件的 URL。更多信息请参见 视频缩略图 和图片要求 X 媒体指南
videoTitle
string
设置视频的标题。映射到 X Media Studio 中的标题字段。更多信息请参见 视频元数据
videoDescription
string
设置视频的描述。映射到 X Media Studio 中的描述字段。更多信息请参见 视频元数据
thread
boolean
默认值:false
将长帖子分成连接的线程系列,可选择编号和媒体。更多信息请参见 线程
threadNumber
boolean
默认值:false
自动以 1/n 格式在线程末尾添加编号。需要 thread: true
mediaUrls
array of strings
将媒体对象添加到线程。每个媒体对象将按顺序添加到每个线程。使用 null 跳过特定线程的媒体。使用具有多个 URL 的对象为每个线程添加多个媒体。

替代文本

为推文的图片添加替代文本(也称为 alt text)。X 替代文本是一项无障碍功能,用于提供附加的用户信息并支持屏幕阅读器。 twitterOptions 对象中使用 altText
X Alt Text
每条替代文本必须对应 mediaUrls 数组中的一张图片。替代文本将按顺序应用于每张图片。
替代文本不能应用于视频。如果 mediaUrls 中包含带有 altText 的视频, 该视频将不会发布。替代文本必须为 1,000 个字符或更少。

地理限制

你可以通过将 blockCountriesallowCountries 参数与 国家/地区代码 结合使用,将 X 媒体(例如图片或视频)限制到特定国家/地区。 帖子仍将在所有国家/地区显示,但媒体将在指定国家/地区不可用。
你一次只能使用 blockCountriesallowCountries 中的一个参数。 如果同时使用两个参数或某个国家/地区不受 X 支持,地理限制将被忽略。

长帖子

拥有 Premium X 账户(如 Premium 或 Premium Plus)的用户,能够发布最长 25,000 个字符的长帖子。Ayrshare 会自动允许 Premium X 账户用户发布长帖子。 如果用户更改了他们的 X Premium 状态,请等待 24 小时以在 Ayrshare 中反映。你可以使用 /user/analytics 端点检查用户的 Premium 订阅状态。 你还可以通过 longPost body 参数强制接受长格式帖子。可以通过在请求中包含以下 JSON 来完成:
X Long Post
但是,如果没有 Premium 账户的用户尝试发布长推文,系统将返回 code: 111 错误。

长视频

需要 Business 或 Enterprise 计划。 X 要求视频的 最大视频长度 为 2 分 20 秒。 但是,如果你已获得 X 的批准上传较长的视频,例如用户的 X 账户为 Premium 账户或在 Amplify Partner 计划 中,你可以发布长达 10+ 分钟的视频。
在使用 longVideo 参数之前,请验证你的用户的 X 账户是 Premium 或在 Amplify Partner 计划 中 。如果你的用户的 X 账户未获授权发布长视频 ,系统将返回错误。
发布长视频时使用 longVideo twitterOptions 参数:
X Long Video

提及

通过在帖子文本中添加 @handle 来提及其他 X 用户。例如:
X Mention
请查看提及功能的重要规则

投票

使用 twitterOptionspoll 参数进行 X 投票。
X Poll
  • duration:指定投票持续时间的分钟数。
  • options:投票选项的字符串数组。

引用推文

你可以通过指定底层推文 ID 引用另一条推文。ID 可以通过 /post 响应中的 postIds 字段、获取历史 或直接从推文 URL 检索:https://twitter.com/Ayrshare/status/1651601430669664256
X Quote Tweet

回复设置

你可以为帖子设置回复设置,仅允许某些类型的用户回复。
X Reply Settings
replySettings 参数可以是以下值之一:
  • following:仅 X 账户关注的用户可以回复。
  • mentioned:仅在帖子中被提及的用户可以回复。
  • subscribers:仅发布帖子的 X 账户的订阅者可以回复。
  • verified:仅在 X 上经过验证的用户可以回复帖子。

仅订阅者

你可以使用 subscribersOnly 参数将帖子设置为仅对订阅者可见。
X Subscribers Only

视频字幕/说明

你可以通过包含 SRT 文件 为视频添加 X 字幕(也称为 X 说明)。在 twitterOptions 对象中使用 subTitleUrl 字段指定 SRT 文件的 URL。
X Subtitles
  • subTitleUrl:有效的 SRT 文件。URL 必须以 https:// 开头,以 .srt 结尾,并且是 有效的 SRT 文件。
  • subTitleLanguage:可选:字幕的语言。必须是有效的 语言 代码。默认:“en”。
  • subTitleName:可选:字幕轨道的名称。该名称旨在 在播放期间作为选项对用户可见。支持的最大名称长度为 150 个字符。 默认:“English”。

视频缩略图

为 Twitter/X 视频设置缩略图(封面图)。缩略图在视频播放前显示,帮助用户理解视频内容。在 twitterOptions 对象中使用 thumbNail
Twitter/X Video Thumbnail
  • “thumbNail”:缩略图图片的 URL。支持的图片格式是 JPEG、PNG、BMP 和 WebP。
  • 缩略图应该代表视频内容,并且具有视觉吸引力以鼓励互动。
  • 图片要求请参见 X 媒体指南

视频元数据

为发布到 X 的视频设置标题和描述。这些映射到 X Media Studio 中的标题和描述字段。在 twitterOptions 对象中使用 videoTitlevideoDescription 字段。
X Video Metadata
  • videoTitle:视频的标题,映射到 X Media Studio 的标题字段。
  • videoDescription:视频的描述,映射到 X Media Studio 的描述 字段。

视频变现 (Pro Media)

Ayrshare 支持通过 X 的 Pro Media 计划为符合条件的账户提供 X (Twitter) 视频变现。这是一项受限的功能 — 如果你想获得访问权限,请 联系我们

线程

X 线程(也称为 tweetstorm)是 X(前 Twitter)上一系列相连的帖子,可以让你分享超出单个帖子字符限制的更长想法,一起查看时呈现为一个连续的叙述。 X Thread

发布线程

X 线程可以通过 API 发布。 线程是一个被分成一组回复线程的帖子,并在 X 中用一条线关联。 你可以自动拆分帖子,也可以在帖子文本中指定 线程分隔符
X Thread
  • thread: true 根据换行自动将帖子文本拆分为多个线程。
  • threadNumber: true 自动以 1/n 格式在线程末尾添加编号。 例如,5 个线程中的第 2 个将追加:2/5
  • mediaUrls: [array of urls] 按顺序将每个媒体对象(图片或视频)添加到线程。 每个线程仅按顺序添加一个媒体对象。
如果帖子作为 X 线程发送,返回的帖子分析将是推文的数组,"twitter": []。更多信息请参见 帖子分析 200 响应

线程媒体

跳过媒体
通过在数组中使用 null 跳过线程的媒体。例如: ["https://site.com/image1.png", null, "https://site.com/image2.png"] 这会将 image1 放在第一条推文上,第二条推文没有图片,image2 放在第三条推文上。
多个媒体
通过在 mediaUrls 数组中添加带有媒体 URL 的对象 {},可以为线程中的推文添加多个媒体对象。可以使用任何唯一的对象键。例如:
X Thread with Multiple Media URLs
在此示例中,第一条推文将包含 photo-1.jpg,第二条推文包含 photo-2.jpg 和 photo-3.jpg,第三条推文包含 photo-4.jpg。

线程分隔符

Ayrshare 会自动将帖子文本拆分为适合推文长度(> 280 个字符)的推文。 在创建线程时,我们优先考虑在可能的情况下将完整句子保留在一个帖子中。 如果一个句子放不下,我们会在句子之间拆分。 对于非常长的句子,我们会在单词之间拆分。 在单词过长的极少情况下,我们会拆分单词本身。 你也可以手动向帖子文本添加 \n\n 段落分隔符,以指示应创建一个独立的线程。 如果帖子文本中有 \n\n,我们将不会自动将帖子拆分为线程。 例如:
Example X Thread
将生成线程中的两条推文。 如果你想添加段落但不拆分为多条推文,请使用 \u2063\n\u2063\n
X Thread with Paragraphs
由于帖子少于 280 个字符,将生成一条包含两个段落的推文。

删除线程

要删除推文风暴,使用响应中返回的顶层帖子 ID 调用 /post 删除端点。所有线程都将被删除。

字符限制

更多信息请参见 X/Twitter 字符限制

X 视频兼容性

某些视频软件创建的 MP4 文件与 X 不兼容。例如,早于 2019.0.9 的 Camtasia 版本创建的 MP4 文件被 X 拒绝。另外,多个音轨通常会导致问题。 如果你在发布时收到以下消息,则表明视频与 Twitter 不兼容,需要重新编码。 "file is currently unsupported" 请检查你的视频软件的兼容性。例如,Adobe Media Encoder 有 Twitter 1080p Full HD 的导出预设。 Adobe Media Encoder 有关 更多 X API 示例,请参见此处。

仅订阅者

你可以使用 subscribersOnly 参数将帖子设置为仅对订阅者可见。
X Subscribers Only

回复设置

你可以为帖子设置回复设置,仅允许某些类型的用户回复。
X Reply Settings
replySettings 参数可以是以下值之一:
  • following:仅 X 账户关注的用户可以回复。
  • mentioned:仅在帖子中被提及的用户可以回复。
  • subscribers:仅发布帖子的 X 账户的订阅者可以回复。
  • verified:仅在 X 上经过验证的用户可以回复帖子。