请求和响应架构

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 参数必须放置在 additionalModelRequestFields 中，不能放置在 inferenceConfig 中。

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

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

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：（选填）控制模型输出生成的配置参数。

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：（选填）遵循 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 负责任的人工智能政策
malformed_model_output：模型生成无效输出
malformed_tool_use：模型生成无效的工具使用输出
service_unavailable：无法访问内置工具服务
invalid_query：对内置工具的查询无效
max_tool_invocations：内置工具重试后仍未生成有效结果

usage：（必填）词元使用信息：

inputTokens：模型处理的输入词元总数
outputTokens：生成的词元数量
totalTokens：输入词元数与输出词元数之和

metrics：（必填）性能指标：

latencyMs：推理总耗时（毫秒）

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

API 和 SDK 参考

SDK 参考