简介

以下页面介绍了 X API 中包含的 Spaces endpoint。要了解有关 Spaces 的更多通用信息，请访问 help.x.com。

Spaces 通过实时音频对话实现表达与互动。Spaces endpoint 提供了围绕 Spaces 构建新功能的工具。你可以使用这些 endpoint 查询正在进行或已计划的 Spaces，或构建发现体验，帮助你的用户找到他们可能感兴趣的 Spaces。

我们鼓励你发挥创意，将 Spaces 的应用拓展到我们最初的实现之外。借助这些 endpoint，你可以根据 title 中的关键词为听众推荐 Spaces，或呈现由用户关注的账号正在主持或即将主持的 Spaces；你还可以帮助主持人更好地了解其 Spaces 的表现，并获得更多受众洞察。

​

重要资源

以下资源将帮助您入门并与 Spaces 的 endpoint 集成：

• 获取 X API v2 访问权限

• Spaces 数据字典

• 向 Spaces 的一个 endpoint 发送您的首个请求

   

​

当前可用内容

Spaces 查找	按单个 Spaces ID 查找 按多个 Spaces ID 查找 按创建者 ID 查找 查找已购买门票的用户列表
搜索 Spaces	使用关键词搜索 Spaces

​

了解 Spaces 的生命周期

与 X Developer Platform 的其他资源不同，Spaces 具有特定的生命周期。Spaces 最多可在计划开始日期前 14 天进行预定，并在结束后变为不可用。主持人还可以在开始之前的任何时间取消先前已预定的 Space。

Spaces 在直播期间可访问；一旦结束，将无法再通过 Spaces endpoint 进行检索，并会返回错误消息以表明这一情况。

当你的 App 处理 Spaces data 时，你有责任返回最新信息，并移除平台上已不再可用的 data。Spaces lookup endpoint 可帮助你确保符合并尊重用户的期望与意图。  

​

Spaces 中的角色

这些 endpoint 反映了 X 应用中 Spaces 的工作方式。在 Spaces 中，X 用户会根据他们如何参与某个 Space 而被赋予相应角色。  

​

创建者（或主要主持人）

主要主持人是创建某个 Space 的用户，也是该 Space 的所有者。目前，Spaces 只能有一名主持人，因此主要主持人即为唯一的主持人。在 Spaces data dictionary 中，主要主持人信息位于 creator_id 字段，可展开为一个 用户对象。  

​

主持人

主要主持人可以将一名或多名用户设为协同主持。在 Spaces 数据字典中，这些主持人会显示为 host_ids，可展开为用户对象列表。主持人身份在一个 Space 的进行过程中可能发生变化，这些 endpoint 返回的 metadata 将反映请求时的状态。

你的 App 可以通过检查 creator_id 的值来识别主要主持人，并通过检查 host_ids 的值来识别协同主持人。  

​

Speaker

Speaker 是在 Space 中拥有发言权限的用户。任意时刻可以有零个或多个 Speaker，且在一个 Space 中最多可有 10 位 Speaker（包含 Host）。在 Space 数据字典中，Speaker 会在 speaker_ids 列表中返回，您可以将其展开为一个用户对象的列表。  

​

Listener

Listener 可以收听 Space，随时使用预设表情进行互动，并在（当 Host 在 Space 设置中允许时）申请成为发言者。Listener 信息仅以参与者总数（包括 Host）汇总形式返回，位于 participant_count 字段。