Truy cập tương thích OpenAI cho Gemini API thông qua router

Khả năng tương thích Gemini API với OpenAI hữu ích cho hai lộ trình di chuyển khác nhau. Google cung cấp tài liệu về một endpoint tương thích trực tiếp với OpenAI cho Gemini, và Flatkey cung cấp cho các nhóm một lộ trình qua router khi họ muốn truy cập Gemini trong cùng một cổng gateway một khóa mà họ dùng cho các mô hình khác.

Lộ trình trực tiếp của Google là thay đổi base URL thành https://generativelanguage.googleapis.com/v1beta/openai/ cùng với một khóa API Gemini. Lộ trình Flatkey giữ nguyên cấu trúc của OpenAI SDK nhưng trỏ client của bạn tới https://router.flatkey.ai/v1, dùng khóa Flatkey, và chọn một ID mô hình Gemini từ danh mục Flatkey trước khi kiểm tra logs, chi phí và khả năng hỗ trợ tính năng.

Hướng dẫn này giải thích cách sử dụng an toàn một tuyến Gemini API OpenAI compatible. Nội dung bao gồm những gì tài liệu tương thích của Google thực sự hỗ trợ, khi nào một router làm thay đổi mô hình vận hành, và những gì cần xác minh trước khi chuyển lưu lượng sản xuất.

Trả lời nhanh: Định tuyến tương thích OpenAI của Gemini API

Nếu ứng dụng của bạn đã sử dụng SDK OpenAI Python hoặc JavaScript, quá trình chuyển sang Gemini API tương thích OpenAI bắt đầu từ cấu hình, không phải viết lại.

Quyết định	Gemini API trực tiếp	Gemini qua Flatkey
API key	Gemini API key từ Google AI Studio	Flatkey API key
Base URL	https://generativelanguage.googleapis.com/v1beta/openai/	https://router.flatkey.ai/v1
Mục tiêu chính	Gọi Gemini bằng cú pháp SDK OpenAI	Định tuyến Gemini cùng các nhà cung cấp model khác sau một khóa duy nhất
Lựa chọn model	Model ID Gemini của Google từ tài liệu Google	Model ID Gemini của Flatkey từ bảng giá hoặc dashboard
Xác thực	Phản hồi, hành vi model, thanh toán Google	Phản hồi, nhật ký sử dụng Flatkey, đơn vị giá, hạn ngạch, hoàn nguyên

Hãy dùng endpoint Google trực tiếp khi bạn chỉ cần Gemini và muốn kiểm soát tài khoản theo nhà cung cấp gốc. Hãy dùng bộ định tuyến Flatkey khi Gemini cần đứng cạnh GPT, Claude, DeepSeek, Qwen, image, video và các quyền truy cập model khác sau một khóa, một dashboard, và một nơi hiển thị thanh toán.

Những gì tài liệu tương thích OpenAI của Google xác nhận

Tài liệu tương thích OpenAI của Google cho biết các mô hình Gemini có thể được truy cập bằng các thư viện OpenAI cho Python và JavaScript, cùng với REST, bằng cách cập nhật API key, base URL và model. Base URL trực tiếp được tài liệu nêu là https://generativelanguage.googleapis.com/v1beta/openai/.

Cùng trang này cũng hiển thị các ví dụ cho chat completions, phản hồi streaming, function calling, hiểu hình ảnh và embeddings. Trang cũng lưu ý rằng hiện tại upload và download tệp tương thích với OpenAI chưa được hỗ trợ, vì vậy các quy trình làm việc với tệp cần xử lý bằng Google GenAI client thay vì mặc định là tương đương hoàn toàn với file của OpenAI.

Đó là bài học chính cho bất kỳ hướng dẫn Gemini API OpenAI compatible nào: khả năng tương thích phụ thuộc vào endpoint và tính năng. Một chat completion có thể chỉ cần di chuyển sang base URL mới, trong khi các quy trình upload tệp, hình ảnh, batch, tool hoặc embedding vẫn cần được kiểm thử riêng.

Flatkey thay đổi phần cài đặt Gemini như thế nào

