API tương thích OpenAI của Amazon Bedrock: Base URL, xác thực, mô hình và mã (2026)

API tương thích OpenAI của Amazon Bedrock: Base URL, xác thực, mô hình và mã (2026)

Có. Amazon Bedrock có API tương thích OpenAI. Trỏ OpenAI SDK tới https://bedrock-runtime.{region}.amazonaws.com/openai/v1, xác thực bằng API key của Bedrock (hoặc AWS SigV4) và truyền ID mô hình Bedrock như openai.gpt-oss-120b-1:0. Theo cách này, Bedrock phục vụ cả Chat Completions API lẫn Responses API. AWS khuyên dùng endpoint bedrock-runtime cho ứng dụng mới và giữ bedrock-mantle làm lựa chọn tương thích. Lưu ý: bedrock-runtime không triển khai GET /models. Mọi thông tin đều lấy từ tài liệu Chat Completions chính thức của Bedrock, kiểm tra ngày 20 tháng 10 năm 2026.

Hướng dẫn này trình bày cả hai endpoint, hai loại API key, ID mô hình, mã curl, Python và Node, Guardrails, giá, các lỗi bạn sẽ gặp và khi nào Bedrock phù hợp hơn một gateway đa nhà cung cấp.

Tra cứu nhanh

Mục	Giá trị (tính đến 20/10/2026)
Base URL khuyến nghị	https://bedrock-runtime.{region}.amazonaws.com/openai/v1
Base URL tương thích	https://bedrock-mantle.{region}.api.aws/v1 (một số mô hình dùng /openai/v1)
API OpenAI được hỗ trợ	Chat Completions, Responses (tùy mô hình), cùng Anthropic Messages API
Xác thực	API key Bedrock dạng Authorization: Bearer …, hoặc AWS SigV4
Ví dụ ID mô hình	openai.gpt-oss-120b-1:0, openai.gpt-oss-20b-1:0, global.openai.gpt-5.6-sol
Liệt kê mô hình qua /models	Chỉ trên bedrock-mantle. Trên bedrock-runtime, dùng ListFoundationModels
Phạm vi vùng	Key và endpoint đều theo vùng

Nguồn: Chat Completions API, Endpoint suy luận, Bắt đầu nhanh.

bedrock-runtime hay bedrock-mantle: nên dùng endpoint nào

AWS cho biết cả hai endpoint "dùng chung một công cụ suy luận Mantle bên dưới". Tên gọi chỉ một bề mặt endpoint, không phải một công cụ khác. Chúng khác nhau ở tính năng:

	bedrock-runtime (khuyến nghị)	bedrock-mantle (tương thích)
Base URL	bedrock-runtime.{region}.amazonaws.com/openai/v1	bedrock-mantle.{region}.api.aws/v1
API	InvokeModel, Converse, Chat Completions, Responses, Messages	Chat Completions, Responses, Messages
GET /models	Không hỗ trợ (404 UnknownOperationException)	Có hỗ trợ
Guardrails, định tuyến prompt thông minh, suy luận liên vùng	Có	Xem thẻ mô hình
Công cụ phía máy chủ (ví dụ tìm kiếm web), suy luận nền, Projects, Workspaces	Không	Có
Hạn mức	Hạn mức theo mô hình cho endpoint này	Hạn mức theo mô hình riêng

Nguyên tắc của AWS: bắt đầu với bedrock-runtime. Chỉ chuyển sang bedrock-mantle khi mô hình hoặc tính năng bạn cần chỉ có ở đó. Trên bedrock-mantle, tiền tố đường dẫn khác nhau theo mô hình. Yêu cầu sai tiền tố sẽ báo lỗi "model … isn't supported on this route", vì vậy hãy xem bảng Programmatic Access trong thẻ mô hình.

Xác thực: API key Bedrock hay SigV4

API key của Bedrock cho phép OpenAI SDK xác thực bằng bearer token thay vì ký yêu cầu bằng thông tin xác thực AWS (tài liệu API key, 20/10/2026):

Loại key	Thời hạn	Dựa trên	Khuyến nghị của AWS
Ngắn hạn	Tối đa 12 giờ (hoặc bằng thời lượng phiên)	Quyền của IAM principal đã tạo key	Môi trường production
Dài hạn	Đến thời điểm hết hạn đã cấu hình	Một IAM user riêng có gắn chính sách	Chỉ để thử nghiệm

