如何发出请求

身份验证

要开始使用 Authentication（身份验证），请查看服务帐户身份验证文档。对于要与 Safe Voice 集成的 UGS 项目，您需要为其创建新的服务帐户，并为其创建凭据。然后，使用标准 Basic Auth（基本身份验证）对 Safe Voice 终端进行身份验证，如以上链接中的文档所述。

您的服务帐户需要拥有 Safe Voice Processor（Safe Voice 处理员）角色。

玩家 ID

在 Safe Voice 中，玩家的身份通过其 Vivox 玩家 ID 进行标识。这是用户用于登录 Vivox 的 ID。可从 Vivox 用户 SIP URI 中提取玩家 ID：

sip:.issuer.playerId.@domain.vivox.com

用户 URI 结构的每个部分详述如下：

  • sip - 表示 SIP 会话。
  • issuer - 服务器签发者。
  • playerId - 由 Safe Voice 用于识别玩家身份的用户帐户 ID。
  • @domain.vivox.com - 用户连接的 Vivox 服务器。

注意：Vivox 可以使用任意玩家 ID，只要这些 ID 在频道内具有唯一性即可。如果 Vivox 玩家 ID 与 Vivox 使用的 ID 不同，Safe Voice 用户应确保 Vivox 玩家 ID 可以映射到游戏玩家 ID。

Safe Voice 提供了一个名为 displayName 的字段，用于提交每个玩家的自定义名称或 ID 以显示在 Safe Voice UI 上。此字段可用于提供从 Vivox 玩家 ID 到自定义玩家 ID 的映射。

向 Safe Voice API 发出请求

请参阅 OpenAPI 规范以了解有关请求正文和参数的信息。

POST /safevoice/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/screenings

路径参数

Safe Voice API 提供了多种记录和接收数据的方法。下面将介绍每个查询参数的用途以及它们如何影响输出结果。

参数描述必需
organization要与 Safe Voice 集成的 UGS 组织的 Organization ID（组织 ID）。是
project要与 Safe Voice 集成的 UGS 项目的 Project ID（项目 ID）。是
environment要与 Safe Voice 集成的 UGS 环境的 Environment ID（环境 ID）。是

请求正文

请求正文包含以下字段：

字段描述必需
targetUri要筛查的频道的 URI。要了解有关 Vivox 频道 URI 结构的更多信息，请参阅频道 URI 结构。是
history您希望录制多长时间的历史音频。最长为 15 分钟。否
receiveResults允许将可听音频连同分析结果一起上传到您的存储桶。默认为 false。如果您希望将数据存储在自己的存储桶中，可以将 receiveResults 设置为 true，并为您的存储桶提供 destinationCredentials。否
destinationCredentials包含目标存储桶 (S3) 凭据的对象。 
{
    "bucket": "string",
    "accessKeyId": "string",
    "secretAccessKey": "string"
}
提供此参数允许将可听音频连同分析结果一起上传到您的存储桶。		否
callbackUrl输入服务器进行监听以接收错误和状态回调的完整 URL。一旦筛查完成或出现错误，Safe Voice 便会调用此终端。否
callbackKey如果要验证发送到回调终端的回调来自 Safe Voice，请使用此参数。Safe Voice 将在回调请求的 Authorization 标头中以基本 auth 标头的形式发送该字段的内容。这意味着标头将如下所示："Authorization": "callbackKey"。否
eventType负责音频会话处理的事件类型。例如，report：根据用户举报创建的筛查。random_sample：通过随机匹配样本创建的筛查。mute：根据静音事件创建的筛查。custom：通过未指定的事件创建的筛查。否
playerReportEvents游戏过程中玩家之间发生的举报事件列表。每个事件由下面显示的模式进行定义。否
customMetadata元数据对象可用于为 Safe Voice 提供额外数据。这些数据将在处理结果的结果对象中提供。否
players玩家数据列表。如果提供了玩家数据，Safe Voice 只会录制和处理玩家 consentStatus == "granted" 的音频。提供的 playerId 字段必须与登录 Vivox 时使用的玩家 ID 匹配，这一点很重要。请在上文中了解有关玩家 ID 的更多信息。 
{
    "playerId": "string",
    "consentStatus": "granted" OR "denied"
}
如果玩家列表为空，则默认录制频道中的所有人。不过，这只有在与 Safe Voice Consent Management API 集成后才能实现。如果没有集成，筛查请求将返回错误。		否

playerReportEvents

游戏过程中玩家之间发生的举报事件列表。每个事件由以下字段进行定义：

  • reportType（必填）- 用于定义举报类型的标签。
  • reportReason - 事件描述。
  • reportTimestamp - 发送举报的时间的 Unix 时间戳。
  • reportedPlayerId - 被举报的玩家的玩家 ID。请在上文中了解有关玩家 ID 的更多信息。
  • reporterPlayerId（必填）- 发送举报的玩家的玩家 ID。请在上文中了解有关玩家 ID 的更多信息。

players

游戏过程中玩家之间发生的举报事件列表。每个事件由以下字段进行定义：

  • playerId（必填）- 用于登录 Vivox 的玩家 ID。请在上文中了解有关玩家 ID 的更多信息。
  • displayName - 如果为玩家提供了 displayName，它将显示在 Safe Voice UI 中。
  • consentStatus - 玩家同意状态，专门用于 Safe Voice 同意上下文，包括：
    • 录制玩家音频。
    • 处理玩家的音频，以便进行内容审核。
    • 存储玩家的音频，用于改进产品。
  • consentTimestamp - 设置同意状态的时间的时间戳。

