docs
API

Gemini generateContent

Markdown

Savasis Google Gemini formatas: Gemini CLI, Google GenAI SDK ir REST klientams.

Visas vadovas
POSThttps://api.ailoot.ai/v1beta/models/{model}:generateContent
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": "Sugalvok tris pavadinimus kavinei."}]}
    ]
  }' 
200 OK
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "1. „Pupelė ir garai“ 2. „Rytinis malimas“ 3. „Kampinė kavinė“" }]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  },
  "modelVersion": "gemini-3.8-flash"
}

Autorizacija

  • x-goog-api-keyheaderprivalomas

    Raktas sk-…. Taip pat tinka Authorization: Bearer arba x-api-key. Suderinamumui su Google taip pat priimamas ?key= adrese — jam teikiamas mažiausias prioritetas; ?api_key= atmetamas grąžinant 400. Rekomenduojame antraštę: taip raktas nepatenka į žurnalus.

Kelias

  • modelstringprivalomas

    Gemini formato modelio ID, pavyzdžiui, gemini-3.8-flash arba gemini-3.1-pro. Iš viso 27.

POSThttps://api.ailoot.ai/v1beta/models/{model}:streamGenerateContent?alt=sse
GEThttps://api.ailoot.ai/v1beta/models

Užklausos turinys

  • contentsarrayprivalomas

    Pranešimai su role (user/model) ir parts: text, inlineData/fileData, functionCall/functionResponse. Priedai — tie, kuriuos modelis priima kaip įvestį.

  • systemInstructionobjectneprivalomas

    Tekstinė sistemos instrukcija: {"parts": [{"text": "…"}]}.

  • generationConfigobjectneprivalomas

    generationConfig priima temperature, topP, topK, maxOutputTokens, thinkingConfig, responseMimeType (text/plain arba application/json), responseSchema arba responseJsonSchema (JSON objektas), stopSequences (eilučių masyvas), candidateCount: 1, sveikąjį skaičių seed, skaitines reikšmes presencePenalty ir frequencyPenalty. Leistini intervalai ir galimybės priklauso nuo konkretaus modelio; JSON atsakymui pasirinkite vieną palaikomą schemos formą ir application/json. Tekstinių modelių responseModalities — tik ["TEXT"].

  • safetySettingsarrayneprivalomas

    Objektai su privalomais category ir threshold, neprivalomu method. Reikšmes turi palaikyti konkretus modelis.

  • toolsarrayneprivalomas

    Kliento functionDeclarations vykdo jūsų programa. Tekstiniai modeliai taip pat priima {"googleSearch": {}} ir {"urlContext": {}}: atskirai arba kartu masyve tools. Nei Google Search, nei URL context negalima derinti su functionDeclarations vienoje užklausoje. Vaizdų išvesčiai prieinamos tik kliento funkcijos. Kiti integruoti įrankiai ir explicit cache nepalaikomi. Search/URL context gali reikėti rezervo pagal visą įvesties limitą; faktiniai toolUsePromptTokenCount įskaičiuojami kaip įvesties žetonai.

  • toolConfigobjectneprivalomas

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

Jei modelis nepalaiko lauko, priedo ar įrankių derinio, užklausa atmetama prieš rezervuojant lėšas — nieko nenurašoma. Grąžinamas HTTP 400 su status INVALID_ARGUMENT ir klase invalid_request (lauke ErrorInfo.reason — INVALID_REQUEST). Netaisyklingas JSON, kelio parametrų ir kitų patikrų klaidos taip pat grąžina 400; skaitykite klaidos tekstą ir Request ID. Galimybės priklauso nuo modelio: kataloge patikrinkite jo formatus ir įvestis.

PDF, garsas, vaizdo įrašai ir nuorodos

