Source: https://ailoot.ai/docs/kk/api/gemini/ Canonical: https://ailoot.ai/docs/kk/api/gemini/ Language: kk [API](https://ailoot.ai/docs/kk/) # Gemini generateContent [Markdown](https://ailoot.ai/docs/kk/api/gemini/index.md) Google Gemini-дің төл форматы: Gemini CLI, Google GenAI SDK және REST клиенттері үшін. POST`https://api.ailoot.ai/v1beta/models/{model}:generateContent` Gemini generateContent ```bash 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": "Кофеханаға үш атау ойлап тап."}]} ] }' ``` ```python 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) ``` ```js 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); ``` 200 OK ```json { "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-key` | header | міндетті | Кілт `sk-…`. Мыналар да жарайды: `Authorization: Bearer` немесе `x-api-key`. Google-мен үйлесімділік үшін мына нұсқа да қабылданады: `?key=` мекенжайда — ең төмен басымдықпен; `?api_key=` 400 қатесімен қабылданбайды. Тақырыпты қолдануды ұсынамыз: сонда кілт журналдарға түспейді. | ## Жол | Параметр | Түрі | Міндетті | Сипаттама | | --- | --- | --- | --- | | `model` | string | міндетті | Gemini форматындағы модель ID-і, мысалы `gemini-3.8-flash` немесе `gemini-3.1-pro`. Барлығы 27. | POST`https://api.ailoot.ai/v1beta/models/{model}:streamGenerateContent?alt=sse` GET`https://api.ailoot.ai/v1beta/models` ## Сұрау денесі | Параметр | Түрі | Міндетті | Сипаттама | | --- | --- | --- | --- | | `contents` | array | міндетті | Мына өрістері бар хабарламалар: `role` (`user`/`model`) және `parts`: text, inlineData/fileData, functionCall/functionResponse. Тіркемелер — модель кіріс ретінде қабылдайтын түрлер. | | `systemInstruction` | object | міндетті емес | Мәтіндік жүйелік нұсқау: `{"parts": [{"text": "…"}]}`. | | `generationConfig` | object | міндетті емес | `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"]`. | | `safetySettings` | array | міндетті емес | Мына міндетті өрістері бар нысандар: `category` және `threshold`, мына өріс міндетті емес: `method`. Мәндерге нақты модель қолдау көрсетуі керек. | | `tools` | array | міндетті емес | Клиенттік `functionDeclarations` арқылы анықталған функцияларды қолданбаңыз орындайды. Мәтіндік модельдерде мыналар да қабылданады: `{"googleSearch": {}}` және `{"urlContext": {}}`: бөлек немесе мына массивте бірге: `tools`. Google Search те, URL context те `functionDeclarations` функция анықтамаларымен бір сұрауда бірге қолданылмайды. Шығыстағы суреттер үшін тек клиенттік функциялар қолжетімді. Басқа кіріктірілген құралдарға және explicit cache мүмкіндігіне қолдау көрсетілмейді. Search/URL context толық кіріс лимиті бойынша резервті талап етуі мүмкін; нақты `toolUsePromptTokenCount` кіріс токендері ретінде есепке алынады. | | `toolConfig` | object | міндетті емес | `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-тен аспайды. Дене көлемі, контекст, рұқсат етілген кіріс және жауап лимиті модель мен форматқа қарай тексеріледі. | Кіріс | Қолдау көрсетілетін MIME | | --- | --- | | Inline суреттер | image/png, image/jpeg, image/webp | | Құжаттар | 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 | | Аудио | audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac | | Бейне | video/mp4, video/mpeg, video/mov, video/quicktime, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp | ```python 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` кіріс токендері ретінде есепке алынады. ```json {"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`. ```python 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 жіберіңіз. ```python 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.parts` | array | | Модельдің жауабы. | | `usageMetadata` | object | | `promptTokenCount`, `candidatesTokenCount`, `totalTokenCount`. | Gemini-дің ақылы жауабы жеке сөздермен біртіндеп емес, құны есептелгеннен кейін толық келеді. Gemini ағынында қызметтік жолдар жоқ — клиенттің күту уақытын жеткілікті қорымен орнатыңыз. Сұрақтарыңыз қалды ма? Request ID мен сипаттаманы жіберіңіз — мәселені анықтауға көмектесеміз.[Қолдау қызметіне жазу](mailto:support@ailoot.ai) ## Ailoot · Компания және оның жобалар портфелі Ailoot жинақталған жұмыс тәжірибесіне, кең клиенттік базаға, тұрақты қызметке және KPI көрсеткіштерін үздіксіз бақылауға сүйенеді. Компания және оның жобалар портфелі: миллиондаған клиент; ай сайынғы сату көлемі миллиардтармен есептеледі. Ailoot осы тәжірибені клиенттердің өнімдерінде, агенттерінде, қолданбаларында және автоматтандыруларында жасанды интеллект мүмкіндіктеріне API арқылы қол жеткізуді қамтамасыз етуге пайдаланады.