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.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-3.5-flash",
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.5-flash", []*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.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 .
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
Список загруженных файлов
The following code gets a list of all the files uploaded:
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"
Информация об использовании
You can use the Files API to upload and interact with media files. The Files API lets you store up to 20 GB of files per project, with a per-file maximum size of 2 GB. Files are stored for 48 hours. During that time, you can use the API to get metadata about the files, but you can't download the files. The Files API is available at no cost in all regions where the Gemini API is available.
стратегии запроса файлов
В этом разделе представлены рекомендации и лучшие практики использования медиафайлов с запросами к API Gemini.
Возможность использовать различные типы данных в ваших запросах дает вам большую гибкость в плане того, какие задачи вы можете решать с помощью API Gemini. Например, вы можете отправить модели фотографию вкусного блюда и попросить ее написать короткий пост в блоге об этом блюде.
| Быстрый | Ответ |
Напишите короткий, увлекательный пост в блоге, основанный на этой фотографии. Он должен включать описание блюда на фото и рассказ о моем опыте приготовления еды заранее.  | Предварительная подготовка еды — отличный способ сэкономить время и деньги, а также помочь вам питаться здоровее. Это блюдо — прекрасный пример полезного и вкусного блюда, которое легко приготовить заранее. В состав этого блюда входят бурый рис, запеченные овощи и курица терияки. Бурый рис — это полезный и сложный источник углеводов, который обеспечит вас энергией на длительное время. Запеченные овощи — отличный способ получить ежедневную дозу витаминов и минералов, а курица терияки — вкусный и богатый белком вариант. Это блюдо очень легко приготовить. Просто сварите коричневый рис, запеките овощи и приготовьте курицу терияки. После того, как все будет готово, разложите по контейнерам для хранения и уберите в холодильник. Тогда вы сможете взять контейнер и отправиться готовить по утрам, когда у вас мало времени! Если вы ищете полезное и вкусное блюдо, которое легко приготовить заранее, это отличный вариант. Оно богато питательными веществами и обладает насыщенным вкусом, и гарантированно обеспечит вам чувство сытости и удовлетворения. Желаем вам здорового и вкусного питания при приготовлении еды заранее! |
Если у вас возникли проблемы с получением желаемого результата от запросов, использующих медиафайлы, существуют стратегии, которые могут помочь вам добиться желаемого результата. В следующих разделах представлены подходы к проектированию и советы по устранению неполадок для улучшения запросов, использующих мультимодальный ввод.
Вы можете улучшить свои мультимодальные подсказки, следуя этим рекомендациям:
Prompt design fundamentals
- Будьте конкретны в своих инструкциях : составьте четкие и лаконичные инструкции, которые сведут к минимуму возможность неправильного толкования.
- Добавьте несколько примеров к своему заданию: используйте реалистичные примеры из нескольких кадров, чтобы проиллюстрировать, чего вы хотите достичь.
- Разбейте задачу на этапы : разделите сложные задачи на выполнимые подзадачи, направляя модель на протяжении всего процесса.
- Укажите формат вывода : в командной строке укажите желаемый формат вывода, например, Markdown, JSON, HTML и другие.
- В подсказках с одним изображением размещайте изображение первым : хотя Gemini может обрабатывать изображения и текст в любом порядке, для подсказок, содержащих одно изображение, может быть эффективнее, если это изображение (или видео) будет размещено перед текстовой подсказкой. Однако для подсказок, требующих частого чередования изображений и текста для обеспечения осмысленности, используйте тот порядок, который вам наиболее естественен.
Устранение неполадок с многомодальным приглашением
- Если модель не получает информацию из соответствующей части изображения: укажите, из каких аспектов изображения вы хотите, чтобы модель получала информацию.
- Если выходные данные модели слишком общие (недостаточно адаптированы к входному изображению/видео): в начале запроса попробуйте попросить модель описать изображение(я) или видео до предоставления инструкции к заданию, или попробуйте попросить модель сослаться на то, что изображено на картинке.
- Чтобы определить, какая именно часть не сработала: попросите модель описать изображение или объяснить свои рассуждения, чтобы оценить ее первоначальное понимание.
- If your prompt results in hallucinated content: Try dialing down the temperature setting or asking the model for shorter descriptions so that it's less likely to extrapolate additional details.
- Tuning the sampling parameters: Experiment with different temperature settings and top-k selections to adjust the model's creativity.
Будьте конкретны в своих инструкциях.
Наиболее эффективные запросы достигаются, когда они ясны и подробны. Если у вас есть конкретное требование к результату, лучше указать его в запросе, чтобы гарантировать получение желаемого результата.
В случае с этим изображением табло аэропорта, запрос к модели просто «опишите это изображение» может сгенерировать общее описание. Если вам нужно, чтобы модель определила время и город на изображении, вы можете включить этот запрос непосредственно в ваше сообщение.
| Быстрый | Ответ модели |
|---|---|
 Опишите это изображение. | На изображении показано табло прибытия и отправления рейсов в аэропорту. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
