Gemini может одновременно обрабатывать различные типы входных данных, включая текст, изображения и аудио.
В этом руководстве показано, как работать с медиафайлами с помощью Files API. Основные операции одинаковы для аудиофайлов, изображений, видео, документов и других поддерживаемых типов файлов.
Инструкции по настройке параметров файлов см. в разделе « Руководство по настройке параметров файлов» .
Загрузите файл
Для загрузки медиафайлов можно использовать Files API. Всегда используйте Files API, если общий размер запроса (включая файлы, текстовое сообщение, системные инструкции и т. д.) превышает 100 МБ. Для файлов PDF лимит составляет 50 МБ.
Следующий код загружает файл, а затем использует этот файл в вызове функции generateContent .
Python
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-3-flash-preview", 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-3-flash-preview",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
Идти
file, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
defer client.Files.Delete(ctx, file.Name)
resp, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", []*genai.Content{
{
Parts: []*genai.Part{
genai.NewPartFromFile(*file),
genai.NewPartFromText("Describe this audio clip"),
},
},
}, nil)
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-3-flash-preview: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 .
Python
from google import genai
client = genai.Client()
myfile = client.files.upload(file='path/to/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)
JavaScript
import {
GoogleGenAI,
} 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 fileName = myfile.name;
const fetchedFile = await ai.files.get({ name: fileName });
console.log(fetchedFile);
}
await main();
Идти
file, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
gotFile, err := client.Files.Get(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
Список загруженных файлов
Следующий код получает список всех загруженных файлов:
Python
from google import genai
client = genai.Client()
print('My files:')
for f in client.files.list():
print(' ', f.name)
JavaScript
import {
GoogleGenAI,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const listResponse = await ai.files.list({ config: { pageSize: 10 } });
for await (const file of listResponse) {
console.log(file.name);
}
}
await main();
Идти
for file, err := range client.Files.All(ctx) {
if err != nil {
log.Fatal(err)
}
fmt.Println(file.Name)
}
ОТДЫХ
echo "My files: "
curl "https://generativelanguage.googleapis.com/v1beta/files" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Удалить загруженные файлы
Файлы автоматически удаляются через 48 часов. Вы также можете удалить загруженный файл вручную:
Python
from google import genai
client = genai.Client()
myfile = client.files.upload(file='path/to/sample.mp3')
client.files.delete(name=myfile.name)
JavaScript
import {
GoogleGenAI,
} 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 fileName = myfile.name;
await ai.files.delete({ name: fileName });
}
await main();
Идти
file, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
client.Files.Delete(ctx, file.Name)
ОТДЫХ
curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name \
-H "x-goog-api-key: $GEMINI_API_KEY"
Информация об использовании
Вы можете использовать Files API для загрузки медиафайлов и взаимодействия с ними. Files API позволяет хранить до 20 ГБ файлов на проект, при этом максимальный размер каждого файла составляет 2 ГБ. Файлы хранятся в течение 48 часов. В течение этого времени вы можете использовать API для получения метаданных о файлах, но не можете их загрузить. Files API доступен бесплатно во всех регионах, где доступен Gemini API.
стратегии запроса файлов
В этом разделе представлены рекомендации и лучшие практики использования медиафайлов с запросами к API Gemini.
Возможность использовать различные типы данных в ваших запросах дает вам большую гибкость в плане того, какие задачи вы можете решать с помощью API Gemini. Например, вы можете отправить модели фотографию вкусного блюда и попросить ее написать короткий пост в блоге об этом блюде.
| Быстрый | Ответ |
Напишите короткий, увлекательный пост в блоге, основанный на этой фотографии. Он должен включать описание блюда на фото и рассказ о моем опыте приготовления еды заранее.  | Предварительная подготовка еды — отличный способ сэкономить время и деньги, а также помочь вам питаться здоровее. Это блюдо — прекрасный пример полезного и вкусного блюда, которое легко приготовить заранее. В состав этого блюда входят бурый рис, запеченные овощи и курица терияки. Бурый рис — это полезный и сложный источник углеводов, который обеспечит вас энергией на длительное время. Запеченные овощи — отличный способ получить ежедневную дозу витаминов и минералов, а курица терияки — вкусный и богатый белком вариант. Это блюдо очень легко приготовить. Просто сварите коричневый рис, запеките овощи и приготовьте курицу терияки. После того, как все будет готово, разложите по контейнерам для хранения и уберите в холодильник. Тогда вы сможете взять контейнер и отправиться готовить по утрам, когда у вас мало времени! Если вы ищете полезное и вкусное блюдо, которое легко приготовить заранее, это отличный вариант. Оно богато питательными веществами и обладает насыщенным вкусом, и гарантированно обеспечит вам чувство сытости и удовлетворения. Желаем вам здорового и вкусного питания при приготовлении еды заранее! |
Если у вас возникли проблемы с получением желаемого результата от запросов, использующих медиафайлы, существуют стратегии, которые могут помочь вам добиться желаемого результата. В следующих разделах представлены подходы к проектированию и советы по устранению неполадок для улучшения запросов, использующих мультимодальный ввод.
Вы можете улучшить свои мультимодальные подсказки, следуя этим рекомендациям:
Основы оперативного проектирования
- Будьте конкретны в своих инструкциях : составьте четкие и лаконичные инструкции, которые сведут к минимуму возможность неправильного толкования.
- Добавьте несколько примеров к своему заданию: используйте реалистичные примеры из нескольких кадров, чтобы проиллюстрировать, чего вы хотите достичь.
- Разбейте задачу на этапы : разделите сложные задачи на выполнимые подзадачи, направляя модель на протяжении всего процесса.
- Укажите формат вывода : в командной строке укажите желаемый формат вывода, например, Markdown, JSON, HTML и другие.
- В подсказках с одним изображением размещайте изображение первым : хотя Gemini может обрабатывать изображения и текст в любом порядке, для подсказок, содержащих одно изображение, может быть эффективнее, если это изображение (или видео) будет размещено перед текстовой подсказкой. Однако для подсказок, требующих частого чередования изображений и текста для обеспечения осмысленности, используйте тот порядок, который вам наиболее естественен.
Устранение неполадок с многомодальным приглашением
- Если модель не получает информацию из соответствующей части изображения: укажите, из каких аспектов изображения вы хотите, чтобы модель получала информацию.
- Если выходные данные модели слишком общие (недостаточно адаптированы к входному изображению/видео): в начале запроса попробуйте попросить модель описать изображение(я) или видео до предоставления инструкции к заданию, или попробуйте попросить модель сослаться на то, что изображено на картинке.
- Чтобы определить, какая именно часть не сработала: попросите модель описать изображение или объяснить свои рассуждения, чтобы оценить ее первоначальное понимание.
- Если ваш запрос приводит к галлюцинациям: попробуйте уменьшить температуру или попросить модель дать более короткие описания, чтобы она с меньшей вероятностью могла додумать дополнительные детали.
- Настройка параметров выборки: поэкспериментируйте с различными настройками температуры и выбором k лучших результатов, чтобы отрегулировать творческие возможности модели.
Будьте конкретны в своих инструкциях.
Наиболее эффективные запросы достигаются, когда они ясны и подробны. Если у вас есть конкретное требование к результату, лучше указать его в запросе, чтобы гарантировать получение желаемого результата.
В случае с этим изображением табло аэропорта, запрос к модели просто «опишите это изображение» может сгенерировать общее описание. Если вам нужно, чтобы модель определила время и город на изображении, вы можете включить этот запрос непосредственно в ваше сообщение.
| Быстрый | Ответ модели |
|---|---|
 Опишите это изображение. | На изображении показано табло прибытия и отправления рейсов в аэропорту. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
