# 完全なリクエストスキーマ
<a name="complete-request-schema"></a>

リクエストスキーマは、Invoke API (ストリーミングと非ストリーミング) と Converse API の間でほぼ同じです。画像および動画のペイロードエンコーディングには微妙な違いがあります。Amazon Nova Micro は画像や動画を入力としてサポートしていないため、リクエストスキーマのこれらの部分は Amazon Nova Micro には適用されません。それ以外の場合、リクエストスキーマはすべての Amazon Nova の理解モデルで同じです。

**重要**  
Amazon Nova への推論呼び出しのタイムアウト期間は 60 分です。デフォルトでは、AWS SDK クライアントは 1 分後にタイムアウトします。AWS SDK クライアントの読み取りタイムアウト期間を少なくとも 60 分に増やすことをお勧めします。例えば、AWS Python botocore SDK では、[botocore.config](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#) の `read_timeout`フィールドの値を少なくとも 3600 に変更します。  

```
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",
    config=Config(
        connect_timeout=3600,  # 60 minutes
        read_timeout=3600,     # 60 minutes
        retries={'max_attempts': 1}
    )
)
```

```
{
  "system": [
    {
      "text": "string"
    }
  ],
  "messages": [
    {
      "role": "user", //first turn should always be the user turn
      "content": [
        {
          "text": "string"
        },
        {
          "image": {
            "format": "jpeg" | "png" | "gif" | "webp",
            "source": {
              "bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
            }
          }
        },
        {
          "video": {
            "format": "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
            "source": {
              // Option 1: Sending a S3 location 
              "s3Location": {
                "uri": "string", // example: s3://my-bucket/object-key
                "bucketOwner": "string" // (Optional) example: "123456789012"
              },
              // Option 2: Sending file bytes 
              "bytes": video // Binary array (Converse API) or Base64-encoded string (Invoke API)
            }
          }
        },
        {
            "audio": {
                "format": "mp3" | "opus" | "wav" | "aac" | "flac" | "mp4" | "ogg" | "mkv",
                "source": {
                    // Option 1: Sending a S3 location 
                    "s3Location": {
                        "uri": "string", // example: s3://my-bucket/object-key
                        "bucketOwner": "string" // (Optional) example: "123456789012"
                    },
                    // Option 2: Sending file bytes 
                    "bytes": audio // Binary array (Converse API) or Base64-encoded string (Invoke API)
                }
            }
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "text": "string" //prefilling assistant turn
        }
      ]
    }
  ],
 "inferenceConfig":{ // all Optional, Invoke parameter names used in this example
    "maxTokens": int, // greater than 0, equal or less than 5k (default: dynamic*)
    "temperature": float, // greater than 0 and less than 1.0 (default: 0.7)
    "topP": float, // greater than 0, equal or less than 1.0 (default: 0.9)
    "topK": int, // 0 or greater (default: 50)
    "stopSequences": ["string"],
    "reasoningConfig": {
        "type": "string", //"enabled"/"disabled" (default: "disabled")
        "maxReasoningEffort": "string" // "low", "medium", "high"
    }
  },
  "toolConfig": { // all Optional
        "tools": [
            {
                "toolSpec": {
                    "name": "string", //meaningful tool name (Max char: 64)
                    "description": "string", //meaningful description of the tool
                    "inputSchema": {
                        "json": { // The JSON schema for the tool. For more information, see JSON Schema Reference
                            "type": "object",
                            "properties": {
                                "arg1": { //arguments 
                                    "type": "string", //argument data type
                                    "description": "string" //meaningful description
                                }
                            },
                            "required": [
                                "string" //args
                            ]
                        }
                    }
                }
            }
        ],
    },
    "toolChoice": { //can select one of three options
      "auto": {},
      "any": {},
      "tool": {
        "name": "string" //name of tool
      }
    }
}
```

次の内容は必須パラメータです。
+ `system` – (オプション) リクエストのシステムプロンプト。

  システムプロンプトは、特定の目標やロールの指定など、Amazon Nova にコンテキストおよび指示を与える方法です。
+ `messages` – (必須) 入力メッセージ。
  + `role` – 会話ターンのロール。有効な値は、`user` および `assistant` です。
  + `content` – (必須) 会話のコンテンツを含む [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) オブジェクトのリスト。各オブジェクトには、コンテンツのタイプ (`text`、`image`、`video`、または `audio`) を指定するキーが含まれています。オブジェクトの値は、キーのタイプによって異なります。サポートされているキーのタイプを以下に示します。
    + `text` – 会話ターンのテキストプロンプトの値が入った単一のフィールド `text` を含むオブジェクトにマッピングします。会話ターンに `image` または `video` オブジェクトも含まれている場合、`text` オブジェクトは画像または動画に付随するテキストプロンプトとして解釈されます。
    + `image` – (Amazon Nova Micro ではサポートされていません) 画像コンテンツを表し、次のフィールドを含むオブジェクトにマッピングします。
      + `format` – (必須) 画像形式。以下の画像形式を指定できます。
        + `jpeg`
        + `png`
        + `webp`
        + `gif`
      + `source` – (必須) 画像データ。Invoke API の場合、Base64 でエンコードされた画像文字列である必要があります。Converse API の場合、バイト配列である必要があります。
      + `bytes` – (必須) 画像データ。Invoke API の場合、Base64 でエンコードされた画像文字列である必要があります。Converse API の場合、バイト配列である必要があります。
    + `video` – (Amazon Nova Micro ではサポートされていません) 動画コンテンツを表し、次のフィールドを含むオブジェクトにマッピングします。
      + `format` – (必須) 動画形式。次の値を指定できます。
        + `mkv`
        + `mov`
        + `mp4`
        + `webm`
        + `three_gp`
        + `flv`
        + `mpeg`
        + `mpg`
        + `wmv`
      + `source` – (必須) 動画データのソース。リクエストで Amazon S3 URI または動画ファイルのバイトを指定できます。
        + `uri` – (必須) 動画ファイルの Amazon S3 URI。例: `“s3://my-bucket/object-key”`
        + `bucketOwner` – (オプション) バケットを所有しているアカウント ID。別のアカウントからモデルを呼び出す場合は、これを使用します。
        + `bytes` – (必須) 動画データ。Invoke API の場合、Base64 でエンコードされた動画文字列である必要があります。Converse API の場合、バイト配列である必要があります。
    + `audio` – ( のみ) 音声コンテンツを表し、次のフィールドを含むオブジェクトにマッピングします。
      + `format` – (必須) 音声形式。次の値を指定できます。
        + `aac`
        + `flac`
        + `mkv`
        + `mp3`
        + `mp4`
        + `ogg`
        + `opus`
        + `wav`
      + `source` – (必須) 音声データのソース。リクエストで Amazon S3 URI または音声ファイルのバイトを指定できます。
        + `uri` – (必須) 音声ファイルの Amazon S3 URI。例: `"s3://my-bucket/object-key"`
        + `bucketOwner` – (オプション) バケットを所有しているアカウント ID。別のアカウントからモデルを呼び出す場合は、これを使用します。
        + `bytes` – (必須) 音声データ。Invoke API の場合、Base64 でエンコードされた音声文字列である必要があります。Converse API の場合、バイト配列である必要があります。
+ `inferenceConfig:` 推論で渡すことができる推論設定値です。
  + `maxTokens` – (オプション) 停止する前に生成するトークンの最大数。

    Amazon Nova モデルは、`maxTokens` の値に達する前にトークンの生成を停止する場合があるので注意してください。許可される新しいトークンの最大値は 5K です。
  + `temperature` – (オプション) レスポンスに注入されるランダム性の量。有効な値は 0.00001 ～ 1 で、その範囲に限ります。デフォルト値は 0.7 です。
  + `topP` – (オプション) 中核サンプリングを使用します。

    Amazon Nova は、後続の各トークンのすべてのオプションに対する累積分布を確率の降順で計算し、`topP` で指定された特定の確率に達すると切り捨てます。`temperature` または `topP` のいずれかを変更する必要がありますが、両方を変更することはできません。有効な値は 0 ～ 1 で、その範囲に限ります。デフォルト値は 0.9 です。
  + `topK` – (オプション) 後続の各トークンの top K オプションによるサンプルのみ。

    `topK` パラメータを使用してロングテールの低確率レスポンスを削除します。有効な値は 0 ～ 128 です。デフォルト値は、このパラメータが使用されていないことです。
**注記**  
`topK` パラメータで Converse API を使用する際、追加の `inferenceConfig` パラメータを `additionalModelRequestFields` フィールドに含める必要があります。これらのパラメータが渡される方法の例については、「[Converse API の使用](using-converse-api.md)」を参照してください。
  + `stopSequences` – (オプション) 停止シーケンスを含む文字列の配列。モデルがこの文字列のいずれかを生成する場合、生成が停止されてその時点までのレスポンスが返されます。
  + `reasoningConfig` – (Amazon Nova Pro と Amazon Nova Lite のみ) 推論で渡すことができる推論設定値。
    + `type` – (オプション) 推論を有効または無効にするかどうか。有効なオプションは `enabled` または `disabled` です。デフォルト値は `disabled` です。
    + `maxReasoningEffort` – 推論プロセスで使用される計算労力。有効なオプションは `low`、`medium`、または `high` です。ストリーミングでは、`low` および `medium` 設定を使用する場合、推論コンテンツは `ConverseStream` の使用時に各トークンが生成されるたびにストリーミングされますが、`high` は異なる方法で動作し、品質を向上させるためにさまざまなアプローチを適用して、最終チャンク内にすべての推論コンテンツを出力します。
**注記**  
`reasoningConfig` パラメータとともに Converse API を使用する場合は、パラメータを `additionalModelRequestFields` フィールドに配置する必要があります。これらのパラメータが渡される方法の例については、「[Converse API の使用](using-converse-api.md)」を参照してください。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/nova/latest/userguide/complete-request-schema.html)
+ `toolConfig` – (オプション) ツール仕様およびツール選択を含む [ToolConfig スキーマ](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)に従う JSON オブジェクト。このスキーマは[Converse API が](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)続くものと同じです。
  + `toolChoice` – (オプション) モデルが使用できるツールを指定します。以下の 3 つのオプションから 1 つを選択できます。
    + `auto` – モデルは、ツールを使用するかどうか、およびどのツールを使用するかを自動的に決定します。
    + `any` – モデルは、提供されたツールの少なくとも 1 つを使用する必要があります。
    + `tool` – モデルは、名前で識別される特定のツールを使用する必要があります。