Flatkey không yêu cầu bạn thay một ứng dụng tương thích OpenAI bằng SDK của nhà cung cấp mới cho lần thử đầu tiên. Giao diện sản phẩm công khai của Flatkey được xây dựng xoay quanh một API key, không cần tài khoản nhà cung cấp riêng, giá rõ ràng, thanh toán hợp nhất, và một dashboard cho key, mức sử dụng và định tuyến. Nó cũng hiển thị base URL của bộ định tuyến tương thích OpenAI là https://router.flatkey.ai/v1.

Với một tuyến Gemini API OpenAI compatible đi qua Flatkey, thay đổi quan trọng không phải là tên phương thức của OpenAI SDK. Điều quan trọng là về vận hành:

• Bạn chọn một mã model Gemini từ Flatkey, không chỉ từ tài liệu của Google.
• Bạn kiểm tra mức sử dụng và chi phí trong Flatkey sau khi gửi yêu cầu, không chỉ trong phản hồi của ứng dụng.
• Bạn giữ Gemini trong cùng quy trình định tuyến và hạn mức với các nhà cung cấp khác.
• Bạn tránh tạo một luồng tài khoản nhà cung cấp riêng cho từng team hoặc công cụ.
• Bạn giữ việc khôi phục đơn giản bằng cách kiểm soát base URL, key và model thông qua cấu hình.

Bản chụp giá trực tiếp của Flatkey được kiểm tra cho bài viết này có bao gồm các dòng catalog mang tên Gemini, nhưng tình trạng sẵn có và tên model chính xác có thể thay đổi. Hãy xem catalog như nguồn sự thật tại thời điểm xuất bản: chọn model trong pricing hoặc dashboard, rồi kiểm tra mã model chính xác trước khi đưa vào lưu lượng production.

Mẫu di chuyển Base URL

Bắt đầu bằng cách tách quá trình di chuyển thành ba biến môi trường:

FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="replace-with-flatkey-gemini-model-id"

Điều đó cho bạn một công tắc chuyển đổi rõ ràng cho bất kỳ client Gemini API tương thích OpenAI nào. Mã ứng dụng vẫn giữ đường dẫn SDK tương thích OpenAI. Cấu hình sẽ quyết định request được gửi trực tiếp tới Google, Flatkey, hay một endpoint tương thích khác.

Thành phần cấu hình	Vì sao quan trọng	Điều cần tránh
Base URL	Giữ lựa chọn router bên ngoài logic nghiệp vụ.	Hardcode URL của nhà cung cấp trong nhiều file.
API key	Tách riêng thông tin xác thực của nhà cung cấp trực tiếp khỏi thông tin xác thực của router.	Tái sử dụng các key cũ của nhà cung cấp cho tuyến Flatkey.
Model ID	Cho phép bạn ánh xạ có chủ đích một model của Google sang model trong danh mục của Flatkey.	Giả định mọi bí danh model của nhà cung cấp đều tồn tại phía sau router.
Giá trị khôi phục	Cho phép bạn nhanh chóng khôi phục tuyến trước đó.	Để việc khôi phục yêu cầu triển khai code.

Mẫu Python cho Định tuyến Flatkey Gemini

Chỉ là mẫu: hãy chạy đoạn này với một khóa Flatkey hợp lệ và một ID mô hình Flatkey Gemini đã được xác nhận trước khi sử dụng trong môi trường production.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_GEMINI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Trả lời bằng một câu xác nhận rằng tuyến Gemini đã được cấu hình.",
        }
    ],
)

print(response.choices[0].message.content)
print(response.usage)

Phương thức trong OpenAI SDK thì quen thuộc, nhưng đừng coi đây là một quá trình chuyển đổi Gemini API tương thích với OpenAI đã hoàn tất cho đến khi nhật ký sử dụng của Flatkey hiển thị yêu cầu, mô hình, mức sử dụng token, trạng thái và chi phí.

Mẫu JavaScript cho Định tuyến Flatkey Gemini

