Settings 模块 API 文档¶

Settings（账号设置）模块提供 X (Twitter) 账号隐私与敏感内容设置的查询和修改功能，支持一键开启敏感账号模式，也支持精细化控制各项设置。

目录¶

模块概述
SettingsClient 类
类型定义
使用示例
最佳实践
常见问题

模块概述¶

Settings 模块提供两种使用方式：

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

from x_api import Twitter

client = await Twitter.create(cookies)
result = await client.settings.set_sensitive_account()

方式 2: 独立创建 SettingsClient¶

from x_api.settings import SettingsClient

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

功能说明¶

Settings 模块围绕以下三项敏感内容控制参数展开：

参数	含义	对应 API 字段
`nsfw_user`	将账号标记为敏感内容发布者	`nsfw_user` (account settings)
`display_sensitive`	在时间线中展示其他用户的敏感媒体	`display_sensitive_media` (account settings)
`search_hide_sensitive`	搜索结果中隐藏敏感内容	`optInFiltering` (search safety)

注意: set_sensitive_account() 是一键方法，等价于同时执行：nsfw_user=true、display_sensitive=true、search_hide_sensitive=false（即不在搜索中隐藏敏感内容）。

SettingsClient 类¶

创建方法¶

@staticmethod
async def create(
    cookies: str,
    proxy_url: str | None = None,
    enable_ja3: bool = True
) -> SettingsClient

异步创建 Settings 客户端实例。

参数:

cookies (str): Twitter 账号的 cookies 字符串
proxy_url (str | None): 可选的代理服务器 URL（格式：http://host:port 或 socks5://host:port）
enable_ja3 (bool): 是否启用 JA3/TLS 指纹模拟（默认 True，增强反检测能力）

返回: SettingsClient 实例

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

示例:

# 基础使用
client = await SettingsClient.create(cookies)

# 使用代理
client = await SettingsClient.create(cookies, proxy_url="http://proxy:8080")

# 禁用 JA3 指纹模拟
client = await SettingsClient.create(cookies, enable_ja3=False)

set_sensitive_account¶

async def set_sensitive_account() -> SetSensitiveAccountResult

一键将账号设置为敏感内容模式。等价于同时执行以下三项：

将账号标记为 NSFW（nsfw_user = true）
开启展示敏感媒体（display_sensitive_media = true）
关闭搜索隐藏敏感内容过滤（search_hide_sensitive = false）

参数: 无

返回: SetSensitiveAccountResult 对象，包含三项子操作的结果

异常: RuntimeError - 请求失败（网络错误、认证失败等）

示例:

result = await client.settings.set_sensitive_account()

if result.success:
    print("账号已设置为敏感内容模式")
    print(f"  nsfw_user: {result.nsfw_user}")
    print(f"  display_sensitive: {result.display_sensitive}")
    print(f"  search_sensitive: {result.search_sensitive}")
else:
    print(f"设置失败，错误详情:")
    for err in result.errors:
        print(f"  - {err}")

set_nsfw_user¶

async def set_nsfw_user(enabled: bool) -> SettingResult

设置账号的 NSFW（敏感内容发布者）标志。开启后，账号发布的内容会被平台标记为敏感，关注者需要在设置中允许才能看到。

参数:

enabled (bool): True 开启 NSFW 标志，False 关闭

返回: SettingResult 对象

异常: RuntimeError - 请求失败

示例:

# 开启 NSFW 标志
result = await client.settings.set_nsfw_user(True)
if result.success:
    print("NSFW 标志已开启")
else:
    print(f"设置失败: {result.error_msg}")

# 关闭 NSFW 标志
result = await client.settings.set_nsfw_user(False)

set_display_sensitive¶

async def set_display_sensitive(enabled: bool) -> SettingResult

设置是否在时间线中展示其他用户发布的敏感媒体内容。关闭后，被标记为敏感的图片/视频将被折叠隐藏。

参数:

enabled (bool): True 展示敏感媒体，False 隐藏敏感媒体

返回: SettingResult 对象

异常: RuntimeError - 请求失败

示例:

# 开启展示敏感媒体
result = await client.settings.set_display_sensitive(True)
if result.success:
    print("敏感媒体展示已开启")
else:
    print(f"设置失败: {result.error_msg}")

set_search_hide_sensitive¶

async def set_search_hide_sensitive(enabled: bool) -> SettingResult

