Settings 模块 API 文档¶

Settings（账号设置）模块提供 X (Twitter) 账号设置的查询和修改功能。v2.0.0 重构为 端点级方法，覆盖 4 个 API 端点、8 个方法，接口设计与 Twitter API 一一对应。

目录¶

模块概述
SettingsClient 类
端点一：account/settings.json
端点二：searchSafety
端点三：AudienceAndTagging（GraphQL）
端点四：explore_settings
类型定义
使用示例
注意事项

模块概述¶

Settings 模块覆盖 4 个独立 API 端点，提供 8 个方法（每个端点对应一个 GET + 一个 SET）：

端点	读方法	写方法
`api.x.com/1.1/account/settings.json`	`get_account_settings()`	`update_account_settings(params)`
`x.com/i/api/1.1/strato/column/User/{id}/search/searchSafety`	`get_search_safety()`	`set_search_safety(filtering, blocking)`
GraphQL `AudienceAndTagging*`	`get_audience_settings()`	`set_protect_videos(enabled)`
`x.com/i/api/2/guide/set_explore_settings.json`	`get_explore_settings()`	`set_explore_settings(params)`

方式 1: 通过 Twitter 主入口访问（推荐）¶

from x_api_rs import Twitter

client = await Twitter.create(cookies)
account = await client.settings.get_account_settings()

方式 2: 独立创建 SettingsClient¶

from x_api_rs.settings import SettingsClient

settings_client = await SettingsClient.create(cookies, proxy_url="http://proxy:8080")
account = await settings_client.get_account_settings()

SettingsClient 类¶

创建方法¶

@staticmethod
async def create(
    cookies: str,
    proxy_url: str | None = None,
    profile: ClientProfile | None = None
) -> SettingsClient

参数:

cookies (str): Twitter 账号的 cookies 字符串
proxy_url (str | None): 可选的代理服务器 URL（格式：http://host:port 或 socks5://host:port）
profile (ClientProfile | None): 可选浏览器指纹 profile（TLS+HTTP 一体），None 时默认 Chrome 136 Windows x64

返回: SettingsClient 实例

异常: RuntimeError — 初始化失败（cookies 格式错误、网络不可达等）

端点一：account/settings.json¶

对应 Twitter REST API：

读：GET api.x.com/1.1/account/settings.json
写：POST api.x.com/1.1/account/settings.json（form-urlencoded，只需传入要修改的字段）

get_account_settings¶

Rust trait:

async fn get_account_settings(&self) -> Result<AccountSettings>

Python:

async def get_account_settings(self) -> AccountSettings

查询账号的完整设置信息，包含账号基本信息、隐私设置、DM 权限、可发现性等 18 个字段。

参数: 无

返回: AccountSettings 对象

异常: RuntimeError — 查询失败

示例:

account = await client.settings.get_account_settings()

print(f"用户名: @{account.screen_name}")
print(f"语言: {account.language}")
print(f"国家: {account.country_code}")
print(f"受保护账号: {account.protected}")
print(f"NSFW 用户: {account.nsfw_user}")
print(f"展示敏感媒体: {account.display_sensitive_media}")
print(f"DM 权限: {account.allow_dms_from}")
print(f"DM 已读回执: {account.dm_receipt_setting}")
print(f"提及过滤: {account.mention_filter}")

update_account_settings¶

Rust trait:

async fn update_account_settings(&self, params: AccountSettingsUpdate) -> Result<AccountSettings>

Python:

async def update_account_settings(self, params: AccountSettingsUpdate) -> AccountSettings

批量更新账号设置。AccountSettingsUpdate 中所有字段均为 Option/可选，只有非 None 的字段才会被发送到 API，多个字段合并为一次 POST 请求。

参数:

