Gemini generateContent

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": "Cadangkan tiga nama untuk kedai kopi."}]}
    ]
  }' 

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"),  # tanpa /v1beta
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Cadangkan tiga nama untuk kedai kopi.",
)
print(resp.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.AILOOT_API_KEY,
  httpOptions: { baseUrl: "https://api.ailoot.ai" }, // tanpa /v1beta
});

const resp = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Cadangkan tiga nama untuk kedai kopi.",
});
console.log(resp.text);

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "1. «Biji dan Wap» 2. «Kisaran Pagi» 3. «Kedai Kopi di Sudut»" }]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  },
  "modelVersion": "gemini-3.8-flash"
}

Pengesahan

• x-goog-api-keyheaderwajib

  Kunci sk-…. Pengepala berikut juga diterima Authorization: Bearer atau x-api-key. Untuk keserasian dengan Google, bentuk berikut juga diterima ?key= dalam alamat — dengan keutamaan paling rendah; ?api_key= ditolak dengan 400. Kami mengesyorkan pengepala: dengan cara ini kunci tidak masuk ke dalam log.

Laluan

• modelstringwajib

  ID model yang menggunakan format Gemini, contohnya gemini-3.8-flash atau gemini-3.1-pro. Jumlahnya 27.

Badan permintaan

• contentsarraywajib

  Mesej dengan role (user/model) dan parts: text, inlineData/fileData, functionCall/functionResponse. Lampiran mestilah jenis yang diterima oleh model sebagai input.

• systemInstructionobjectpilihan

  Arahan sistem berbentuk teks: {"parts": [{"text": "…"}]}.

• generationConfigobjectpilihan

  generationConfig menerima temperature, topP, topK, maxOutputTokens, thinkingConfig, responseMimeType (text/plain atau application/json), responseSchema atau responseJsonSchema (objek JSON), stopSequences (tatasusunan rentetan), candidateCount: 1, integer seed, nilai berangka presencePenalty dan frequencyPenalty. Julat dan keupayaan yang dibenarkan bergantung pada model tepat; untuk respons JSON, pilih satu bentuk skema yang disokong dan application/json. Bagi model teks responseModalities — hanya ["TEXT"].

• safetySettingsarraypilihan

  Objek dengan medan wajib category dan threshold, medan pilihan method. Nilai mesti disokong oleh model tepat.

• toolsarraypilihan

  Fungsi klien functionDeclarations dilaksanakan oleh aplikasi anda. Model teks juga menerima {"googleSearch": {}} dan {"urlContext": {}}: secara berasingan atau bersama-sama dalam tatasusunan tools. Google Search dan URL context tidak boleh digabungkan dengan functionDeclarations dalam permintaan yang sama. Untuk output imej, hanya fungsi klien tersedia. Alat terbina dalam lain dan explicit cache tidak disokong. Search/URL context mungkin memerlukan rizab berdasarkan had penuh input; nilai sebenar toolUsePromptTokenCount dikira sebagai token input.

• toolConfigobjectpilihan

  functionCallingConfig: mode (AUTO/ANY/NONE/VALIDATED/MODE_UNSPECIFIED), allowedFunctionNames.

Jika model tidak menyokong medan, lampiran atau gabungan alat, permintaan ditolak sebelum rizab dibuat — tiada caj dikenakan. HTTP yang diterima ialah 400 dengan status INVALID_ARGUMENT dan kelas invalid_request (dalam ErrorInfo.reason — INVALID_REQUEST). JSON tidak sah, ralat parameter laluan dan kegagalan semakan lain juga mengembalikan 400; baca mesej ralat dan Request ID. Keupayaan bergantung pada model: semak format dan inputnya dalam katalog.

PDF, audio, video dan pautan

Bagi model Gemini yang menyokong input berkenaan parts[].inlineData mengandungi mimeType dan data base64 yang tidak kosong; PDF mestilah fail PDF sebenar. fileData mengandungi alamat awam berprotokol httpsdalam fileUri dan jenis MIME fail. Untuk YouTube, MIME boleh diabaikan. http, alamat peribadi, gs:// dan objek Google Files API tidak disokong, begitu juga muat naik melalui Google Files API. Untuk video, anda boleh menambah videoMetadata: startOffset/endOffset sebagai rentetan dalam saat (contohnya, 1.5s) dan fps lebih daripada 0 dan tidak melebihi 24. Saiz badan permintaan, konteks, input yang dibenarkan dan had respons diperiksa mengikut model dan format.

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"},
    )
    # Hantar sekali sahaja. Selepas tamat masa, semak Request ID dalam sejarah penggunaan anda sebelum mencuba semula.
    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

