Using the Converse API

The text field maps to a string specifying the prompt. The text field is interpreted alongside other fields that are specified in the same ContentBlock.

(Optional) For certain models, you can add cache checkpoints using cachePoint fields to utilize prompt caching. Prompt caching is a feature that enables you to begin caching the context of conversations to achieve cost and latency savings. For more information, see Prompt caching for faster model inference.

The following shows a Message object with a content array containing only a text ContentBlock:

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        }
    ]
}

The following shows a Message object with a content array containing a text ContentBlock and an optional cachePoint field. The content in the text ContentBlock is added to the cache as a result.

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

The image field maps to an ImageBlock. Pass the raw bytes, encoded in base64, for an image in the bytes field. If you use an AWS SDK, you don't need to encode the bytes in base64.

If you exclude the text field, the model describes the image.

(Optional) For certain models, you can add cache checkpoints using cachePoint fields to utilize prompt caching. Prompt caching is a feature that enables you to begin caching the context of conversations to achieve cost and latency savings. For more information, see Prompt caching for faster model inference.

The following shows a Message object with a content array containing only an image ContentBlock:

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        }
    ]
}

The following shows a Message object with a content array containing an image ContentBlock and an optional cachePoint field. The image content is added to the cache as a result.

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

The document field maps to an DocumentBlock. If you include a DocumentBlock, check that your request conforms to the following restrictions:

(Optional) For certain models, you can add cache checkpoints using cachePoint fields to utilize prompt caching. Prompt caching is a feature that enables you to begin caching the context of conversations to achieve cost and latency savings. For more information, see Prompt caching for faster model inference.

The following shows a Message object with a content array containing only a document ContentBlock and a required accompanying text ContentBlock.

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        }
    ]
}

The following shows a Message object with a content array containing a document ContentBlock and a required accompanying text ContentBlock, as well as a cachePoint that adds both the document and text contents to the cache.

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

The video field maps to a VideoBlock object. Pass the raw bytes in the bytes field, encoded in base64. If you use the AWS SDK, you don't need to encode the bytes in base64.

If you don't include the text field, the model will describe the video.

The following shows a Message object with a content array containing only a video ContentBlock.

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "bytes": "video in bytes"
                }
            }
        }
    ]
}

Note that for files with a .3gp extension, the format needs to be specified as three_gp.

You can also pass a video through an Amazon S3 URI instead of passing the bytes directly in the request body. The following shows a Message object with a content array containing only a video ContentBlock with the video source passed through an Amazon S3 URI.

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "s3Location": {
                        "uri": "${S3Uri}",
                        "bucketOwner": "${AccountId}"
                    }
                }
            }
        }
    ]
}

The s3Location parameter is only supported in the US East (N. Virginia) region.

The guardContent field maps to a GuardrailConverseContentBlock object. You can use this field to target an input to be evaluated by the guardrail defined in the guardrailConfig field. If you don't specify this field, the guardrail evaluates all messages in the request body. You can pass the following types of content in a GuardBlock:

For more information about using guardrails, see Stop harmful content in models using Amazon Bedrock Guardrails.

The reasoningContent field maps to a ReasoningContentBlock. This block contains content regarding the reasoning that was carried out by the model to generate the response in the accompanying ContentBlock.

The following shows a Message object with a content array containing only a ReasoningContentBlock and an accompanying text ContentBlock.

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "reasoningContent": {
                "reasoningText": {
                    "text": "string",
                    "signature": "string"
                }
                "redactedContent": "base64-encoded binary data object"
            }
        }
    ]
}

The ReasoningContentBlock contains the reasoning used to generate the accompanying content in the reasoningText field, in addition to any content in the reasoning that was encrypted by the model provider for trust and safety reasons in the redactedContent field.

Within the reasoningText field, the text fields describes the reasoning. The signature field is a hash of all the messages in the conversation and is a safeguard against tampering of the reasoning used by the model. You must include the signature and all previous messages in subsequent Converse requests. If any of the messages are changed, the response throws an error.

Contains information about a tool for the model to use. For more information, see Use a tool to complete an Amazon Bedrock model response.

Contains information about the result from the model using a tool. For more information, see Use a tool to complete an Amazon Bedrock model response.