参数	类型	说明
`protected`	bool \| None	帖子保护（仅粉丝可见）。`True` 在 Web UI 会触发确认弹窗（API 直接生效）
`nsfw_user`	bool \| None	将账号标记为敏感内容发布者
`display_sensitive_media`	bool \| None	是否展示他人发布的敏感媒体
`geo_enabled`	bool \| None	是否启用地理位置功能
`allow_dms_from`	str \| None	DM 接收来源：`"following"` / `"verified"` / `"all"`
`allow_dm_groups_from`	str \| None	DM 群组邀请来源：`"following"` / `"verified"` / `"all"`
`allow_media_tagging`	str \| None	照片标记权限：`"all"` / `"following"` / `"none"`
`discoverable_by_email`	bool \| None	是否允许通过邮箱发现账号
`discoverable_by_mobile_phone`	bool \| None	是否允许通过手机号发现账号
`dm_receipt_setting`	str \| None	DM 已读回执：`"all_enabled"` / `"all_disabled"`
`dm_quality_filter`	str \| None	低质量 DM 过滤：`"enabled"` / `"disabled"`
`mention_filter`	str \| None	提及过滤：`"unfiltered"` / `"following"` / `"verified"`
`allow_ads_personalization`	bool \| None	是否允许广告个性化
`allow_sharing_data_for_third_party_personalization`	bool \| None	是否允许第三方数据共享

返回: AccountSettings 对象（更新后的完整账号设置，与 get_account_settings() 相同结构）

异常: RuntimeError — 请求失败

示例:

from x_api_rs.settings import AccountSettingsUpdate

# 只修改部分字段 — 其余字段不受影响
params = AccountSettingsUpdate()
params.nsfw_user = True
params.display_sensitive_media = True
params.allow_dms_from = "following"
params.dm_receipt_setting = "all_disabled"
result = await client.settings.update_account_settings(params)
print(f"更新后 NSFW: {result.nsfw_user}")   # True
print(f"DM 已读回执: {result.dm_receipt_setting}")  # all_disabled

# 一次 POST 同时关闭多项个性化设置
params = AccountSettingsUpdate()
params.allow_ads_personalization = False
params.allow_sharing_data_for_third_party_personalization = False
params.discoverable_by_email = False
params.discoverable_by_mobile_phone = False
params.geo_enabled = False
params.mention_filter = "following"
result = await client.settings.update_account_settings(params)

迁移说明: 旧版单字段 setter（set_nsfw_user、set_protected 等）已删除。多个字段现在可以合并为一次调用，减少 HTTP 请求数。

旧代码：await client.settings.set_nsfw_user(True)

新代码：params = AccountSettingsUpdate(); params.nsfw_user = True; await client.settings.update_account_settings(params)

端点二：searchSafety¶

对应 Twitter API：

读：GET x.com/i/api/1.1/strato/column/User/{user_id}/search/searchSafetyReadonly
写：POST x.com/i/api/1.1/strato/column/User/{user_id}/search/searchSafety（JSON body）

get_search_safety¶

Rust trait:

async fn get_search_safety(&self) -> Result<SearchSafetyResponse>

Python:

async def get_search_safety(self) -> SearchSafety

读取搜索安全两项设置的当前值：是否隐藏敏感内容（opt_in_filtering）和是否从搜索结果中移除已屏蔽/静音账号（opt_in_blocking）。

参数: 无

返回: SearchSafety 对象

异常: RuntimeError — 查询失败

示例:

safety = await client.settings.get_search_safety()
print(f"隐藏搜索敏感内容: {safety.opt_in_filtering}")   # True = 过滤敏感内容
print(f"移除已屏蔽账号: {safety.opt_in_blocking}")      # True = 移除屏蔽/静音账号

set_search_safety¶

Rust trait:

async fn set_search_safety(&self, filtering: bool, blocking: bool) -> Result<SettingResult>

Python:

async def set_search_safety(self, filtering: bool, blocking: bool) -> SettingResult

同时设置搜索安全的两项参数。不需要预先读取当前值——两个参数必须同时传入，API 一次写入两个字段。

参数:

参数	类型	说明
`filtering`	bool	`True` = 搜索中隐藏敏感内容（Hide sensitive content）
`blocking`	bool	`True` = 从搜索结果中移除已屏蔽/静音账号（Remove blocked and muted accounts）

返回: SettingResult 对象

异常: RuntimeError — 请求失败

示例:

# 关闭敏感过滤 + 开启屏蔽账号过滤
result = await client.settings.set_search_safety(filtering=False, blocking=True)
if result.success:
    print("搜索安全设置已更新")