设置搜索结果中是否隐藏敏感内容。当 enabled=True 时，敏感内容将从搜索结果中过滤；当 enabled=False 时，搜索结果包含敏感内容。

注意: 此设置对应搜索安全 API 的 optInFiltering 参数，语义上是"是否启用过滤"。设置 enabled=False 意味着不过滤，搜索结果中会显示敏感内容。

参数:

enabled (bool): True 在搜索中隐藏敏感内容，False 在搜索中显示敏感内容

返回: SettingResult 对象

异常: RuntimeError - 请求失败

示例:

# 在搜索中隐藏敏感内容
result = await client.settings.set_search_hide_sensitive(True)

# 在搜索中显示敏感内容（敏感账号通常设为 False）
result = await client.settings.set_search_hide_sensitive(False)

if result.success:
    print(f"搜索敏感内容设置已更新")
else:
    print(f"设置失败: {result.error_msg}")

get_sensitive_settings¶

async def get_sensitive_settings() -> SensitiveSettings

查询当前账号的敏感内容相关设置（三项核心设置）。该方法会同时查询账号设置 API 和搜索安全 API，并汇总返回。

参数: 无

返回: SensitiveSettings 对象，包含三项敏感设置的当前值

异常: RuntimeError - 查询失败（网络错误、认证失败等）

示例:

settings = await client.settings.get_sensitive_settings()

print(f"NSFW 标志: {settings.nsfw_user}")
print(f"展示敏感媒体: {settings.display_sensitive}")
print(f"搜索隐藏敏感: {settings.search_hide_sensitive}")

get_account_settings¶

async def get_account_settings() -> AccountSettings

查询账号的完整设置信息，包含账号基本信息、隐私设置、DM 权限等。适合需要了解账号全貌的场景。

参数: 无

返回: 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}")

类型定义¶

SensitiveSettings¶

敏感内容相关设置的查询结果。由 get_sensitive_settings() 返回。

属性:

属性	类型	说明
`nsfw_user`	bool	账号是否被标记为 NSFW
`display_sensitive`	bool	是否展示敏感媒体
`search_hide_sensitive`	bool	搜索是否隐藏敏感内容

示例:

settings = await client.settings.get_sensitive_settings()
print(settings.nsfw_user)           # True / False
print(settings.display_sensitive)   # True / False
print(settings.search_hide_sensitive)  # True / False

SetSensitiveAccountResult¶

set_sensitive_account() 的执行结果，包含三项子操作的综合状态。

属性:

属性	类型	说明
`success`	bool	三项设置是否全部成功
`nsfw_user`	bool	nsfw_user 设置后的值（成功时为 True）
`display_sensitive`	bool	display_sensitive_media 设置后的值（成功时为 True）
`search_sensitive`	bool	search_hide_sensitive 设置后的值（成功时为 False）
`errors`	list[str]	失败的子操作错误信息列表（全部成功时为空列表）

注意: success 为 True 当且仅当三项子操作全部成功。如果只有部分成功，success 为 False，errors 中会列出具体失败项。

示例:

result = await client.settings.set_sensitive_account()

if result.success:
    # 全部成功
    print(f"nsfw_user = {result.nsfw_user}")           # True
    print(f"display_sensitive = {result.display_sensitive}")  # True
    print(f"search_sensitive = {result.search_sensitive}")    # False
else:
    # 部分或全部失败
    for err in result.errors:
        print(f"错误: {err}")

SettingResult¶

单项设置操作的结果。由 set_nsfw_user()、set_display_sensitive()、set_search_hide_sensitive() 返回。

属性:

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

示例:

result = await client.settings.set_nsfw_user(True)
print(result.success)       # True
print(result.setting_name)  # "nsfw_user"
print(result.error_msg)     # ""（成功时为空）

AccountSettings¶

账号完整设置信息。由 get_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"`、`"all"`）
`allow_dm_groups_from`	str	群组 DM 接收权限
`allow_media_tagging`	str	媒体标记权限（如 `"all"`、`"following"`、`"none"`）
`discoverable_by_email`	bool	是否允许通过邮箱搜索账号
`discoverable_by_mobile_phone`	bool	是否允许通过手机号搜索账号

示例:

account = await client.settings.get_account_settings()

