> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 发布推文
> 代表已认证的源用户发布推文，支持纯文本、回复、引用、投票或附带媒体。还支持在 X 的编辑时间窗口内编辑现有推文。
代表已认证的源用户发布推文。该端点代理官方 [X v2 `POST /2/tweets` 端点](https://docs.x.com/x-api/posts/create-post)，并通过位于 `https://api.aisa.one/apis/v1/twitter/post_twitter` 的 AIsa 网关进行路由。
一个端点涵盖所有变体：
`{ "text": "Hello, World!" }`
设置 `reply.in_reply_to_tweet_id`。
设置 `quote_tweet_id`。
设置 `poll.options` + `poll.duration_minutes`。
设置 `media.media_ids`（1–4 个 ID）。
设置 `edit_options.previous_post_id`（须在 X 的编辑时限内）。
## 前置条件
* 一个 **AIsa API 密钥**（每个请求均使用 Bearer token）。
* 对源用户账户进行一次性 **OAuth 授权**。通过调用 [`POST /apis/v1/twitter/auth_twitter`](/zh/api-reference/twitter/post_twitter-auth-twitter) 关联你的 X 账户——AIsa 会将会话与 API 密钥关联存储，并在每次写入调用时自动使用该会话。
* X 会话必须拥有 `tweet.read`、`tweet.write`、`users.read`。
## 互斥字段
单个请求中最多只能出现以下字段中的**一个**：
* `media`
* `poll`
* `quote_tweet_id`
* `card_uri`
如果设置了多个字段，X 将拒绝请求（`400 invalid-request`）。
## 响应
成功时，端点返回 `201 Created`：
```json theme={null}
{
"data": {
"id": "1346889436626259968",
"text": "Hello, World!"
}
}
```
返回的 `text` 反映 X 实际存储的内容（例如缩短后的 URL）。可使用 `data.id` 在后续调用中引用该推文（回复、引用、点赞、编辑、删除）。
## 编辑推文
传入 `edit_options.previous_post_id` 可编辑现有推文，而不是创建新推文。编辑受 X 的编辑时限和编辑次数限制；如果已超过时限或编辑配额已用尽，端点将返回 `409 conflict`。
## 回复设置
使用 `reply_settings` 限制可回复的用户：
| 值 | 可回复的用户 |
| ---------------- | ---------------- |
| `following` | 你关注的人 |
| `mentionedUsers` | 推文中明确提及的用户 |
| `subscribers` | 你的 X Premium 订阅者 |
| `verified` | 已认证账户 |
省略该字段则使用默认设置（所有人）。
## 常见 4xx 原因
* `400 invalid-request`——设置了两个互斥字段、文本过长、投票持续时间无效等。
* `403 client-forbidden`——OAuth 会话缺少 `tweet.write` scope。请通过 `auth_twitter` 重新关联。
* `404 resource-not-found`——引用的 `in_reply_to_tweet_id`、`quote_tweet_id` 或 `previous_post_id` 不存在，或对源用户不可见。
* `409 conflict`——内容重复，或在允许的时限之外进行编辑。
完整列表请参阅[错误代码](/zh/api-reference/errors)，各层级上限请参阅[速率限制](/zh/api-reference/rate-limits)。
## 相关内容
启动此端点所需的 OAuth 流程。
使用同一 OAuth 会话的另一个写入端点。
封装完整 Twitter 功能面的 Agent 技能。
## OpenAPI
````yaml openapi/zh/twitter-actions.json POST /twitter/post_twitter
openapi: 3.0.3
info:
title: Twitter Actions API
version: 1.0.0
description: >-
对 X/Twitter 执行写入操作，并通过 AIsa 网关路由。参照官方 X v2 API 端点建模（例如 POST
/2/users/{id}/following）。
servers:
- url: https://api.aisa.one/apis/v1
security:
- BearerAuth: []
paths:
/twitter/post_twitter:
post:
summary: 发布或编辑推文
description: >-
代表已认证的源用户发布新推文，或编辑现有推文。此接口镜像[官方 X v2 `POST /2/tweets`
端点](https://docs.x.com/x-api/posts/create-post)，并通过 AIsa 网关路由。
**身份验证。**需要源用户的 OAuth 会话，并将其关联到你的 AIsa API 密钥。通过 `POST
/apis/v1/twitter/auth_twitter` 完成一次账户关联。
**权限范围。**底层 X 会话必须具有 `tweet.read`、`tweet.write` 和 `users.read` 权限。
**互斥字段。**`media`、`poll`、`quote_tweet_id` 和 `card_uri`
不能在同一请求中组合使用。最多只能设置其中一个字段。
operationId: postTwitter
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: 推文内容。发布媒体、投票或引用推文时可选；其他情况下必填。
example: Hello from AIsa — shipping agent-friendly Twitter APIs.
reply:
type: object
description: 作为对另一条推文的回复发布。
required:
- in_reply_to_tweet_id
properties:
in_reply_to_tweet_id:
type: string
description: 被回复的 Tweet ID。
pattern: ^[0-9]{1,19}$
auto_populate_reply_metadata:
type: boolean
description: 根据原始推文自动填充回复中的 @提及。
exclude_reply_user_ids:
type: array
items:
type: string
pattern: ^[0-9]{1,19}$
maxItems: 10
description: 要从回复自动提及中排除的用户 ID（最多 10 个）。
quote_tweet_id:
type: string
description: 要引用的 Tweet ID。不能与 `media`、`poll` 和 `card_uri` 同时使用。
pattern: ^[0-9]{1,19}$
media:
type: object
description: 附加媒体。不能与 `poll`、`quote_tweet_id` 和 `card_uri` 同时使用。
required:
- media_ids
properties:
media_ids:
type: array
items:
type: string
minItems: 1
maxItems: 4
description: 来自 X media-upload API 的 1–4 个媒体 ID。
tagged_user_ids:
type: array
items:
type: string
pattern: ^[0-9]{1,19}$
maxItems: 10
description: 媒体中标记的用户 ID（最多 10 个）。
poll:
type: object
description: 附加投票。不能与 `media`、`quote_tweet_id` 和 `card_uri` 同时使用。
required:
- options
- duration_minutes
properties:
options:
type: array
items:
type: string
maxLength: 25
minItems: 2
maxItems: 4
description: 2–4 个投票选项，每个选项 1–25 个字符。
duration_minutes:
type: integer
minimum: 5
maximum: 10080
description: 投票持续时间（分钟，5–10080，即最长 7 天）。
reply_settings:
type: string
enum:
- following
- mentionedUsers
- subscribers
- verified
card_uri:
type: string
description: >-
卡片 URI。不能与 `media`、`poll`、`quote_tweet_id` 和
`direct_message_deep_link` 同时使用。
direct_message_deep_link:
type: string
description: 将对话跳转至私信的深层链接。
geo:
type: object
description: 为推文附加地点。
properties:
place_id:
type: string
description: X 地点 ID。
reply_settings:
type: string
enum:
- following
- mentionedUsers
- subscribers
- verified
description: 允许回复的用户。
for_super_followers_only:
type: boolean
default: false
description: 仅超级关注者可见。
nullcast:
type: boolean
default: false
description: Nullcast（仅推广）推文——不会显示在公开时间线中，也不会向关注者显示。
paid_partnership:
type: boolean
description: 将推文标记为付费合作内容。
made_with_ai:
type: boolean
description: 标记该推文包含 AI 生成的媒体。
community_id:
type: string
pattern: ^[0-9]{1,19}$
description: 发布到指定社区。
share_with_followers:
type: boolean
default: false
description: 同时向你的关注者分享该社区帖子。
edit_options:
type: object
description: 编辑现有推文，而不是创建新推文（受 X 的编辑时间窗口限制）。
required:
- previous_post_id
properties:
previous_post_id:
type: string
pattern: ^[0-9]{1,19}$
description: 要编辑的推文 ID。
examples:
simple_text:
summary: Plain text tweet
value:
text: Hello, World!
reply:
summary: Reply to a tweet
value:
text: Totally agree 👌
reply:
in_reply_to_tweet_id: '1234567890123456789'
auto_populate_reply_metadata: true
with_poll:
summary: Tweet with a poll
value:
text: 'Pick your favorite:'
poll:
options:
- Option A
- Option B
- Option C
duration_minutes: 60
with_media:
summary: Tweet with media
value:
text: Ship log 📸
media:
media_ids:
- '1146654567674912769'
tagged_user_ids:
- '2244994945'
quote:
summary: Quote tweet
value:
text: 'Worth reading:'
quote_tweet_id: '1234567890123456789'
edit:
summary: Edit an existing tweet
value:
text: Updated tweet content (typo fixed).
edit_options:
previous_post_id: '1234567890123456789'
responses:
'201':
description: Tweet 已成功创建（或编辑）。
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
pattern: ^[0-9]{1,19}$
description: 新创建或编辑的推文 ID。
text:
type: string
description: X 存储的推文最终文本。
example:
data:
id: '1346889436626259968'
text: Hello, World!
'400':
description: 无效请求——违反互斥规则、缺少必填字段或文本过长。
'401':
description: AIsa API 密钥缺失或无效。
'403':
description: >-
OAuth 会话缺失、已过期或缺少 `tweet.write` 权限。请通过 `POST
/apis/v1/twitter/auth_twitter` 重新授权。
'404':
description: 未找到引用的推文（回复、引用或编辑目标）。
'409':
description: 冲突——例如，推文内容重复或在允许的时间窗口之外编辑。
'429':
description: 已达到速率限制。
'500':
description: 内部错误。
'502':
description: 无法连接上游 X API。
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: AISA API Key
description: 你的 AIsa API 密钥。经过身份验证的源用户（执行关注操作的账户）由附加到你的密钥的 OAuth 会话决定。
````