AZZ API

Hướng dẫn truy cập Gemini API: Gọi tương thích Google và bối cảnh siêu lớn

Gọi các mô hình của chúng tôi thông qua cách tương thích với Google Gemini API: payload generateContent, địa chỉ giao diện, xác thực, ví dụ curl, trường yêu cầu/phản hồi, luồng và mã lỗi.

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 máy 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 đến cổng Gemini của trang web chúng tôi và thay khóa API bằng khóa sk- do hệ thống cung cấp.

Các dòng mô hình Gemini hiện có được dựa trên bảng danh mục mô hình (ví dụ: gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, v.v.). Danh sách đầy đủ và đơn giá có thể được truy vấn thông qua GET /v1/models.

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

Phương thứcĐường dẫnMô tả
POST/v1beta/models/{model}:generateContentCổng vào tạo nội dung Gemini, thân yêu cầu là payload của generateContent
POST/v1beta/models/{model}:streamGenerateContent?alt=sseTạo nội dung theo luồng (SSE)
GET/v1/modelsDanh sách mô hình và đơn giá (không yêu cầu xác thực)

Địa chỉ Gateway: https://www.relay-api.com. Tên mô hình được nối vào URL (/v1beta/models/{model}:generateContent, giống với Google chính thức); thân yêu cầu là payload của 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 của chúng tôi, hãy sử dụng khóa sk- của bạn:

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

Cũng hỗ trợ tiêu đề x-api-key và tiêu đề x-goog-api-key: sk-khóa_của_bạn theo chuẩn Google.

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

4.1 Không theo 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 trong một câu"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 Kèm theo 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 dày dặn kinh nghiệm, 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 luồng và không theo luồng?"}]}
    ]
  }'

V. Tham số yêu cầu

TrườngKiểuBắt buộcMô tả
modelstringCóSlug mô hình, ví dụ: gemini-3.7-flash
contentsarrayCóNội dung hội thoại, phần tử là {role, parts[]}; role nhận giá trị user / model
contents[].partsarrayCóKhối nội dung, thường dùng khối văn bản {text}
systemInstructionobjectKhôngChỉ dẫn hệ thống, cấu trúc {parts: [{text}]}
generationConfig.temperaturenumberKhôngNhiệt độ lấy mẫu, mặc định 1.0
generationConfig.topPnumberKhôngLấy mẫu nhân (top-p)
generationConfig.topKintKhôngLấy mẫu Top-K
generationConfig.maxOutputTokensintKhôngSố token đầu ra tối đa
generationConfig.stopSequencesarrayKhôngChuỗi dừng
streamboolKhôngCó trả về theo luồng 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ợ đầu vào văn bản, đa phương thức và đầu ra theo luồng."}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}
TrườngMô tả
candidates[].content.parts[].textVăn bản do mô hình tạo ra
candidates[].finishReasonLý do kết thúc: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCountSố token đầu vào (căn cứ tính phí)
usageMetadata.candidatesTokenCountSố token đầu ra (căn cứ tính phí)
usageMetadata.totalTokenCountTổng số token

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

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

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

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

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

Máy khách phân tích từng dòng data: và nối candidates[0].content.parts[0].text; khi finishReason của chunk cuối cùng là STOP, nghĩa là việc tạo nội dung đã hoàn tất.

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

Mã trạng thái HTTPÝ nghĩaKhuyên dùng
400Định dạng yêu cầu sai (thiếu contents, mô hình không tồn tại, v.v.)Kiểm tra thân yêu cầu và tên mô hình
401Khóa API không hợp lệ hoặc bị thiếuKiểm tra tiêu đề Authorization / x-api-key
403Khó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àyNạp tiền hoặc kiểm tra quyền của khóa
404Mô hình hoặc điểm cuối không tồn tạiXác nhận lại slug mô hình
429Yêu cầu quá thường xuyênChờ và thử lại (backoff)
500Lỗ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ệ CSKH

Thân phản hồi lỗi có cấu trúc đồng nhất: {"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 truy cập thông qua điểm cuối tùy chỉnh.
  • Hỗ trợ tất cả các máy khách tương thích với Gemini nhắm mục tiêu vào generateContent.
  • Tên mô hình dựa trên slug được trả về bởi GET /v1/models.

Ghi chú về Base URL: Trang web này chấp nhận cả /v1beta/models/... và /v1beta/v1beta/models/... (cũng như /v1/... và /v1/v1/...), vì vậy việc máy khách có tự bổ sung /v1 hay /v1beta hay không đều không ảnh hưởng đến việc gọi API: Bạn có thể điền Base URL là tên miền gốc hoặc địa chỉ chứa /v1beta đều được. Vui lòng tra cứu và sao chép ID mô hình từ mục "ID mô hình" ở góc trên bên phải của trang "Mã thông báo" trong bảng điều khiển.