本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 請求和回應結構描述
<a name="request-response-schema"></a>

叫用 API 和 Converse API 之間的請求結構描述幾乎相同。主要差異在於二進位資料 （影像、影片、音訊） 的編碼方式：Converse API 使用二進位陣列，而叫用 API 使用 Base64-encoded字串。

## 完成請求結構
<a name="complete-request-structure"></a>

以下顯示 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` 參數放置在 中，`additionalModelRequestFields`而不是 `inferenceConfig`。

以下各節提供每個請求參數的詳細說明：

### system
<a name="system-parameter"></a>

`system` – (選用) 請求的系統提示詞。系統提示會提供內容和指示給 Amazon Nova，例如指定特定目標或角色。

### messages
<a name="messages-parameter"></a>

`messages` – （必要） 包含對話轉彎的輸入訊息陣列。
+ `role` – （必要） 對話輪換的角色。有效值為 `user` 和 `assistant`。第一個訊息必須一律使用 `user`角色。
+ `content` – （必要） 內容區塊的陣列。每個區塊指定內容類型 (`text`、`video`、 `image`或 `audio`)：
  + `text` – 對話回合的文字內容。如果 與影像或視訊結合， 會解譯為隨附的文字。
  + `image` – （不支援 Nova 2 Lite) 具有下列項目的影像內容：
    + `format` – （必要） 影像格式：`jpeg`、`webp`、 `png`或 `gif`
    + `source.bytes` – （必要） 影像資料為二進位陣列 (Converse API) 或 Base64 字串 （叫用 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
<a name="inferenceconfig-parameter"></a>

`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，請傳入 `topK` `additionalModelRequestFields`。
+ `stopSequences` – （選用） 字串陣列，會在遇到時停止產生。
+ `reasoningConfig` – （僅限 Amazon Nova Sonic 和 ) 原因組態：
  + `type` – （選用） `enabled`或 `disabled`（預設：`disabled`)
  + `maxReasoningEffort` – 運算工作：`medium`、 `low`或 `high`。使用 `low`和 `medium`，以增量方式推理串流；在最終區塊中`high`輸出推理。
**注意**  
針對 Converse API，請傳入 `reasoningConfig` `additionalModelRequestFields`。

### toolConfig
<a name="toolconfig-parameter"></a>

`toolConfig` – （選用） [ToolConfiguration 結構描述之後的工具](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)組態。
+ `tools` – 使用 `name`、 `description`和 的工具規格陣列 `inputSchema`
+ `toolChoice` – （選用） 控制工具選擇：
  + `auto` – 模型決定是否要使用哪些工具
  + `any` – 模型必須至少使用一個工具
  + `tool` – 模型必須使用指定的工具名稱

## 完整的回應結構
<a name="complete-response-structure"></a>

以下顯示 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
<a name="output-response"></a>

`output` – （必要） 包含模型的回應訊息。
+ `message` – （必要） 具有角色和內容陣列的助理回應訊息。
+ `content` – （必要） 內容區塊陣列，可包含：
  + `reasoningContent` – （選用） 如果已啟用推理，則傳回。包含推理文字，一律會在回應`[REDACTED]`中。
  + `toolUse` – （選用） 如果呼叫工具，則傳回。包含工具使用 ID、名稱和輸入引數。
  + `text` – （選用） 如果模型以文字內容回應，則傳回。
  + `image` – （選用，僅限） 如果模型產生映像，則傳回。格式一律為 PNG。

### stopReason
<a name="stopreason-response"></a>

`stopReason` – （必要） 指出模型停止產生輸出的原因：
+ `end_turn` – 已到達自然結束回應
+ `max_tokens` – 達到 maxTokens 限制或模型的最大輸出限制
+ `content_filtered` – 輸出違反 AWS 責任 AI 政策
+ `malformed_model_output` – 模型產生無效的輸出
+ `malformed_tool_use` – 模型產生的無效工具使用輸出
+ `service_unavailable` – 無法連線內建工具服務
+ `invalid_query` – 對內建工具的查詢無效
+ `max_tool_invocations` – 內建工具在重試後未產生有效結果

### 使用方式
<a name="usage-response"></a>

`usage` – （必要） 字符用量資訊：
+ `inputTokens` – 模型擷取的字符總數
+ `outputTokens` – 產生的字符數量
+ `totalTokens` – 輸入和輸出字符的總和

### 指標
<a name="metrics-response"></a>

`metrics` – （必要） 效能指標：
+ `latencyMs` – 推論完成時間總計，以毫秒為單位