A família de modelos de inteligência artificial (IA) Gemini foi criada para processar vários tipos de dados de entrada, incluindo texto, imagens e áudio. Como esses modelos podem processar mais de um tipo ou modo de dados, eles são chamados de modelos multimodais ou explicados como tendo recursos multimodais.
Este guia mostra como trabalhar com arquivos de mídia usando a API Files. As operações básicas são as mesmas para arquivos de áudio, imagens, vídeos, documentos e outros tipos de arquivos aceitos.
Para orientações sobre comandos de arquivos, consulte a seção Guia de comandos de arquivos.
Carregar um arquivo
Você pode usar a API Files para fazer upload de um arquivo de mídia. Sempre use a API Files quando o tamanho total da solicitação (incluindo arquivos, comando de texto, instruções do sistema etc.) for maior que 20 MB.
O código abaixo faz upload de um arquivo e o usa em uma chamada para
generateContent.
Python
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-2.0-flash", contents=["Describe this audio clip", myfile]
)
print(response.text)
JavaScript
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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.0-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
Go
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.0-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)
REST
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?key=${GOOGLE_API_KEY}" \
-D upload-header.tmp \
-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.0-flash:generateContent?key=$GOOGLE_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
Receber metadados de um arquivo
É possível verificar se a API armazenou o arquivo enviado e acessar os metadados dele chamando files.get.
Python
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);
Go
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)
REST
# 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 > 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
Listar arquivos enviados
É possível fazer upload de vários arquivos usando a API Files. O código a seguir recebe uma lista de todos os arquivos enviados:
Python
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);
}
Go
iter := client.ListFiles(ctx)
for {
ifile, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
log.Fatal(err)
}
fmt.Println(ifile.Name)
}
REST
echo "My files: "
curl "https://generativelanguage.googleapis.com/v1beta/files?key=$GOOGLE_API_KEY"
Excluir arquivos enviados
Os arquivos são excluídos automaticamente após 48 horas. Também é possível excluir manualmente um arquivo enviado:
Python
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 });
Go
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
client.DeleteFile(ctx, file.Name)
REST
curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name?key=$GOOGLE_API_KEY
Informações de uso
É possível usar a API Files para fazer upload e interagir com arquivos de mídia. A API Files permite armazenar até 20 GB de arquivos por projeto, com um tamanho máximo de 2 GB por arquivo. Os arquivos são armazenados por 48 horas. Durante esse período, é possível usar a API para receber metadados sobre os arquivos, mas não é possível fazer o download deles. A API Files está disponível sem custo financeiro em todas as regiões onde a API Gemini está disponível.
Estratégias de comando de arquivos
Esta seção oferece orientações e práticas recomendadas para usar arquivos de mídia com comandos para a API Gemini.
A capacidade de usar vários tipos de dados nos comandos oferece mais flexibilidade em termos de tarefas que você pode realizar com a API Gemini. Por exemplo, você pode enviar para o modelo uma foto de uma refeição deliciosa e pedir que ele escreva um blog curto sobre ela.
| Comando | Resposta |
|
Escreva uma postagem curta e interessante para o blog com base nessa foto. A foto deve incluir uma descrição da refeição e falar sobre a preparação das refeições. 
|
Preparar refeições é uma ótima maneira de economizar tempo e dinheiro, e também pode ajudar você a comer de forma mais saudável. Essa refeição é um ótimo exemplo de uma refeição saudável e deliciosa que pode ser preparada com facilidade com antecedência. Esta refeição inclui arroz integral, legumes assados e frango teriyaki. O arroz integral é um carboidrato saudável e complexo que vai fornecer energia por mais tempo. Os legumes assados são uma ótima maneira de consumir sua dose diária de vitaminas e minerais, e o frango teriyaki é uma opção deliciosa e rica em proteínas. Esta refeição também é muito fácil de preparar. Basta cozinhar o arroz integral, assar os vegetais e cozinhar o frango teriyaki. Quando tudo estiver cozido, divida em recipientes de preparação de refeições e armazene na geladeira. Você pode pegar um contêiner e sair em manhãs agitadas. Se você está procurando uma refeição saudável e deliciosa que possa ser facilmente preparada com antecedência, essa é uma ótima opção. Ele é cheio de nutrientes e sabor, e vai deixar você se sentindo satisfeito. Que comece a preparação de refeições saudáveis e deliciosas! |
Se você está com problemas para receber a saída desejada de comandos que usam arquivos de mídia, há algumas estratégias que podem ajudar a conseguir os resultados que você quer. As seções a seguir oferecem abordagens de design e dicas de solução de problemas para melhorar comandos que usam entrada multimodal.
É possível melhorar os prompts multimodais seguindo estas práticas recomendadas:
-
Conceitos básicos do design de comandos
- Seja específico nas instruções: crie instruções claras e concisas que deixem pouco espaço para interpretações equivocadas.
- Adicione alguns exemplos ao comando: use exemplos realistas de few-shot para ilustrar o que você quer alcançar.
- Detalhamento por etapas: divida tarefas complexas em submetas gerenciáveis para guiar o modelo pelo processo.
- Especifique o formato de saída: no comando, peça que a saída esteja no formato desejado, como markdown, JSON, HTML e muito mais.
- Coloque sua imagem em primeiro lugar nos comandos de imagem única: o Gemini processa entradas de imagem e texto em qualquer ordem, mas para comandos com uma única imagem, o desempenho pode ser melhor se a imagem (ou vídeo) for colocada antes no comando de texto. No entanto, nos comandos que exigem que as imagens sejam altamente intercaladas com textos para fazer sentido, use a ordem mais natural.
-
Como solucionar problemas do comando multimodal
- Se o modelo não estiver desenhando informações da parte relevante da imagem: solte dicas com os aspectos da imagem de que você quer que o comando extraia informações.
- Se a saída do modelo for muito genérica (não personalizada o suficiente para a entrada de imagem/vídeo): no início do comando, peça para o modelo descrever as imagens ou o vídeo antes de fornecer a tarefa ou peça ao modelo para consultar o conteúdo da imagem.
- Para resolver problemas de qual parte falhou: peça para o modelo descrever a imagem ou explicar o raciocínio para avaliar o entendimento inicial dele.
- Se o comando resultar em conteúdo alucinado: diminua a configuração de temperatura ou peça ao modelo descrições mais curtas para diminuir a probabilidade de extrapolar detalhes.
- Ajuste os parâmetros de amostragem: teste diferentes configurações de temperatura e as seleções de top-k para ajustar a criatividade do modelo.
Especificar as instruções
As instruções têm mais sucesso quando são claras e detalhadas. Se você tiver uma saída específica em mente, é melhor incluir esse requisito no comando para garantir a saída desejada.
Para essa imagem de uma placa de aeroporto, pedir ao modelo apenas "descrever esta imagem" poderia gerar uma descrição geral. Se você precisa que o modelo analise a hora e a cidade a partir da imagem, inclua essa solicitação diretamente no comando.
| Comando | Resposta do modelo |
|---|---|
 Descreva esta imagem. |
