Пакетный API

API Gemini Batch предназначен для асинхронной обработки больших объемов запросов со скоростью, составляющей 50% от стандартной . Целевое время выполнения составляет 24 часа, но в большинстве случаев оно значительно быстрее.

Используйте Batch API для крупномасштабных, несрочных задач, таких как предварительная обработка данных или проведение оценок, где не требуется немедленный ответ.

Создание пакетного задания

В Batch API у вас есть два способа отправлять запросы:

  • Встроенные запросы : список объектов GenerateContentRequest непосредственно включенных в ваш пакетный запрос на создание контента. Это подходит для небольших пакетов, общий размер запроса которых не превышает 20 МБ. Результатом работы модели является список объектов inlineResponse .
  • Входной файл : файл JSON Lines (JSONL) , где каждая строка содержит полный объект GenerateContentRequest . Этот метод рекомендуется для больших запросов. Выходные данные , возвращаемые моделью, представляют собой файл JSONL, где каждая строка является либо объектом GenerateContentResponse , либо объектом статуса.

Встроенные запросы

Для небольшого количества запросов вы можете напрямую встраивать объекты GenerateContentRequest в ваш BatchGenerateContentRequest . В следующем примере метод BatchGenerateContent вызывается с помощью встроенных запросов:

Python 


from google import genai
from google.genai import types

client = genai.Client()

# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
    {
        'contents': [{
            'parts': [{'text': 'Tell me a one-sentence joke.'}],
            'role': 'user'
        }]
    },
    {
        'contents': [{
            'parts': [{'text': 'Why is the sky blue?'}],
            'role': 'user'
        }]
    }
]

inline_batch_job = client.batches.create(
    model="gemini-3.7-flash",
    src=inline_requests,
    config={
        'display_name': "inlined-requests-job-1",
    },
)

print(f"Created batch job: {inline_batch_job.name}")

JavaScript 


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

const ai = new GoogleGenAI({});

const inlinedRequests = [
    {
        contents: [{
            parts: [{text: 'Tell me a one-sentence joke.'}],
            role: 'user'
        }]
    },
    {
        contents: [{
            parts: [{'text': 'Why is the sky blue?'}],
            role: 'user'
        }]
    }
]

const response = await ai.batches.create({
    model: 'gemini-3.7-flash',
    src: inlinedRequests,
    config: {
        displayName: 'inlined-requests-job-1',
    }
});

console.log(response);

ОТДЫХ 

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:batchGenerateContent \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type:application/json" \
-d '{
    "batch": {
        "display_name": "my-batch-requests",
        "input_config": {
            "requests": {
                "requests": [
                    {
                        "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
                        "metadata": {
                            "key": "request-1"
                        }
                    },
                    {
                        "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
                        "metadata": {
                            "key": "request-2"
                        }
                    }
                ]
            }
        }
    }
}'

Входной файл

Для обработки больших наборов запросов подготовьте файл JSON Lines (JSONL). Каждая строка в этом файле должна представлять собой объект JSON, содержащий заданный пользователем ключ и объект запроса, где запрос является допустимым объектом GenerateContentRequest . Заданный пользователем ключ используется в ответе для указания того, какой результат является следствием какого запроса. Например, ответ на запрос с ключом request-1 будет аннотирован тем же именем ключа.

Этот файл загружается с помощью File API . Максимально допустимый размер входного файла составляет 2 ГБ.

Ниже приведён пример JSONL-файла. Вы можете сохранить его в файле с именем my-batch-requests.json :

{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generation_config": {"temperature": 0.7}}}
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}

Аналогично встроенным запросам, вы можете указывать другие параметры, такие как системные инструкции, инструменты или другие конфигурации, в каждом JSON-запросе.

Вы можете загрузить этот файл, используя File API , как показано в следующем примере. Если вы работаете с мультимодальным вводом, вы можете ссылаться на другие загруженные файлы в своем JSONL-файле.

Python 


import json
from google import genai
from google.genai import types

client = genai.Client()

# Create a sample JSONL file
with open("my-batch-requests.jsonl", "w") as f:
    requests = [
        {"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]}},
        {"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
    ]
    for req in requests:
        f.write(json.dumps(req) + "\n")

# Upload the file to the File API
uploaded_file = client.files.upload(
    file='my-batch-requests.jsonl',
    config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)

print(f"Uploaded file: {uploaded_file.name}")

JavaScript 


import {GoogleGenAI} from '@google/genai';
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from 'url';

const ai = new GoogleGenAI({});
const fileName = "my-batch-requests.jsonl";

// Define the requests
const requests = [
    { "key": "request-1", "request": { "contents": [{ "parts": [{ "text": "Describe the process of photosynthesis." }] }] } },
    { "key": "request-2",