Chỉ là mẫu: hãy chạy với một khóa Flatkey hợp lệ và một model ID đã được xác nhận từ danh mục Flatkey hiện tại.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_GEMINI_MODEL,
  messages: [
    {
      role: "user",
      content: "Reply with one sentence confirming the Gemini route is configured.",
    },
  ],
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Đối với các đội đã sử dụng SDK tương thích với OpenAI, cách này giúp việc chuyển đổi trở nên nhỏ gọn. Phần công việc sản xuất nằm ở xác thực tính năng, ánh xạ model, hạn mức và kiểm tra thanh toán.

Danh sách kiểm tra tính năng trước khi đưa vào sản xuất

Sử dụng danh sách kiểm tra này trước khi coi một tuyến Gemini API tương thích OpenAI là sẵn sàng.

Tính năng	Tín hiệu từ Google Docs	Kiểm tra Flatkey Router
Hoàn thành chat cơ bản	Các ví dụ SDK OpenAI và REST được tài liệu hóa.	Xác nhận phản hồi và nhật ký sử dụng Flatkey.
Streaming	Google tài liệu hóa streaming với các lời gọi kiểu OpenAI.	Kiểm tra xử lý luồng, timeout và phân tích đầu ra một phần.
Gọi hàm	Google tài liệu hóa gọi công cụ/hàm thông qua các ví dụ tương thích.	Kiểm tra chính xác schema công cụ và hành vi lựa chọn công cụ của bạn.
Hiểu hình ảnh	Google tài liệu hóa đầu vào hình ảnh thông qua chat completions.	Xác nhận mô hình Flatkey chấp nhận định dạng hình ảnh mà SDK của bạn gửi.
Embeddings và batch	Google tài liệu hóa embeddings và các ví dụ liên quan đến batch.	Kiểm tra như một đường dẫn endpoint riêng, không giả định là chat.
Tải lên/tải xuống tệp	Google cho biết tải lên/tải xuống tương thích OpenAI hiện chưa được hỗ trợ.	Sử dụng một kế hoạch tệp riêng theo nhà cung cấp nếu quy trình của bạn phụ thuộc vào tệp.
Giá	Google duy trì trang giá cho Gemini Developer API.	Sử dụng giá của Flatkey cho lưu lượng được định tuyến, sau đó xác minh nhật ký chi phí thực tế.

Smoke Test Runbook

Một bài kiểm tra khói tương thích với Gemini API OpenAI nên chứng minh cả hành vi API lẫn khả năng hiển thị của router.

1. Chọn một ID mô hình Gemini từ danh mục Flatkey hiện tại.
2. Tạo hoặc chọn một khóa Flatkey ít rủi ro để kiểm thử.
3. Đặt OPENAI_BASE_URL thành https://router.flatkey.ai/v1.
4. Chạy một prompt chat đơn giản không streaming.
5. Xác nhận dạng của thông điệp trợ lý khớp với bộ phân tích cú pháp của ứng dụng bạn.
6. Kiểm tra nhật ký sử dụng Flatkey cho mô hình, trạng thái, token và chi phí.
7. Chạy một bài kiểm tra mô hình sai và ghi lại dạng lỗi.
8. Chỉ chạy streaming, gọi công cụ, vision hoặc embeddings nếu ứng dụng của bạn sử dụng chúng.
9. Đặt một hạn mức nhỏ trước khi bất kỳ lưu lượng thực nào được gửi.
10. Giữ URL base của nhà cung cấp trước đó và mô hình làm cấu hình rollback.

Mục tiêu không chỉ là làm cho một phản hồi Gemini xuất hiện. Mục tiêu là biết yêu cầu đã đi qua tuyến nào, chi phí là bao nhiêu, lỗi trông như thế nào, và bạn có thể rollback nhanh đến mức nào.

Các lỗi thường gặp

• Sử dụng URL gốc tương thích OpenAI Gemini trực tiếp của Google khi bạn định kiểm tra Flatkey.
• Sử dụng ID mô hình của Google mà không xác nhận chuỗi mô hình trong danh mục của Flatkey.
• Giả định rằng tải lên/tải xuống tệp hoạt động qua mọi đường dẫn tương thích OpenAI.
• Chỉ kiểm tra chat completions khi môi trường production dùng streaming hoặc tools.
• Bỏ qua kiểm tra usage-log và billing sau khi nhận được phản hồi thành công.
• Xuất bản các đoạn mã có khóa trông như thật hoặc ID mô hình production chưa được kiểm thử.