Gemini modeliuose, palaikančiuose atitinkamą įvestį, parts[].inlineData apima mimeType ir netuščius base64 duomenis; PDF turi būti tikras PDF failas. fileData apima viešą https adresą lauke fileUri ir failo tipo MIME. YouTube atveju MIME galima nenurodyti. http, privatūs adresai, gs:// ir Google Files API objektai nepalaikomi, taip pat nepalaikomas įkėlimas per Google Files API. Vaizdo įrašams galima pridėti videoMetadata: startOffset/endOffset eilute sekundėmis (pavyzdžiui, 1.5s) ir fps didesnis už 0 ir ne didesnis už 24. Turinio dydis, kontekstas, leistina įvestis ir atsakymo limitas tikrinami pagal modelį ir formatą.

ĮvestisPalaikomi MIME tipai
Įterptieji vaizdaiimage/png, image/jpeg, image/webp
Dokumentaiapplication/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
Garsasaudio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac
Vaizdo įrašaivideo/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"},
    )
    # Siųskite vieną kartą. Jei baigėsi laukimo laikas, prieš bandydami dar kartą naudojimo istorijoje patikrinkite Request ID.
    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

# Pateikite tikrą savo kompiuteryje esantį PDF, garso arba vaizdo failą ir palaikomą jo MIME tipą.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
    {"text": "Trumpai apibūdink failo turinį."},
    {"inlineData": {"mimeType": mime,
                    "data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Kitas priedo pateikimo būdas: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Jei naudojate tikrą YouTube URL: {"fileData": {"fileUri": youtube_url}}

Search ir URL context

Kliento functionDeclarations vykdo jūsų programa. Tekstiniai modeliai taip pat priima {"googleSearch": {}} ir {"urlContext": {}}: atskirai arba kartu masyve tools. Nei Google Search, nei URL context negalima derinti su functionDeclarations vienoje užklausoje. Vaizdų išvesčiai prieinamos tik kliento funkcijos. Kiti integruoti įrankiai ir explicit cache nepalaikomi. Search/URL context gali reikėti rezervo pagal visą įvesties limitą; faktiniai toolUsePromptTokenCount įskaičiuojami kaip įvesties žetonai.

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

Vaizdų išvestis

Vaizdus Gemini formato atsakyme gali pateikti tik gemini-3.1-flash-image. Tai atskira galimybė nuo /v1/images/generations: kiti vaizdų modeliai čia neveikia. Šio modelio įvestis — iki 131072 žetonų, atsakymas — iki 32768; visa ilgiausio atsakymo kaina rezervuojama iš anksto.

responseModalities — netuščia TEXT/IMAGE aibė be pasikartojimų. 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. Šio modelio įvestis — tekstas ir įterptieji PNG/JPEG/WebP; PDF/audio/video/fileData ir integruoti Search/URL context čia nepriimami. Prieinamumas ir kainos jūsų raktui — kataloge ir 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"},
    )
    # Siųskite vieną kartą. Jei baigėsi laukimo laikas, prieš bandydami dar kartą naudojimo istorijoje patikrinkite Request ID.
    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": "Akvarelė: švyturys auštant"}]}],
    "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)

Visas function calling ciklas

Funkcijas vykdo klientas. Grąžinkite visą pradinį modelio content su thoughtSignature nepakeistą, tada functionResponse su tuo pačiu name ir id, jei jis buvo 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"},
    )
    # Siųskite vieną kartą. Jei baigėsi laukimo laikas, prieš bandydami dar kartą naudojimo istorijoje patikrinkite Request ID.
    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": "Padauginti du skaičius",
    "parameters": {"type": "object", "properties": {
        "a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Naudodamas funkciją padaugink 7 iš 8"}]}]
for turn in range(4):  # Apribokite įrankių ciklo iteracijų skaičių; pakartotinai nesiųskite užklausos, kurios rezultatas neaiškus.
    reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
    content = reply["candidates"][0]["content"]
    contents.append(content)  # Visas pradines dalis (ALL) ir thoughtSignature palikite be pakeitimų.
    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")

Atsakymas

  • candidates[].content.partsarray

    Modelio atsakymas.

  • usageMetadataobject

    promptTokenCount, candidatesTokenCount, totalTokenCount.

Liko klausimų? Atsiųskite Request ID ir aprašymą — padėsime išsiaiškinti.Rašyti pagalbos tarnybai