> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bedrock API Part 2
> Compares Bedrock InvokeModel low-level model-specific API with Converse high-level message-based API, explaining use cases, examples, and best practices for invoking foundation models.
This lesson shows how to make inference requests with the Amazon Bedrock Runtime client and compares the two primary ways to call foundation models:
* InvokeModel — a low-level, model-specific API that gives full control over the request body.
* Converse — a higher-level, standardized, message-based API designed for chat and multi-turn interactions.
Both have use cases depending on whether you need model-specific features or a portable chat-style interface.
## InvokeModel
InvokeModel is a low-level API that accepts a model-specific JSON payload. Use it when you need fine-grained control (for example, image-generation options, custom token settings, or other model-specific fields). Because the payload is tailored to the model, it is not guaranteed to be portable across different models or vendors.
Example (InvokeModel):
```python theme={null}
import json
response = client.invoke_model(
modelId="model-id",
body=json.dumps(body)
)
```
Key points:
* Supply `modelId` (the model's programmatic identifier).
* The `body` is a JSON string (commonly produced by `json.dumps()` from a Python dict).
* Payload structure and supported fields are model-specific.
## Converse
Converse is a high-level API built around a unified `messages` structure. Each message contains a `role` (for example, `"user"`, `"assistant"`, or `"system"`) and `content` items (for example, `{"type": "text", "text": "..."}`). This abstraction makes payloads portable across models and vendors, simplifying multi-turn and chat-style workflows.
Example (Converse):
```python theme={null}
response = client.converse(
modelId="us.meta.llama3-2-3b-instruct-v1:0",
messages=[
{
"role": "user",
"content": [{"type": "text", "text": "Explain Bedrock in 2 sentences."}]
}
]
)
```
Key points:
* Use `messages` with roles (`"user"`, `"system"`, `"assistant"`).
* Content items typically include a `type` (such as `"text"`) and the payload text.
* Converse is ideal for conversational flows, multi-turn sessions, or instruction-style prompts.
* The unified format improves portability between models and cloud vendors.
## When to use which
* Use InvokeModel when you need model-specific parameters or nonstandard inputs.
* Use Converse for chat, multi-turn interactions, or when you want a portable, standardized message format.
Quick comparison:
| Area | InvokeModel (low-level) | Converse (high-level) |
| - | - | - |
| Input format | Model-specific JSON | Standardized `messages` (role + content) |
| Best for | Model-specific features, custom parameters | Chat, multi-turn, cross-model portability |
| Ease of use | Requires adapting to each model | Unified API surface, simpler payloads |
| Cross-model portability | Low | High |
## Full example: InvokeModel with boto3 (Python)
The following concise example demonstrates creating a Bedrock Runtime client, building a model-specific body, calling `invoke_model()`, and decoding the response. Note that the SDK returns a streaming body that must be read and decoded before parsing JSON.
```python theme={null}
import json
import boto3
# Create the Bedrock Runtime client
client = boto3.client("bedrock-runtime", region_name="us-east-1")
prompt = "Explain Amazon Bedrock in one sentence."
# Model-specific request payload
body = {
"prompt": prompt,
"max_tokens": 100
}
# Invoke the model (replace modelId with the target model)
response = client.invoke_model(
modelId="amazon.nova-micro-v1:0",
body=json.dumps(body)
)
# The SDK returns a StreamingBody under response["body"]
# Read the stream, decode to text, then parse JSON
result = json.loads(response["body"].read().decode("utf-8"))
print(result)
```
Always decode the `response["body"]` streaming object before `json.loads()` — otherwise you will attempt to parse raw bytes and encounter errors.
What this code does:
* Imports `json` and `boto3`.
* Constructs a Bedrock Runtime client for `us-east-1`.
* Builds a model-specific `body` containing `prompt` and `max_tokens`.
* Calls `invoke_model()` with `modelId` and the serialized `body`.
* Reads and decodes the streaming response body and deserializes the JSON result.
## Best practices and tips
* Prefer Converse for conversational agents and when you want portability across models or cloud vendors.
* Use InvokeModel when needing special model features (image inputs, advanced sampling parameters, token controls, or vendor/model-specific flags).
* Always read and decode streaming responses before parsing JSON.
* Verify the required/requested fields for the target model in its documentation—field names and structures vary per model.
Model-specific fields in InvokeModel are not standardized; sending the wrong structure can cause errors or unexpected outputs. Consult the model's documentation for the exact request format.
## Summary
* InvokeModel: low-level, model-specific JSON payloads; use for full control and nonstandard inputs.
* Converse: high-level, standardized `messages` format; use for conversational flows and cross-model portability.
## Links and references
* Amazon Bedrock overview: [https://docs.aws.amazon.com/bedrock/latest/ug/what-is-amazon-bedrock.html](https://docs.aws.amazon.com/bedrock/latest/ug/what-is-amazon-bedrock.html)
* boto3 documentation: [https://boto3.amazonaws.com/v1/documentation/api/latest/index.html](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
* AWS SDKs and tools: [https://aws.amazon.com/tools/](https://aws.amazon.com/tools/)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.