Đây là những chi tiết nhỏ, nhưng chính tại đó hầu hết các lần di chuyển Gemini API OpenAI compatible bị thất bại. Bộ định tuyến giúp việc truy cập dễ hơn; nó không loại bỏ nhu cầu kiểm tra đúng định dạng yêu cầu.

Cách Điều Này Phù Hợp Với Các Hướng Dẫn Di Chuyển Flatkey Hiện Có

Nếu đây là lần đầu tiên bạn di chuyển router, hãy bắt đầu với hướng dẫn di chuyển API tương thích OpenAI tổng quát hơn. Hướng dẫn này bao gồm mẫu URL cơ sở, biến môi trường, kiểm tra nhanh, quay lui và các kiểm tra trên dashboard áp dụng cho bất kỳ nhà cung cấp nào.

Sau đó, hãy dùng hướng dẫn dành riêng cho Gemini này để xem các chi tiết về nhà cung cấp: endpoint tương thích trực tiếp của Google, lựa chọn mô hình Gemini, hỗ trợ tính năng và các giới hạn xử lý tệp. Đối với các mẫu truy cập mô hình liền kề, hãy so sánh hướng dẫn truy cập API DeepSeek và hướng dẫn proxy vs router cho API Claude.

FAQ

Gemini API có tương thích với OpenAI không?

Google có tài liệu về khả năng tương thích với OpenAI cho Gemini thông qua các thư viện OpenAI Python và JavaScript cùng các ví dụ REST. Điều đó không có nghĩa mọi endpoint hay tham số của OpenAI đều hoạt động giống hệt, vì vậy hãy kiểm tra đúng tính năng mà ứng dụng của bạn sử dụng.

URL gốc OpenAI trực tiếp của Gemini là gì?

URL gốc OpenAI-compatible trực tiếp được Google tài liệu hóa là https://generativelanguage.googleapis.com/v1beta/openai/. Hãy dùng URL đó khi gọi trực tiếp Google bằng khóa API Gemini.

Tôi nên dùng URL gốc nào cho Gemini qua Flatkey?

Hãy dùng https://router.flatkey.ai/v1 cho tuyến Flatkey tương thích với OpenAI. Sau đó chọn một model ID Gemini từ bảng giá Flatkey hoặc dashboard và kiểm tra yêu cầu trước khi đưa vào sản xuất.

Tôi có thể dùng cùng model ID từ tài liệu của Google trong Flatkey không?

Không phải tự động. Chuỗi model và mức độ khả dụng có thể khác nhau theo danh mục và tuyến. Hãy chọn model ID từ Flatkey vào ngày bạn kiểm thử và lưu nó trong cấu hình.

OpenAI-compatible có nghĩa là tương đương đầy đủ tính năng không?

Không. OpenAI-compatible thường có nghĩa là các dạng yêu cầu và phản hồi phổ biến hoạt động với những endpoint được hỗ trợ. Google nêu rõ rằng upload và download tương thích với OpenAI hiện chưa được hỗ trợ, vì vậy cần kiểm thử ở cấp tính năng.

Tôi nên lập ngân sách cho Gemini qua một router như thế nào?

Hãy dùng tài liệu giá của Google cho ngữ cảnh Gemini trực tiếp và bảng giá Flatkey cho lượt sử dụng qua router. Sau đó xác minh chi phí yêu cầu thực tế trong log của Flatkey vì model, cache, batch và các đơn vị modality có thể khác nhau.

Xem giá trước khi bạn chuyển lưu lượng sản xuất

Gemini API OpenAI compatible là một lộ trình chuyển đổi thực tế khi ứng dụng của bạn đã sử dụng các lệnh gọi SDK theo kiểu OpenAI. Hãy giữ thay đổi ở mức nhỏ: cập nhật base URL, dùng khóa Flatkey, chọn một mô hình Gemini hiện tại, chạy các bài kiểm tra khói, và xác minh mức sử dụng cũng như giá trước khi triển khai.

Xem giá để xác nhận các tùy chọn mô hình Flatkey Gemini hiện tại và đơn vị chi phí trước khi bạn gửi lưu lượng sản xuất.