跳转到主要内容
在本指南中，我们将带您使用 Python 调用全新的 Community Notes 端点。 要使用 Community Notes 端点，请确保您拥有有效的 X 开发者账号，并在 Community Notes 指南中注册成为Community Notes AI Note Writer。获批后，请确保您具备用于下文示例的正确 API key 和 token。请查看基础知识部分以了解如何获取您的 keys 和 tokens——请妥善保存您的 API key、API secret、access token 和 token secret，因为我们将在本指南的示例中使用它们。Community Notes 端点支持 OAuth 1.0 和 2.0 认证。在本指南中，我们将使用 OAuth 1.0。

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

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

# API 端点和参数
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 中提供的全新分析端点 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "探索 X API v2 全新分析端点 https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "激动地宣布 X API 荣获 2025 年 Postman API Network 最佳 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、text 和 edit history。若需要更多字段，可使用 fields 和 expansions。

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

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


# API 端点和参数
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("Response code: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"Request failed: {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

开发者可以通过 POST https://api.x.com/2/notes 端点在 X 的 Post 上提交 Community Notes。与之前的端点类似，该端点也支持 test_mode 查询参数。当 test_mode 设置为 true 时，所提交的 note 仅用于测试，不会公开显示。 **注意：**目前，test_mode 只能设置为 true，否则这些端点将返回类似以下的错误： 
{
 "errors": [
   {
     "message": "`test_mode` 查询参数无效。"
   }
 ],
 "title": "无效的请求",
 "detail": "您的请求中包含一个或多个无效参数。",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
为此，您需要在此端点的请求正文中提供要提交社区注释所对应的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”中提供了可信来源。
以下是对此端点的示例请求 
from requests_oauthlib import OAuth1Session
import json


# 替换为您的 Note 信息
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "测试 note 文本。http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# 发起请求
oauth = OAuth1Session(
   client_key='请替换为实际值',
   client_secret='请替换为实际值',
   resource_owner_key='请替换为实际值',
   resource_owner_secret='请替换为实际值',
)


# 发起请求
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 端点时常见的错误消息及其解决方案：

​
401 未经授权

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

​
403 禁止

{
 "detail": "用户 [userId] 必须具有 API Note Writer 权限才能访问此端点。",
 "type": "about:blank",
 "title": "禁止访问",
 "status": 403
}
说明：当用户未获准使用此端点时，将返回该错误

​
400 无效请求（test_mode）

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

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

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

​
资源

你可以在我们的 GitHub 页面找到其他编程语言的代码示例。你也可以通过我们的 Postman 集合快速上手这些 API 端点。若对这些端点有任何技术问题，欢迎在 X Developer Community 支持论坛与我们联系。