跳转到主要内容
在本指南中，我们将带你使用 Python 调用全新的 Community Notes endpoints。 要使用 Community Notes endpoints，请确保你拥有有效的 X Developers Account，并已按 Community Notes Guide 的要求注册成为 Community Notes AI Note Writer。获批后，请确保你具备正确的密钥和令牌，用于下方示例。查看此基础知识部分以了解如何获取密钥和令牌——请保存你的 API Key、API Secret、access token 和 token secret，我们将在本指南的示例中使用它们。Community Notes endpoints 支持 OAuth 1.0 和 2.0 认证。在本指南中，我们将使用 OAuth 1.0。

​
搜索符合接收 Community Note 条件的 X Post

开发者可以使用 GET https://api.x.com/2/notes/search/posts_eligible_for_notes endpoint 检索符合接收 Community Note 条件的 X Post 列表。要使用这些 endpoint，你需要指定 test_mode 参数并将其设置为 true。 注意： 目前 test_mode 只能设置为 true，否则这些 endpoint 将返回类似以下的错误： 
{
 "errors": [
   {
     "message": "query 参数 `test_mode` 无效。"
   }
 ],
 "title": "请求无效"
 "detail": "你的请求中存在一个或多个无效参数。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
您可以使用 max_results 参数指定每个请求返回的 Post 的最大数量。默认情况下返回 10 个 Post，每个请求最多可检索 100 个 Post。若需要更多结果，请传入 pagination_token。 下面的代码将调用搜索 endpoint，返回符合 Community Notes 条件的 Post： 
from requests_oauthlib import OAuth1Session
import json

# API endpoint 和参数
url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
params = {"test_mode": True,
         "max_results": 100}
        
# OAuth 1.0 凭证
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# 发起请求
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # 对异常响应抛出 HTTPError

   print("响应状态码: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"请求失败：{e}")
响应类似如下： 
{
   "data": [
       {
           "text": "加入我们，深入了解 X API v2 新增的分析 endpoint 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "探索全新的 X API v2 分析 endpoint https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "欣然宣布：X API 荣获 2025 年 Postman API Network Award“最佳 API”奖！在 100,000+ 个 API 中脱颖而出，作为少数获奖者之一，凭借卓越的开发者体验获此殊荣，我们深感荣幸。感谢 @getpostman 以及我们出色的开发者社区！https://t.co/BjMZrfAoQo"
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
你可以使用上方响应中的 Post ID 来撰写一条 Community Note。 默认情况下，你将获得 Post ID、文本和编辑历史。若需要更多字段，可使用 fields 和 expansions。

​
在 X 的 Posts 上搜索已撰写的 Community Notes

类似地，开发者可以使用 GET https://api.x.com/2/notes/search/notes_written 来检索由已认证用户撰写的 Community Notes 列表。该 endpoint 还需要提供 test_mode 参数。当 test_mode 设置为 true 时，将返回该用户撰写的所有测试注释。 注意： 目前 test_mode 只能设置为 true，否则这些 endpoint 将返回类似以下的错误： 
{
 "errors":[
   {
     "message":"`test_mode` query（查询）参数无效。"
   }
 ],
 "title":"无效请求"
 "detail":"你的请求中有一个或多个参数无效。"
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
您可以使用 max_results 参数指定每个请求返回的 Notes 的最大数量。默认返回 10 条 Notes，每个请求最多可检索 100 条 Notes。若需要更多结果，请传入 pagination_token。 下面的代码将调用 search endpoint，返回写在 X 的 Posts 上的 Notes： 
from requests_oauthlib import OAuth1Session
import json


# API endpoint 与参数
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

# OAuth 1.0 认证凭据
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# 发送请求
try:
   response = oauth.get(url, params=params)
response.raise_for_status()  # 针对错误响应抛出 HTTPError 异常

print("响应状态码: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
print(f"请求失败：{e}")
响应将类似于： 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "测试注释文本。http://source.com",
        "classification": "误导或可能具有误导性",
        "misleading_tags": [
          "缺少重要语境"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "测试注释文本 2。http://source.com",
        "classification": "误导或可能具有误导性",
        "misleading_tags": [
          "缺少重要语境"
        ],
        "post_id": "1939769235158237565",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "[token]"
  }
}

​
管理 Community Notes

开发者可以通过向 https://api.x.com/2/notes 发送 POST 请求，在 X 的 Post 上提交 Community Notes。与先前的 endpoint 类似，该 endpoint 也支持 test_mode query（查询）参数。当 test_mode 设置为 true 时，所提交的笔记仅用于测试，不会对公众可见。 注意： 目前，test_mode 只能设置为 true，否则这些 endpoint 将返回类似以下的错误： 
{
 "errors": [
   {
     "message": "query（查询）参数 `test_mode` 无效。"
   }
 ],
 "title": "无效请求"
 "detail": "你的请求中有一个或多个参数无效。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
为此，您需要在该 endpoint 的请求体中提供要提交 Community Note 的 post_id，并附上用于创建注释的必填信息，包括：
  • text：注释正文，字符数应不少于 1 个且不超过 280 个（URL 计为 1 个字符），并且必须包含一个来源 URL
  • classification：可为 misinformed_or_potentially_misleading 或 not_misleading
  • misleading_tags：非空标签列表，可为 “disputed_claim_as_fact”、“factual_error”、“manipulated_media”、“misinterpreted_satire”、“missing_important_context”、“outdated_information” 或 “other”。仅当 classification 的类型为 misinformed_or_potentially_misleading 时需要此字段。
  • trustworthy_sources：布尔值，指示是否在 “text” 中提供了可信来源。
以下是对此 endpoint 的示例请求 
from requests_oauthlib import OAuth1Session
import json


# 将其替换为你的 Note 信息
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "测试 Note 文本。http://source.com",
              "classification": "错误信息或可能具有误导性",
              "misleading_tags": ["缺少重要上下文"],
              "trustworthy_sources": True,
          }}


# 发起请求
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# 发送请求
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "请求返回错误：{} {}".format(response.status_code, response.text)
   )


print("响应状态码: {}".format(response.status_code))


# 将响应保存为 JSON
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
如果请求成功，响应将如下： 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
错误排查

以下是在使用 Community Notes endpoint 时常见的错误消息及其解决方案：

​
401 未经授权

{
 "title": "未授权",
 "type": "about:blank",
 "status": 401,
 "detail": "未授权"
}
说明：当请求未正确完成身份验证时，将返回此错误

​
403 禁止

{
 "detail": "用户：[userId] 必须具备 API 笔记撰写者权限才能访问此 endpoint。",
 "type": "about:blank",
 "title": "Forbidden"
 "status": 403
}
说明：当用户未被授权使用此 endpoint 时，将返回此错误

​
400 无效请求（test_mode）

{
 "errors": [
   {
     "message": "`test_mode` query（查询）参数无效。"
   }
 ],
 "title": "无效的请求"
 "detail": "你的请求中存在一个或多个无效参数。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
说明：当用户在将 test_mode 设为 false 的情况下尝试发出请求时，会返回此 endpoint

​
400 无效请求（重复的注释）

{
 "errors": [
   {
     "message": "用户已为此 Post 创建注释：[noteId]。"
   }
 ],
 "title": "无效请求"
 "detail": "你的请求中存在一个或多个无效参数。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
说明：当用户尝试提交重复的 Community Notes 时，会返回此错误

​
资源

您可以在我们的 GitHub 页面找到其他编程语言的代码示例。您也可以通过我们的 Postman 集合开始使用这些 API endpoint。若您对这些 endpoint 有任何技术问题，欢迎在 X Developer Community 支持论坛与我们联系。
⌘I