請求和回應結構描述

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

完成請求結構

以下顯示 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 – (選用) 請求的系統提示詞。系統提示會提供內容和指示給 Amazon Nova，例如指定特定目標或角色。

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、webmthree_gp、flv、、 mpeg mpg或 wmv
  - source – （必要）透過 S3 URI (s3Location.uri 和選用 bucketOwner) 或檔案位元組 (bytes) 的視訊來源
- audio – （僅限 Amazon Nova Sonic 和 ) 具有下列項目的音訊內容：
  - format – （必要）音訊格式：mp3、opus、wav、aac、flacmp4、ogg、或 mkv
  - source – （必要）透過 S3 URI 或檔案位元組的音訊來源

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 – （選用） ToolConfiguration 結構描述之後的工具組態。

tools – 使用 name、 description和的工具規格陣列 inputSchema
toolChoice – （選用）控制工具選擇：
- auto – 模型決定是否要使用哪些工具
- any – 模型必須至少使用一個工具
- 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 – （必要）包含模型的回應訊息。

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

stopReason – （必要）指出模型停止產生輸出的原因：

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

usage – （必要）字符用量資訊：

inputTokens – 模型擷取的字符總數
outputTokens – 產生的字符數量
totalTokens – 輸入和輸出字符的總和

metrics – （必要）效能指標：

latencyMs – 推論完成時間總計，以毫秒為單位

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

API 和 SDK 參考

SDK 參考