# 请求和响应架构
<a name="request-response-schema"></a>

Invoke API 和 Converse API 之间的请求架构几乎相同。主要区别在于二进制数据（图像、视频、音频）的编码方式：Converse API 使用二进制数组，而 Invoke API 使用 Base64 编码的字符串。

## 完整请求结构
<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` 中。

以下章节详细说明了每个请求参数：

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

`system` –（可选）请求的系统提示。系统提示词为 Amazon Nova 提供上下文信息和操作指令，例如指定特定的目标或角色。

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

`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
<a name="inferenceconfig-parameter"></a>

`inferenceConfig`：（选填）控制模型输出生成的配置参数。
+ `maxTokens`：（选填）停止前要生成的最大词元数量。Amazon Nova 模型可能会在达到此限制之前停止。最大值为 5,000。未指定时，将根据请求上下文使用动态默认值。
+ `temperature`：（选填）响应的随机性。有效范围：0.00001 – 1（默认值：0.7）。数值越低，输出结果越具确定性。
+ `topP`：（选填）核采样阈值。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
<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 负责任的人工智能政策
+ `malformed_model_output`：模型生成无效输出
+ `malformed_tool_use`：模型生成无效的工具使用输出
+ `service_unavailable`：无法访问内置工具服务
+ `invalid_query`：对内置工具的查询无效
+ `max_tool_invocations`：内置工具重试后仍未生成有效结果

### usage
<a name="usage-response"></a>

`usage`：（必填）词元使用信息：
+ `inputTokens`：模型处理的输入词元总数
+ `outputTokens`：生成的词元数量
+ `totalTokens`：输入词元数与输出词元数之和

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

`metrics`：（必填）性能指标：
+ `latencyMs`：推理总耗时（毫秒）