Lưu ý thực tế:

• Tạo key ngắn hạn trong mã bằng pip install aws-bedrock-token-generator (Python) hoặc npm install @aws/bedrock-token-generator (Node), và gọi provider trước mỗi yêu cầu. Provider trả về token đã lưu đệm khi token đó vẫn còn hiệu lực.
• Key dài hạn chỉ hoạt động trong vùng đã tạo ra nó. Gọi sang vùng khác sẽ lỗi Credential should be scoped to a valid region.
• Giới hạn việc dùng key bằng các hành động IAM bedrock:CallWithBearerToken và bedrock-mantle:CallWithBearerToken.
• Các lệnh gọi API được ghi trong CloudTrail. Bản thân key thì không được ghi lại.
• Với boto3, biến AWS_BEARER_TOKEN_BEDROCK yêu cầu boto3 1.39.0 trở lên (Bắt đầu nhanh).

Mã: gọi Bedrock bằng OpenAI SDK

curl (API key)

export OPENAI_API_KEY="<bedrock-api-key>"
curl -X POST "https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "openai.gpt-oss-120b-1:0",
       "messages": [{"role": "user", "content": "Hello from Bedrock"}]}'

curl (SigV4, không cần API key)

curl -X POST "https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  --aws-sigv4 "aws:amz:us-east-1:bedrock" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -d '{"model": "openai.gpt-oss-120b-1:0", "messages": [{"role": "user", "content": "Hello"}]}'

Python với key ngắn hạn tự làm mới

from aws_bedrock_token_generator import provide_token   # pip install aws-bedrock-token-generator openai
from openai import OpenAI

REGION = "us-east-1"

def bedrock_client() -> OpenAI:
    # provide_token() returns a cached token or mints a fresh short-term key (<= 12h)
    return OpenAI(base_url=f"https://bedrock-runtime.{REGION}.amazonaws.com/openai/v1",
                  api_key=provide_token())

r = bedrock_client().chat.completions.create(
    model="openai.gpt-oss-120b-1:0",
    messages=[{"role": "user", "content": "Explain Bedrock API keys in one sentence."}],
)
print(r.choices[0].message.content, r.usage)

Node.js

import OpenAI from "openai";
import { getTokenProvider } from "@aws/bedrock-token-generator";

const provideToken = getTokenProvider();
const client = new OpenAI({
  baseURL: "https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1",
  apiKey: await provideToken(),
});

const r = await client.chat.completions.create({
  model: "openai.gpt-oss-20b-1:0",
  messages: [{ role: "user", content: "Name two Bedrock endpoints." }],
});
console.log(r.choices[0].message.content);

Liệt kê mô hình

client.models.list() trả về 404 trên bedrock-runtime. Hãy chạy aws bedrock list-foundation-models --region us-east-1, hoặc trỏ SDK tới bedrock-mantle để liệt kê mô hình:

curl -s "https://bedrock-mantle.us-east-1.api.aws/v1/models" -H "Authorization: Bearer $OPENAI_API_KEY"

Thêm Bedrock Guardrail vào yêu cầu kiểu OpenAI

Guardrails được truyền qua các header bổ sung. Một trường tùy chọn trong body bật tính năng gắn thẻ đầu vào:

r = bedrock_client().chat.completions.create(
    model="openai.gpt-oss-20b-1:0",
    messages=[{"role": "user", "content": "What is the weather like today?"}],
    extra_headers={
        "X-Amzn-Bedrock-GuardrailIdentifier": "GR12345",
        "X-Amzn-Bedrock-GuardrailVersion": "DRAFT",
        "X-Amzn-Bedrock-Trace": "ENABLED",
    },
    extra_body={"amazon-bedrock-guardrailConfig": {"tagSuffix": "xyz"}},
)

Tên header lấy từ ví dụ guardrail chính thức.

Những mô hình nào dùng được với API tương thích OpenAI?

Mức hỗ trợ API khác nhau theo mô hình và theo endpoint, vì vậy hãy kiểm tra từng thẻ mô hình (bảng tương thích API). Ví dụ từ tài liệu AWS tính đến 20/10/2026:

Mô hình	Chat Completions trên runtime	Responses trên runtime	Ghi chú
openai.gpt-oss-120b-1:0 / -20b-1:0	Có	Không (Responses chỉ có trên mantle)	GPT OSS trọng số mở
global.openai.gpt-5.6-sol	Có	Có	Xuất hiện trong phần Bắt đầu nhanh của AWS, hồ sơ suy luận toàn cầu
Dòng GPT-6, GPT-5.x	Theo thẻ mô hình	Theo thẻ mô hình	Liệt kê trong mục OpenAI của bảng tương thích
Anthropic Claude	Dùng Messages API (/anthropic)	n/a	ANTHROPIC_BASE_URL=https://bedrock-runtime.{region}.amazonaws.com/anthropic

Giá Bedrock cho lệnh gọi tương thích OpenAI

Bạn trả theo đơn giá token thông thường của Bedrock cho mô hình đó. Giao diện tương thích OpenAI không tính phụ phí. Ví dụ từ trang giá Bedrock, 20/10/2026, cho mỗi 1 triệu token:

Mô hình	Vùng	Đầu vào	Đầu ra
gpt-oss-20b	Châu Á – Thái Bình Dương (Sydney)	$0.0721	$0.3090
gpt-oss-120b	Châu Á – Thái Bình Dương (Sydney)	$0.1545	$0.6180
GPT OSS Safeguard 20B	Miền Đông/Tây Hoa Kỳ	$0.07	$0.20
GPT OSS Safeguard 120B	Miền Đông/Tây Hoa Kỳ	$0.15	$0.60

Đơn giá khác nhau theo vùng, và Bedrock còn có các gói Priority, Flex và Batch. Dùng bộ chọn vùng trên trang giá để xem chính xác mức bạn sẽ trả.

Lỗi thường gặp và cách khắc phục

Lỗi	Nguyên nhân	Cách khắc phục
404 UnknownOperationException trên /models	bedrock-runtime không triển khai Models API	Dùng ListFoundationModels, hoặc gọi /models trên bedrock-mantle
model … isn't supported on this route	Sai tiền tố đường dẫn trên bedrock-mantle	Kiểm tra thẻ mô hình xem là /v1 hay /openai/v1
Credential should be scoped to a valid region	Dùng key dài hạn ngoài vùng của nó	Tạo key trong vùng đích
Unable to locate credentials	boto3 cũ hơn 1.39.0 bỏ qua AWS_BEARER_TOKEN_BEDROCK	pip install --upgrade boto3
Responses API không hỗ trợ GPT OSS	GPT OSS chỉ hỗ trợ Responses trên bedrock-mantle	Dùng Chat Completions hoặc đổi endpoint
AccessDenied	Thiếu quyền truy cập mô hình hoặc CallWithBearerToken bị từ chối	Bật quyền truy cập mô hình và rà soát chính sách IAM

Bedrock, gọi OpenAI trực tiếp hay gateway đa nhà cung cấp

Nhu cầu	Bedrock tương thích OpenAI	API trực tiếp của nhà cung cấp	Gateway đa nhà cung cấp (ví dụ Flatkey)
Ở trong tài khoản AWS, với IAM và CloudTrail	Tốt nhất	Không	Không
Dùng credit AWS hoặc cam kết Enterprise Discount Program (EDP)	Có	Không	Không
Guardrails và kiểm soát gần VPC	Có	Tùy nhà cung cấp	Tùy gateway
Có mô hình mới nhất ngay ngày ra mắt	Tùy mô hình	Thường có sớm nhất	Tùy trường hợp
Một key cho OpenAI, Anthropic, Google, Alibaba, DeepSeek, Moonshot, Zhipu	Chỉ các mô hình Bedrock lưu trữ	Không	Có
Quản lý key theo vùng	Bắt buộc	Không	Không

Nếu bạn dùng AWS toàn diện, API tương thích OpenAI của Bedrock là lựa chọn gọn gàng nhất. Nếu bạn còn cần các mô hình mà Bedrock không lưu trữ, hãy giữ nguyên mã OpenAI SDK và chỉ đổi base URL. Với Flatkey, một key duy nhất tại https://router.flatkey.ai/v1 truy cập được GPT, Claude, Gemini, Qwen, DeepSeek, Kimi và GLM:

import os
from openai import OpenAI

ROUTES = {
    "bedrock": OpenAI(base_url="https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1",
                      api_key=os.environ["AWS_BEARER_TOKEN_BEDROCK"]),
    "flatkey": OpenAI(base_url="https://router.flatkey.ai/v1",
                      api_key=os.environ["FLATKEY_API_KEY"]),
}

