Nếu bạn đã sử dụng OpenAI SDK, cách nhanh nhất để thử Gemini là thay đổi API key, base URL và model ID. Base URL tương thích OpenAI chính thức của Gemini API là:
https://generativelanguage.googleapis.com/v1beta/openai/
Đối với Flatkey, base URL của router tương thích OpenAI là:
https://router.flatkey.ai/v1
Đó là cốt lõi của Thiết lập Base URL tương thích OpenAI của Gemini API và Flatkey Router: Gemini trực tiếp dùng API key của Google và endpoint tương thích OpenAI của Google; Flatkey dùng key Flatkey, router Flatkey và một model ID Gemini có sẵn trong tài khoản Flatkey của bạn.
Hãy dùng lộ trình Google trực tiếp khi bạn chỉ cần Gemini và muốn thiết lập gần với nhà cung cấp nhất. Hãy dùng lộ trình Flatkey khi bạn đã đang so sánh Gemini với GPT, Claude, DeepSeek, Qwen hoặc các model khác và muốn một base URL tương thích OpenAI, một danh sách model và một nhật ký sử dụng duy nhất.
Thiết lập Base URL tương thích OpenAI của Gemini API và Flatkey Router trong nháy mắt
| Lựa chọn thiết lập | Base URL | API key | Nguồn model ID | Phù hợp nhất |
|---|---|---|---|---|
| Gemini trực tiếp | https://generativelanguage.googleapis.com/v1beta/openai/ |
Gemini API key | Tài liệu model của Google Gemini API hoặc client.models.list() |
Bạn chỉ cần Gemini và muốn truy cập trực tiếp từ Google. |
| Flatkey router | https://router.flatkey.ai/v1 |
Flatkey API key | Flatkey /v1/models hoặc Model Directory |
Bạn muốn Gemini đứng cạnh các nhà cung cấp model khác sau một key duy nhất. |
Đừng trộn lẫn hai cách này. Một Gemini API key sẽ không xác thực được với Flatkey, và một key Flatkey sẽ không xác thực được với endpoint Gemini trực tiếp của Google.
Thiết lập Gemini trực tiếp với OpenAI SDK
Lớp tương thích OpenAI của Google cho phép bạn giữ nguyên cấu trúc OpenAI SDK cho các quy trình chat-completion phổ biến. Điểm khác biệt quan trọng là cấu hình client.
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{"role": "user", "content": "Write one sentence about model routing."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GEMINI_API_KEY,
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const response = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "user", content: "Write one sentence about model routing." },
],
});
console.log(response.choices[0].message.content);
REST
curl https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{"role": "user", "content": "Viết một câu về định tuyến mô hình."}
]
}'
Trước khi triển khai, hãy chạy client.models.list() hoặc GET /openai/models trên cùng base URL đó. Việc này sẽ phát hiện lỗi phổ biến nhất: sao chép một model ID cũ từ bài blog và cho rằng nó vẫn tồn tại cho tài khoản của bạn.
Thiết lập Flatkey router cho Gemini
Flatkey giữ nguyên cấu trúc của OpenAI SDK, nhưng base URL và key lại thay đổi. Bạn dùng Flatkey router, rồi chọn một Gemini model ID từ phản hồi /v1/models của Flatkey hoặc Model Directory trực tiếp.
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
models = client.models.list()
gemini_models = [model.id for model in models.data if "gemini" in model.id]
print(gemini_models)
response = client.chat.completions.create(
model=os.environ.get("FLATKEY_GEMINI_MODEL", "gemini-2.5-flash"),
messages=[
{"role": "user", "content": "Viết một câu về định tuyến mô hình."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
});
const models = await client.models.list();
console.log(models.data.map((model) => model.id).filter((id) => id.includes("gemini")));
const response = await client.chat.completions.create({
model: process.env.FLATKEY_GEMINI_MODEL || "gemini-2.5-flash",
messages: [
{ role: "user", content: "Viết một câu về định tuyến mô hình." },
],
});
console.log(response.choices[0].message.content);
Trong môi trường production, đừng giả định model ID trực tiếp của Google và model ID được định tuyến của Flatkey sẽ luôn giống hệt nhau. Hãy coi danh sách model là nguồn sự thật cho tài khoản mà bạn đang gọi.
Các biến môi trường để việc chuyển đổi có thể đảo ngược
Một thiết lập Gemini API OpenAI Compatibility Base URL và Flatkey Router Setup gọn gàng nên giúp việc kiểm thử trực tiếp và qua router dễ so sánh mà không cần chỉnh sửa mã ứng dụng.
# Gemini trực tiếp
GEMINI_API_KEY="..."
GEMINI_OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
GEMINI_MODEL="gemini-3.8-flash"
# Flatkey router
FLATKEY_API_KEY="..."
FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="gemini-2.5-flash"
Sau đó chọn route từ cấu hình:
import os
from openai import OpenAI
route = os.environ.get("AI_ROUTE", "flatkey")
if route == "direct_gemini":
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url=os.environ["GEMINI_OPENAI_BASE_URL"],
)
model = os.environ["GEMINI_MODEL"]
else:
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ["FLATKEY_BASE_URL"],
)
model = os.environ["FLATKEY_GEMINI_MODEL"]
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Trả về chính xác: route ok"}],
)
Mẫu này cho phép một indie hacker thử Gemini trực tiếp trước, thêm Flatkey sau, và quay lại mà không cần viết lại đường dẫn request.
Danh sách kiểm tra smoke-test trước khi chuyển lưu lượng
| Kiểm tra | Gemini trực tiếp | Flatkey router |
|---|---|---|
| Xác thực | Xác nhận khóa Gemini chỉ hoạt động với endpoint của Google. | Xác nhận khóa Flatkey chỉ hoạt động với router.flatkey.ai. |
| Danh sách model | Chạy client.models.list() trên base URL của Gemini. |
Chạy client.models.list() trên Flatkey và lọc các ID Gemini. |
| Chat cơ bản | Gửi một lượt chat completion ngắn, không streaming. | Gửi cùng prompt đó qua model Gemini của Flatkey. |
| Streaming | Chỉ kiểm tra streaming nếu ứng dụng của bạn dùng streaming. | Kiểm tra streaming trên đúng model đã được routing trước khi bật cho người dùng. |
| Gọi tool | Kiểm tra một schema hàm nhỏ nếu ứng dụng của bạn dùng tools. | Xác nhận model đã được routing hỗ trợ hành vi tool mà ứng dụng của bạn mong đợi. |
| Đầu ra có cấu trúc | Xác thực đầu ra JSON thực tế, không chỉ trạng thái 200. |
Xác thực cùng schema và hành vi thử lại. |
| Rà soát mức sử dụng | Kiểm tra mức sử dụng và lỗi của Google trong tài khoản nhà cung cấp của bạn. | Kiểm tra Flatkey Usage Logs để xem model, số lượng token, độ trễ và chi phí. |
OpenAI-compatible không có nghĩa là mọi tính năng đặc thù của nhà cung cấp đều hoạt động giống hệt nhau. Nó có nghĩa là hình dạng client của bạn có thể đủ gần để dùng với các workflow phổ biến của SDK. Smoke test nên bao phủ những tính năng mà ứng dụng của bạn thực sự phụ thuộc.
Các lỗi base URL phổ biến
Bỏ quên /openai/ trên route Gemini trực tiếp
Đối với các lệnh gọi Gemini tương thích OpenAI trực tiếp, hãy dùng:
https://generativelanguage.googleapis.com/v1beta/openai/
Đừng dùng endpoint Gemini gốc generateContent với code chat-completion của OpenAI SDK. Ví dụ API Gemini gốc và ví dụ tương thích OpenAI có cấu trúc request khác nhau.
Dùng base_url trong Node hoặc baseURL trong Python
Cấu hình OpenAI SDK trong Python dùng base_url. JavaScript SDK dùng baseURL.
OpenAI(base_url="https://router.flatkey.ai/v1")
new OpenAI({ baseURL: "https://router.flatkey.ai/v1" })
Xem model ID là cố định vĩnh viễn
Tên model thay đổi nhanh hơn mã thiết lập SDK. Với đường dẫn trực tiếp, hãy kiểm tra tài liệu model của Google hoặc liệt kê model thông qua endpoint tương thích OpenAI của Gemini. Với Flatkey, hãy kiểm tra /v1/models và Model Directory.
Bỏ qua log
Phản hồi thành công đầu tiên không phải là kết thúc của quá trình thiết lập. Sau request Flatkey đầu tiên, hãy mở Usage Logs và xác minh model, số lượng token, độ trễ và chi phí. Điều đó khiến Gemini API OpenAI Compatibility Base URL và Flatkey Router Setup có thể truy vết về mặt vận hành thay vì chỉ đúng về mặt cú pháp.
Khi Flatkey mang lại giá trị
Flatkey hữu ích khi Gemini chỉ là một đường dẫn trong một stack model rộng hơn. Ví dụ:
- Bạn muốn Gemini, Claude, GPT, DeepSeek và Qwen nằm sau một base URL tương thích OpenAI duy nhất.
- Bạn đang kiểm thử hành vi fallback của model và không muốn các khóa nhà cung cấp riêng lẻ bị phân tán khắp các app và agent.
- Bạn cần một sổ cái sử dụng chung cho model ID, số lượng token, độ trễ và chi phí theo từng request.
- Bạn muốn dev có thể thay đổi tham số model mà không cần thay đổi client SDK.
Nếu ứng dụng của bạn chỉ bao giờ gọi Gemini, thiết lập trực tiếp của Google có thể đã đủ. Nếu sản phẩm của bạn đang so sánh các nhà cung cấp, router Flatkey sẽ cho bạn một lộ trình chuyển đổi gọn gàng hơn.
Những liên kết nội bộ nên mở
- Hướng dẫn khởi động nhanh Flatkey API
- Hướng dẫn di chuyển tương thích OpenAI
- Kiểm tra tuyến Gemini so với Claude
- Flatkey Model Directory
- Trang giá của Flatkey
- Trang trạng thái của Flatkey
Câu hỏi thường gặp
Base URL chính thức tương thích OpenAI của Gemini là gì?
Base URL chính thức tương thích OpenAI của Gemini là https://generativelanguage.googleapis.com/v1beta/openai/. Hãy dùng nó với Gemini API key, không phải Flatkey key.
Tôi nên dùng base URL nào cho Gemini qua Flatkey?
Hãy dùng https://router.flatkey.ai/v1 với Flatkey API key. Sau đó chọn một Gemini model ID từ phản hồi /v1/models của Flatkey hoặc từ Model Directory trực tiếp.
Tôi có thể dùng cùng một Gemini model ID ở cả hai nơi không?
Đôi khi có, nhưng đừng mặc định như vậy. Cách an toàn là liệt kê model cho đúng route và tài khoản bạn đang dùng, rồi cố định ID đó trong cấu hình.
Tương thích OpenAI có nghĩa là đầy đủ tính năng tương đương không?
Không. Hãy xem tương thích OpenAI như một tiện ích cho SDK và định dạng request. Hãy kiểm thử streaming, tools, structured output, files và đầu vào multimodal trên đúng model và route trước khi triển khai production.
Indie hacker nên bắt đầu trực tiếp hay với Flatkey?
Hãy bắt đầu trực tiếp nếu bạn chỉ đang chứng minh Gemini hoạt động. Hãy bắt đầu với Flatkey nếu quyết định thực sự là model nào nên vận hành sản phẩm, chứ không phải liệu chỉ riêng Gemini có trả lời được prompt hay không.
Kết luận
Gemini API OpenAI Compatibility Base URL và Flatkey Router Setup rất đơn giản khi bạn tách hai đường dẫn ra:
- Gemini trực tiếp:
https://generativelanguage.googleapis.com/v1beta/openai/ - Flatkey router:
https://router.flatkey.ai/v1
Hãy giữ các khóa tách biệt, liệt kê các model trước khi gọi chat completions, kiểm tra các tính năng mà ứng dụng của bạn sử dụng, và xác minh mức sử dụng sau yêu cầu đầu tiên. Khi bạn sẵn sàng so sánh Gemini với các nhà cung cấp khác thông qua một lớp tương thích OpenAI duy nhất, hãy tạo một khóa Flatkey và chuyển từng workload một cách lần lượt.
