Hướng dẫn tích hợp Gemini API: Gọi API tương thích Google và hỗ trợ ngữ cảnh lớn

I. Tổng quan

Trang web này cung cấp khả năng truy cập tương thích với định dạng Google Gemini API, hỗ trợ hai phương thức gọi là generateContent và tạo luồng (streaming). Các dự án sử dụng Google GenAI SDK hoặc các trình khách tương thích với Gemini có thể kết nối bằng cách trỏ địa chỉ yêu cầu tới cổng Gemini của trang web chúng tôi và thay thế khóa (key) bằng khóa sk- do trang web cung cấp.

Các dòng mô hình Gemini hiện có sẵn tuân theo danh sách tại trung tâm mô hình (như gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, v.v.). Bạn có thể truy vấn danh sách đầy đủ và đơn giá thông qua GET /v1/models.

II. Địa chỉ giao diện (API Endpoint)

Phương thức	Đường dẫn	Mô tả
POST	/v1beta/models/{model}:generateContent	Điểm cuối tạo Gemini, phần thân yêu cầu là payload generateContent
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	Tạo luồng (SSE)
GET	/v1/models	Danh sách mô hình và đơn giá (không cần xác thực)

Địa chỉ gateway: https://www.relay-api.com. Tên mô hình được nối trực tiếp vào URL (/v1beta/models/{model}:generateContent, giống với quy định chính thức của Google); phần thân yêu cầu là payload generateContent.

III. Phương thức xác thực

Tương tự như các giao diện khác trên trang web, hãy sử dụng khóa sk- của hệ thống:

Authorization: Bearer sk-khóa_của_bạn

Hệ thống cũng tương thích với tiêu đề x-api-key và tiêu đề x-goog-api-key: sk-khóa_của_bạn của Google.

IV. Bắt đầu nhanh (curl)

4.1 Không tạo luồng (Non-streaming)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-khóa_của_bạn" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Giới thiệu về Gemini API bằng một câu"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 Sử dụng chỉ dẫn hệ thống (systemInstruction)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-khóa_của_bạn" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "Bạn là một kỹ sư tích hợp API chuyên nghiệp, hãy trả lời ngắn gọn."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Làm thế nào để chọn giữa giao diện tạo luồng và không tạo luồng?"}]}
    ]
  }'

V. Tham số yêu cầu

Trường	Loại	Bắt buộc	Mô tả
model	string	Có	Slug của mô hình, ví dụ: gemini-3.7-flash
contents	array	Có	Nội dung hội thoại, các phần tử là {role, parts[]}; role nhận giá trị user / model
contents[].parts	array	Có	Khối nội dung, thường dùng khối văn bản {text}
systemInstruction	object	Không	Chỉ dẫn hệ thống, cấu trúc {parts: [{text}]}
generationConfig.temperature	number	Không	Nhiệt độ lấy mẫu, mặc định 1.0
generationConfig.topP	number	Không	Lấy mẫu hạt nhân
generationConfig.topK	int	Không	Lấy mẫu Top-K
generationConfig.maxOutputTokens	int	Không	Số lượng token đầu ra tối đa
generationConfig.stopSequences	array	Không	Chuỗi dừng
stream	bool	Không	Có trả về theo luồng hay không, mặc định false

VI. Cấu trúc phản hồi

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini API hỗ trợ văn bản, đầu vào đa phương thức và đầu ra luồng."}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

Trường	Mô tả
candidates[].content.parts[].text	Văn bản do mô hình tạo ra
candidates[].finishReason	Lý do kết thúc: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	Số lượng token đầu vào (căn cứ tính phí)
usageMetadata.candidatesTokenCount	Số lượng token đầu ra (căn cứ tính phí)
usageMetadata.totalTokenCount	Tổng số token

VII. Đầu ra luồng (Streaming)

Sau khi thêm "stream": true vào phần thân yêu cầu, máy chủ sẽ trả về nội dung ứng viên theo từng khối SSE:

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " API hỗ trợ"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " đầu ra luồng."}]}, "index": 0, "finishReason": "STOP"}]}

Trình khách phân tích từng dòng data: và nối candidates[0].content.parts[0].text; khi finishReason của khối cuối cùng là STOP, quá trình tạo đã hoàn tất.

VIII. Mã lỗi phổ biến

Mã trạng thái HTTP	Ý nghĩa	Đề xuất xử lý
400	Sai định dạng yêu cầu (thiếu contents, mô hình không tồn tại, v.v.)	Kiểm tra phần thân yêu cầu và tên mô hình
401	Khóa API không hợp lệ hoặc bị thiếu	Kiểm tra tiêu đề Authorization / x-api-key
403	Khóa bị vô hiệu hóa, không đủ số dư hoặc khóa không được cấp quyền cho mô hình/tuyến đường này	Nạp tiền hoặc kiểm tra quyền của khóa
404	Mô hình hoặc điểm cuối không tồn tại	Xác nhận lại slug của mô hình
429	Yêu cầu quá thường xuyên	Chờ và thử lại
500	Lỗi máy chủ nội bộ	Thử lại sau, nếu lỗi tiếp diễn vui lòng liên hệ dịch vụ khách hàng

Phần thân phản hồi lỗi có cấu trúc thống nhất là {"code": mã_trạng_thái, "message": "Mô tả lỗi", "data": null}.

IX. Ghi chú về tính tương thích

• Google GenAI SDK (google-genai) có thể được kết nối thông qua endpoint tùy chỉnh.
• Hỗ trợ tất cả các trình khách tương thích với Gemini nhắm mục tiêu là generateContent.
• Tên mô hình phải dựa trên slug được trả về từ GET /v1/models.