A imagem mostra um painel de chegadas e partidas do aeroporto. |
| Comando atualizado | Resposta aprimorada |
|---|---|
Analise a hora e a cidade no quadro do aeroporto mostrado nesta imagem em uma lista. |
Adicionar alguns exemplos
O modelo Gemini pode aceitar várias entradas que podem ser usadas como exemplos para entender a saída que você quer. Adicionar esses exemplos pode ajudar o modelo a identificar os padrões e aplicar a relação entre as imagens e respostas fornecidas ao novo exemplo. Isso também é chamado de aprendizado "few-shot".
No exemplo abaixo, a saída inicial é escrita na forma de frase e também contém o país (Brasil). Suponha que você queira a saída em um formato ou estilo diferente e queira apenas a cidade, não o país. Adicionar alguns exemplos ao comando pode fazer com que o modelo responda da maneira desejada.
| Comando | Resposta do modelo |
|---|---|
 Determine a cidade junto com o ponto de referência. |
O ponto turístico é a estátua do Cristo Redentor no Rio de Janeiro, Brasil. |
| Comando atualizado | Resposta aprimorada |
|---|---|
|
Determine a cidade junto com o ponto de referência. 
|
cidade: Roma, ponto de referência: o Coliseu. |
|
cidade: Pequim, ponto de referência: Cidade Proibida |
|
|
cidade: Rio de Janeiro, ponto de referência: estátua do Cristo Redentor |
Detalhar por etapas
Para tarefas complexas, como as que exigem compreensão e raciocínio visual, pode ser útil dividir a tarefa em etapas menores e mais diretas. Também poderia ser eficaz se você pedisse diretamente ao modelo para “pensar passo a passo” no comando.
| Comando | Resposta do modelo |
|---|---|
 Quando vou ficar sem papel higiênico? |
