Settings 账号设置模块示例

本文档提供 Settings 账号设置模块的完整使用示例，涵盖敏感内容设置查询与修改的典型场景。

目录

• 前置准备
• 查询敏感设置
• 一键设置敏感账号
• 单独设置各项
• 查询完整账号设置
• 错误处理

前置准备

安装依赖

maturin develop

认证说明

Settings 模块使用 cookies 进行认证。cookies 字符串需包含以下关键字段：

• ct0 — CSRF token
• auth_token — 认证令牌
• twid — 账号 ID（格式：u%3D<user_id>）

创建客户端

import x_api

cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"

# 方式 1：通过 Twitter 主入口（推荐）
twitter = await x_api.Twitter.create(cookies)
# 之后通过 twitter.settings 访问设置模块

# 方式 2：独立创建 SettingsClient
from x_api.settings import SettingsClient
settings_client = await SettingsClient.create(cookies)

# 使用代理
twitter = await x_api.Twitter.create(cookies, "http://127.0.0.1:7890")

---

查询敏感设置

查询当前账号的三项核心敏感内容设置。

查询敏感设置（精简版）

import asyncio
import x_api

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

    settings = await twitter.settings.get_sensitive_settings()

    print("=== 当前敏感内容设置 ===")
    print(f"  NSFW 标志（账号为敏感内容发布者）: {settings.nsfw_user}")
    print(f"  展示敏感媒体（时间线展示）:        {settings.display_sensitive}")
    print(f"  搜索隐藏敏感内容:                  {settings.search_hide_sensitive}")

asyncio.run(check_sensitive_settings())

输出示例：

=== 当前敏感内容设置 ===
  NSFW 标志（账号为敏感内容发布者）: False
  展示敏感媒体（时间线展示）:        False
  搜索隐藏敏感内容:                  True

设置前先确认当前状态

import asyncio
import x_api

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

    # 先查询
    before = await twitter.settings.get_sensitive_settings()
    print("修改前:")
    print(f"  nsfw_user = {before.nsfw_user}")
    print(f"  display_sensitive = {before.display_sensitive}")
    print(f"  search_hide_sensitive = {before.search_hide_sensitive}")

    # 执行修改
    result = await twitter.settings.set_sensitive_account()

    # 再查询确认
    after = await twitter.settings.get_sensitive_settings()
    print("\n修改后:")
    print(f"  nsfw_user = {after.nsfw_user}")
    print(f"  display_sensitive = {after.display_sensitive}")
    print(f"  search_hide_sensitive = {after.search_hide_sensitive}")

asyncio.run(check_before_change())

输出示例：

修改前:
  nsfw_user = False
  display_sensitive = False
  search_hide_sensitive = True

修改后:
  nsfw_user = True
  display_sensitive = True
  search_hide_sensitive = False

---

一键设置敏感账号

set_sensitive_account() 是最常用的方法，一次调用同时完成三项设置。

基础用法

import asyncio
import x_api

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

    print("正在设置敏感账号模式...")
    result = await twitter.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"设置失败（{len(result.errors)} 个错误）:")
        for err in result.errors:
            print(f"  - {err}")

asyncio.run(setup_sensitive_account())

输出示例：

正在设置敏感账号模式...
账号已成功设置为敏感内容模式
  nsfw_user = True
  display_sensitive = True
  search_sensitive = False

批量处理多个账号

import asyncio
import x_api
from x_api.settings import SettingsClient

async def batch_setup_sensitive(cookie_list: list[str]):
    """批量将多个账号设置为敏感模式"""

    success_count = 0
    failure_count = 0

    for i, cookies in enumerate(cookie_list, 1):
        print(f"[{i}/{len(cookie_list)}] 处理账号...")

        try:
            client = await SettingsClient.create(cookies)
            result = await client.set_sensitive_account()

            if result.success:
                print(f"  成功")
                success_count += 1
            else:
                print(f"  失败: {result.errors}")
                failure_count += 1

        except Exception as e:
            print(f"  异常: {e}")
            failure_count += 1

    print(f"\n批量结果: {success_count} 成功, {failure_count} 失败")


async def main():
    # 多账号 cookies 列表
    cookie_list = [
        "ct0=aaa; auth_token=bbb; twid=u%3D111",
        "ct0=ccc; auth_token=ddd; twid=u%3D222",
        "ct0=eee; auth_token=fff; twid=u%3D333",
    ]
    await batch_setup_sensitive(cookie_list)

asyncio.run(main())

输出示例：

[1/3] 处理账号...
  成功
[2/3] 处理账号...
  成功
[3/3] 处理账号...
  失败: ["设置 nsfw_user 失败: HTTP 403"]

批量结果: 2 成功, 1 失败

---

单独设置各项

当只需修改某一项设置时，使用对应的单项方法。

设置 NSFW 标志

