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": "Кофеханаға үш атау ойлап тап."}]}
    ]
  }' 

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"),  # /v1beta қоспай
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Кофеханаға үш атау ойлап тап.",
)
print(resp.text)

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

const ai = new GoogleGenAI({
  apiKey: process.env.AILOOT_API_KEY,
  httpOptions: { baseUrl: "https://api.ailoot.ai" }, // /v1beta қоспай
});

const resp = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Кофеханаға үш атау ойлап тап.",
});
console.log(resp.text);

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "1. «Дән мен бу» 2. «Таңғы ұнтақтау» 3. «Бұрыштағы кофехана»" }]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  },
  "modelVersion": "gemini-3.8-flash"
}

Авторизация

• x-goog-api-keyheaderміндетті

  Кілт sk-…. Мыналар да жарайды: Authorization: Bearer немесе x-api-key. Google-мен үйлесімділік үшін мына нұсқа да қабылданады: ?key= мекенжайда — ең төмен басымдықпен; ?api_key= 400 қатесімен қабылданбайды. Тақырыпты қолдануды ұсынамыз: сонда кілт журналдарға түспейді.

Жол

• modelstringміндетті

  Gemini форматындағы модель ID-і, мысалы gemini-3.8-flash немесе gemini-3.1-pro. Барлығы 27.

Сұрау денесі

• contentsarrayміндетті

  Мына өрістері бар хабарламалар: role (user/model) және parts: text, inlineData/fileData, functionCall/functionResponse. Тіркемелер — модель кіріс ретінде қабылдайтын түрлер.

• systemInstructionobjectміндетті емес

  Мәтіндік жүйелік нұсқау: {"parts": [{"text": "…"}]}.

• generationConfigobjectміндетті емес

  generationConfig мына мәндерді қабылдайды: temperature, topP, topK, maxOutputTokens, thinkingConfig, responseMimeType (text/plain немесе application/json), responseSchema немесе responseJsonSchema (JSON нысаны), stopSequences (жолдар массиві), candidateCount: 1, бүтін санды seed, сандық presencePenalty және frequencyPenalty. Рұқсат етілген аралықтар мен мүмкіндіктер нақты модельге байланысты; JSON жауабы үшін қолдау көрсетілетін бір схема пішімін және мынаны таңдаңыз: application/json. Мәтіндік модельдерде responseModalities — тек ["TEXT"].

• safetySettingsarrayміндетті емес

  Мына міндетті өрістері бар нысандар: category және threshold, мына өріс міндетті емес: method. Мәндерге нақты модель қолдау көрсетуі керек.

• toolsarrayміндетті емес

  Клиенттік functionDeclarations арқылы анықталған функцияларды қолданбаңыз орындайды. Мәтіндік модельдерде мыналар да қабылданады: {"googleSearch": {}} және {"urlContext": {}}: бөлек немесе мына массивте бірге: tools. Google Search те, URL context те functionDeclarations функция анықтамаларымен бір сұрауда бірге қолданылмайды. Шығыстағы суреттер үшін тек клиенттік функциялар қолжетімді. Басқа кіріктірілген құралдарға және explicit cache мүмкіндігіне қолдау көрсетілмейді. Search/URL context толық кіріс лимиті бойынша резервті талап етуі мүмкін; нақты toolUsePromptTokenCount кіріс токендері ретінде есепке алынады.

• toolConfigobjectміндетті емес

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

Модель өрісті, тіркемені немесе құралдар үйлесімін қолдамаса, сұрау резервке дейін қабылданбайды — ештеңе есептен шығарылмайды. HTTP коды келеді: 400 мына мәнмен: status INVALID_ARGUMENT және мына класпен: invalid_request (мына өрісте: ErrorInfo.reason — INVALID_REQUEST). Қате JSON, жол параметрлерінің және басқа тексерулердің қателері де мына кодты қайтарады: 400; қате мәтінін және Request ID-ді оқыңыз. Мүмкіндіктер модельге байланысты: оның форматтары мен кірістерін каталогтан тексеріңіз.

PDF, аудио, бейне және сілтемелер