С помощью программы для обработки времени и названия города, отображаемых на табло аэропорта на этом изображении, сформируйте список. |
Приведите несколько примеров.
Модель Gemini может принимать несколько входных данных, которые она может использовать в качестве примеров для понимания желаемого результата. Добавление этих примеров помогает модели выявлять закономерности и применять взаимосвязь между заданными изображениями и ответами к новому примеру. Это также называется обучением с малым количеством примеров.
В приведенном ниже примере исходный вывод представлен в виде предложения и содержит название страны (Бразилия). Предположим, вам нужен вывод в другом формате или стиле, и вы хотите получить только название города, а не страны. Добавление нескольких примеров к вашему запросу может направить модель к нужному вам способу ответа.
| Быстрый | Ответ модели |
|---|---|
 Определите город и достопримечательность. | The landmark is the Christ the Redeemer statue in Rio de Janeiro, Brazil. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Определите город и достопримечательность.  | Город: Рим, достопримечательность: Колизей. |
 | Город: Пекин, достопримечательность: Запретный город. |
| Город: Рио-де-Жанейро, достопримечательность: статуя Христа-Искупителя. |
Разберите это пошагово.
Для сложных задач, требующих как визуального восприятия, так и логического мышления, может быть полезно разбить задачу на более мелкие, простые шаги. В качестве альтернативы, может быть эффективно, если вы прямо попросите модель «думать шаг за шагом» в своем задании.
| Быстрый | Ответ модели |
|---|---|
 Когда у меня закончится туалетная бумага? | Вскоре у вас останется всего 3 рулона. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
|
|
Математические задачи или другие виды текстовых задач отлично подходят для того, чтобы попросить модель мыслить пошагово.
| Быстрый | Ответ |
|---|---|
 Какой четвертый член последовательности? | -135 |
Ответ модели неверен. Для улучшения ситуации можно попросить модель проанализировать задачу перед тем, как ответить на вопрос.
| Быстрый | Ответ |
|---|---|
Parse the formula in the image first. Затем, опираясь на формулу, ответьте на вопрос: «Какой четвертый член последовательности?». | $$ 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. | | Тема | Статус | Время | Дата начала | Дата окончания | | ------- | ------ | ---- | ---------- | ------ | | Math | Done | 1.5 hrs | 11/29/2023 | 12/1/2023 | | География | Готово | 30 мин | 02.12.2023 | 04.12.2023 | | Физика | В процессе | 2 часа | 03.12.2023 | 05.12.2023 | | Биология | Не начато | 6 часов | 02.11.2016 | 06.12.2023 | |
| Быстрый | Ответ модели |
|---|---|
 Предоставьте список всех следующих атрибутов: Ингредиенты, тип кухни, вегетарианская или нет, в формате JSON. | ```json { "ингредиенты": [ "рис", "креветка", "моллюски", "моллюски", "горох", «помидоры», «лук», "чеснок", "оливковое масло", «паприка» "соль", "перец" ], «Тип кухни»: «испанская». "вегетарианец": ложь } ``` |
При выборе одного изображения, разместите ваше изображение первым.
Хотя Близнецы могут интерпретировать изображение и текст в любом порядке в рамках подсказки, размещение одного изображения перед текстовой подсказкой может привести к лучшим результатам. В следующих примерах вы заметите, что в каждой подсказке изображение стоит перед текстом.
Устранение неполадок с многомодальным приглашением
Если вы не получаете полезного ответа, возможно, вам потребуется устранить неполадки в работе командной строки. Вот несколько стратегий, которые вы можете попробовать.
If the model is not drawing information from the relevant part of the image
Чтобы получить более конкретный ответ, вы можете указать, какие аспекты изображения вы хотите, чтобы система использовала для формирования ответа.
| Быстрый | Ответ модели |
|---|---|
 How many days will these diapers last a baby? | Подгузников хватит на 198 дней. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
