version: 2.0.0
author: generated-from-utools-docs
tags: twitter ,x,fapi,api,full-api

Fapi.uk Twitter/X API 全量接入技能

1. 何时使用本技能

当用户或任务需要任何 Twitter/X 数据或操作时使用本技能，包括但不限于：

查询用户资料、粉丝、关注关系
读取推文、时间线、搜索
发推、回复、转推、点赞、私信等写操作
登录 Twitter 账号并获取凭证
列表 / 社区 / Spaces / Grok / 通知等全部能力

2. 前置条件

在 https://fapi.uk 通过 Twitter 或 Google 授权登录，获取 apiKey。
所有请求必须在 Header 中携带 apiKey（敏感信息，禁止硬编码到公开仓库/前端）。

3. 统一调用规范（适用于所有端点）

所有端点遵循同一套调用模式，掌握本节即可调用任意端点：

{METHOD} https://fapi.uk/api/base/apitools/{端点名}?{参数}
Header: apiKey: <你的 apiKey>

约定项	说明
Method	绝大多数端点 GET / POST 均可（参数都放 query string）。仅 `loginPost`、`createCommunity`、`addResponsePost` 三个端点仅支持 POST
Header	`apiKey: <你的 apiKey>`（唯一鉴权方式，必填）
`resFormat`	所有端点通用，强烈建议固定传 `json`，直接返回可解析 JSON 对象；不传则返回 JSON 字符串
`proxyUrl`	所有端点通用，可选代理地址
`cursor`	分页端点通用，首页不传或传 `-1`，翻页取上一页返回中的 cursor
`auth_token` / `ct0`	写操作及登录态相关端点的 Twitter 账号凭证（cookie），二选一获取方式：① 调用 `login` 系列端点；② 从浏览器登录 x.com 后提取 cookie
超时建议	建议 30 秒

通用响应结构

{
  "code": 0,
  "msg": "success",
  "data": { },
  "result": { }
}

code：业务状态码（0 或成功相关值表示成功）
msg：提示信息
data / result：业务数据所在字段（以实际返回为准，嵌套可能较深）

通用 HTTP 状态码

HTTP	含义	处理建议
200	成功	解析 `data`/`result`
400	参数错误	检查参数格式（如 ID 是否为数字、逗号分隔是否规范）
401	apiKey 缺失或无效	提示用户检查 apiKey
500	服务器内部错误	重试或检查目标 ID 是否存在

通用请求模板

cURL

curl -G "https://fapi.uk/api/base/apitools/<端点名>" \
  --data-urlencode "<参数1>=<值>" \
  --data-urlencode "resFormat=json" \
  -H "apiKey: YOUR_API_KEY_HERE"

Python

import requests

def call_fapi(endpoint: str, params: dict, api_key: str) -> dict:
    """fapi.uk Twitter API 通用调用函数"""
    params["resFormat"] = "json"
    resp = requests.get(
        f"https://fapi.uk/api/base/apitools/{endpoint}",
        params=params,
        headers={"apiKey": api_key},
        timeout=30,
    )
    resp.raise_for_status()
    data = resp.json()
    # 按需从 data / result 提取业务数据
    return data

# 示例：批量查用户
result = call_fapi("usersByIdRestIds",
                   {"userIds": "1574242047661207552,95033252842778600"}, API_KEY)

JavaScript / Node.js