else:
    print(f"设置失败: {result.error_msg}")

# 两项全部关闭（敏感账号通常的设置）
result = await client.settings.set_search_safety(filtering=False, blocking=False)

端点三：AudienceAndTagging（GraphQL）¶

对应 Twitter GraphQL API：

读：GET /i/api/graphql/FWApxg844rupV7YVWzHNug/AudienceAndTaggingQuery
写：POST /i/api/graphql/oe9_UzzuQUeSU4qYVtMwQg/AudienceAndTaggingAllowVideoDownloadsMutation

注意: 此端点使用 GraphQL，与其他端点使用的 REST API 不同。isAllowed=false 表示保护视频（禁止下载）。

get_audience_settings¶

Rust trait:

async fn get_audience_settings(&self) -> Result<AudienceSettings>

Python:

async def get_audience_settings(self) -> AudienceSettings

查询受众与标记相关的视频保护设置。

参数: 无

返回: AudienceSettings 对象

异常: RuntimeError — 查询失败

示例:

audience = await client.settings.get_audience_settings()
print(f"视频下载保护: {audience.protect_videos}")  # True = 他人无法下载

set_protect_videos¶

Rust trait:

async fn set_protect_videos(&self, enabled: bool) -> Result<SettingResult>

Python:

async def set_protect_videos(self, enabled: bool) -> SettingResult

开启或关闭视频下载保护。开启后，其他用户无法通过官方途径下载账号发布的视频。

参数:

参数	类型	说明
`enabled`	bool	`True` = 开启视频下载保护；`False` = 允许他人下载

返回: SettingResult 对象

异常: RuntimeError — 请求失败

示例:

result = await client.settings.set_protect_videos(True)
if result.success:
    print("视频下载保护已开启")
else:
    print(f"设置失败: {result.error_msg}")

端点四：explore_settings¶

对应 Twitter API：

读：GET x.com/i/api/2/guide/get_explore_settings.json
写：POST x.com/i/api/2/guide/set_explore_settings.json（JSON body）

get_explore_settings¶

Rust trait:

async fn get_explore_settings(&self) -> Result<ExploreSettings>

Python:

async def get_explore_settings(self) -> ExploreSettings

读取 Explore 个性化设置的当前值。

参数: 无

返回: ExploreSettings 对象

异常: RuntimeError — 查询失败

示例:

explore = await client.settings.get_explore_settings()
print(f"个性化趋势: {explore.use_personalized_trends}")
print(f"基于当前位置: {explore.use_current_location}")

set_explore_settings¶

Rust trait:

async fn set_explore_settings(&self, params: ExploreSettingsUpdate) -> Result<SettingResult>

Python:

async def set_explore_settings(self, params: ExploreSettingsUpdate) -> SettingResult

更新 Explore 个性化设置。两个字段均为可选，未传入的字段不会被修改。

参数:

参数（ExploreSettingsUpdate 字段）	类型	说明
`use_personalized_trends`	bool \| None	是否开启"Trends for you"个性化。部分地区（如日本区）服务端可能忽略 `False`
`use_current_location`	bool \| None	是否基于当前位置显示 Explore 内容

返回: SettingResult 对象

异常: RuntimeError — 请求失败

示例:

from x_api_rs.settings import ExploreSettingsUpdate

# 关闭个性化趋势
params = ExploreSettingsUpdate()
params.use_personalized_trends = False
result = await client.settings.set_explore_settings(params)
if result.success:
    print("个性化趋势已关闭")

# 同时关闭两项
params = ExploreSettingsUpdate()
params.use_personalized_trends = False
params.use_current_location = False
result = await client.settings.set_explore_settings(params)

类型定义¶

AccountSettingsUpdate¶

update_account_settings() 的入参结构体。所有字段均为可选，Default::default() = 不修改任何字段。