import asyncio
import x_api

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

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

    # 关闭 NSFW 标志
    result = await twitter.settings.set_nsfw_user(False)
    if result.success:
        print("NSFW 标志已关闭")

asyncio.run(toggle_nsfw_flag())

设置敏感媒体展示

import asyncio
import x_api

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

    # 开启：时间线中显示其他用户的敏感媒体
    result = await twitter.settings.set_display_sensitive(True)
    if result.success:
        print("敏感媒体展示已开启")
    else:
        print(f"设置失败: {result.error_msg}")

asyncio.run(toggle_display_sensitive())

设置搜索敏感内容过滤

import asyncio
import x_api

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

    # 关闭搜索过滤（搜索结果中显示敏感内容）
    result = await twitter.settings.set_search_hide_sensitive(False)
    if result.success:
        print("搜索敏感内容过滤已关闭（搜索结果包含敏感内容）")
    else:
        print(f"设置失败: {result.error_msg}")

    # 开启搜索过滤（搜索结果中隐藏敏感内容）
    result = await twitter.settings.set_search_hide_sensitive(True)
    if result.success:
        print("搜索敏感内容过滤已开启（搜索结果过滤敏感内容）")

asyncio.run(toggle_search_filter())

按需修改示例

import asyncio
import x_api

async def selective_update():
    """只修改需要更改的设置项"""
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    twitter = await x_api.Twitter.create(cookies)

    # 先查询当前状态
    current = await twitter.settings.get_sensitive_settings()

    # 只在必要时修改
    if not current.nsfw_user:
        r = await twitter.settings.set_nsfw_user(True)
        print(f"NSFW: {'已开启' if r.success else '开启失败'}")
    else:
        print("NSFW: 已是开启状态，跳过")

    if not current.display_sensitive:
        r = await twitter.settings.set_display_sensitive(True)
        print(f"展示敏感媒体: {'已开启' if r.success else '开启失败'}")
    else:
        print("展示敏感媒体: 已是开启状态，跳过")

    if current.search_hide_sensitive:
        r = await twitter.settings.set_search_hide_sensitive(False)
        print(f"搜索显示敏感: {'已设置' if r.success else '设置失败'}")
    else:
        print("搜索显示敏感: 已是正确状态，跳过")

asyncio.run(selective_update())

输出示例：

NSFW: 已是开启状态，跳过
展示敏感媒体: 已开启
搜索显示敏感: 已是正确状态，跳过

---

查询完整账号设置

get_account_settings() 返回账号的完整配置，适合需要了解账号全貌的场景。

基础查询

import asyncio
import x_api

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

    account = await twitter.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.geo_enabled}")
    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_full_settings())

输出示例：

=== 账号基本信息 ===
  用户名:     @example_user
  语言:       en
  国家代码:   US

=== 隐私设置 ===
  受保护账号: False
  位置服务:   False
  邮箱可搜索: True
  手机可搜索: False

=== 敏感内容 ===
  NSFW 用户:        True
  NSFW 管理员标记:  False
  展示敏感媒体:     True

=== 互动权限 ===
  DM 权限:        following
  群组 DM 权限:   following
  媒体标记权限:   all

账号状态诊断

import asyncio
import x_api

async def diagnose_account():
    """检查账号关键设置，输出状态报告"""
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    twitter = await x_api.Twitter.create(cookies)

    account = await twitter.settings.get_account_settings()
    sensitive = await twitter.settings.get_sensitive_settings()

    print(f"账号 @{account.screen_name} 状态报告")
    print("=" * 40)

    # 检查敏感内容设置
    is_sensitive_ready = (
        sensitive.nsfw_user
        and sensitive.display_sensitive
        and not sensitive.search_hide_sensitive
    )

    if is_sensitive_ready:
        print("[OK] 敏感账号模式已完整开启")
    else:
        print("[需修复] 敏感账号模式未完整配置:")
        if not sensitive.nsfw_user:
            print("  - nsfw_user 未开启")
        if not sensitive.display_sensitive:
            print("  - display_sensitive 未开启")
        if sensitive.search_hide_sensitive:
            print("  - search_hide_sensitive 仍为开启（应关闭）")

    # 检查账号保护状态
    if account.protected:
        print("[注意] 账号设为受保护，内容仅粉丝可见")

asyncio.run(diagnose_account())

输出示例：

账号 @example_user 状态报告
========================================
[需修复] 敏感账号模式未完整配置:
  - nsfw_user 未开启
  - search_hide_sensitive 仍为开启（应关闭）

---

错误处理

基础错误处理

import asyncio
import x_api

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

    try:
        twitter = await x_api.Twitter.create(cookies)
        result = await twitter.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:
        # 网络错误、认证失败、cookies 格式错误等
        error_str = str(e)
        if "401" in error_str or "auth" in error_str.lower():
            print("认证失败，请检查 cookies 是否过期")
        elif "403" in error_str:
            print("权限不足，账号可能被限制")
        elif "429" in error_str:
            print("请求过于频繁，请稍后重试")
        else:
            print(f"请求失败: {e}")

    except Exception as e:
        print(f"未知错误: {e}")