На сколько мне хватит этих подгузников, прежде чем они закончатся? Используйте вес, указанный на коробке, чтобы определить возраст ребенка, и общее количество подгузников в коробке. Разделите общее количество на число подгузников, которые ребенок использует в день. | В коробке 198 подгузников. На коробке указано, что подгузники предназначены для ребенка весом от 22 до 37 фунтов. В среднем, ребенку в этом весовом диапазоне, вероятно, от 1 до 2 лет. Двухлетний ребенок обычно использует 6 подгузников в день, поэтому подгузников хватит примерно на 33 дня (198/6). |
Если выходные данные модели слишком общие и недостаточно адаптированы к входному изображению,
Чтобы помочь модели адаптировать свой ответ к изображению (изображениям), попробуйте попросить ее описать изображения, прежде чем выполнять задачу рассуждения.
| Быстрый | Ответ модели |
|---|---|
   Что общего между этими изображениями? | Все четыре изображения являются примерами пейзажной фотографии. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Для начала подробно опишите, что изображено на каждом изображении. Что общего у этих изображений? | На первом изображении человек упаковывает чемодан. На втором изображении — пустой коридор в торговом центре. На третьем изображении — рулон туалетной бумаги. На четвёртом изображении — тёмное и бушующее море. Общим для всех этих изображений является то, что все они являются примерами пограничных пространств. Пограничные пространства — это места или ситуации, находящиеся между двумя другими местами или ситуациями. Они часто характеризуются чувством неопределенности или двусмысленности. The first image shows the person in between being at home and being on a trip. The second image shows the hallway in between two stores. The third image is of toilet paper, which can represent a bathroom. A bathroom is a transitional space between private and public realms. It's a place where we prepare ourselves to enter or leave the outside world. На четвертом изображении показано море в периоды между спокойствием и штормом. Пограничные пространства могут быть одновременно захватывающими и тревожными. Они могут быть местом новых начал или местом завершения. Они могут быть местом для размышлений или местом для действий. |
Вы также можете попробовать явно попросить модель ссылаться на то, что изображено на картинке.
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Что общего между этими изображениями? В своем ответе укажите, что изображено на картинках. | Все изображения связаны с путешествиями. На первом изображении человек упаковывает чемодан, на втором — пустой коридор в торговом центре, на третьем — стопка туалетной бумаги, а на четвёртом — тёмное и бушующее море. Все эти изображения связаны с путешествиями, поскольку на них изображены вещи, которые нужны или используются людьми во время поездок. На первом изображении человек упаковывает чемодан, что является обычным делом для тех, кто отправляется в путешествие. На втором изображении показан пустой коридор в торговом центре, где люди часто покупают вещи для своих поездок. На третьем изображении показана стопка туалетной бумаги, что также часто используется в путешествиях. На четвертом изображении показано темное и бушующее море, с которым люди часто сталкиваются во время путешествий. |
The same tips work for creative output from images. In the following example with the rabbit, explicitly asking the model to include aspects from the image can improve the output.
| Быстрый | Ответ модели |
|---|---|
 Можете написать стихотворение об этом изображении? | Маленький кролик, такой мягкий и коричневый, Ты пощипываешь траву, такую зеленую и сладкую. |
| Обновлено сообщение | Улучшенная реакция |
|---|---|
Не могли бы вы написать для меня описательное и драматичное стихотворение об этом изображении, указав при этом место съемки? | Маленький кролик на зелёном газоне, Is it the ocean blue, Маленький кролик, скажи мне правду, Возможно, дело в масштабах всего происходящего. Маленький зайчик, интересно, что тебе снится? Whatever it may be, little bunny, |
Выявление причины сбоя части запроса.
Трудно определить, почему запрос не сработал: либо модель изначально не поняла изображение , либо поняла его, но не выполнила необходимые шаги рассуждения . Чтобы разграничить эти причины, попросите модель описать, что изображено на картинке.
В следующем примере, если модель выдает в ответ закуску, которая кажется неожиданной в сочетании с чаем (например, попкорн), вы можете сначала провести диагностику, чтобы определить, правильно ли модель распознала наличие чая на изображении.
| Быстрый | Запрос на устранение неполадок |
|---|---|
 Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? | Опишите, что изображено на этом снимке. |
Another strategy is to ask the model to explain its reasoning. That can help you narrow down which part of the reasoning broke down, if any.
| Быстрый | Запрос на устранение неполадок |
|---|---|
Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? | Какую закуску можно приготовить за 1 минуту, которая хорошо бы к этому подошла? Пожалуйста, объясните, почему. |
Что дальше?
- Попробуйте создать собственные мультимодальные подсказки с помощью Google AI Studio .
- Для получения информации об использовании API Gemini Files для загрузки медиафайлов и их включения в запросы см. руководства по обработке видео , аудио и документов .
- Дополнительные рекомендации по разработке подсказок, например, по настройке параметров выборки, см. на странице «Стратегии подсказок» .