字段	Python 类型	默认值	说明
`protected`	bool \| None	None	帖子保护
`nsfw_user`	bool \| None	None	NSFW 账号标记
`display_sensitive_media`	bool \| None	None	展示敏感媒体
`geo_enabled`	bool \| None	None	地理位置功能
`allow_dms_from`	str \| None	None	DM 接收来源
`allow_dm_groups_from`	str \| None	None	DM 群组邀请来源
`allow_media_tagging`	str \| None	None	照片标记权限
`discoverable_by_email`	bool \| None	None	邮箱可发现性
`discoverable_by_mobile_phone`	bool \| None	None	手机号可发现性
`dm_receipt_setting`	str \| None	None	DM 已读回执
`dm_quality_filter`	str \| None	None	低质量 DM 过滤
`mention_filter`	str \| None	None	提及过滤规则
`allow_ads_personalization`	bool \| None	None	广告个性化
`allow_sharing_data_for_third_party_personalization`	bool \| None	None	第三方数据共享

AccountSettings¶

get_account_settings() 和 update_account_settings() 的返回类型。

属性	类型	说明
`screen_name`	str	账号用户名（不含 `@`）
`language`	str	账号界面语言（如 `"en"`、`"zh-cn"`）
`country_code`	str	账号所在国家代码（如 `"US"`、`"CN"`）
`protected`	bool	账号是否设置为受保护（帖子仅粉丝可见）
`geo_enabled`	bool	是否启用地理位置功能
`nsfw_user`	bool	账号是否被标记为 NSFW
`nsfw_admin`	bool	账号是否被管理员标记为 NSFW
`display_sensitive_media`	bool	是否展示敏感媒体内容
`allow_dms_from`	str	DM 接收权限（`"following"` / `"verified"` / `"all"`）
`allow_dm_groups_from`	str	群组 DM 接收权限
`allow_media_tagging`	str	媒体标记权限（`"all"` / `"following"` / `"none"`）
`discoverable_by_email`	bool	是否允许通过邮箱搜索账号
`discoverable_by_mobile_phone`	bool	是否允许通过手机号搜索账号
`dm_receipt_setting`	str	DM 已读回执状态（`"all_enabled"` / `"all_disabled"`）
`dm_quality_filter`	str	低质量 DM 过滤状态（`"enabled"` / `"disabled"`）
`mention_filter`	str	提及过滤规则（`"unfiltered"` / `"following"` / `"verified"`）
`allow_ads_personalization`	bool	是否允许广告个性化
`allow_sharing_data_for_third_party_personalization`	bool	是否允许第三方数据共享

SearchSafetyResponse / SearchSafety¶

get_search_safety() 的返回类型。

属性	类型	说明
`opt_in_filtering`	bool	`True` = 搜索中隐藏敏感内容（Hide sensitive content）
`opt_in_blocking`	bool	`True` = 从搜索结果中移除已屏蔽/静音账号

AudienceSettings¶

get_audience_settings() 的返回类型。

属性	类型	说明
`protect_videos`	bool	`True` = 他人无法下载该账号的视频

ExploreSettings¶

get_explore_settings() 的返回类型。

属性	类型	说明
`use_personalized_trends`	bool	是否使用个性化"Trends for you"
`use_current_location`	bool	是否基于当前位置显示 Explore 内容

ExploreSettingsUpdate¶

set_explore_settings() 的入参结构体。

字段	Python 类型	默认值	说明
`use_personalized_trends`	bool \| None	None	个性化趋势开关
`use_current_location`	bool \| None	None	位置感知开关

SettingResult¶

所有写操作方法（除 update_account_settings）的返回类型。

属性	类型	说明
`success`	bool	操作是否成功
`setting_name`	str	被修改的设置项名称
`error_msg`	str	错误信息（失败时有值，成功时为空字符串）

使用示例¶

账号检测场景：3 次 POST 搞定 6 项设置¶

批量配置一个"敏感内容账号"的典型设置——NSFW 标记、展示敏感媒体、开放 DM、关闭 DM 已读回执、关闭邮箱发现性、搜索不过滤敏感内容：

import asyncio
from x_api_rs import Twitter
from x_api_rs.settings import AccountSettingsUpdate