Em breve, você só tem mais três rolos. |
| Comando atualizado | Resposta aprimorada |
|---|---|
|
|
Problemas matemáticos ou outros tipos de problemas são ótimos candidatos para pedir que o modelo pense em etapas.
| Comando | Resposta |
|---|---|
Qual é o quarto termo na sequência? |
-135 |
A resposta do modelo está incorreta. Uma maneira de melhorar isso é pedir ao modelo que analise o problema antes de responder ao comando.
| Comando | Resposta |
|---|---|
Analise a fórmula na imagem primeiro. Depois, com base na fórmula, responda "qual é o quarto termo na sequência?". |
Clique para abrir o resultado\( 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 \) Portanto, o quarto termo na sequência é -405. |
A resposta do modelo está correta. Agora, para simplificar ainda mais, peça ao modelo que pense em etapas detalhadas.
| Comando atualizado | Resposta aprimorada |
|---|---|
Qual é o quarto termo na sequência? Pense em etapas. |
O primeiro termo é 15. O segundo termo é b(1) * (-3) = 15 * (-3) = -45. O terceiro termo é b(2) * (-3) = -45 * (-3) = 135. O quarto termo é b(3) * (-3) = 135 * (-3) = -405. |
especifique o formato das respostas
Um problema comum é a necessidade de a saída do modelo estar em um determinado formato (por exemplo, markdown, JSON, HTML), especialmente se ela precisar ser ingerida por uma tarefa downstream. Você pode tentar produzir saídas nesse formato instruindo o modelo a fazer isso no comando. Veja dois exemplos:
| Comando | Resposta do modelo |
|---|---|
 Analise a tabela nesta imagem no formato markdown |
| Assunto | Status | Hora | Data de início | Prazo | | ------- | ------ | ---- | --------- | ------ | | Matemática | Concluído | 1h30 | 29/11/2023 | 01/12/2023 | | Geografia | Concluído | 30 min | 02/12/2023 | 04/12/2023 | | Física | Em andamento | 2h | 03/12/2023 | 05/12/2023 | | Biologia | Não começou | 6 horas | 02/11/2016 | 06/12/2023 | |
| Comando | Resposta do modelo |
|---|---|
Forneça uma lista com todos os atributos a seguir: Ingredientes, tipo de culinária, vegetariano ou não, no formato JSON |
|
Colocar a imagem em primeiro lugar nos comandos com uma imagem
O Gemini pode interpretar imagem e texto em qualquer ordem em um comando, mas colocar uma única imagem antes do comando de texto pode levar a resultados melhores. Nos exemplos a seguir, você notará que a imagem vem antes do texto em cada comando.
solucionar problemas do comando multimodal
Se você não receber uma resposta útil, talvez seja necessário resolver problemas do comando. Aqui estão algumas estratégias que você pode tentar.
Se o modelo não estiver desenhando informações da parte relevante da imagem
Para receber uma resposta mais específica, indique de quais aspectos da imagem você quer que a solicitação extraia informações para embasar a resposta.
| Comando | Resposta do modelo |
|---|---|
 Quantos dias essas fraldas vão durar para um bebê? |