示例：

{
  "targetUri": "sip:confctl-e-issuer.id@domain.vivox.com",
  "history": 15,
  "receiveResults": true,
  "destinationCredentials": {
    "bucket": "test-bucket",
    "accessKeyId": "access-key-id-secret",
    "secretAccessKey": "secret-access-key-secret"
  },
  "callbackUrl": "https://test-domain.test/test-callback-endpoint",
  "callbackKey": "secret-callback-auth-key",
  "eventType": "report",
  "playerReportEvents": [
    {
      "reportType": ["loud voice"],
      "reporterPlayerId": "player_1",
      "reportedPlayerId": "player_2",
      "reportReason": "Loud voice, disturbs the game"
    }
  ],
  "players": [
    {
      "playerId": "player_1",
      "displayName": "player1",
      "consentStatus": "granted",
      "consentTimestamp": "1668432971"
    },
    {
      "playerId": "player_2",
      "displayName": "player2",
      "consentStatus": "denied",
      "consentTimestamp": "1668432971"
    }
  ],
  "customMetadata": {
    "customProperty1": "some value"
  }
}

示例 API 调用

请求 15 分钟的历史音频

curl --request POST -H 'Authorization: Basic <Service Account Credentials>' -H 'Content-Type: application/json' 'https://services.api.unity.com/safevoice/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/screenings' \
--data '{
  "targetUri": "sip:confctl-e-issuer.id@domain.vivox.com",
  "history": 15,
  "receiveResults": true,
  "destinationCredentials": {
    "bucket": "test-bucket",
    "accessKeyId": "access-key-id-secret",
    "secretAccessKey": "secret-access-key-secret"
  },
  "callbackUrl": "https://test-domain.test/test-callback-endpoint",
  "callbackKey": "secret-callback-auth-key",
  "eventType": "report",
  "players": [
    {
      "playerId": "sa_888d4baa",
      "displayName": "player1",
      "consentStatus": "granted",
      "consentTimestamp": "1668432971"
    },
    {
      "playerId": "sa_999d4baa",
      "displayName": "player2",
      "consentStatus": "denied",
      "consentTimestamp": "1668432972"
    }
  ],
  "playerReportEvents": [
    {
      "reportType": [ "loud voice" ],
      "reporterPlayerId": "sa_888d4baa",
      "reportedPlayerId": "sa_999d4baa",
      "reportReason": "Loud voice, disturbs the game"
    }
  ],
  "customMetadata": {
    "matchId": "some value"
  }
}'

在此示例中，history 为 15。这将为您提供 15 分钟的历史记录，从发出请求时算起。receiveResults 设置为 true，因此 S3 存储桶中将包含玩家在分析时的语音 .wav 文件。此外，还提交了 callbackUrl，因此在筛查完成后会发送回调。eventType 设置为 report，因为该筛查是根据玩家举报触发的。触发筛查的举报随付有 playerReportEvents 元数据。

另外，此示例还会提交所有参与玩家的玩家同意信息，因此只有其中一名玩家将被录制和分析。

在 customMetadata 对象中提交了自定义的 matchId，以便将筛查映射到游戏匹配。

在现有筛查中添加额外的举报事件

请参阅 OpenAPI 规范以了解有关终端的详细信息。

POST /safevoice/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/screenings/{screeningId}/player-report-events

路径参数

参数描述必需
organization要与 Safe Voice 集成的 UGS 组织的 Organization ID（组织 ID）。是
project要与 Safe Voice 集成的 UGS 项目的 Project ID（项目 ID）。是
environment要与 Safe Voice 集成的 UGS 环境的 Environment ID（环境 ID）。是

请求正文

请求正文包含以下字段：

字段描述必需
reportType用于定义举报类型的标签。是
reportReason事件描述。否
reportedPlayerId被举报的玩家的玩家 ID。请在[上文](#Player_IDs)中了解有关玩家 ID 的更多信息。否
reporterPlayerId发送举报的玩家的玩家 ID。请在[上文](#Player_IDs)中了解有关玩家 ID 的更多信息。是

以下是请求正文的示例：

{
  "reportType": ["loud voice"],
  "reporterPlayerId": "sa_888d4baa",
  "reportedPlayerId": "sa_999d4baa",
  "reportReason": "Loud voice, disturbs the game"
}

示例 API 调用

将举报附加到现有筛查

curl --request POST -H 'Authorization: Basic <Service Account Credentials>' -H 'Content-Type: application/json' 'https://services.api.unity.com/safevoice/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/screenings/{screeningId}/player-report-events' \
--data '{
  "reportType": [ "loud voice" ],
  "reporterPlayerId": "sa_888d4baa",
  "reportedPlayerId": "sa_999d4baa",
  "reportReason": "Loud voice, disturbs the game"
}'

查看筛查结果

对举报的筛查将产生一个会话，可在 Unity Dashboard（Unity 后台）的 Safe Voice > Sessions（会话）下进行查看。

如需有关后台原理的更多信息，请参阅以仲裁者身份使用 Safe Voice 页面。

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.