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.

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

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

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.

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

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

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

{ "role": "user", "content": [ { "image": { "format": "png", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myImage", "bucketOwner": "111122223333" } } } } ] }

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

When using a document you can enable the citations tag, which will provide document specific citations in the response of the API call. See the DocumentBlock API for more details.

The following shows a sample 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", "name": "MyDocument", "source": { "bytes": "document in bytes" } } } ] }

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

{ "role": "user", "content": [ { "text": "string" }, { "document": { "format": "pdf", "name": "MyDocument", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myDocument", "bucketOwner": "111122223333" } } } } ] }

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 sample Message object with a content array containing only a video ContentBlock.

{ "role": "user", "content": [ { "video": { "format": "mp4", "source": { "bytes": "video in bytes" } } } ] }

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

{ "role": "user", "content": [ { "video": { "format": "mp4", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myVideo", "bucketOwner": "111122223333" } } } } ] }

You can add cache checkpoints as a block in a message alongside an accompanying prompt by using cachePoint fields to utilize prompt caching. Prompt caching is a feature that lets you 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 sample 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", "name": "string", "source": { "bytes": "document in bytes" } } }, { "cachePoint": { "type": "default" } } ] }

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 Detect and filter harmful content by 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.