# 使用双向 API 处理输出事件
<a name="output-events"></a>

**注意**  
本文档适用于 Amazon Nova 版本 1。如需 Amazon Nova 2 Sonic 指南，请访问[使用双向 API 处理输出事件](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-output-events.html)。

Amazon Nova Sonic 模型回复问题时会遵循结构化事件序列。该流程以包含 `sessionId`、`promptName` 和 `completionId` 等唯一标识符的 `completionStart` 事件开始。这些标识符在整个回复周期中保持一致，并统一了后续的所有回复事件。

每种回复类型都遵循一致的三部分模式：`contentStart` 定义内容类型和格式，接着是实际的内容事件，然后以 `contentEnd` 结束该部分。回复通常按顺序包括多个内容块：自动语音识别（ASR）转录（即用户所说的话）、可选的“工具使用”（即需要外部信息时）、文本回复（即模型计划要说的话）和音频回复（即语音输出）。

ASR 转录会首先显示，在 `contentStart` 中通过 `role: "USER"` 和 `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` 提供模型对用户语音的理解。模型需要外部数据时，它会发送包含特定工具名称和参数的工具相关事件。文本回复通过 `role: "ASSISTANT"` 和 `"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"` 提供计划语音的预览。然后，音频回复会传送 base64 编码的语音片段，并在整个流中共享相同的 `contentId`。

在音频生成过程中，Amazon Nova Sonic 通过其可插入对话的功能来支持自然的对话流程。如果用户中断正在说话的 Amazon Nova Sonic，Nova Sonic 会立即停止生成语音，切换到聆听模式，并发送内容通知，表明已发生中断。由于 Nova Sonic 的运行速度比实时速度更快，有些音频可能已经传送但尚未播放。中断通知让客户端应用程序能够清除其音频队列并立即停止播放，从而打造回复式对话体验。

音频生成完成（或通过插入功能中断）后，Amazon Nova Sonic 会提供额外的文本回复，其中包含实际说话内容的句子级转录。此文本回复包括带有 `role: "ASSISTANT"` 和 `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` 的 `contentStart` 事件。

在整个响应处理过程中，会发送 `usageEvent` 事件来跟踪令牌消耗情况。这些事件包含输入令牌和输出令牌（语音和文本）的详细指标及其累计总数。每个 `usageEvent` 都与对话流中的其他事件保持相同的 `sessionId`、`promptName`、和 `completionId`。详细信息部分提供令牌使用情况的增量变化 (delta) 和运行合计，从而能够精确监控对话期间的使用情况。

模型会发送一个 `completionEnd` 事件，其中包含原始标识符以及表明对话如何结束的 `stopReason`。此事件层次结构确保应用程序可以跟踪回复的哪些部分属于同一部分并相应地加以处理，从而在多个回合中维护对话上下文。

输出事件流程从进入回复生成阶段开始。该流程从自动语音识别开始，选择要使用的工具，转录语音，生成音频，完成转录，然后完成会话。

