# 双方向 API を使用した出力イベントの処理
<a name="sonic-output-events"></a>

Amazon Nova Sonic モデルが応答する際は、構造化されたイベントシーケンスに従います。フローは、`sessionId`、`promptName`、`completionId` などの一意の識別子を含む `completionStart` イベントで始まります。これらの識別子はレスポンスサイクル全体で一貫性があり、後続のすべてのレスポンスイベントを統一します。

## 概要
<a name="sonic-output-overview"></a>

各レスポンスタイプは一貫した 3 つの部分からなるパターンに従います。`contentStart` は、コンテンツタイプと形式、実際のコンテンツイベントを定義し、`contentEnd` はそのセグメントを閉じます。レスポンスには、通常、自動音声認識 (ASR) 文字起こし (ユーザーの発言)、オプションのツールの使用 (外部情報が必要な場合)、テキストレスポンス (モデルの発言予定内容)、音声レスポンス (音声出力) の複数のコンテンツブロックが順番に含まれます。

## レスポンスコンテンツタイプ
<a name="sonic-response-content-types"></a>

### ASR 文字起こし
<a name="sonic-asr-transcription"></a>

ASR 文字起こしが最初に表示され、`contentStart` で `role: "USER"` および `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` を使用してモデルのユーザーの音声を理解できます。

### ツール使用
<a name="sonic-tool-use-response"></a>

モデルに外部データが必要な場合、特定のツール名とパラメータを含むツール関連のイベントが送信されます。

### テキストレスポンス
<a name="sonic-text-response"></a>

テキストレスポンスは、`role: "ASSISTANT"` と `"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"` で予定された音声のプレビューを提供します。

### 音声レスポンス
<a name="sonic-audio-response"></a>

その後、音声レスポンスは、ストリーム全体で同じ `contentId` を共有する、base64 でエンコードされた音声チャンクを配信します。

## 割り込みサポート
<a name="sonic-barge-in-support"></a>

オーディオ生成中、Amazon Nova Sonic は割り込み機能を通じて自然な会話フローをサポートします。Amazon Nova Sonic が話している間にユーザーがそれを中断すると、Nova Sonic は直ちに音声の生成を停止し、リッスンモードに切り替え、中断が発生したことを示すコンテンツ通知を送信します。Nova Sonic はリアルタイムよりも速く動作するため、一部のオーディオは配信済みでも再生されていない場合があります。中断通知により、クライアントアプリケーションはオーディオキューをクリアし、すぐに再生を停止できるため、応答性の高い会話エクスペリエンスが得られます。

## 最終文字起こし
<a name="sonic-final-transcription"></a>

音声生成が完了すると (または割り込みによって中断されると)、Amazon Nova Sonic は、実際に話された内容の文レベルの文字起こしを含む追加のテキストレスポンスを提供します。このテキストレスポンスには、`role: "ASSISTANT"` および `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` を含む `contentStart` イベントが含まれます。

## 使用状況の追跡
<a name="sonic-usage-tracking"></a>

レスポンス処理全体を通して、トークン消費を追跡するために `usageEvent` イベントが送信されます。これらのイベントには、入力トークンと出力トークン (音声とテキストの両方) の詳細なメトリクス、およびその累積合計が含まれます。各 `usageEvent` は、会話フローの他のイベントと同じ `sessionId`、`promptName`、および `completionId` を維持します。詳細セクションには、増分変更 (デルタ) とトークン使用率の累計の両方が表示され、会話中の使用率を正確にモニタリングできます。

## 完了
<a name="sonic-completion"></a>

モデルは、元の識別子と、会話が終了した仕方を示す `stopReason` を含む `completionEnd` イベントを送信します。このイベント階層により、アプリケーションはレスポンスのどの部分が一緒に属しているかを追跡し、それに応じて処理できるため、複数のターンにわたって会話コンテキストを維持できます。

出力イベントフローは、レスポンス生成フェーズに入ることから開始されます。自動音声認識で始まり、使用するツールを選択し、音声を書き起こし、音声を生成し、書き起こしを確定して、セッションを終了します。

![開始から、ASR、ツール処理、テキストとオーディオのレスポンスを通じて、関連付けられたイベントでの終了までの会話ステージを示すフロー図。](http://docs.aws.amazon.com/ja_jp/nova/latest/nova2-userguide/images/Output-Event -Flow_3.png)


## 出力イベントフロー
<a name="sonic-output-event-flow"></a>

出力イベントフローの構造については、このセクションで説明します。

### 1. UsageEvent
<a name="sonic-usage-event"></a>

```
"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
    }
}
```

### 2. CompleteStartEvent
<a name="sonic-completion-start-event"></a>

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

### 3. TextOutputContent
<a name="sonic-text-output-content"></a>

#### ContentStart
<a name="sonic-text-output-content-start"></a>

```
"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
<a name="sonic-text-output"></a>

```
"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
<a name="sonic-text-output-content-end"></a>

```
"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"
    }
}
```

### 4. ToolUse
<a name="sonic-tool-use-output"></a>

#### ContentStart
<a name="sonic-tool-use-content-start"></a>

```
"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
<a name="sonic-tool-use-event"></a>

```
"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
<a name="sonic-tool-use-content-end"></a>

```
"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"
    }
}
```

### 5. AudioOutputContent
<a name="sonic-audio-output-content"></a>

#### ContentStart
<a name="sonic-audio-output-content-start"></a>

```
"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
<a name="sonic-audio-output-event"></a>

```
"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
<a name="sonic-audio-output-content-end"></a>

```
"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"
    }
}
```

### 6. CompletionEndEvent
<a name="sonic-completion-end-event"></a>

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