Тиісті кірісті қолдайтын Gemini модельдерінде parts[].inlineData құрамында mimeType және бос емес base64 деректері болады; PDF шынайы PDF болуы керек. fileData құрамында ашық https-мекенжайы мына өрісте болады: fileUri және файл түрінің MIME мәні. YouTube үшін MIME көрсетпесе де болады. http, жеке мекенжайлар, gs:// және Google Files API нысандарына қолдау көрсетілмейді; Google Files API арқылы жүктеуге де қолдау көрсетілмейді. Бейнеге мынаны қосуға болады: videoMetadata: startOffset/endOffset секундпен берілген жол түрінде (мысалы, 1.5s) және fps 0-ден үлкен және 24-тен аспайды. Дене көлемі, контекст, рұқсат етілген кіріс және жауап лимиті модель мен форматқа қарай тексеріледі.

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"},
    )
    # Бір рет жіберіңіз. Күту уақыты аяқталса, қайта әрекет жасамас бұрын пайдалану тарихындағы 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

# Нақты жергілікті PDF, аудио немесе бейне файлын және оған қолдау көрсетілетін MIME түрін көрсетіңіз.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
    {"text": "Файлдың мазмұнын қысқаша сипатта."},
    {"inlineData": {"mimeType": mime,
                    "data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Тіркеменің балама түрі: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Нақты YouTube URL үшін: {"fileData": {"fileUri": youtube_url}}

Search және URL context

Клиенттік functionDeclarations арқылы анықталған функцияларды қолданбаңыз орындайды. Мәтіндік модельдерде мыналар да қабылданады: {"googleSearch": {}} және {"urlContext": {}}: бөлек немесе мына массивте бірге: tools. Google Search те, URL context те functionDeclarations функция анықтамаларымен бір сұрауда бірге қолданылмайды. Шығыстағы суреттер үшін тек клиенттік функциялар қолжетімді. Басқа кіріктірілген құралдарға және explicit cache мүмкіндігіне қолдау көрсетілмейді. Search/URL context толық кіріс лимиті бойынша резервті талап етуі мүмкін; нақты toolUsePromptTokenCount кіріс токендері ретінде есепке алынады.

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

Шығыстағы суреттер

Gemini форматындағы жауапта сурет бере алатын жалғыз модель — gemini-3.1-flash-image. Бұл мынадан бөлек мүмкіндік: /v1/images/generations: басқа сурет модельдері мұнда жұмыс істемейді. Бұл модельдің кірісі 131072 токенге дейін, жауабы 32768-ге дейін; ең ұзын жауаптың толық құны алдын ала резервтеледі.

responseModalities — қайталанбайтын, бос емес TEXT/IMAGE жиыны. 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. Бұл модельдің кірісі — мәтін және inline PNG/JPEG/WebP; мұнда PDF/audio/video/fileData және кіріктірілген Search/URL context қабылданбайды. Кілтіңіз үшін қолжетімділік пен бағалар каталогта және мына жерде: 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"},
    )
    # Бір рет жіберіңіз. Күту уақыты аяқталса, қайта әрекет жасамас бұрын пайдалану тарихындағы 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": "Акварель: таңсәрідегі маяк"}]}],
    "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)

Function calling толық циклі

Функцияларды клиент орындайды. Модельдің thoughtSignature бар бүкіл бастапқы content мазмұнын өзгеріссіз қайтарыңыз, содан кейін дәл сол name және functionCall ішінде болған болса, дәл сол id бар functionResponse жіберіңіз.

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"},
    )
    # Бір рет жіберіңіз. Күту уақыты аяқталса, қайта әрекет жасамас бұрын пайдалану тарихындағы 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": "Екі санды көбейту",
    "parameters": {"type": "object", "properties": {
        "a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Функцияның көмегімен 7-ні 8-ге көбейт"}]}]
for turn in range(4):  # Құралды шақыру циклін шектеңіз; нәтижесі белгісіз сұрауды қайта жібермеңіз.
    reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
    content = reply["candidates"][0]["content"]
    contents.append(content)  # Бастапқы parts бөліктерінің БАРЛЫҒЫН (ALL) және 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")

Жауап

• candidates[].content.partsarray

  Модельдің жауабы.

• usageMetadataobject

  promptTokenCount, candidatesTokenCount, totalTokenCount.