# Sediakan fail PDF, audio atau video setempat yang sebenar berserta jenis MIME yang disokong.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
    {"text": "Huraikan kandungan fail secara ringkas."},
    {"inlineData": {"mimeType": mime,
                    "data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Lampiran alternatif: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Untuk URL YouTube sebenar: {"fileData": {"fileUri": youtube_url}}

Search dan URL context

Fungsi klien functionDeclarations dilaksanakan oleh aplikasi anda. Model teks juga menerima {"googleSearch": {}} dan {"urlContext": {}}: secara berasingan atau bersama-sama dalam tatasusunan tools. Google Search dan URL context tidak boleh digabungkan dengan functionDeclarations dalam permintaan yang sama. Untuk output imej, hanya fungsi klien tersedia. Alat terbina dalam lain dan explicit cache tidak disokong. Search/URL context mungkin memerlukan rizab berdasarkan had penuh input; nilai sebenar toolUsePromptTokenCount dikira sebagai token input.

{"tools": [{"googleSearch": {}}, {"urlContext": {}}]}

Output imej

Hanya model berikut boleh menghasilkan imej dalam respons berformat Gemini gemini-3.1-flash-image. Keupayaan ini berasingan daripada /v1/images/generations: model imej lain tidak berfungsi di sini. Model ini menerima input sehingga 131072 token dan respons sehingga 32768; kos penuh respons paling panjang dirizabkan terlebih dahulu.

responseModalities — set TEXT/IMAGE yang tidak kosong tanpa pengulangan. imageConfig.imageSize: 1K/2K/4K; aspectRatio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1. Input model ini ialah teks dan PNG/JPEG/WebP inline; PDF/audio/video/fileData dan Search/URL context terbina dalam tidak diterima di sini. Ketersediaan dan harga bagi kunci anda terdapat dalam katalog dan GET /v1/models.

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"},
    )
    # Hantar sekali sahaja. Selepas tamat masa, semak Request ID dalam sejarah penggunaan anda sebelum mencuba semula.
    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

reply = generate("gemini-3.1-flash-image", {
    "contents": [{"role": "user", "parts": [{"text": "Cat air: rumah api pada waktu fajar"}]}],
    "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"},
    },
})
index = 0
for candidate in reply.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        if "text" in part:
            print(part["text"])
        blob = part.get("inlineData", {})
        if blob.get("mimeType", "").startswith("image/") and blob.get("data"):
            index += 1
            extension = {"image/png": "png", "image/jpeg": "jpg",
                         "image/webp": "webp"}.get(blob["mimeType"], "bin")
            pathlib.Path(f"gemini-image-v{index}.{extension}").write_bytes(
                base64.b64decode(blob["data"]))
print("All returned images:", index)

Kitaran penuh function calling

Fungsi dilaksanakan oleh klien. Kembalikan keseluruhan content asal model bersama thoughtSignature tanpa perubahan, kemudian functionResponse dengan name dan id yang sama, jika id ada dalam functionCall.

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"},
    )
    # Hantar sekali sahaja. Selepas tamat masa, semak Request ID dalam sejarah penggunaan anda sebelum mencuba semula.
    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": "Mendarab dua nombor",
    "parameters": {"type": "object", "properties": {
        "a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Darabkan 7 dengan 8 menggunakan fungsi"}]}]
for turn in range(4):  # Hadkan gelung alat; jangan hantar semula permintaan yang hasilnya tidak jelas.
    reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
    content = reply["candidates"][0]["content"]
    contents.append(content)  # Kekalkan SEMUA (ALL) bahagian asal dan thoughtSignature tanpa perubahan.
    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")

Respons

• candidates[].content.partsarray

  Respons model.

• usageMetadataobject

  promptTokenCount, candidatesTokenCount, totalTokenCount.