Raw HTTP 调试接口 API 文档¶

Raw HTTP 模块提供对任意 X API 端点的直接 HTTP 访问能力，主要用于调试目的。所有请求自动复用 Twitter 客户端的认证体系（Bearer Token、CSRF Token、Cookies）、JA3/H2 指纹模拟和 ClientTransaction 签名注入。

目录¶

模块概述
访问方式
raw_get 方法
raw_post 方法
RawResponse 类型
使用示例
注意事项

模块概述¶

Raw HTTP 模块的设计目标：

调试新端点：在正式封装为 SDK 方法前，快速验证接口响应
探索未文档化 API：直接发送请求并检查原始响应
复用认证栈：无需手动处理 Bearer Token、CSRF、Cookie、JA3 指纹
零额外配置：通过 Twitter 主入口访问，使用与其他模块相同的 HTTP 客户端

访问方式¶

Raw HTTP 模块通过 Twitter 主入口的 .raw 属性访问：

import x_api_rs
import asyncio

async def main():
    cookies = "..."  # 从浏览器获取的 cookies 字符串
    client = x_api_rs.Twitter(cookies)

    # 通过 .raw 访问 Raw HTTP 模块
    response = await client.raw.raw_get("https://api.x.com/1.1/account/settings.json")
    print(response.status)
    print(response.body)

asyncio.run(main())

raw_get 方法¶

发送带认证的 GET 请求到指定 URL。

签名¶

async def raw_get(
    self,
    url: str,
    params: list[tuple[str, str]] | None = None
) -> RawResponse

参数¶

参数	类型	必填	说明
`url`	`str`	是	目标 URL，支持 `https://api.x.com/...` 和 `https://x.com/i/api/...` 等
`params`	`list[tuple[str, str]] \\| None`	否	URL 查询参数列表，格式为 `[("key", "value"), ...]`，默认 `None`

返回值¶

返回 RawResponse 对象，包含状态码、响应体和响应头。

示例¶

# 获取账号设置（带查询参数）
response = await client.raw.raw_get(
    "https://api.x.com/1.1/account/settings.json",
    params=[
        ("include_nsfw_user_flag", "true"),
        ("include_mention_filter", "true"),
    ]
)
print(response.status)  # 200
print(response.body)    # {"protected":false,"screen_name":"...",...}

raw_post 方法¶

发送带认证的 POST 请求到指定 URL，支持 JSON body 和表单 body 两种模式。

签名¶

async def raw_post(
    self,
    url: str,
    params: list[tuple[str, str]] | None = None,
    json_str: str | None = None,
    form: list[tuple[str, str]] | None = None
) -> RawResponse

参数¶

参数	类型	必填	说明
`url`	`str`	是	目标 URL
`params`	`list[tuple[str, str]] \\| None`	否	URL 查询参数列表，附加到 URL query string，默认 `None`
`json_str`	`str \\| None`	否（互斥）	JSON 请求体字符串（`Content-Type: application/json`）。需通过 `json.dumps()` 序列化后传入
`form`	`list[tuple[str, str]] \\| None`	否（互斥）	表单字段列表（`Content-Type: application/x-www-form-urlencoded`），格式为 `[("key", "value"), ...]`

互斥规则：json_str 和 form 不能同时使用。当两者同时传入时，json_str 优先，form 被忽略。

返回值¶

返回 RawResponse 对象。

示例¶

JSON body 请求¶

import json

# 修改搜索安全设置（JSON body）
payload = {
    "optInFiltering": True,
    "optInBlocking": False
}
user_id = "44196397"
response = await client.raw.raw_post(
    f"https://x.com/i/api/1.1/strato/column/User/{user_id}/search/searchSafety",
    json_str=json.dumps(payload)
)
print(response.status)  # 200

表单 body 请求¶

# 修改账号设置（form body）
response = await client.raw.raw_post(
    "https://api.x.com/1.1/account/settings.json",
    form=[
        ("nsfw_user", "true"),
        ("display_sensitive_media", "true"),
    ]
)
print(response.status)  # 200
print(response.body)    # 返回完整的账号设置 JSON

RawResponse 类型¶

RawResponse 是 Raw HTTP 请求的响应对象，包含原始 HTTP 响应的完整信息。

属性¶

属性	类型	说明
`status`	`int`	HTTP 状态码（如 `200`、`401`、`403`）
`body`	`str`	响应体原始文本
`headers`	`dict[str, str]`	响应头字典，key 为小写 header 名

示例¶

response = await client.raw.raw_get("https://api.x.com/1.1/account/settings.json")

print(response.status)           # 200
print(response.body[:100])       # {"protected":false,"screen_name":"..."
print(response.headers.get("content-type"))  # application/json;charset=utf-8

# 解析 JSON 响应体
import json
data = json.loads(response.body)
print(data["screen_name"])

使用示例¶

探索未封装的 API 端点¶

import x_api_rs
import json
import asyncio

async def explore_api():
    cookies = open("cookies.txt").read().strip()
    client = x_api_rs.Twitter(cookies)

    # 探索受众设置（GraphQL）
    import urllib.parse
    variables = urllib.parse.quote("{}")
    response = await client.raw.raw_get(
        f"https://x.com/i/api/graphql/FWApxg844rupV7YVWzHNug/AudienceAndTaggingQuery",
        params=[("variables", "{}")]
    )
    if response.status == 200:
        data = json.loads(response.body)
        prefs = data["data"]["user_preferences"]
        print(f"allow_video_downloads: {prefs.get('allow_video_downloads')}")
    else:
        print(f"请求失败: {response.status}")
        print(response.body)

asyncio.run(explore_api())

调试 form POST 响应结构¶

async def debug_form_post():
    cookies = open("cookies.txt").read().strip()
    client = x_api_rs.Twitter(cookies)

    # 发送 form POST 并检查完整响应
    response = await client.raw.raw_post(
        "https://api.x.com/1.1/account/settings.json",
        form=[("geo_enabled", "false")]
    )
    print(f"Status: {response.status}")
    print(f"Content-Type: {response.headers.get('content-type', 'N/A')}")

    if response.status == 200:
        data = json.loads(response.body)
        print(f"geo_enabled: {data.get('geo_enabled')}")
    else:
        print(f"Error body: {response.body}")

注意事项¶

json_str 必须预序列化¶

json_str 参数接受字符串而非 Python dict。在传入前必须使用 json.dumps() 序列化：

import json

# 正确
payload = {"optInFiltering": True}
await client.raw.raw_post(url, json_str=json.dumps(payload))

# 错误（会抛出类型错误）
await client.raw.raw_post(url, json_str={"optInFiltering": True})

json_str 和 form 互斥¶

两者同时传入时 json_str 优先，form 被静默忽略。建议不要同时传入两者：

# 避免这样写（form 会被忽略）
await client.raw.raw_post(url, json_str='{"a":1}', form=[("b", "2")])

认证头由 SDK 自动注入¶

无需手动设置以下 header，SDK 会自动处理：

Authorization: Bearer <token>
x-csrf-token: <csrf>
Cookie: <cookies>
x-client-transaction-id: <transaction>
User-Agent、Sec-Ch-Ua（JA3 指纹相关）

此模块仅用于调试¶

Raw HTTP 接口绕过了 SDK 对响应的类型化封装。生产代码应使用对应模块的封装方法（如 client.settings.get_account_settings()）以获得强类型响应。

Host 头自动匹配¶

SDK 根据 URL 自动设置正确的 Host 头，支持以下 host： - api.x.com - x.com（含 /i/api/ 路径） - upload.x.com