POST /model/{modelId}/converse and
POST /model/{modelId}/converse-stream), so an unmodified
boto3 bedrock-runtime client works by overriding the endpoint
and credentials — every converse() / converse_stream() call
site, message shape, toolConfig, and modelId string
stays byte-identical:
Authorization header’s
Credential field. The gateway authenticates the
aireserve_api_… key it finds there — the key itself is the bearer secret,
carried over TLS, exactly the same trust model as the x-api-key header on
every other endpoint. The SigV4 signature (which is what the fake secret key
produces) is ignored, and no region routing exists — there is one gateway.
Full example
converse_stream() responses
are real AWS binary event streams (application/vnd.amazon.eventstream,
per-frame CRC32 checksums), yielding the standard Bedrock event union
(messageStart → contentBlockDelta → … → messageStop → metadata) with token
usage in the final metadata event:
@aws-sdk/client-bedrock-runtime):
Model IDs
Your existing AWS model ids work as-is. The gateway resolves the Bedrock model ids below to their AI Reserve catalog equivalents, so migrating code keeps itsmodelId strings untouched. Region inference-profile prefixes
(us. / eu. / apac.) are optional, and full Bedrock ARNs
(foundation-model or inference-profile) are accepted too.
AI Reserve catalog names also work — the same IDs every other endpoint
takes (anything
GET /v1/models returns), including non-Bedrock models like
gpt-5.4-mini or gemini-2.5-flash: the Converse surface is bridged
to every provider, not just Anthropic-on-Bedrock. AWS ids not in the table above
return ResourceNotFoundException.
Supported operations
Errors arrive in the AWS wire shape (
__type +
x-amzn-ErrorType), so boto3 raises its normal typed exceptions:
bad key → AccessDeniedException, rate limit →
ThrottlingException (with Retry-After), spend cap →
ServiceQuotaExceededException, unknown model →
ResourceNotFoundException. For converse_stream(), errors
before the first event use the same HTTP shapes (raised from the
converse_stream() call itself); a failure after streaming has
started arrives as an in-stream internalServerException event frame,
which boto3 raises as an EventStreamError from the stream iterator —
the connection is never silently dropped mid-stream.
Which path should I use?
- boto3 / AWS SDK against the gateway — you have an existing Bedrock codebase (or a vendor tool that only speaks Bedrock) and want zero code changes beyond the client constructor —
converse()andconverse_stream()both supported. - audacity-sdk — you want the same Converse surface plus streaming, retries tuned for the gateway, typed exceptions, file upload, and image generation. The recommended default for new integrations.
- OpenAI-compatible API (
/v1/chat/completions) — your stack is already built on OpenAI SDKs, LangChain, or anything OpenAI-shaped. Full streaming, broadest ecosystem support.