Bedrock's Unified Model-Invocation API

One API surface across Claude, Llama, Nova, and Titan model families.

Amazon Bedrock is a managed AWS service that hosts foundation models from several providers and serves them all through ordinary, SigV4-signed AWS API calls. This is the native Bedrock Runtime API - not any provider's own SDK. The idea this page builds is that one operation, Converse, gives you a single request and response shape that works no matter which model family you point it at.

Summary

• Bedrock exposes foundation-model inference as a normal AWS service: you build a bedrock-runtime client, send a request, and read a structured response, exactly like S3 or DynamoDB.
• Insight: the Converse operation is model-agnostic - it normalizes messages, system, inferenceConfig, and toolConfig so you stop hand-building each model family's bespoke JSON body.
• Key Concepts: foundation model, model id / inference profile, bedrock-runtime data plane, bedrock control plane, Converse vs InvokeModel, content blocks.
• When to Use: any time application code needs text generation, chat, tool use, or multimodal reasoning from a hosted model at runtime.
• Limitations/Trade-offs: Converse smooths over most differences, but model families still differ in capability, context window, cost, and which features (tools, vision, documents) they support.
• Related Topics: the Converse-vs-InvokeModel split, streaming, model selection, and provisioned throughput.

Foundations

Think of Bedrock as two services that share a name.

The control plane, reached through the bedrock client, is where you discover and manage models: list what is available, read a model's capabilities, or reserve dedicated capacity. The data plane, reached through the bedrock-runtime client, is where you actually run inference - you send prompts and get generated text back.

Almost all day-to-day work happens on the data plane, and the operation you reach for is Converse. You give it a modelId, a list of messages, and optional system instructions and inferenceConfig, and it returns the model's reply as structured content.

# --- Python (boto3) ---
import boto3
 
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",  # representative id - verify per region
    messages=[{"role": "user", "content": [{"text": "Say hello in one word."}]}],
)
print(resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
 
const brt = new BedrockRuntimeClient({ region: "us-east-1" });
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0", // representative id - verify per region
  messages: [{ role: "user", content: [{ text: "Say hello in one word." }] }],
}));
console.log(resp.output?.message?.content?.[0]?.text);

The surfaces differ by language, but both call the same Bedrock Converse API and read the reply out of output.message.content. Model IDs and inference-profile requirements are region- and version-specific - list current options with the bedrock control-plane client (ListFoundationModels, ListInferenceProfiles) and verify at build time rather than trusting any hardcoded id.

Mechanics & Interactions

A Converse request is built from a small, fixed vocabulary that stays the same across model families.

Messages are an ordered list of turns, each with a role (user or assistant) and a content array of content blocks. A block is usually {"text": "..."}, but the same array is where images, documents, tool calls, and tool results also live. System is a separate top-level list of instruction blocks, kept apart from the conversation so the model treats it as guidance rather than dialogue.

inferenceConfig carries the generation knobs in normalized names: maxTokens, temperature, topP, and stopSequences. Because Converse renames these consistently, you do not need to remember that one family calls the limit max_gen_len and another maxTokenCount - the SDK maps them for you.

The response is equally uniform. You get output.message (role plus content blocks), a stopReason (end_turn, max_tokens, stop_sequence, tool_use, or content_filtered), a usage block with inputTokens/outputTokens/totalTokens, and metrics.latencyMs. Token usage is how Bedrock bills you, so it is worth logging on every call.

Underneath, this is a normal AWS request: the SDK resolves credentials, signs with SigV4, and sends HTTPS to a regional bedrock-runtime endpoint. There is no separate API key - Bedrock access is governed by IAM permissions like bedrock:InvokeModel on the model's ARN, plus model access being enabled for your account.

Advanced Considerations & Applications

The older sibling of Converse is InvokeModel. It sends a raw JSON body that each model family defines for itself, and returns a raw JSON body you parse yourself. It predates Converse and still matters: it is the only way to reach a handful of model-specific parameters, and it is what embeddings and image-generation models use, since those do not fit the chat-shaped Converse contract.

The trade-off is portability. With InvokeModel you own the schema, so switching from a Claude body to a Llama body means rewriting the request. With Converse you change one string - the modelId - and the same code keeps working. That is why Converse is the recommended default for text and chat, and why most pages in this section use it.

A practical consequence: because Converse abstracts the family, your selection logic can treat the model id as configuration. You can A/B a cheaper model against a stronger one, or fail over across families, without touching the call site - the same pattern the rest of AWS uses, where one client shape serves many resources.

Common Misconceptions

• "Bedrock is the Anthropic SDK or an OpenAI-style API." - No. It is a native AWS service reached with the AWS SDK and SigV4 signing; Claude is just one of several model families it hosts.
• "There is a Bedrock API key." - No. Access is IAM-based (bedrock:InvokeModel and friends), plus per-account model access enablement; the SDK resolves credentials from the normal chain.
• "The model id is stable and universal." - No. IDs are region- and version-specific, and many modern models require a cross-region inference profile id (like us.anthropic.claude-...) instead of a bare model id.
• "Converse and InvokeModel are interchangeable." - They overlap for chat, but only InvokeModel reaches non-chat modalities (embeddings, image generation) and certain model-specific parameters.
• "One client does inference and management." - No. bedrock-runtime runs inference; the separate bedrock control-plane client lists models and manages provisioned throughput.

FAQs

Related

• The Converse API vs InvokeModel - the two surfaces compared side by side with real bodies.
• Bedrock Basics - your first Converse call, step by step.
• Model Selection: Claude, Llama, Nova & Titan Trade-offs - picking a model id for the job.
• Streaming Responses with ConverseStream - the token-by-token variant of this same API.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Bedrock model IDs and inference profiles are region/version-specific - verify against the current Bedrock catalog at build time.