print(f"@{account.screen_name}")           # @example_user
print(f"语言: {account.language}")          # en
print(f"受保护: {account.protected}")       # False
print(f"NSFW: {account.nsfw_user}")         # True
print(f"DM 权限: {account.allow_dms_from}") # following

使用示例¶

基础示例：一键设置敏感账号¶

import asyncio
from x_api import Twitter

async def main():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    client = await Twitter.create(cookies)

    result = await client.settings.set_sensitive_account()
    if result.success:
        print("账号已设置为敏感内容模式")
    else:
        for err in result.errors:
            print(f"错误: {err}")

asyncio.run(main())

查询当前设置¶

import asyncio
from x_api import Twitter

async def check_settings():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    client = await Twitter.create(cookies)

    settings = await client.settings.get_sensitive_settings()
    print(f"NSFW 标志:      {settings.nsfw_user}")
    print(f"展示敏感媒体:   {settings.display_sensitive}")
    print(f"搜索隐藏敏感:   {settings.search_hide_sensitive}")

asyncio.run(check_settings())

精细化控制各项设置¶

import asyncio
from x_api import Twitter

async def fine_grained_settings():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    client = await Twitter.create(cookies)

    # 单独开启 NSFW 标志
    r1 = await client.settings.set_nsfw_user(True)
    print(f"NSFW 标志: {'成功' if r1.success else r1.error_msg}")

    # 单独开启展示敏感媒体
    r2 = await client.settings.set_display_sensitive(True)
    print(f"展示敏感媒体: {'成功' if r2.success else r2.error_msg}")

    # 搜索中不隐藏敏感内容
    r3 = await client.settings.set_search_hide_sensitive(False)
    print(f"搜索显示敏感: {'成功' if r3.success else r3.error_msg}")

asyncio.run(fine_grained_settings())

查询完整账号设置¶

import asyncio
from x_api import Twitter

async def view_account_settings():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    client = await Twitter.create(cookies)

    account = await client.settings.get_account_settings()

    print("=== 账号信息 ===")
    print(f"用户名:   @{account.screen_name}")
    print(f"语言:     {account.language}")
    print(f"国家:     {account.country_code}")

    print("\n=== 隐私设置 ===")
    print(f"受保护账号:     {account.protected}")
    print(f"邮箱可搜索:     {account.discoverable_by_email}")
    print(f"手机号可搜索:   {account.discoverable_by_mobile_phone}")

    print("\n=== 敏感内容 ===")
    print(f"NSFW 用户:      {account.nsfw_user}")
    print(f"NSFW 管理员标记: {account.nsfw_admin}")
    print(f"展示敏感媒体:   {account.display_sensitive_media}")

    print("\n=== 互动权限 ===")
    print(f"DM 权限:        {account.allow_dms_from}")
    print(f"群组 DM 权限:   {account.allow_dm_groups_from}")
    print(f"媒体标记权限:   {account.allow_media_tagging}")

asyncio.run(view_account_settings())

独立 SettingsClient 示例¶

import asyncio
from x_api.settings import SettingsClient

async def main():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"

    # 独立创建，支持代理
    client = await SettingsClient.create(
        cookies,
        proxy_url="http://127.0.0.1:7890"
    )

    result = await client.set_sensitive_account()
    print(f"设置结果: {'成功' if result.success else '失败'}")

asyncio.run(main())

最佳实践¶

1. 设置前先查询当前状态¶

修改设置前建议先查询现有状态，避免不必要的写操作：

settings = await client.settings.get_sensitive_settings()

# 仅在需要时才修改
if not settings.nsfw_user:
    result = await client.settings.set_nsfw_user(True)
    if result.success:
        print("NSFW 标志已开启")

2. 错误处理¶

try:
    result = await client.settings.set_sensitive_account()
    if result.success:
        print("设置成功")
    else:
        # 处理部分失败
        print(f"部分设置失败（共 {len(result.errors)} 个错误）:")
        for err in result.errors:
            print(f"  - {err}")
except RuntimeError as e:
    # 处理网络错误、认证失败等
    print(f"请求异常: {e}")
except Exception as e:
    print(f"未知错误: {e}")

3. 使用 set_sensitive_account() 而非多次单独调用¶

若目标是完整开启敏感账号模式，优先使用 set_sensitive_account()，它只需两次网络请求（账号设置 + 搜索安全），比分三次调用单项方法更高效：

# 推荐：一次调用完成三项设置
result = await client.settings.set_sensitive_account()

