# リクエストとレスポンスのスキーマ
リクエストスキーマは、Invoke API と Converse API の間でほぼ同じです。主な違いは、バイナリデータ (画像、動画、オーディオ) のエンコード方法です。Converse API はバイナリ配列を使用し、Invoke API は Base64 でエンコードされた文字列を使用します。
## 完全なリクエスト構造
Amazon Nova モデルの完全なリクエスト構造を次に示します。必須としてマークされていない限り、すべてのフィールドはオプションです。
```
{
"system": [
{
"text": "string"
}
],
"messages": [ // Required
{
"role": "user", // Required - first turn must be user
"content": [ // Required
{
"text": "string"
},
{
"image": {
"format": "jpeg" | "png" | "gif" | "webp", // Required
"source": { // Required
"bytes": image // Binary array (Converse) or Base64 string (Invoke)
}
}
},
{
"video": {
"format": "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
"source": {
// Option 1: S3 location
"s3Location": {
"uri": "string", // e.g., s3://my-bucket/object-key
"bucketOwner": "string" // Optional, e.g., "123456789012"
},
// Option 2: File bytes
"bytes": video // Binary array (Converse) or Base64 string (Invoke)
}
}
},
{
"audio": { // Nova 2 Omni and Sonic only
"format": "mp3" | "opus" | "wav" | "aac" | "flac" | "mp4" | "ogg" | "mkv",
"source": {
// Option 1: S3 location
"s3Location": {
"uri": "string",
"bucketOwner": "string" // Optional
},
// Option 2: File bytes
"bytes": audio // Binary array (Converse) or Base64 string (Invoke)
}
}
}
]
},
{
"role": "assistant",
"content": [
{
"text": "string" // For prefilling assistant response
}
]
}
],
"inferenceConfig": { // All optional
"maxTokens": int, // 1-5000, default: dynamic
"temperature": float, // 0.00001-1, default: 0.7
"topP": float, // 0-1, default: 0.9
"topK": int, // 0-128, default: not used
"stopSequences": ["string"],
"reasoningConfig": { // Nova 2 Lite and Sonic only
"type": "enabled" | "disabled", // default: "disabled"
"maxReasoningEffort": "low" | "medium" | "high"
}
},
"toolConfig": { // Optional
"tools": [
{
"toolSpec": {
"name": "string", // Max 64 characters
"description": "string",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"arg1": {
"type": "string",
"description": "string"
}
},
"required": ["string"]
}
}
}
}
],
"toolChoice": { // Choose one option
"auto": {},
"any": {},
"tool": {
"name": "string"
}
}
}
}
```
主要なリクエストパラメータ:
+ `system`: コンテキストと指示を提供するシステムプロンプト
+ `messages`: ロール (ユーザーまたはアシスタント) とコンテンツを含む会話ターンの配列
+ `inferenceConfig`: モデルの出力動作 (温度、トークンなど) を制御します
+ `toolConfig`: 関数呼び出しのツール仕様
**注記**
Converse API を使用する場合は、`topK` パラメータと `reasoningConfig` パラメータを `inferenceConfig` の代わりに `additionalModelRequestFields` に配置する必要があります。
以下のセクションでは、各リクエストパラメータの詳細な説明を示します。
### system
`system` – (オプション) リクエストのシステムプロンプト。システムプロンプトは、Amazon Nova にコンテキストおよび指示 (特定の目標やロールの指定など) を提供します。
### messages
`messages` – (必須) 会話ターンを含む入力メッセージ配列。
+ `role` – (必須) 会話ターンのロール。有効な値は、`user` および `assistant` です。最初のメッセージは常に `user` ロールを使用する必要があります。
+ `content` – (必須) コンテンツブロックの配列。各ブロックはコンテンツタイプ (`text`、`image`、`video`、または `audio`) を指定します。
+ `text` – 会話ターンのテキストコンテンツ。画像または動画と組み合わせると、付随するテキストとして解釈されます。
+ `image` – (Nova 2 Lite ではサポートされていません) 以下を含む画像コンテンツ:
+ `format` – (必須) 画像形式: `jpeg`、`png`、`webp` または `gif`
+ `source.bytes` – (必須) バイナリ配列 (Converse API) または Base64 文字列 (Invoke API) としての画像データ
+ `video` – (Nova 2 Lite ではサポートされていません) 以下を含む動画コンテンツ。
+ `format` – (必須) 動画形式: `mkv`、`mov`、`mp4`、`webm`、`three_gp`、`flv`、`mpeg`、`mpg`、または `wmv`
+ `source` – (必須) S3 URI (`s3Location.uri` およびオプションの `bucketOwner`) またはファイルバイト (`bytes`) を介した動画ソース
+ `audio` – (Amazon Nova Sonic のみ) 以下を含むオーディオコンテンツ。
+ `format` – (必須) オーディオ形式: `mp3`、`opus`、`wav`、`aac`、`flac`、`mp4`、`ogg` または `mkv`
+ `source` – (必須) S3 URI またはファイルバイト経由のオーディオソース
### inferenceConfig
`inferenceConfig` – (オプション) モデル出力の生成を制御する設定パラメータ。
+ `maxTokens` – (オプション) 停止する前に生成する最大トークン数。Amazon Nova モデルは、この制限に達する前に停止することがあります。最大値は 5,000 です。指定しない場合、リクエストコンテキストに基づいて動的デフォルトを使用します。
+ `temperature` – (オプション) レスポンスのランダム性。有効な範囲: 0.00001～1 (デフォルト: 0.7)。値を小さくすると、より決定的な出力が生成されます。
+ `topP` – (オプション) Nucleus サンプリングしきい値。Amazon Nova は、累積確率が `topP` に達するトークンからサンプリングを行います。有効範囲: 0～1 (デフォルト: 0.9)。`temperature` または `topP` のいずれか (両方ではなく) を調整します。
+ `topK` – (オプション) 上位 K トークンからのみサンプリングを行います。確率の低いレスポンスを削除します。有効な範囲: 0～128 (デフォルト: 使用しません)。
**注記**
Converse API の場合は、`additionalModelRequestFields` で `topK` を渡します。
+ `stopSequences` – (オプション) 発生時に生成を停止する文字列の配列。
+ `reasoningConfig` – (Amazon Nova Sonic のみ) 推論設定:
+ `type` – (オプション) `enabled`または `disabled` (デフォルト: `disabled`)
+ `maxReasoningEffort` – 計算労力: `low`、`medium`、または `high`。`low` と `medium` では、推論は増分的にストリーミングされます。`high` は推論を最終チャンクに出力します。
**注記**
Converse API の場合は、`additionalModelRequestFields` で `reasoningConfig` を渡します。
### toolConfig
`toolConfig` – (オプション) [ToolConfiguration スキーマ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)に続くツール設定。
+ `tools` – `name`、`description` および `inputSchema` を使用したツール仕様の配列
+ `toolChoice` – (オプション) 次のツールの選択を制御します。
+ `auto` – モデルは、ツールを使用するか否か、および使用するツールを決定します
+ `any` – モデルは少なくとも 1 つのツールを使用する必要があります
+ `tool` – モデルは指定されたツールを名前で使用する必要があります
## 完全なレスポンス構造
Amazon Nova モデルの完全なレスポンス構造を次に示します。
```
{
"ResponseMetadata": {
"RequestId": "string",
"HTTPStatusCode": int,
"HTTPHeaders": {
"date": "string",
"content-type": "application/json",
"content-length": "string",
"connection": "keep-alive",
"x-amzn-requestid": "string"
},
"RetryAttempts": 0
},
"output": {
"message": {
"role": "assistant",
"content": [
{
"reasoningContent": { // Optional - if reasoning enabled
"reasoningText": {
"text": "[REDACTED]"
}
}
},
{
"toolUse": { // Optional - if tool called
"toolUseId": "string",
"name": "string",
"input": {} // Tool-specific arguments
}
},
{
"text": "string" // Optional - text response
},
{
"image": { // Optional - Nova 2 Omni only
"format": "png",
"source": {
"bytes": image // Binary array (Converse) or Base64 string (Invoke)
}
}
}
]
}
},
"stopReason": "string", // See stop reasons below
"usage": {
"inputTokens": int,
"outputTokens": int,
"totalTokens": int
},
"metrics": {
"latencyMs": int
}
}
```
停止理由:
+ `end_turn`: レスポンスが自然に終了した
+ `max_tokens`: maxTokens の上限に達した
+ `content_filtered`: コンテンツポリシーに違反した
+ `malformed_model_output`:モデル出力が無効
+ `malformed_tool_use`: ツール使用出力が無効
+ `service_unavailable`: 組み込みツールサービスにアクセスできない
+ `invalid_query`: 組み込みツールへのクエリが無効
+ `max_tool_invocations`: ツールの再試行回数を使い切った
以下のセクションでは、各レスポンスフィールドの詳細な説明を示します。
### output
`output` – (必須) モデルのレスポンスメッセージが含まれます。
+ `message` – (必須) ロールとコンテンツ配列を含むアシスタントの応答メッセージ。
+ `content` – (必須) 以下を含むことができる 1 つ以上のコンテンツブロックの配列:
+ `reasoningContent` – (オプション) 推論が有効になっている場合に返されます。推論テキストが含まれ、レスポンスでは常に `[REDACTED]` になります。
+ `toolUse` – (オプション) ツールが呼び出された場合に返されます。ツール使用 ID、名前、および入力引数が含まれます。
+ `text` – (オプション) モデルがテキストコンテンツで応答した場合に返されます。
+ `image` – (オプション、のみ) モデルが画像を生成した場合に返されます。形式は常に PNG です。
### stopReason
`stopReason` – (必須) モデルが出力の生成を停止した理由を示します。
+ `end_turn` – レスポンスが自然に終了した
+ `max_tokens` – maxTokens 上限またはモデルの最大出力制限に達した
+ `content_filtered` – 出力が AWS 責任ある AI ポリシーに違反している
+ `malformed_model_output` – モデルが無効な出力を生成した
+ `malformed_tool_use` – モデルが無効なツール使用の出力を生成した
+ `service_unavailable` – 組み込みツールサービスにアクセスできなかった
+ `invalid_query` – 組み込みツールへのクエリが無効
+ `max_tool_invocations` – 組み込みツールが再試行後に有効な結果を生成しなかった
### usage
`usage` – (必須) トークンの使用情報:
+ `inputTokens` – モデルによって取り込まれたトークンの合計
+ `outputTokens` – 生成されたトークンの数
+ `totalTokens` – 入力トークンと出力トークンの合計
### metrics
`metrics` – (必須) パフォーマンスメトリクス:
+ `latencyMs` – ミリ秒単位の合計推論完了時間