def ask(route, model, prompt):
    r = ROUTES[route].chat.completions.create(model=model, messages=[{"role": "user", "content": prompt}])
    return r.choices[0].message.content

print(ask("bedrock", "openai.gpt-oss-120b-1:0", "hi"))
print(ask("flatkey", "qwen3.8-max", "hi"))         # same SDK, different provider
print(ask("flatkey", "claude-sonnet-5-5", "hi"))

Tính đến 20/10/2026, trang gpt-6-sol trên Flatkey ghi $1.20 đầu vào và $6.00 đầu ra cho mỗi 1 triệu token, mức giá khuyến mãi so với giá niêm yết $2 / $10. Hãy so sánh với đơn giá Bedrock của bạn cho cùng mô hình. Đọc thêm: base URL của API tương thích OpenAI, tài khoản trực tiếp với nhà cung cấp hay AI API gateway và checklist AI API gateway cho doanh nghiệp.

Checklist chuyển đổi: từ ứng dụng OpenAI sang Bedrock

1. Chọn vùng và xác nhận quyền truy cập mô hình trong bảng điều khiển Bedrock.
2. Thay OPENAI_BASE_URL bằng https://bedrock-runtime.{region}.amazonaws.com/openai/v1.
3. Thay key bằng provider API key Bedrock ngắn hạn. Đừng đưa key dài hạn lên production.
4. Ánh xạ tên mô hình sang ID Bedrock, ví dụ gpt-oss-120b → openai.gpt-oss-120b-1:0.
5. Xóa các lệnh gọi client.models.list(), hoặc chuyển chúng sang bedrock-mantle.
6. Kiểm thử streaming, gọi công cụ và đầu ra có cấu trúc theo thẻ của từng mô hình.
7. Thêm header guardrail ở những nơi chính sách yêu cầu.
8. Kiểm tra hạn mức của endpoint đã chọn (xử lý giới hạn tốc độ).
9. Theo dõi chi tiêu theo mô hình và theo nhóm (phân bổ chi phí).

Câu hỏi thường gặp

Amazon Bedrock có hỗ trợ API OpenAI không?

Có. Bedrock triển khai OpenAI Chat Completions và Responses API tại https://bedrock-runtime.{region}.amazonaws.com/openai/v1, nên mã OpenAI SDK hiện có vẫn chạy được khi bạn đổi base URL, API key và ID mô hình.

Base URL tương thích OpenAI của Bedrock là gì?

URL khuyến nghị là https://bedrock-runtime.{region}.amazonaws.com/openai/v1, ví dụ https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1. Endpoint tương thích là https://bedrock-mantle.{region}.api.aws/v1.

Làm sao xác thực OpenAI SDK với Bedrock?

Dùng API key của Amazon Bedrock làm api_key, gửi dưới dạng Authorization: Bearer. AWS khuyên dùng key ngắn hạn (tối đa 12 giờ) cho production. Ký SigV4 cũng hoạt động trên bedrock-runtime.

Vì sao models.list() lỗi trên Bedrock?

Endpoint bedrock-runtime không triển khai thao tác GET /models của OpenAI và trả về 404 UnknownOperationException. Hãy dùng ListFoundationModels, hoặc gọi /models trên bedrock-mantle.

Có thể dùng GPT OSS với Responses API trên Bedrock không?

Không phải trên bedrock-runtime. Ở đó GPT OSS hỗ trợ Chat Completions, còn Responses API cho GPT OSS chỉ có trên bedrock-mantle.

Endpoint tương thích OpenAI có tính thêm phí không?

AWS không liệt kê khoản phí riêng nào cho giao diện này. Bạn trả theo giá token chuẩn của Bedrock cho mô hình, tùy vùng và gói dịch vụ.

Kết luận

Để dùng OpenAI SDK trên AWS, hãy đặt base URL là bedrock-runtime.{region}.amazonaws.com/openai/v1, dùng API key Bedrock ngắn hạn, ánh xạ ID mô hình và bỏ models.list(). Nếu hệ thống của bạn còn cần mô hình ngoài Bedrock, cùng cách dùng SDK đó vẫn hoạt động với một key duy nhất qua router của Flatkey.

Cập nhật lần cuối: 20/10/2026 · Flatkey Team. Thông tin được trích từ tài liệu chính thức của AWS có liên kết trong bài.