> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS SDK (boto3) / Bedrock migration

> Keep your unmodified boto3 / AWS SDK Bedrock code — override the endpoint and credentials, and every call site stays byte-identical.

**Already on Bedrock? Keep your code.** The gateway serves the Bedrock
Converse API at the same paths the AWS SDKs call
(`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:

```diff theme={"dark"}
 import boto3

-# Before — real AWS Bedrock
-client = boto3.client("bedrock-runtime", region_name="us-east-1")
+# After — AI Reserve gateway (the whole migration)
+client = boto3.client(
+    "bedrock-runtime",
+    endpoint_url="https://api.aireserve.com",
+    aws_access_key_id=os.environ["AUDACITY_API_KEY"],  # your aireserve_api_… key
+    aws_secret_access_key="audacity",  # ignored — any value
+    region_name="us-east-1",           # ignored — any value
+)

 response = client.converse(
     modelId="us.anthropic.claude-sonnet-4-5-20250929-v1:0",  # unchanged
     messages=[{"role": "user", "content": [{"text": "Hi"}]}],
     inferenceConfig={"maxTokens": 256},
 )
```

**Why the secret key and region don't matter:** boto3 signs every request
with SigV4 and puts the access-key ID in the `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

```python theme={"dark"}
import os
import boto3

client = boto3.client(
    service_name="bedrock-runtime",
    endpoint_url="https://api.aireserve.com",
    aws_access_key_id=os.environ["AUDACITY_API_KEY"],
    aws_secret_access_key="audacity",
    region_name="us-east-1",
)

response = client.converse(
    modelId="claude-sonnet-4-6-bedrock",
    messages=[{"role": "user", "content": [{"text": "Say hello in five words."}]}],
    inferenceConfig={"maxTokens": 64, "temperature": 0.5},
)

print(response["output"]["message"]["content"][0]["text"])
print(response["usage"])       # {"inputTokens": …, "outputTokens": …, "totalTokens": …}
print(response["stopReason"])  # "end_turn"
```

**Streaming** works the same way — `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:

```python theme={"dark"}
stream_response = client.converse_stream(
    modelId="claude-sonnet-4-6-bedrock",
    messages=[{"role": "user", "content": [{"text": "Write me a haiku."}]}],
)

for event in stream_response["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"].get("text", ""), end="", flush=True)
    elif "metadata" in event:
        print("\n", event["metadata"]["usage"])  # {"inputTokens": …, "outputTokens": …, "totalTokens": …}
```

The same two overrides work from the AWS JS SDK
(`@aws-sdk/client-bedrock-runtime`):

```typescript theme={"dark"}
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";

const client = new BedrockRuntimeClient({
  endpoint: "https://api.aireserve.com",
  region: "us-east-1", // ignored — any value
  credentials: {
    accessKeyId: process.env.AUDACITY_API_KEY!, // your aireserve_api_… key
    secretAccessKey: "audacity",                // ignored — any value
  },
});

const response = await client.send(new ConverseCommand({
  modelId: "claude-sonnet-4-6-bedrock",
  messages: [{ role: "user", content: [{ text: "Hi" }] }],
}));
```

## 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 its `modelId` strings untouched. Region inference-profile prefixes
(`us.` / `eu.` / `apac.`) are optional, and full Bedrock ARNs
(`foundation-model` or `inference-profile`) are accepted too.

| AWS model id (as-is)                           | AI Reserve id               | Notes                                                            |
| ---------------------------------------------- | --------------------------- | ---------------------------------------------------------------- |
| `us.anthropic.claude-opus-4-6-v1`              | `claude-opus-4-6-bedrock`   | Served via AWS Bedrock                                           |
| `us.anthropic.claude-sonnet-4-6`               | `claude-sonnet-4-6-bedrock` | Served via AWS Bedrock                                           |
| `us.anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5-bedrock` | Served via AWS Bedrock                                           |
| `us.anthropic.claude-haiku-4-5-20251001-v1:0`  | `claude-haiku-4-5-bedrock`  | Served via AWS Bedrock                                           |
| `us.meta.llama4-maverick-17b-instruct-v1:0`    | `llama-4-maverick-bedrock`  | Served via AWS Bedrock                                           |
| `us.meta.llama4-scout-17b-instruct-v1:0`       | `llama-4-scout-bedrock`     | Served via AWS Bedrock                                           |
| `mistral.mistral-large-3-675b-instruct`        | `mistral-large-bedrock`     | Served via AWS Bedrock (on-demand id — no region prefix)         |
| `us.deepseek.r1-v1:0`                          | `deepseek-reasoner-bedrock` | Served via AWS Bedrock                                           |
| `us.anthropic.claude-fable-5`                  | `claude-fable-5-bedrock`    | Temporarily served via Anthropic direct (Bedrock access pending) |
| `us.anthropic.claude-opus-4-8`                 | `claude-opus-4-8-bedrock`   | Temporarily served via Anthropic direct (Bedrock access pending) |
| `us.anthropic.claude-opus-4-7`                 | `claude-opus-4-7-bedrock`   | Temporarily served via Anthropic direct (Bedrock access pending) |

**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

| Operation                                                         | Status                                  | Use instead                                  |
| ----------------------------------------------------------------- | --------------------------------------- | -------------------------------------------- |
| `converse()`                                                      | Supported                               | —                                            |
| Tool use (`toolConfig`, `toolUse`, `toolResult`)                  | Supported                               | —                                            |
| Images in messages                                                | Supported                               | —                                            |
| Prompt caching (`cachePoint`)                                     | Supported                               | —                                            |
| `converse_stream()`                                               | Supported                               | —                                            |
| Tool-use streaming (`contentBlockStart` + `toolUse` input deltas) | Supported                               | —                                            |
| `invoke_model()` / `…_with_response_stream()`                     | Not served (404)                        | `converse()`, or the audacity-sdk            |
| Documents / video content blocks                                  | Not yet — returns `ValidationException` | audacity-sdk (video), `/v1/chat/completions` |
| Guardrails, Knowledge Bases, Agents                               | Out of scope                            | —                                            |

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()` and `converse_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.