Семейство моделей искусственного интеллекта (ИИ) Gemini создано для обработки различных типов входных данных, включая текст, изображения и аудио. Поскольку эти модели могут обрабатывать более одного типа или режима данных, их называют мультимодальными моделями или моделями, обладающими мультимодальными возможностями .
В этом руководстве показано, как работать с медиафайлами с помощью API Files. Основные операции одинаковы для аудиофайлов, изображений, видео, документов и других поддерживаемых типов файлов.
Инструкции по работе с запросами на открытие файлов см. в разделе «Руководство по работе с запросами на открытие файлов» .
Загрузить файл
Вы можете использовать API Files для загрузки медиафайлов. Всегда используйте API Files, если общий размер запроса (включая файлы, текстовую подсказку, системные инструкции и т. д.) превышает 20 МБ.
Следующий код загружает файл, а затем использует его при вызове generateContent .
Питон
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-2.5-flash", contents=["Describe this audio clip", myfile]
)
print(response.text)
JavaScript
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
Идти
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
model := client.GenerativeModel("gemini-2.5-flash")
resp, err := model.GenerateContent(ctx,
genai.FileData{URI: file.URI},
genai.Text("Describe this audio clip"))
if err != nil {
log.Fatal(err)
}
printResponse(resp)
ОТДЫХ
AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-D "${tmp_header_file}" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Describe this audio clip"},
{"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
Получить метаданные для файла
Вы можете убедиться, что API успешно сохранил загруженный файл и получить его метаданные, вызвав files.get .
Питон
myfile = client.files.upload(file='path/to/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)
JavaScript
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const fileName = myfile.name;
const fetchedFile = await ai.files.get({ name: fileName });
console.log(fetchedFile);
Идти
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
gotFile, err := client.GetFile(ctx, file.Name)
if err != nil {
log.Fatal(err)
}
fmt.Println("Got file:", gotFile.Name)
ОТДЫХ
# file_info.json was created in the upload example
name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name \
-H "x-goog-api-key: $GEMINI_API_KEY" > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
Список загруженных файлов
Вы можете загрузить несколько файлов с помощью API Files. Следующий код получает список всех загруженных файлов:
Питон
print('My files:')
for f in client.files.list():
print(' ', f.name)
JavaScript
const listResponse = await ai.files.list({ config: { pageSize: 10 } });
for await (const file of listResponse) {
console.log(file.name);
}
Идти
iter := client.ListFiles(ctx)
for {
ifile, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
log.Fatal(err)
}
fmt.Println(ifile.Name)
}
ОТДЫХ
echo "My files: "
curl "https://generativelanguage.googleapis.com/v1beta/files" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Удалить загруженные файлы
Файлы автоматически удаляются через 48 часов. Вы также можете удалить загруженный файл вручную:
Питон
myfile = client.files.upload(file='path/to/sample.mp3')
client.files.delete(name=myfile.name)
JavaScript
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const fileName = myfile.name;
await ai.files.delete({ name: fileName });
Идти
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
client.DeleteFile(ctx, file.Name)
ОТДЫХ
curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name \
-H "x-goog-api-key: $GEMINI_API_KEY"
Информация об использовании
Вы можете использовать API Files для загрузки и работы с медиафайлами. API Files позволяет хранить до 20 ГБ файлов в каждом проекте, при этом максимальный размер файла составляет 2 ГБ. Файлы хранятся 48 часов. В течение этого времени вы можете использовать API для получения метаданных о файлах, но не можете их скачивать. API Files доступен бесплатно во всех регионах, где доступен API Gemini.
Стратегии подсказки файлов
В этом разделе приведены рекомендации и рекомендации по использованию медиафайлов с подсказками для API Gemini.
Возможность использования различных типов данных в подсказках даёт вам больше гибкости в выборе задач, которые можно решить с помощью API Gemini. Например, вы можете отправить модели фотографию вкусного блюда и попросить её написать короткий пост о нём в блоге.
| Быстрый | Ответ |
Напишите короткий, увлекательный пост в блоге на основе этой фотографии. Он должен включать описание блюда, изображённого на фотографии, и рассказ о том, как я готовил еду в путешествии.  | Приготовление еды заранее — отличный способ сэкономить время и деньги, а также питаться здоровее. Это блюдо — отличный пример полезного и вкусного блюда, которое можно легко приготовить заранее. Это блюдо включает в себя коричневый рис, жареные овощи и курицу терияки. Коричневый рис — это полезный и сложный источник углеводов, который обеспечит вас энергией на долгие годы. Жареные овощи — отличный способ получить суточную дозу витаминов и минералов, а курица терияки — вкусный и богатый белком вариант. Это блюдо очень просто приготовить. Просто отварите бурый рис, обжарьте овощи и приготовьте курицу терияки. После того, как всё будет приготовлено, разложите его по контейнерам для заготовок и храните в холодильнике. Теперь можно взять контейнер и продолжать свои дела каждое утро! Если вы ищете полезное и вкусное блюдо, которое можно легко приготовить заранее, это блюдо — отличный вариант. Оно богато питательными веществами и вкусом, и вы обязательно ощутите сытость и удовлетворение. Давайте готовить здоровую и вкусную еду! |
Если у вас возникли проблемы с получением желаемого результата от подсказок, использующих медиафайлы, существует несколько стратегий, которые могут помочь вам добиться желаемого результата. В следующих разделах представлены подходы к проектированию и советы по устранению неполадок для улучшения подсказок, использующих мультимодальный ввод.
Вы можете улучшить свои мультимодальные подсказки, следуя этим рекомендациям:
Основы оперативного проектирования
- Будьте конкретны в своих инструкциях : создавайте понятные и краткие инструкции, которые оставляют минимум места для неправильного толкования.
- Добавьте несколько примеров к вашему предложению: используйте реалистичные примеры из нескольких кадров, чтобы проиллюстрировать, чего вы хотите добиться.
- Разбейте процесс на этапы : разделите сложные задачи на выполнимые подцели, направляя модель на протяжении всего процесса.
- Укажите формат вывода : в командной строке укажите желаемый формат вывода, например, Markdown, JSON, HTML и т. д.
- В подсказках с одним изображением размещайте изображение первым : хотя Gemini может обрабатывать изображения и текст в любом порядке, для подсказок, содержащих одно изображение, система может работать эффективнее, если это изображение (или видео) будет располагаться перед текстовой подсказкой. Однако для подсказок, требующих частого чередования изображений и текста для большей осмысленности, используйте наиболее естественный порядок.
Устранение неполадок в мультимодальном запросе
- Если модель не извлекает информацию из соответствующей части изображения: укажите, из каких аспектов изображения должна черпаться информация.
- Если выходные данные модели слишком общие (не соответствуют входным данным изображения/видео): В начале подсказки попробуйте попросить модель описать изображение(я) или видео, прежде чем предоставить инструкцию по выполнению задания, или попробуйте попросить модель сослаться на то, что изображено на изображении.
- Чтобы определить, какая часть дала сбой: попросите модель описать изображение или попросите ее объяснить ход своих рассуждений, чтобы оценить первоначальное понимание модели.
- Если ваша подсказка приводит к появлению галлюцинаторного содержания: попробуйте снизить настройку температуры или попросить модель дать более короткие описания, чтобы она с меньшей вероятностью экстраполировала дополнительные детали.
- Настройка параметров выборки: поэкспериментируйте с различными настройками температуры и выбором top-k, чтобы отрегулировать креативность модели.
Будьте конкретны в своих инструкциях
Подсказки наиболее эффективны, когда они понятны и подробны. Если вы хотите получить конкретный результат, лучше включить это требование в подсказку, чтобы быть уверенным, что получите именно то, что хотите.
Для этого изображения табло аэропорта запрос к модели «Опишите это изображение» может сгенерировать общее описание. Если вам нужно, чтобы модель распознала время и город на изображении, вы можете включить этот запрос непосредственно в запрос.
| Быстрый | Модель ответа |
|---|---|
 Опишите это изображение. | На изображении показано табло прилетов и вылетов аэропорта. |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Проанализируйте время и город на табло аэропорта, показанном на этом изображении, и представьте их в виде списка. |
Добавьте несколько примеров
Модель Gemini может принимать несколько входных данных, которые она может использовать в качестве примеров для понимания желаемого результата. Добавление этих примеров помогает модели выявлять закономерности и применять взаимосвязь между заданными изображениями и ответами к новому примеру. Это также называется обучением «с малым количеством попыток».
В примере ниже начальный вывод представлен в форме предложения и также содержит название страны (Бразилия). Предположим, вы хотите получить вывод в другом формате или стиле, например, указать только город, а не страну. Добавление нескольких примеров в подсказку может настроить модель на нужный вам ответ.
| Быстрый | Модель ответа |
|---|---|
 Определите город и достопримечательность. | Достопримечательностью является статуя Христа-Искупителя в Рио-де-Жанейро, Бразилия. |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Определите город и достопримечательность.  | город: Рим, достопримечательность: Колизей. |
 | город: Пекин, достопримечательность: Запретный город |
| город: Рио-де-Жанейро, достопримечательность: статуя Христа-Искупителя |
Разберём это шаг за шагом
Для сложных задач, требующих как визуального понимания, так и рассуждения, может быть полезно разбить задачу на более мелкие, более простые этапы. В качестве альтернативы, можно также прямо попросить модель «думать шаг за шагом» в подсказке.
| Быстрый | Модель ответа |
|---|---|
 Когда у меня закончится туалетная бумага? | Вскоре у вас останется всего 3 рулона. |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
|
|
Математические задачи или другие типы текстовых задач отлично подходят для того, чтобы попросить модель думать шаг за шагом.
| Быстрый | Ответ |
|---|---|
 Каков 4-й член последовательности? | -135 |
Ответ модели неверен. Один из способов исправить ситуацию — попросить модель проанализировать проблему, прежде чем отвечать на подсказку.
| Быстрый | Ответ |
|---|---|
Сначала проанализируем формулу на изображении. Затем, опираясь на формулу, ответьте: «Какой четвертый член в последовательности?». | $$ b(n) = b(n-1) * (-3) $$ $$ b(1) = 15 $$ $$ b(4) = b(4-1) * (-3) $$ $$ b(4) = b(3) * (-3) $$ $$ b(3) = b(3-1) * (-3) $$ $$ b(3) = b(2) * (-3) $$ $$ b(2) = b(2-1) * (-3) $$ $$ b(2) = b(1) * (-3) $$ $$ b(2) = 15 * (-3) $$ $$ b(2) = -45 $$ $$ b(3) = b(2) * (-3) $$ $$ b(3) = -45 * (-3) $$ $$ b(3) = 135 $$ $$ b(4) = b(3) * (-3) $$ $$ b(4) = 135 * (-3) $$ $$ b(4) = -405 $$ Следовательно, 4-й член последовательности равен -405. |
Этот ответ модели правильный — теперь, чтобы сделать ответ еще более рационализированным, вы можете попросить модель думать пошагово.
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Какой четвёртый член последовательности? Подумайте пошагово. | Первый член — 15. Второй член равен b(1) * (-3) = 15 * (-3) = -45. Третий член равен b(2) * (-3) = -45 * (-3) = 135. Четвертый член: b(3) * (-3) = 135 * (-3) = -405. |
Укажите выходной формат
Распространенной проблемой является необходимость представления выходных данных модели в определённом формате (например, Markdown, JSON, HTML), особенно если выходные данные модели должны быть использованы последующей задачей. Вы можете попытаться сформировать выходные данные в этом формате, указав модели на это в командной строке. Ниже приведены два примера:
| Быстрый | Модель ответа |
|---|---|
 Преобразовать таблицу на этом изображении в формат Markdown | | Тема | Статус | Время | Дата начала | Срок выполнения | | ------- | ------ | ---- | ---------- | ------ | | Математика | Готово | 1,5 часа | 29.11.2023 | 01.12.2023 | | География | Готово | 30 мин | 02.12.2023 | 04.12.2023 | | Физика | В процессе | 2 часа | 03.12.2023 | 05.12.2023 | | Биология | Не начато | 6 часов | 02.11.2016 | 06.12.2023 | |
| Быстрый | Модель ответа |
|---|---|
 Предоставьте список всех следующих атрибутов: ингредиенты, тип кухни, вегетарианская или нет, в формате JSON | ```json { "ингредиенты": [ "рис", "креветка", "моллюски", "моллюски", "горох", "помидоры", "лук", "чеснок", "оливковое масло", "паприка", "соль", "перец" ], "тип кухни": "испанская", "вегетарианец": ложь } ``` |
Для подсказок с одним изображением поставьте изображение первым
Хотя Gemini может интерпретировать изображения и текст в любом порядке в подсказке, размещение одного изображения перед текстовой подсказкой может привести к лучшим результатам. В следующих примерах вы заметите, что в каждой подсказке изображение идёт перед текстом.
Устранение неполадок в мультимодальном запросе
Если вы не получаете полезного ответа, возможно, вам придётся устранить неполадки в работе подсказки. Вот несколько стратегий, которые вы можете попробовать.
Если модель не извлекает информацию из соответствующей части изображения
Чтобы получить более конкретный ответ, вы можете указать, из каких аспектов изображения вы хотите, чтобы подсказчик черпал информацию для своего ответа.
| Быстрый | Модель ответа |
|---|---|
 На сколько дней хватит этих подгузников для ребенка? | Подгузников хватит на 198 дней, после чего они закончатся. |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
На сколько мне хватит этих подгузников, прежде чем они закончатся? Определите возраст ребенка по весу, указанному на коробке, и укажите общее количество подгузников в коробке. Разделите общее число на количество подгузников, которые ребенок меняет в день. | В коробке 198 подгузников. На коробке указано, что подгузники рассчитаны на ребёнка весом от 10 до 16 кг. Средний возраст ребенка в этом диапазоне веса составляет от 1 до 2 лет. Двухлетнему ребенку обычно требуется 6 подгузников в день, поэтому подгузников хватит примерно на 33 дня (198/6). |
Если выходные данные модели слишком общие и недостаточно соответствуют входным данным изображения
Чтобы помочь модели адаптировать свою реакцию к изображению(ям), попробуйте попросить ее описать изображения, прежде чем выполнять задачу рассуждения.
| Быстрый | Модель ответа |
|---|---|
   Что общего между этими изображениями? | Все четыре изображения являются примерами пейзажной фотографии. |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Сначала подробно опишите каждое изображение. Что общего между ними? | На первом изображении изображён человек, пакующий чемодан. На втором — пустой коридор торгового центра. На третьем — рулон туалетной бумаги. На четвёртом — тёмное бурное море. Общим между этими изображениями является то, что все они являются примерами лиминальных пространств. Лиминальные пространства — это места или ситуации, находящиеся между двумя другими местами или ситуациями. Они часто характеризуются ощущением неопределённости или двусмысленности. На первом изображении человек находится в состоянии, которое можно разделить на время между пребыванием дома и поездкой. На втором изображен коридор между двумя магазинами. На третьем изображена туалетная бумага, которая может символизировать ванную комнату. Ванная комната — это переходное пространство между личным и общественным пространством. Это место, где мы готовимся к выходу из внешнего мира или уходу из него. На четвертом изображении показано море в состоянии между штилем и штормом. Пограничные пространства могут быть одновременно захватывающими и тревожными. Они могут быть местом нового начала или местом завершения. Они могут быть местом размышлений или местом действия. |
Вы также можете попробовать прямо попросить модель сослаться на то, что изображено на изображении.
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Что общего между этими изображениями? В своём ответе укажите, что изображено на изображениях. | Все изображения связаны с путешествиями. На первом изображен человек, пакующий чемодан, на втором — пустой коридор торгового центра, на третьем — стопка туалетной бумаги, а на четвёртом — тёмное штормовое море. Все эти изображения связаны с путешествиями, поскольку представляют собой вещи, которые нужны людям или которые они используют во время путешествия. На первом изображен человек, пакующий чемодан, что часто происходит, когда люди отправляются в путешествие. На втором изображен пустой коридор торгового центра, куда люди часто заходят за покупками в дорогу. На третьем изображена стопка туалетной бумаги, которой люди часто пользуются во время путешествий. На четвёртом изображено тёмное и бурное море, с которым люди часто сталкиваются во время путешествий. |
Те же советы применимы и для творческого вывода изображений. В следующем примере с кроликом, явное указание модели включить аспекты изображения может улучшить результат.
| Быстрый | Модель ответа |
|---|---|
 Можете ли вы написать мне стихотворение об этом изображении? | Маленький кролик, такой мягкий и коричневый, Ты щиплешь траву, такую зеленую и сладкую, |
| Обновленная подсказка | Улучшенный ответ |
|---|---|
Можете ли вы написать мне описательное и драматичное стихотворение об этом изображении, указав место, где оно было сделано? | Маленький зайчик на зелени, Это синий океан, Маленький зайчик, скажи мне правду, Возможно, дело в необъятности всего этого, Маленький зайчик, мне интересно, что тебе снится, Что бы это ни было, маленький зайчик, |
Устранение неполадок, связанных с тем, какая часть запроса не удалась
Иногда бывает сложно понять, была ли подсказка не выполнена, потому что модель изначально не поняла изображение , или же она поняла изображение, но не выполнила правильные шаги рассуждения . Чтобы разобраться в этих причинах, попросите модель описать, что изображено на изображении.
В следующем примере, если модель отвечает за закуску, которая кажется неожиданной в сочетании с чаем (например, попкорн), вы можете сначала устранить неполадки, чтобы определить, правильно ли модель распознала, что изображение содержит чай.
| Быстрый | Запрос на устранение неполадок |
|---|---|
 Какую закуску я могу приготовить за 1 минуту, чтобы она хорошо к этому подошла? | Опишите, что изображено на этой картинке. |
Другая стратегия — попросить модель объяснить ход своих рассуждений. Это поможет вам определить, какая часть рассуждений дала сбой, если таковой вообще имелся.
| Быстрый | Запрос на устранение неполадок |
|---|---|
Какую закуску я могу приготовить за 1 минуту, чтобы она хорошо к этому подошла? | Какую закуску можно приготовить за минуту, чтобы она хорошо к этому подошла? Объясните, пожалуйста, почему. |
Что дальше?
- Попробуйте написать собственные многомодальные подсказки с помощью Google AI Studio .
- Информацию об использовании API Gemini Files для загрузки медиафайлов и включения их в ваши запросы см. в руководствах по обработке Vision , Audio и Document .
- Дополнительные рекомендации по разработке подсказок, например, по настройке параметров выборки, см. на странице «Стратегии подсказок» .