Response structure highlights - Amazon Nova

Response structure highlights

The following shows the key elements of the response structure returned by the non-streaming Converse and InvokeModel functions. For details on the full response structure as well as the request and response structures for the streaming functions, see the API documentation.

{
    "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
    }
}

The following are key response elements:

  • output – (Required) Contains the model's response message.

    • message – (Required) The assistant's response message.

      • content – (Required) An array of one or more content blocks that can include:

        • reasoningContent – (Optional) Returned if reasoning was enabled. Contains the reasoning text, which will always be [REDACTED] in the response.

        • toolUse – (Optional) Returned if a tool was called. Contains the tool use ID, name, and input arguments.

        • text – (Optional) Returned if the model responded with text content.

        • image – (Optional, only) Returned if the model generated an image. The format will always be PNG for images generated by .

  • stopReason – (Required) An enum value indicating why the model stopped generating output. Supported values include:

    • end_turn – The logical end of the turn was reached.

    • max_tokens – Output reached the maxTokens limit set by the user or the model's own maximum output token limit.

    • content_filtered – The model's output violated the AWS Responsible AI policy.

    • malformed_model_output – The model produced invalid output.

    • malformed_tool_use – The model produced invalid toolUse output.

    • service_unavailable – One of the built-in tool services could not be reached.

    • invalid_query – The query that the model sent to the built-in Web Grounding tool was invalid.

    • max_tool_invocations – Indicates a built-in tool was called but did not produce a valid result, even after multiple retries.

  • usage – (Required) Token usage information including input tokens, output tokens, and total tokens.

  • metrics – (Required) Performance metrics including the total inference latency in milliseconds.