async def setup_sensitive_account(cookies: str):
    client = await Twitter.create(cookies)

    # POST 1：account/settings — 一次设置 6 项账号级配置
    params = AccountSettingsUpdate()
    params.nsfw_user = True
    params.display_sensitive_media = True
    params.allow_dms_from = "all"
    params.dm_receipt_setting = "all_disabled"
    params.discoverable_by_email = False
    params.discoverable_by_mobile_phone = False
    account = await client.settings.update_account_settings(params)
    print(f"账号设置已更新: nsfw={account.nsfw_user}, dms={account.allow_dms_from}")

    # POST 2：searchSafety — 关闭搜索过滤
    result = await client.settings.set_search_safety(filtering=False, blocking=False)
    print(f"搜索安全设置: {result.success}")

    # POST 3：视频下载保护 — 关闭（允许下载）
    result = await client.settings.set_protect_videos(False)
    print(f"视频保护设置: {result.success}")

asyncio.run(setup_sensitive_account("ct0=xxx; auth_token=yyy; twid=u%3D123456789"))

查询当前完整设置¶

import asyncio
from x_api_rs import Twitter

async def view_all_settings(cookies: str):
    client = await Twitter.create(cookies)

    # 账号基本设置
    account = await client.settings.get_account_settings()
    print(f"用户名: @{account.screen_name}")
    print(f"NSFW: {account.nsfw_user}, 展示敏感: {account.display_sensitive_media}")
    print(f"DM 来源: {account.allow_dms_from}, 已读回执: {account.dm_receipt_setting}")

    # 搜索安全
    safety = await client.settings.get_search_safety()
    print(f"搜索过滤: {safety.opt_in_filtering}, 屏蔽过滤: {safety.opt_in_blocking}")

    # 视频保护
    audience = await client.settings.get_audience_settings()
    print(f"视频保护: {audience.protect_videos}")

    # Explore 个性化
    explore = await client.settings.get_explore_settings()
    print(f"个性化趋势: {explore.use_personalized_trends}")

asyncio.run(view_all_settings("ct0=xxx; auth_token=yyy; twid=u%3D123456789"))

错误处理¶

try:
    params = AccountSettingsUpdate()
    params.nsfw_user = True
    result = await client.settings.update_account_settings(params)
    print(f"更新后 NSFW: {result.nsfw_user}")
except RuntimeError as e:
    # 处理网络错误、认证失败等
    print(f"请求失败: {e}")

注意事项¶

v2.0.0 Breaking Change: 所有旧的单字段 setter 方法（set_nsfw_user、set_protected、set_display_sensitive 等共 20 个方法）已删除，请迁移到 update_account_settings(AccountSettingsUpdate())（先创建实例再赋值字段）
已删除的类型: SensitiveSettings、SetSensitiveAccountResult、PrivacySettings、MediaTagging、DmFrom、MentionFilter 均已删除
历史 bug 修复: 1.0.x 版本中 account/settings.json POST 参数被错误追加到 URL query string 而非请求体，导致写操作实际未生效（Twitter 返回 404 code 34）。v2.0.0 已修复
protected 字段: Web UI 修改 protected 会弹出确认框，SDK 直接发 API 无需确认步骤，行为等价
GraphQL queryId 会轮换: AudienceAndTagging* 的 queryId 可能过期，最新值参考 vladkens/twscrape

Settings 模块 API 文档¶

目录¶

模块概述¶

方式 1: 通过 Twitter 主入口访问（推荐）¶

方式 2: 独立创建 SettingsClient¶

SettingsClient 类¶

创建方法¶

端点一：account/settings.json¶

get_account_settings¶

update_account_settings¶

端点二：searchSafety¶

get_search_safety¶

set_search_safety¶

端点三：AudienceAndTagging（GraphQL）¶

get_audience_settings¶

set_protect_videos¶

端点四：explore_settings¶

get_explore_settings¶

set_explore_settings¶

类型定义¶

AccountSettingsUpdate¶

AccountSettings¶

SearchSafetyResponse / SearchSafety¶

AudienceSettings¶

ExploreSettings¶

ExploreSettingsUpdate¶

SettingResult¶

使用示例¶

账号检测场景：3 次 POST 搞定 6 项设置¶

查询当前完整设置¶

错误处理¶

注意事项¶

相关链接¶