# 不推荐：三次独立调用
r1 = await client.settings.set_nsfw_user(True)
r2 = await client.settings.set_display_sensitive(True)
r3 = await client.settings.set_search_hide_sensitive(False)

4. 操作日志记录¶

import logging

logger = logging.getLogger(__name__)

result = await client.settings.set_sensitive_account()
if result.success:
    logger.info("敏感账号设置成功: nsfw_user=True, display_sensitive=True")
else:
    logger.warning(f"敏感账号设置部分失败: errors={result.errors}")

5. 多账号批量处理¶

async def setup_accounts(cookie_list: list[str]):
    """批量将多个账号设置为敏感模式"""
    results = []
    for cookies in cookie_list:
        try:
            client = await SettingsClient.create(cookies)
            result = await client.set_sensitive_account()
            results.append({"success": result.success, "errors": result.errors})
        except Exception as e:
            results.append({"success": False, "errors": [str(e)]})
    return results

常见问题¶

Q1: set_sensitive_account() 和分别调用三个方法有什么区别？¶

set_sensitive_account() 底层会发送两次 API 请求（账号设置接口合并处理 nsfw_user 和 display_sensitive_media，搜索安全接口单独处理 optInFiltering）。分别调用三个单项方法则会发送三次请求。功能上等价，效率上 set_sensitive_account() 更优。

Q2: SetSensitiveAccountResult.success 为 False 但部分设置成功，如何处理？¶

检查 errors 列表了解哪些子操作失败，然后针对失败项单独重试：

result = await client.settings.set_sensitive_account()

if not result.success:
    # 检查失败信息，决定是否重试
    for err in result.errors:
        print(f"失败项: {err}")

    # 也可以单独重试失败的设置
    if not result.nsfw_user:
        await client.settings.set_nsfw_user(True)

Q3: search_hide_sensitive 参数的语义有点反直觉，如何理解？¶

search_hide_sensitive=True 表示在搜索中隐藏（过滤掉）敏感内容，这是"安全搜索"模式。search_hide_sensitive=False 表示不隐藏，搜索结果中包含敏感内容。对于敏感内容账号，通常希望设为 False（set_sensitive_account() 会自动处理这一点）。

Q4: get_account_settings() 和 get_sensitive_settings() 有什么区别？¶

get_sensitive_settings() 专注于三个敏感内容相关字段，同时查询账号设置和搜索安全两个接口，返回精简结果，适合快速确认敏感设置状态。
get_account_settings() 仅查询账号设置接口，返回完整的账号配置信息（包含语言、国家、DM 权限等），但不包含搜索安全设置。

Q5: 修改设置后是否立即生效？¶

是的，API 调用成功后设置立即生效。如需确认，可在修改后调用 get_sensitive_settings() 查询验证。

Q6: 账号需要什么权限才能修改这些设置？¶

使用账号自身的 cookies 即可，无需额外权限。但账号必须处于正常状态（未被封禁、未进入读取模式等）。

Settings 模块 API 文档¶

目录¶

模块概述¶

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

方式 2: 独立创建 SettingsClient¶

功能说明¶

SettingsClient 类¶

创建方法¶

set_sensitive_account¶

set_nsfw_user¶

set_display_sensitive¶

set_search_hide_sensitive¶

get_sensitive_settings¶

get_account_settings¶

类型定义¶

SensitiveSettings¶

SetSensitiveAccountResult¶

SettingResult¶

AccountSettings¶

使用示例¶

基础示例：一键设置敏感账号¶

查询当前设置¶

精细化控制各项设置¶

查询完整账号设置¶

独立 SettingsClient 示例¶

最佳实践¶

1. 设置前先查询当前状态¶

2. 错误处理¶

3. 使用 set_sensitive_account() 而非多次单独调用¶

4. 操作日志记录¶

5. 多账号批量处理¶

常见问题¶

Q1: set_sensitive_account() 和分别调用三个方法有什么区别？¶

Q2: SetSensitiveAccountResult.success 为 False 但部分设置成功，如何处理？¶

Q3: search_hide_sensitive 参数的语义有点反直觉，如何理解？¶

Q4: get_account_settings() 和 get_sensitive_settings() 有什么区别？¶

Q5: 修改设置后是否立即生效？¶

Q6: 账号需要什么权限才能修改这些设置？¶

相关链接¶