asyncio.run(handle_settings_errors())

带重试的设置

import asyncio
import x_api

async def set_with_retry(cookies: str, max_retries: int = 3):
    """带重试机制的敏感账号设置"""
    twitter = await x_api.Twitter.create(cookies)

    for attempt in range(1, max_retries + 1):
        try:
            result = await twitter.settings.set_sensitive_account()

            if result.success:
                print(f"成功（第 {attempt} 次尝试）")
                return result

            # 有错误但不需要重试（如权限问题）
            print(f"设置失败（第 {attempt} 次）: {result.errors}")
            if attempt < max_retries:
                print(f"  {attempt * 2} 秒后重试...")
                await asyncio.sleep(attempt * 2)

        except RuntimeError as e:
            if "429" in str(e):
                wait = 2 ** attempt * 5
                print(f"限流，等待 {wait} 秒...")
                await asyncio.sleep(wait)
            else:
                raise  # 非限流错误直接抛出

    print(f"重试 {max_retries} 次后仍失败")
    return None


async def main():
    cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789"
    result = await set_with_retry(cookies)
    if result and result.success:
        print("最终设置成功")

asyncio.run(main())

从文件读取 cookies

import asyncio
import os
from pathlib import Path
import x_api

async def main():
    # 优先从环境变量读取
    cookies = os.getenv("TWITTER_COOKIES")

    # 其次从文件读取
    if not cookies:
        cookies_file = Path("cookies.txt")
        if cookies_file.exists():
            cookies = cookies_file.read_text().strip()
        else:
            print("请设置 TWITTER_COOKIES 环境变量或创建 cookies.txt 文件")
            return

    twitter = await x_api.Twitter.create(cookies)
    result = await twitter.settings.set_sensitive_account()

    if result.success:
        print("设置成功")
    else:
        print(f"设置失败: {result.errors}")

asyncio.run(main())

常见错误码

HTTP 状态码	说明	处理建议
400	请求参数错误	检查 cookies 格式是否正确
401	认证失败	cookies 已过期，需要重新获取
403	权限不足	账号可能被限制或处于只读模式
429	请求频率限制	降低操作频率，等待后重试
500	服务器错误	X 平台临时故障，稍后重试

---

完整示例脚本

#!/usr/bin/env python3
"""
Settings 模块完整示例
用途：一键将账号设置为敏感内容模式，并输出设置前后对比
"""

import asyncio
import os
import sys
from pathlib import Path

try:
    import x_api
    from x_api.settings import SettingsClient
except ImportError:
    print("请先安装 x_api: maturin develop")
    sys.exit(1)


async def run_demo(cookies: str, proxy_url: str | None = None):
    """完整演示流程"""

    print("创建客户端...")
    twitter = await x_api.Twitter.create(cookies, proxy_url)

    # 步骤 1：查询设置前的状态
    print("\n[步骤 1] 查询当前敏感内容设置...")
    before = await twitter.settings.get_sensitive_settings()
    print(f"  nsfw_user:           {before.nsfw_user}")
    print(f"  display_sensitive:   {before.display_sensitive}")
    print(f"  search_hide_sensitive: {before.search_hide_sensitive}")

    # 判断是否需要修改
    already_set = (
        before.nsfw_user
        and before.display_sensitive
        and not before.search_hide_sensitive
    )

    if already_set:
        print("\n账号已完整配置为敏感模式，无需修改。")
    else:
        # 步骤 2：一键设置敏感账号
        print("\n[步骤 2] 执行一键设置敏感账号...")
        result = await twitter.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"设置失败（{len(result.errors)} 个错误）:")
            for err in result.errors:
                print(f"  - {err}")
            return

    # 步骤 3：查询完整账号设置
    print("\n[步骤 3] 查询完整账号信息...")
    account = await twitter.settings.get_account_settings()
    print(f"  用户名:   @{account.screen_name}")
    print(f"  语言:     {account.language}")
    print(f"  受保护:   {account.protected}")
    print(f"  DM 权限:  {account.allow_dms_from}")

    print("\n完成。")


async def main():
    cookies = os.getenv("TWITTER_COOKIES")
    if not cookies:
        cookies_file = Path("cookies.txt")
        if cookies_file.exists():
            cookies = cookies_file.read_text().strip()
        else:
            print("请设置 TWITTER_COOKIES 环境变量或创建 cookies.txt")
            return

    proxy_url = os.getenv("PROXY_URL")

    try:
        await run_demo(cookies, proxy_url)
    except RuntimeError as e:
        print(f"运行失败: {e}")
    except KeyboardInterrupt:
        print("\n已中断")


if __name__ == "__main__":
    asyncio.run(main())

---

相关链接

• Settings API 文档
• User 模块示例
• 快速开始
• DM 私信示例