Google GenAI SDK
MarkdownĐịnh dạng gốc của Gemini: Google GenAI SDK cho Python và JavaScript cùng các yêu cầu REST trực tiếp.
Hướng dẫn đầy đủ
Cài đặt
pip install google-genainpm install @google/genaiKết nối
Địa chỉ — https://api.ailoot.ai không có /v1beta: SDK sẽ tự tạo đường dẫn /v1beta/models/<mô hình>:generateContent . Trong Python, địa chỉ được đặt qua HttpOptions(base_url=…), còn trong JavaScript là qua httpOptions.baseUrl. SDK sẽ gửi khóa trong tiêu đề x-goog-api-key.
from google import genai
from google.genai import types
import os
client = genai.Client(
api_key=os.environ["AILOOT_API_KEY"],
http_options=types.HttpOptions(base_url="https://api.ailoot.ai"), # không có /v1beta
)
resp = client.models.generate_content(
model="gemini-3.8-flash",
contents="Nghĩ ra ba tên cho một quán cà phê.",
)
print(resp.text)import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: process.env.AILOOT_API_KEY,
httpOptions: { baseUrl: "https://api.ailoot.ai" }, // không có /v1beta
});
const resp = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "Nghĩ ra ba tên cho một quán cà phê.",
});
console.log(resp.text);curl "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $AILOOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "Nghĩ ra ba tên cho một quán cà phê."}]}
]
}' Có thể gửi những gì
- Các trường cấp cao nhất:
contents,systemInstruction,generationConfig,safetySettings,toolsvàtoolConfig. generationConfigchấp nhậntemperature,topP,topK,maxOutputTokens,thinkingConfig,responseMimeType(text/plainhoặcapplication/json),responseSchemahoặcresponseJsonSchema(đối tượng JSON),stopSequences(mảng chuỗi),candidateCount: 1, tham số số nguyênseed, các tham số sốpresencePenaltyvàfrequencyPenalty. Phạm vi giá trị và khả năng hỗ trợ phụ thuộc vào mô hình cụ thể; để nhận phản hồi JSON, hãy chọn một dạng lược đồ được hỗ trợ vàapplication/json. Với các mô hình văn bản,responseModalities— chỉ["TEXT"].safetySettings— mảng các đối tượng cócategory,thresholdvà trường tùy chọnmethod; hãy chọn giá trị theo tài liệu của đúng mô hình.- Với các mô hình Gemini hỗ trợ loại đầu vào tương ứng,
parts[].inlineDatachứamimeTypevà dữ liệu base64 không rỗng; PDF phải là tệp PDF thực.fileDatachứa địa chỉ công khai dùnghttpstrongfileUrivà MIME của loại tệp. Với YouTube, có thể không chỉ định MIME.http, địa chỉ riêng tư,gs://và các đối tượng Google Files API không được hỗ trợ; tải lên qua Google Files API cũng không được hỗ trợ. Với video, có thể thêmvideoMetadata:startOffset/endOffsetdưới dạng chuỗi tính bằng giây (ví dụ,1.5s) vàfpslớn hơn 0 và không quá 24. Kích thước phần thân, ngữ cảnh, đầu vào được phép và giới hạn phản hồi được kiểm tra theo mô hình và định dạng. - Các hàm phía máy khách
functionDeclarationsđược ứng dụng của bạn thực thi. Với các mô hình văn bản, cũng chấp nhận{"googleSearch": {}}và{"urlContext": {}}: riêng lẻ hoặc cùng nhau trong mảngtools. Không được kết hợp Google Search hay URL context vớifunctionDeclarationstrong cùng một yêu cầu. Đối với ảnh đầu ra, chỉ hỗ trợ các hàm phía máy khách. Các công cụ tích hợp khác và explicit cache không được hỗ trợ. Search/URL context có thể yêu cầu giữ tiền theo toàn bộ giới hạn đầu vào; sốtoolUsePromptTokenCountthực tế được tính là token đầu vào. - Nếu mô hình không hỗ trợ trường, tệp đính kèm hoặc tổ hợp công cụ, yêu cầu sẽ bị từ chối trước khi giữ tiền — không có khoản nào bị khấu trừ. Phản hồi HTTP
400cóstatusINVALID_ARGUMENTvà lớpinvalid_request(trongErrorInfo.reason—INVALID_REQUEST). JSON không hợp lệ, lỗi tham số đường dẫn và các lỗi kiểm tra khác cũng trả về400; hãy đọc thông báo lỗi và Request ID. Khả năng hỗ trợ phụ thuộc vào mô hình: kiểm tra định dạng và đầu vào của mô hình trong danh mục.
| Đầu vào | Các MIME được hỗ trợ |
|---|---|
| Ảnh inline | image/png, image/jpeg, image/webp |
| Tài liệu | application/pdf; text/plain, text/html, text/css, text/csv, text/xml, text/rtf, text/markdown, text/javascript, application/x-javascript, text/x-python, application/x-python |
| Âm thanh | audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac |
| Video | video/mp4, video/mpeg, video/mov, video/quicktime, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp |
import json, os, urllib.request
def generate(model, payload):
req = urllib.request.Request(
"https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
data=json.dumps(payload).encode(),
headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
"Content-Type": "application/json"},
)
# Chỉ gửi một lần. Nếu hết thời gian chờ, hãy kiểm tra Request ID trong lịch sử sử dụng trước khi thử lại.
with urllib.request.urlopen(req, timeout=300) as response:
print("Request ID:", response.headers.get("X-Request-ID"))
return json.load(response)
import base64, pathlib, sys
# Cung cấp một tệp PDF, âm thanh hoặc video có thật trên máy cùng loại MIME được hỗ trợ của tệp đó.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
{"text": "Mô tả ngắn gọn nội dung tệp."},
{"inlineData": {"mimeType": mime,
"data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Cách đính kèm khác: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Với URL YouTube có thật: {"fileData": {"fileUri": youtube_url}}Chu trình gọi hàm đầy đủ
Gửi khai báo hàm, nhận functionCall, thực thi hàm của bạn, trả về functionResponse rồi yêu cầu câu trả lời tiếp theo. Giữ nguyên toàn bộ content của mô hình, bao gồm thoughtSignature; không tự tạo chữ ký.
import json, os, urllib.request
def generate(model, payload):
req = urllib.request.Request(
"https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
data=json.dumps(payload).encode(),
headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
"Content-Type": "application/json"},
)
# Chỉ gửi một lần. Nếu hết thời gian chờ, hãy kiểm tra Request ID trong lịch sử sử dụng trước khi thử lại.
with urllib.request.urlopen(req, timeout=300) as response:
print("Request ID:", response.headers.get("X-Request-ID"))
return json.load(response)
tools = [{"functionDeclarations": [{
"name": "multiply", "description": "Nhân hai số",
"parameters": {"type": "object", "properties": {
"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Nhân 7 với 8 bằng hàm"}]}]
for turn in range(4): # Giới hạn số vòng gọi công cụ; không gửi lại yêu cầu khi chưa rõ kết quả.
reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
content = reply["candidates"][0]["content"]
contents.append(content) # Giữ nguyên TẤT CẢ các phần gốc và thoughtSignature.
results = []
for part in content.get("parts", []):
call = part.get("functionCall")
if not call:
continue
if call["name"] != "multiply":
raise ValueError("Unexpected function")
args = call["args"]
result = {"name": call["name"], "response": {"value": args["a"] * args["b"]}}
if "id" in call:
result["id"] = call["id"]
results.append({"functionResponse": result})
if not results:
print(content)
break
contents.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool loop limit reached")Phản hồi dạng luồng
for chunk in client.models.generate_content_stream(
model="gemini-3.8-flash",
contents="Mô tả hoàng hôn trên biển",
):
print(chunk.text, end="", flush=True)curl -N "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $AILOOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Mô tả hoàng hôn trên biển"}]}]}' Các mô hình khả dụng
Có 27 mã định danh hỗ trợ định dạng Gemini: gemini-3.8-flash, gemini-3.1-pro, gemini-pro-agent, gemini-3.8-flash-tiered, gemini-3.8-flash-medium, gemini-3.8-flash-low, gemini-3.8-flash-high, gemini-3.7-flash, gemini-3.7-flash-tiered, gemini-3.7-flash-medium, gemini-3.7-flash-low, gemini-3.7-flash-high, gemini-3.6-flash, gemini-3.6-flash-tiered, gemini-3.6-flash-medium, gemini-3.6-flash-low, gemini-3.6-flash-high, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3.1-pro-low, gemini-3.1-pro-high, gemini-3.1-flash-lite, gemini-3-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-thinking, gemini-2.5-flash-lite.
Các mô hình Gemini cũng dùng được qua định dạng Anthropic Messages — thuận tiện cho ứng dụng chỉ hỗ trợ định dạng này: Anthropic SDK.