As fraldas durarão 198 dias antes de acabarem. |
| Comando atualizado | Resposta aprimorada |
|---|---|
|
Quanto tempo essas fraldas vão durar? Determine a idade da criança e o número total de fraldas na caixa com base no peso total. Divida o total pelo número de fraldas usadas diariamente por uma criança. |
A caixa contém 198 fraldas. Ela também informa que as fraldas são para crianças que pesam de 9 a 16 quilos. Crianças nessa faixa de peso geralmente têm de 1 a 2 anos de idade. Uma criança de dois anos costuma usar 6 fraldas por dia, logo, as fraldas vão durar cerca de 33 dias (198/6). |
Se a saída do modelo for muito genérica e não for personalizada o suficiente para a entrada de imagem
Para ajudar o modelo a adaptar a resposta às imagens, peça para ele descrever as imagens antes de realizar a tarefa de raciocínio.
| Comando | Resposta do modelo |
|---|---|
O que há em comum entre essas imagens? |
As quatro imagens são exemplos de fotografia de paisagem. |
| Comando atualizado | Resposta aprimorada |
|---|---|
|
Primeiro, descreva o que está em cada imagem em detalhes. O que há em comum entre essas imagens? |
A primeira imagem mostra uma pessoa fazendo as malas. A segunda imagem mostra um corredor vazio de um shopping. A terceira imagem mostra um rolo de papel higiênico. A quarta imagem mostra um mar escuro e tempestuoso. O ponto em comum entre essas imagens é que todas são exemplos de espaços liminais. Espaços liminais são lugares ou situações que estão entre dois outros lugares ou situações. Elas costumam ser caracterizadas por um senso de incerteza ou ambiguidade. A primeira imagem mostra a pessoa entre o momento em que está em casa e viajando. A segunda imagem mostra o corredor entre duas lojas. A terceira imagem é de papel higiênico, que pode representar um banheiro. Um banheiro é um espaço de transição entre domínios privados e públicos. É um lugar onde nos preparamos para entrar ou sair do mundo exterior. A quarta imagem mostra o mar entre calmo e tempestuoso. Espaços liminais podem ser empolgantes e perturbadores. Eles podem ser um lugar de recomeço ou de fim. Eles podem ser um local de reflexão ou ação. |
Você também pode tentar pedir explicitamente ao modelo para se referir ao que está na imagem.
| Comando atualizado | Resposta aprimorada |
|---|---|
|
O que há em comum entre essas imagens? Consulte o que está nas imagens na sua resposta. |
Todas as imagens são relacionadas a viagens. A primeira imagem mostra uma pessoa fazendo as malas, a segunda mostra um corredor vazio de um shopping, a terceira imagem mostra uma pilha de papel higiênico e a quarta mostra um mar escuro e violento. Todas essas imagens são relacionadas a viagens, porque são tudo o que as pessoas precisam ou usam quando viajam. A primeira imagem mostra uma pessoa fazendo as malas, que é algo que as pessoas fazem quando viajam. A segunda imagem mostra um corredor vazio de um shopping, que é um lugar onde as pessoas costumam comprar itens para viagens. A terceira imagem mostra uma pilha de papel higiênico, algo que as pessoas costumam usar quando estão viajando. A quarta imagem mostra um mar escuro e tempestuoso, algo que as pessoas encontram com frequência quando estão viajando. |
As mesmas dicas funcionam para resultados criativos de imagens. No exemplo a seguir com o coelho, pedir explicitamente que o modelo inclua aspectos da imagem pode melhorar a saída.
| Comando | Resposta do modelo |
|---|---|
Você pode me escrever um poema sobre esta imagem? |
Coelhinho peludo e marrom Você morde a grama, tão verde e doce, |
| Comando atualizado | Resposta aprimorada |
|---|---|
|
Você pode escrever um poema descritivo e dramático sobre esta imagem e incluir o local? |
Coelhinho no verde É o oceano azul, Coelhinho, fale a verdade: Talvez seja a vastidão de tudo isso, Coelhinho me pergunto o que você sonha, Seja o que for, coelhinho! |
Solução de problemas em qual parte do prompt falhou
Pode ser difícil saber se uma solicitação falhou porque o modelo não entendeu a imagem ou se ele entendeu a imagem mas não executou as etapas de raciocínio corretas. Para fazer essa diferenciação, peça ao modelo que descreva o que aparece na imagem.
No exemplo abaixo, se o modelo responder com um lanche que parece diferente quando combinado com chá (como pipoca), primeiro é possível resolver problemas para determinar se o modelo reconheceu corretamente que a imagem contém chá.
| Comando | Prompt de solução de problemas |
|---|---|
 Que lanchinho eu posso fazer em 1 minuto e que combina com este? |
Descreva o que há na imagem. |
Outra estratégia é pedir que o modelo explique o raciocínio dele. Isso pode ajudar você a filtrar qual parte do raciocínio está incorreta, se houver.
| Comando | Prompt de solução de problemas |
|---|---|
Que lanchinho eu posso fazer em 1 minuto e que combina com este? |
Que lanchinho eu posso fazer em 1 minuto e que combina com este? Explique o motivo. |
A seguir
- Tente escrever seus próprios comandos multimodais usando o Google AI Studio.
- Para informações sobre como usar a API Gemini Files para fazer upload de arquivos de mídia e incluí-los nos comandos, consulte os guias Vision, Áudio e Processamento de documentos.
- Para mais orientações sobre o design de comandos, como ajustar parâmetros de amostragem, consulte a página Estratégias de comando.