async function callFapi(endpoint, params, apiKey) {
    const search = new URLSearchParams({ ...params, resFormat: "json" });
    const resp = await fetch(
        `https://fapi.uk/api/base/apitools/${endpoint}?${search}`,
        { headers: { apiKey } }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
}

4. 端点总目录（114 个端点，按功能分类）

下表「必填」列出该端点特有必填参数；resFormat/proxyUrl 所有端点均可用，不再重复。
auth_token/ct0 为账号凭证，写操作基本必填（详见第 6 节）。

4.1 用户资料（Users）

端点	功能	必填参数	可选参数
`usersByIdRestIds`	批量按数字 ID 查用户详情	`userIds`（逗号分隔）	—
`uerByIdRestIdV2`	按单个数字 ID 查用户	`userId`	`cursor`, `auth_token`
`userByScreenNameV2`	按用户名（@handle）查用户	`screenName`	—
`usernameChanges`	查用户名修改历史	`screenName`	—
`accountAnalytics`	账号数据统计	`rest_id`, `auth_token`	`ct0`
`setProfile`	设置资料（bio/昵称/位置等）	`auth_token`	`ct0`, `bio`, `location`, `url`, `name`, `birthdate_day/month/year`
`setHeadImg`	按 URL 设置头像	`auth_token`	`ct0`, `headUrl`, `headType`
`setHeadImgByFile`	按文件设置头像	`auth_token`	`ct0`, `headUrl`, `headType`
`setBannerImg`	设置横幅图	`auth_token`	`ct0`, `bannerUrl`
`blocksCreate`	拉黑用户	`auth_token`	`userId` 或 `screenName`（二选一）, `ct0`
`blocksDestroy`	取消拉黑	`auth_token`	`userId` 或 `screenName`, `ct0`
`unlock`	账号解锁（需额外购买）	`auth_token`	`ct0`, `email`, `emailPass`, `emailCode`
`getToken` / `tokenSync`	(bsc) 机器人 token 获取/同步	—	`methodKey`, `type`, `username` 等

4.2 用户推文与时间线

端点	功能	必填参数	可选参数
`userTweetsV2`	用户推文时间线	`userId`	`cursor`, `auth_token`
`userTimeline`	同 userTweetsV2	`userId`	`cursor`, `auth_token`
`userMedia`	用户媒体推文	`userId`	`cursor`, `auth_token`
`userLikeV2`	用户点赞列表	`userId`	`cursor`, `auth_token`
`userLikedTweetsOfficial`	官方 API v2 点赞列表	`userId`, `authorizationToken`	`maxResults`, `paginationToken`
`highlightsV2`	用户精选推文	`userId`	`cursor`, `auth_token`
`UserArticlesTweets`	用户长文章推文	`userId`	`cursor`, `auth_token`
`userTweetReply`	用户推文的回复	`userId`	`cursor`
`homeTimeline`	自己账号的主页时间线	`auth_token`	`cursor`

4.3 获取推文（Get Tweets）

端点	功能	必填参数	可选参数
`tweetResultsByRestIds`	批量按推文 ID 查推文	`tweetIds`（逗号分隔）	—
`tweetSimple`	推文简略信息	`id`	`cursor`
`tweetTimeline`	推文详情时间线	`id`	`cursor`
`retweetersV2`	推文的转推者	`tweetId`	`cursor`, `auth_token`
`favoritersV2`	推文的点赞者	`tweetId`	`cursor`, `auth_token`
`quotesV2`	推文的引用（Quote Tweets）	`tweetId`	`cursor`, `auth_token`
`retweetersIds`	转推者 ID（@Deprecated）	`id`	`cursor`
`favoritesList`	点赞列表（@Deprecated，改用 userLikeV2）	`userId`	`screenName`, `sinceId`, `maxId`
`mentionsTimeline`	提及我的推文时间线	`auth_token`	`ct0`, `sinceId`, `maxId`

4.4 发送推文（Send Tweets）—— 均需账号凭证

端点	功能	必填参数	可选参数
`createTweet`	发推	`text`, `auth_token`	`ct0`, `medias`(媒体ID), `attachment_url`(引用推文URL)
`CreateNoteTweet`	发长推文	`text`, `auth_token`	`ct0`, `attachment_url`, `medias`, `inReplyToTweetId` 等
`tweetReply`	回复推文	`text`, `tweetId`, `auth_token`	`ct0`, `medias`
`createRetweet`	转推	`tweetId`, `auth_token`	`ct0`
`deleteRetweet`	删除转推	`id`, `auth_token`	`ct0`
`deleteTweet`	删除推文	`id`, `auth_token`	`ct0`
`createBookmark`	添加书签	`id`, `auth_token`	`ct0`
`deleteBookmark`	删除书签	`id`, `auth_token`	`ct0`
`likeTweet` / `likeV2`	点赞	`id`, `auth_token`	`ct0`
`unlikeTweet` / `unlikeV2`	取消点赞	`id`, `auth_token`	`ct0`
`pinTweet`	置顶推文	`id`, `auth_token`	`ct0`
`pollVote`	推文投票	`cardUri`, `originalTweetId`, `responseCardName`, `cardsPlatform`, `selectedChoice`, `auth_token`	`ct0`
`uploadMedia`	按 URL 上传媒体（gif）	`media_url`, `auth_token`	`ct0`
`uploadMediaFile`	上传媒体文件（发推用，返回 media_id）	`auth_token`	`ct0`
`reportUser`	举报用户	`reportedUserId`, `reportedUserName`, `reportChoice`, `id`, `auth_token`	`ct0`
`reportTweet`	举报推文	`reportedUserId`, `reportChoice`, `id`, `auth_token`	`ct0`

4.5 OAuth 授权发推（Authorized Tweet/Retweet）

端点	功能	必填参数	备注
`getAuthPath`	获取 OAuth 授权路径	—	⚠️ 可能导致 apiKey 变化，调用后需检查更新 apiKey
`createTweetByAuth`	OAuth 方式发推	`text`	`consumerKey`, `consumerSecret`
`createRetweetByAuth`	OAuth 方式转推	`tweetId`, `userId`	`consumerKey`, `consumerSecret`

4.6 搜索与趋势（Search）

端点	功能	必填参数	可选参数
`search`	高级搜索（支持全部过滤条件）	`words`	见下方详细参数表
`searchBox`	简单搜索框	—	`words`, `searchType`
`trending`	全球趋势	—	—
`trends`	指定地区趋势	`id`（WOEID）	—
`news` / `sports` / `entertainment`	新闻/体育/娱乐频道	—	—
`explore`	探索页	—	—

search 高级搜索参数明细：

参数	说明	示例
`words`	包含全部这些词（必填）	`what's happening`
`phrase`	精确短语	`happy hour`
`any`	任一词	`cats dogs`
`none`	排除词	`cats dogs`
`tag`	话题标签	`#ThrowbackThursday`
`from`	来自某账号	`Twitter`
`to`	回复给某账号	`Twitter`
`mentioning`	提及某账号	`@SFBART`
`replies` / `likes` / `retweets`	最少回复/点赞/转推数	`280`
`since` / `until`	起止日期	`2020-01-01`
`product`	结果类型	`Top` / `Latest` / `People` / `Media` / `Lists`
`count`	每页数量	`20`
`cursor`	翻页游标	上页返回值

4.7 关注关系（Follows）

端点	功能	必填参数	可选参数
`follow`	关注	`auth_token`	`userId` 或 `screenName`, `ct0`
`unfollow`	取关	`auth_token`	`userId` 或 `screenName`, `ct0`
`followersList`	粉丝列表	`userId` 或 `screenName`	`cursor`, `auth_token`, `ct0`
`followersListV2`	粉丝列表 V2	`userId`	`cursor`
`followersIds`	粉丝 ID 列表	`userId` 或 `screenName`	`cursor`, `auth_token`, `ct0`
`followingsList`	关注列表	`userId` 或 `screenName`	`cursor`, `auth_token`, `ct0`
`followingsListV2`	关注列表 V2	`userId`	`cursor`
`followingsIds`	关注 ID 列表	`userId` 或 `screenName`	`cursor`, `auth_token`, `ct0`
`followersYouKnowV2`	你认识的粉丝	`userId`, `auth_token`	`ct0`, `cursor`
`blueVerifiedFollowersV2`	蓝V粉丝	`userId`	`cursor`
`friendshipsShow`	两用户关系	—	`source_id`, `target_id` 或 `source_screen_name`, `target_screen_name`

4.8 私信（DMS）—— 均需账号凭证

端点	功能	必填参数	可选参数
`getDMSListV2`	私信会话列表	`max_id`, `auth_token`	`ct0`
`getDMSInitIdV2`	私信初始化	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`
`getUpdateDMSV2`	私信增量更新（可取 `request_id`/`conversation_id`）	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`
`getDMS`	接收私信事件	`id`, `auth_token`	`ct0`
`sendDMS`	发送私信（旧）	`type`, `recipient_id`, `text`, `auth_token`	`ct0`
`sendDMSV2`	发送私信 V2	`conversation_id`, `recipient_ids`, `text`, `request_id`, `auth_token`	`ct0`, `reply_to_dm_id`, `media_id`
`sendDMSMedia`	发送媒体私信	`type`, `recipient_id`, `text`, `attachment_type`, `attachment_media_id`, `auth_token`	`ct0`, `quick_reply_type`
`uploadMediaDM`	上传 DM 媒体（返回 media_id）	`auth_token`	`ct0`
`getCanSendDMS`	检查能否给某些用户发私信	`ids`, `auth_token`	`ct0`
`sendXChat`	发送 XChat（加密私信）	`conversation_id`, `recipient_user_id`, `text`, `auth_token`	`ct0`, `signing_private_key_base64`, `key_version`
`getXChatPublicKeys`	获取 XChat 公钥	`conversation_id`, `recipient_user_id`, `auth_token`	`ct0`

推荐 DM 发送流程：getUpdateDMSV2（取 request_id/conversation_id）→ 如需媒体先 uploadMediaDM → sendDMSV2 发送。

4.9 通知（Notifications）—— 需账号凭证

端点	功能	必填参数	可选参数
`notificationsAll`	全部通知	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`
`notificationsMentions`	提及通知	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`
`notificationsVerified`	认证账号通知	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`
`notificationsV2`	通知 V2	`auth_token`	`ct0`, `cursor`, `timelineType`, `count`

4.10 列表（Lists）

端点	功能	必填参数	可选参数
`listByUserIdOrScreenName`	查某用户的列表	`userId` 或 `screenName`	—
`listByRestIdV2`	按 ID 查列表详情	`listId`	`cursor`, `count`
`listMembersByListId`	列表成员	`listId`	`cursor`, `count`
`listMembersByListIdV2`	列表成员 V2	`listId`	`cursor`, `count`
`listFollowersByListIdV2`	列表关注者	`listId`	`cursor`, `count`
`listLatestTweetsTimelineV2`	列表最新推文	`listId`	`cursor`, `count`
`listSearchTimeline`	在列表内搜索推文	`listId`	`cursor`, `count`, `rawQuery`

4.11 社区（Communities）

端点	功能	必填参数	可选参数
`getCommunitiesByScreenName`	按用户名查社区	`screenName`	—
`CommunitiesFetchOneQuery`	查单个社区详情	`communityId`	`cursor`, `rankingMode`
`CommunityQueryV2`	社区查询	`communityId`	`cursor`, `rankingMode`
`CommunitiesTweetsTimelineV2`	社区推文时间线	`communityId`	`cursor`, `rankingMode`
`CommunitiesTimelineV2`	社区探索时间线	`topicId`	`cursor`
`CommunitiesMemberV2`	社区成员列表	`communityId`	`cursor`, `rankingMode`
`CommunitiesSearchV2`	社区搜索	`word`	`cursor`
`TopicListV2`	话题轮播列表	—	—
`createCommunity`	创建社区（仅 POST）	—	—

4.12 Spaces 与 Grok

端点	功能	必填参数	可选参数
`AudioSpaceById`	按 ID 查语音空间	`id`	`auth_token`, `ct0`
`createGrok`	创建 Grok 会话	—	—
`addResponse`	发送 Grok 消息	`message`	`conversationId`, `grokModelOptionId`, `modelMode`, `isDeepsearch`, `isReasoning` 等
`addResponsePost`	发送 Grok 消息（仅 POST）	—	—
`getGrokItemsByRestId`	按 ID 查 Grok 内容	`restId`	—

4.13 登录与凭证（LoginGetToken）

端点	功能	必填参数	可选参数
`login`	账号密码登录	`screenName`, `password`, `email`, `emailPassword`, `emailType`	`faCode`(2FA), `backCode`
`login2FA`	用 2FA 验证码登录	`code`	—
`loginPost`	登录（仅 POST）	—	—
`getUserIdByToken`	由 auth_token 查用户 ID	`auth_token`	—
`getUserNameByToken`	由 auth_token 查用户名	`auth_token`	—
`getCt0`	由 auth_token 获取 ct0	`auth_token`	—

5. 典型调用示例

示例 1：批量查用户资料（读操作，无需账号凭证）

curl -G "https://fapi.uk/api/base/apitools/usersByIdRestIds" \
  --data-urlencode "userIds=1574242047661207552,95033252842778600" \
  --data-urlencode "resFormat=json" \
  -H "apiKey: YOUR_API_KEY_HERE"

示例 2：高级搜索最新推文

curl -G "https://fapi.uk/api/base/apitools/search" \
  --data-urlencode "words=elon musk" \
  --data-urlencode "product=Latest" \
  --data-urlencode "count=20" \
  --data-urlencode "since=2026-10-01" \
  --data-urlencode "resFormat=json" \
  -H "apiKey: YOUR_API_KEY_HERE"

示例 3：发推（写操作，需账号凭证）

curl -G "https://fapi.uk/api/base/apitools/createTweet" \
  --data-urlencode "text=Hello from fapi.uk!" \
  --data-urlencode "auth_token=YOUR_ACCOUNT_AUTH_TOKEN" \
  --data-urlencode "ct0=YOUR_ACCOUNT_CT0" \
  --data-urlencode "resFormat=json" \
  -H "apiKey: YOUR_API_KEY_HERE"

带媒体：先调 uploadMediaFile 拿到 media_id，再把 medias=<media_id> 传入 createTweet。
引用推文：加 attachment_url=https://x.com/<user>/status/<id>。

示例 4：发私信

curl -G "https://fapi.uk/api/base/apitools/sendDMSV2" \
  --data-urlencode "conversation_id=1535987541232750592-1574242047661207552" \
  --data-urlencode "recipient_ids=1574242047661207552" \
  --data-urlencode "text=Hi there!" \
  --data-urlencode "request_id=<来自 getUpdateDMSV2>" \
  --data-urlencode "auth_token=YOUR_ACCOUNT_AUTH_TOKEN" \
  --data-urlencode "resFormat=json" \
  -H "apiKey: YOUR_API_KEY_HERE"

6. 账号凭证（auth_token / ct0）获取指南

写操作（发推、关注、DM 等）需要目标 Twitter 账号的 cookie 凭证：

方式	操作
方式 1：API 登录	依次调用 `login`（如遇 2FA 再调 `login2FA`）获得 `auth_token`；再调 `getCt0` 获取 `ct0`
方式 2：浏览器提取	登录 x.com 后，从浏览器 cookie 中复制 `auth_token` 和 `ct0`

可用 getUserIdByToken / getUserNameByToken 验证凭证是否有效。

7. AI Agent 执行指引

确认 apiKey：从用户提供、环境变量或配置中获取；缺失时提示去 https://fapi.uk 登录获取。
判断操作类型：
- 只读查询（用户/推文/搜索/列表等）→ 无需账号凭证，直接调用。
- 写操作（发推/关注/DM/点赞等）→ 先确认已具备目标账号的 auth_token（及 ct0），缺失则引导走第 6 节流程。
选择端点：根据第 4 节目录按功能定位端点；同类接口优先选 V2 版本（如 followersListV2 而非 followersIds），避开标注 @Deprecated 的端点。
构造请求：套用第 3 节模板，固定加 resFormat=json；多值参数用英文逗号分隔，不要有空格。
分页：需要全量数据时循环携带上一页返回的 cursor，直到无新数据。
解析响应：优先从 data 或 result 提取业务数据；嵌套较深时按实际结构逐层提取。
错误处理：
- 401 → 检查 apiKey（注意 getAuthPath 会改变 apiKey，调用后需更新）。
- 400 → 检查参数格式（ID 是否为纯数字、逗号分隔、必填参数是否齐全）。
- 500 → 重试一次，仍失败则检查目标对象是否存在。
安全：apiKey 与账号凭证均属敏感信息，不得输出到日志明文或提交到公开仓库。

8. 参考资料

资源	位置
完整 OpenAPI 3.0 规范（含全部参数定义，可导入 Apifox/Postman）	本仓库 `Doc/apiDoc/openai.json`（注意：文件名带 openai 但内容是 fapi.uk Twitter API 规范，共 114 个操作）
官方文档	https://utools.readme.io/reference/usersbyidrestids-1
文档索引（AI 友好）	https://utools.readme.io/llms.txt
获取 apiKey	登录 https://fapi.uk
本项目对应封装	`base` 模块 `/base/apitools/**` 系列接口（`OpenApiGroupConfig.java` 中 `twitter` 分组）

维护提示：fapi.uk 新增端点后，可访问 https://fapi.uk/api/v3/api-docs/twitter 导出最新 OpenAPI JSON，替换/比对 Doc/apiDoc/openai.json 后同步更新本文档第 4 节目录。