С помощью программы для обработки времени и названия города, отображаемых на табло аэропорта на этом изображении, сформируйте список. |
Приведите несколько примеров.
Модель Gemini может принимать несколько входных данных, которые она может использовать в качестве примеров для понимания желаемого результата. Добавление этих примеров помогает модели выявлять закономерности и применять взаимосвязь между заданными изображениями и ответами к новому примеру. Это также называется обучением с малым количеством примеров.
В приведенном ниже примере исходный вывод представлен в виде предложения и содержит название страны (Бразилия). Предположим, вам нужен вывод в другом формате или стиле, и вы хотите получить только название города, а не страны. Добавление нескольких примеров к вашему запросу может направить модель к нужному вам способу ответа.
| Быстрый | Ответ модели |
|---|---|
 Определите город и достопримечательность. | Главная достопримечательность — статуя Христа-Искупителя в Рио-де-Жанейро, Бразилия. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Определите город и достопримечательность.  | Город: Рим, достопримечательность: Колизей. |
 | Город: Пекин, достопримечательность: Запретный город. |
| Город: Рио-де-Жанейро, достопримечательность: статуя Христа-Искупителя. |
Разберите это пошагово.
Для сложных задач, требующих как визуального восприятия, так и логического мышления, может быть полезно разбить задачу на более мелкие, простые шаги. В качестве альтернативы, может быть эффективно, если вы прямо попросите модель «думать шаг за шагом» в своем задании.
| Быстрый | Ответ модели |
|---|---|
 Когда у меня закончится туалетная бумага? | Вскоре у вас останется всего 3 рулона. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
