本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
使用雙向 API 處理輸出事件
當 Amazon Nova Sonic 模型回應時,它會遵循結構化事件序列。流程從包含唯一識別符completionStart
的事件開始,例如 sessionId
、 promptName
和 completionId
。這些識別符在整個回應週期中是一致的,並統一所有後續的回應事件。
每個回應類型都遵循一致的三部分模式: contentStart
定義內容類型和格式、實際的內容事件,並contentEnd
關閉該區段。回應通常會依序包含多個內容區塊:自動語音辨識 (ASR) 轉錄 (使用者說的話)、選用的工具使用 (需要外部資訊時)、文字回應 (模型打算說的話) 和音訊回應 (口語輸出)。
ASR 轉錄會先出現,透過 role: "USER"
和 "additionalModelFields": "{\"generationStage\":\"FINAL\"}"
提供模型對使用者語音的了解contentStart
。當模型需要外部資料時,它會傳送具有特定工具名稱和參數的工具相關事件。文字回應提供使用 role: "ASSISTANT"
和 的規劃語音預覽"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"
。然後,音訊回應會在整個串流contentId
中交付共用相同的 base64 編碼語音區塊。
在音訊產生期間,Amazon Nova Sonic 透過其插斷功能支援自然對話流程。當使用者在說話時中斷 Amazon Nova Sonic 時,Nova Sonic 會立即停止產生語音、切換到接聽模式,並傳送內容通知,指出已發生中斷。由於 Nova Sonic 的運作速度比即時快,因此有些音訊可能已交付但尚未播放。中斷通知可讓用戶端應用程式清除其音訊佇列並立即停止播放,進而建立回應式對話體驗。
音訊產生完成後 (或透過插入中斷),Amazon Nova Sonic 會提供額外的文字回應,其中包含實際說話內容的句子層級轉錄。此文字回應包含具有 role: "ASSISTANT"
和 contentStart
的事件"additionalModelFields": "{\"generationStage\":\"FINAL\"}"
。
在整個回應處理過程中,會傳送usageEvent
事件來追蹤字符消耗。這些事件包含輸入字符和輸出字符 (語音和文字) 及其累積總計的詳細指標。每個 都會usageEvent
維護completionId
與對話流程中其他事件相同的 sessionId
promptName
、 和 。詳細資訊區段同時提供增量變更 (差異) 和執行的字符用量總計,以便在對話期間精確監控用量。
模型會傳送具有原始識別符completionEnd
的事件,以及指出對話結束方式stopReason
的 。此事件階層可確保您的應用程式可以追蹤回應的哪些部分屬於一起,並相應地處理它們,在多個回合中保持對話內容。
輸出事件流程從進入回應產生階段開始。它從自動語音辨識開始,選取要使用的工具、轉錄語音、產生音訊、完成轉錄,以及完成工作階段。

輸出事件流程
本節說明輸出事件流程的結構。
-
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 } }
-
CompleteStartEvent
"event": { "completionStart": { "sessionId": "string", // unique identifier "promptName": "string", // same unique identifier from promptStart event "completionId": "string", // unique identifier } }
-
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" } }
-
-
ToolUse
-
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" } } }
-
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" } }
-
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" } }
-
-
AudioOutputContent
-
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 } } }
-
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 } }
-
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" } }
-
-
CompletionEndEvent
"event": { "completionEnd": { "sessionId": "string", // unique identifier "promptName": "string", // same unique identifier from promptStart event "completionId": "string", // unique identifier "stopReason": "END_TURN" } }