tài liệu
Kết nối

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-genai

Kế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)

Có thể gửi những gì

  • Các trường cấp cao nhất: contents, systemInstruction, generationConfig, safetySettings, tools và toolConfig.
  • generationConfig chấp nhận temperature, topP, topK, maxOutputTokens, thinkingConfig, responseMimeType (text/plain hoặc application/json), responseSchema hoặc responseJsonSchema (đối tượng JSON), stopSequences (mảng chuỗi), candidateCount: 1, tham số số nguyên seed, các tham số số presencePenalty và 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, threshold và trường tùy chọn method; 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[].inlineData chứa mimeType và dữ liệu base64 không rỗng; PDF phải là tệp PDF thực. fileData chứa địa chỉ công khai dùng https trong fileUri và 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êm videoMetadata: startOffset/endOffset dưới dạng chuỗi tính bằng giây (ví dụ, 1.5s) và fps lớ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ảng tools. Không được kết hợp Google Search hay URL context với functionDeclarations trong 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ố toolUsePromptTokenCount thự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 400 có status INVALID_ARGUMENT và lớp invalid_request (trong ErrorInfo.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àoCác MIME được hỗ trợ
Ảnh inlineimage/png, image/jpeg, image/webp
Tài liệuapplication/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 thanhaudio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac
Videovideo/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)

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.

Còn câu hỏi? Hãy gửi Request ID và mô tả — chúng tôi sẽ giúp tìm hiểu.Liên hệ hỗ trợ