|
|
Математические задачи или другие виды текстовых задач отлично подходят для того, чтобы попросить модель мыслить пошагово.
| Быстрый | Ответ |
|---|---|
 Какой четвертый член последовательности? | -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 $$ Следовательно, четвертый член последовательности равен -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 { "ингредиенты": [ "рис", "креветка", "моллюски", "моллюски", "горох", «помидоры», «лук», "чеснок", "оливковое масло", «паприка» "соль", "перец" ], «Тип кухни»: «испанская». "вегетарианец": ложь } ``` |
При выборе одного изображения, разместите ваше изображение первым.
Хотя Близнецы могут интерпретировать изображение и текст в любом порядке в рамках подсказки, размещение одного изображения перед текстовой подсказкой может привести к лучшим результатам. В следующих примерах вы заметите, что в каждой подсказке изображение стоит перед текстом.
Устранение неполадок с многомодальным приглашением
Если вы не получаете полезного ответа, возможно, вам потребуется устранить неполадки в работе командной строки. Вот несколько стратегий, которые вы можете попробовать.
Если модель не извлекает информацию из соответствующей части изображения
Чтобы получить более конкретный ответ, вы можете указать, какие аспекты изображения вы хотите, чтобы система использовала для формирования ответа.
| Быстрый | Ответ модели |
|---|---|
 На сколько дней хватит этих подгузников для ребенка? | Подгузников хватит на 198 дней. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
На сколько мне хватит этих подгузников, прежде чем они закончатся? Используйте вес, указанный на коробке, чтобы определить возраст ребенка, и общее количество подгузников в коробке. Разделите общее количество на число подгузников, которые ребенок использует в день. | В коробке 198 подгузников. На коробке указано, что подгузники предназначены для ребенка весом от 22 до 37 фунтов. В среднем, ребенку в этом весовом диапазоне, вероятно, от 1 до 2 лет. Двухлетний ребенок обычно использует 6 подгузников в день, поэтому подгузников хватит примерно на 33 дня (198/6). |
Если выходные данные модели слишком общие и недостаточно адаптированы к входному изображению,
Чтобы помочь модели адаптировать свой ответ к изображению (изображениям), попробуйте попросить ее описать изображения, прежде чем выполнять задачу рассуждения.
| Быстрый | Ответ модели |
|---|---|
   Что общего между этими изображениями? | Все четыре изображения являются примерами пейзажной фотографии. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Для начала подробно опишите, что изображено на каждом изображении. Что общего у этих изображений? | На первом изображении человек упаковывает чемодан. На втором изображении — пустой коридор в торговом центре. На третьем изображении — рулон туалетной бумаги. На четвёртом изображении — тёмное и бушующее море. Общим для всех этих изображений является то, что все они являются примерами пограничных пространств. Пограничные пространства — это места или ситуации, находящиеся между двумя другими местами или ситуациями. Они часто характеризуются чувством неопределенности или двусмысленности. На первом изображении человек находится в промежутке между домом и поездкой. На втором изображении показан коридор между двумя магазинами. На третьем изображении — туалетная бумага, которая может символизировать ванную комнату. Ванная комната — это переходное пространство между частной и общественной сферами. Это место, где мы готовимся войти во внешний мир или покинуть его. На четвертом изображении показано море в периоды между спокойствием и штормом. Пограничные пространства могут быть одновременно захватывающими и тревожными. Они могут быть местом новых начал или местом завершения. Они могут быть местом для размышлений или местом для действий. |
Вы также можете попробовать явно попросить модель ссылаться на то, что изображено на картинке.
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Что общего между этими изображениями? В своем ответе укажите, что изображено на картинках. | Все изображения связаны с путешествиями. На первом изображении человек упаковывает чемодан, на втором — пустой коридор в торговом центре, на третьем — стопка туалетной бумаги, а на четвёртом — тёмное и бушующее море. Все эти изображения связаны с путешествиями, поскольку на них изображены вещи, которые нужны или используются людьми во время поездок. На первом изображении человек упаковывает чемодан, что является обычным делом для тех, кто отправляется в путешествие. На втором изображении показан пустой коридор в торговом центре, где люди часто покупают вещи для своих поездок. На третьем изображении показана стопка туалетной бумаги, что также часто используется в путешествиях. На четвертом изображении показано темное и бушующее море, с которым люди часто сталкиваются во время путешествий. |
Те же советы применимы и к созданию креативных работ на основе изображений. В следующем примере с кроликом, явное указание модели включить элементы изображения может улучшить результат.
| Быстрый | Ответ модели |
|---|---|
 Можете написать стихотворение об этом изображении? | Маленький кролик, такой мягкий и коричневый, Ты пощипываешь траву, такую зеленую и сладкую. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Не могли бы вы написать для меня описательное и драматичное стихотворение об этом изображении, указав при этом место съемки? | Маленький кролик на зелёном газоне, Это синева океана? Маленький кролик, скажи мне правду, Возможно, дело в масштабах всего происходящего. Маленький зайчик, интересно, что тебе снится? Что бы это ни было, маленький зайчик, |
Выявление причины сбоя части запроса.
Трудно определить, почему запрос не сработал: либо модель изначально не поняла изображение , либо поняла его, но не выполнила необходимые шаги рассуждения . Чтобы разграничить эти причины, попросите модель описать, что изображено на картинке.
В следующем примере, если модель выдает в ответ закуску, которая кажется неожиданной в сочетании с чаем (например, попкорн), вы можете сначала провести диагностику, чтобы определить, правильно ли модель распознала наличие чая на изображении.
| Быстрый | Запрос на устранение неполадок |
|---|---|
 Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? | Опишите, что изображено на этом снимке. |
Ещё одна стратегия — попросить модель объяснить свои рассуждения. Это поможет вам определить, какая часть рассуждений оказалась неверной, если таковая имелась.
| Быстрый | Запрос на устранение неполадок |
|---|---|
Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? | Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? Пожалуйста, объясните, почему. |
Что дальше?
- Попробуйте создать собственные мультимодальные подсказки с помощью Google AI Studio .
- Для получения информации об использовании API Gemini Files для загрузки медиафайлов и их включения в запросы см. руководства по обработке видео , аудио и документов .
- Дополнительные рекомендации по разработке подсказок, например, по настройке параметров выборки, см. на странице «Стратегии подсказок» .