# レスポンス構造のハイライト
<a name="complete-request-schema-response"></a>

以下は、非ストリーミング `Converse` 関数と `InvokeModel` 関数によって返されるレスポンス構造の主要な要素を示しています。完全なレスポンス構造と、ストリーミング関数のリクエストとレスポンス構造の詳細については、API ドキュメントを参照してください。

```
{
    "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": [
                { // Optional
                    "reasoningContent": {
                        "reasoningText": {
                            "text": string
                        }
                    }
                },
                { // Optional
                    "toolUse": {
                        "toolUseId": string,
                        "name": string,
                        "input": object
                    }
                },
                { // Optional
                    "text": string
                },
                { // Optional
                    "image": {
                        "format": "png",
                        "source": {
                            "bytes": {
                                "bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
                            }
                        }
                    }
                }
            ]
        }
    },
    "stopReason": string, // "end_turn" | "content_filtered" | "max_tokens" | "malformed_model_output" | "malformed_tool_use" | etc.
    "usage": {
        "inputTokens": int,
        "outputTokens": int,
        "totalTokens": int
    },
    "metrics": {
        "latencyMs": int
    }
}
```

以下は主要なレスポンス要素です。
+ `output` – (必須) モデルのレスポンスメッセージが含まれます。
  + `message` – (必須) アシスタントのレスポンスメッセージです。
    + `content` – (必須) 以下を含むことができる 1 つ以上のコンテンツブロックの配列です。
      + `reasoningContent` – (オプション) 推論が有効になっている場合に返されます。推論テキストが含まれ、レスポンスでは常に `[REDACTED]` になります。
      + `toolUse` – (オプション) ツールが呼び出された場合に返されます。ツール使用 ID、名前、および入力引数が含まれます。
      + `text` – (オプション) モデルがテキストコンテンツで応答した場合に返されます。
      + `image` – (オプション、のみ) モデルが画像を生成した場合に返されます。生成される画像の形式は常に PNG になります。
+ `stopReason` – (必須) モデルが出力の生成を停止した理由を示す列挙値です。サポートされる値を次に示します。
  + `end_turn` – ターンの論理的な終了に達しました。
  + `max_tokens` – 出力は、ユーザーが設定した `maxTokens` 制限、またはモデル独自の最大出力トークン制限に達しました。
  + `content_filtered` – モデルの出力が AWS の責任ある AI ポリシーに違反しました。
  + `malformed_model_output` – モデルが無効な出力を生成しました。
  + `malformed_tool_use` – モデルが無効な `toolUse` 出力を生成しました。
  + `service_unavailable` – 組み込みツールサービスの 1 つにアクセスできませんでした。
  + `invalid_query` – モデルが組み込みの Web Grounding ツールに送信したクエリが無効でした。
  + `max_tool_invocations` – 組み込みツールが呼び出されましたが、複数回再試行しても有効な結果が生成されなかったことを示します。
+ `usage` – (必須) 入力トークン、出力トークン、合計トークンを含むトークン使用状況情報です。
+ `metrics` – (必須) ミリ秒単位の合計推論レイテンシーを含むパフォーマンスメトリクスです。