![示意图，其中解释了 Amazon Nova Sonic 输出事件流程。](http://docs.aws.amazon.com/zh_cn/nova/latest/userguide/images/output-events.png)


## 输出事件流程
<a name="output-event-flow"></a>

本节介绍了输出事件流程的结构。

1. `UsageEvent`

   ```
   "event": {
       "usageEvent": {
           "completionId": "string", // unique identifier for completion
           "details": {
               "delta": { // incremental changes since last event
                   "input": {
                       "speechTokens": number, // input speech tokens
                       "textTokens": number // input text tokens
                   },
                   "output": {
                       "speechTokens": number, // speech tokens generated
                       "textTokens": number // text tokens generated
                   }
               },
               "total": { // cumulative counts
                   "input": {
                       "speechTokens": number, // total speech tokens processed
                       "textTokens": number // total text tokens processed
                   },
                   "output": {
                       "speechTokens": number, // total speech tokens generated
                       "textTokens": number // total text tokens generated
                   }
               }
           },
           "promptName": "string", // same unique identifier from promptStart event
           "sessionId": "string", // unique identifier
           "totalInputTokens": number, // cumulative input tokens
           "totalOutputTokens": number, // cumulative output tokens
           "totalTokens": number // total tokens in the session
       }
   }
   ```

1. `CompleteStartEvent`

   ```
   "event": {
           "completionStart": {
               "sessionId": "string", // unique identifier
               "promptName": "string", // same unique identifier from promptStart event
               "completionId": "string", // unique identifier
           }
       }
   ```

1. `TextOutputContent`
   + `ContentStart`

     ```
     "event": {
             "contentStart": {
                 "additionalModelFields": "{\"generationStage\":\"FINAL\"}" | "{\"generationStage\":\"SPECULATIVE\"}",
                 "sessionId": "string", // unique identifier
                 "promptName": "string", // same unique identifier from promptStart event
                 "completionId": "string", // unique identifier
                 "contentId": "string", // unique identifier for the content block
                 "type": "TEXT",
                 "role": "USER" | "ASSISTANT",
                 "textOutputConfiguration": {
                     "mediaType": "text/plain"
                 }
             }
         }
     ```
   + `TextOutput`

     ```
     "event": {
             "textOutput": {
                 "sessionId": "string", // unique identifier
                 "promptName": "string", // same unique identifier from promptStart event
                 "completionId": "string", // unique identifier
                 "contentId": "string", // same unique identifier from its contentStart
                 "content": "string" // User transcribe or Text Response
             }
         }
     ```
   + `ContentEnd`

     ```
     "event": {
         "contentEnd": {
                 "sessionId": "string", // unique identifier
                 "promptName": "string", // same unique identifier from promptStart event
                 "completionId": "string", // unique identifier
                 "contentId": "string", // same unique identifier from its contentStart
                 "stopReason": "PARTIAL_TURN" | "END_TURN" | "INTERRUPTED",
                 "type": "TEXT"
         }
       }
     ```

1. `ToolUse`

   1. `ContentStart`

      ```
      "event": {
          "contentStart": {
            "sessionId": "string", // unique identifier
            "promptName": "string", // same unique identifier from promptStart event
            "completionId": "string", // unique identifier
            "contentId": "string", // unique identifier for the content block
            "type": "TOOL",
            "role": "TOOL",
            "toolUseOutputConfiguration": {
              "mediaType": "application/json"
            }
          }
        }
      ```

   1. `ToolUse`

      ```
      "event": {
          "toolUse": {
            "sessionId": "string", // unique identifier
            "promptName": "string", // same unique identifier from promptStart event
            "completionId": "string", // unique identifier
            "contentId": "string", // same unique identifier from its contentStart
            "content": "json",
            "toolName": "string",
            "toolUseId": "string"
          }
        }
      ```

   1. `ContentEnd`

      ```
      "event": {
          "contentEnd": {
            "sessionId": "string", // unique identifier
            "promptName": "string", // same unique identifier from promptStart event
            "completionId": "string", // unique identifier
            "contentId": "string", // same unique identifier from its contentStart
            "stopReason": "TOOL_USE",
            "type": "TOOL"
          }
        }
      ```

1. `AudioOutputContent`

   1. `ContentStart`

      ```
      "event": {
          "contentStart": {
            "sessionId": "string", // unique identifier
            "promptName": "string", // same unique identifier from promptStart event
            "completionId": "string", // unique identifier
            "contentId": "string", // unique identifier for the content block
            "type": "AUDIO",
            "role": "ASSISTANT",
            "audioOutputConfiguration": {
                  "mediaType": "audio/lpcm",
                  "sampleRateHertz": 8000 | 16000 | 24000,
                  "sampleSizeBits": 16,
                  "encoding": "base64",
                  "channelCount": 1
                  }
            }
        }
      ```

   1. `AudioOutput`

      ```
      "event": {
              "audioOutput": {
                  "sessionId": "string", // unique identifier
                  "promptName": "string", // same unique identifier from promptStart event
                  "completionId": "string", // unique identifier
                  "contentId": "string", // same unique identifier from its contentStart
                  "content": "base64EncodedAudioData", // Audio
              }
          }
      ```

   1. `ContentEnd`

      ```
      "event": {
          "contentEnd": {
            "sessionId": "string", // unique identifier
            "promptName": "string", // same unique identifier from promptStart event
            "completionId": "string", // unique identifier
            "contentId": "string", // same unique identifier from its contentStart
            "stopReason": "PARTIAL_TURN" | "END_TURN",
            "type": "AUDIO"
          }
        }
      ```

1. `CompletionEndEvent`

   ```
   "event": {
       "completionEnd": {
         "sessionId": "string", // unique identifier
         "promptName": "string", // same unique identifier from promptStart event
         "completionId": "string", // unique identifier
         "stopReason": "END_TURN" 
       }
     }
   ```