X BYO API 密钥
自 2026 年 3 月 31 日起,所有 X/Twitter 操作都需要你自己的 API 凭据。在通过 OAuth 关联你的 X 账户后,请在每次针对 X 的请求中包含这 2 个 header:
尚未关联?请参见 X BYO Key 设置指南 以连接你的 X 账户。
| Header | 值 |
|---|---|
X-Twitter-OAuth1-Api-Key | 你的 API Key(Consumer Key) |
X-Twitter-OAuth1-Api-Secret | 你的 API Key Secret(Consumer Secret) |
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
字幕轨道的名称。最多 150 个字符。
自动以 1/n 格式在线程末尾添加编号。需要
thread: true。将媒体对象添加到线程。每个媒体对象将按顺序添加到每个线程。使用
null 跳过特定线程的媒体。使用具有多个 URL 的对象为每个线程添加多个媒体。替代文本
为推文的图片添加替代文本(也称为 alt text)。X 替代文本是一项无障碍功能,用于提供附加的用户信息并支持屏幕阅读器。 在twitterOptions 对象中使用 altText。
X Alt Text
mediaUrls 数组中的一张图片。替代文本将按顺序应用于每张图片。
替代文本不能应用于视频。如果
mediaUrls 中包含带有 altText 的视频,
该视频将不会发布。替代文本必须为 1,000 个字符或更少。地理限制
你可以通过将blockCountries 和 allowCountries 参数与 国家/地区代码 结合使用,将 X 媒体(例如图片或视频)限制到特定国家/地区。
帖子仍将在所有国家/地区显示,但媒体将在指定国家/地区不可用。
blockCountries 或 allowCountries 中的一个参数。
如果同时使用两个参数或某个国家/地区不受 X 支持,地理限制将被忽略。
长帖子
拥有 Premium X 账户(如 Premium 或 Premium Plus)的用户,能够发布最长 25,000 个字符的长帖子。Ayrshare 会自动允许 Premium X 账户用户发布长帖子。 如果用户更改了他们的 X Premium 状态,请等待 24 小时以在 Ayrshare 中反映。你可以使用 /user 或 /analytics 端点检查用户的 Premium 订阅状态。 你还可以通过longPost body 参数强制接受长格式帖子。可以通过在请求中包含以下 JSON 来完成:
X Long Post
code: 111 错误。
长视频
需要 Business 或 Enterprise 计划。 X 要求视频的 最大视频长度 为 2 分 20 秒。 但是,如果你已获得 X 的批准上传较长的视频,例如用户的 X 账户为 Premium 账户或在 Amplify Partner 计划 中,你可以发布长达 10+ 分钟的视频。 发布长视频时使用longVideo twitterOptions 参数:
X Long Video
提及
通过在帖子文本中添加@handle 来提及其他 X 用户。例如:
X Mention
投票
使用twitterOptions 的 poll 参数进行 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 对象中使用 videoTitle 和 videoDescription 字段。
X Video Metadata
videoTitle:视频的标题,映射到 X Media Studio 的标题字段。videoDescription:视频的描述,映射到 X Media Studio 的描述 字段。
视频变现 (Pro Media)
Ayrshare 支持通过 X 的 Pro Media 计划为符合条件的账户提供 X (Twitter) 视频变现。这是一项受限的功能 — 如果你想获得访问权限,请 联系我们。线程
X 线程(也称为 tweetstorm)是 X(前 Twitter)上一系列相连的帖子,可以让你分享超出单个帖子字符限制的更长想法,一起查看时呈现为一个连续的叙述。
发布线程
X 线程可以通过 API 发布。 线程是一个被分成一组回复线程的帖子,并在 X 中用一条线关联。 你可以自动拆分帖子,也可以在帖子文本中指定 线程分隔符。X Thread
thread: true根据换行自动将帖子文本拆分为多个线程。threadNumber: true自动以 1/n 格式在线程末尾添加编号。 例如,5 个线程中的第 2 个将追加:2/5mediaUrls: [array of urls]按顺序将每个媒体对象(图片或视频)添加到线程。 每个线程仅按顺序添加一个媒体对象。
"twitter": []。更多信息请参见 帖子分析 200 响应。
线程媒体
跳过媒体
通过在数组中使用null 跳过线程的媒体。例如:
["https://site.com/image1.png", null, "https://site.com/image2.png"]
这会将 image1 放在第一条推文上,第二条推文没有图片,image2 放在第三条推文上。
多个媒体
通过在mediaUrls 数组中添加带有媒体 URL 的对象 {},可以为线程中的推文添加多个媒体对象。可以使用任何唯一的对象键。例如:
X Thread with Multiple Media URLs
线程分隔符
Ayrshare 会自动将帖子文本拆分为适合推文长度(> 280 个字符)的推文。 在创建线程时,我们优先考虑在可能的情况下将完整句子保留在一个帖子中。 如果一个句子放不下,我们会在句子之间拆分。 对于非常长的句子,我们会在单词之间拆分。 在单词过长的极少情况下,我们会拆分单词本身。 你也可以手动向帖子文本添加\n\n 段落分隔符,以指示应创建一个独立的线程。
如果帖子文本中有 \n\n,我们将不会自动将帖子拆分为线程。
例如:
Example X Thread
\u2063\n\u2063\n
X Thread with Paragraphs
删除线程
要删除推文风暴,使用响应中返回的顶层帖子 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 的导出预设。

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