Conheça recursos de áudio com a API Gemini

Python JavaScript Go REST

O Gemini pode responder a comandos sobre áudio. Por exemplo, o Gemini pode:

• Descrever, resumir ou responder a perguntas sobre conteúdo de áudio.
• Forneça uma transcrição do áudio.
• Forneça respostas ou uma transcrição sobre um segmento específico do áudio.

Este guia mostra diferentes maneiras de interagir com arquivos de áudio e conteúdo de áudio usando a API Gemini.

Formatos de áudio compatíveis

O Gemini oferece suporte aos seguintes tipos MIME de formato de áudio:

• WAV - audio/wav
• MP3 - audio/mp3
• AIFF - audio/aiff
• AAC - audio/aac
• OGG Vorbis - audio/ogg
• FLAC - audio/flac

Detalhes técnicos sobre áudio

O Gemini impõe as seguintes regras para áudio:

• O Gemini representa cada segundo de áudio como 32 tokens. Por exemplo, um minuto de áudio é representado como 1.920 tokens.
• O Gemini só pode inferir respostas a comandos em inglês.
• O Gemini pode "entender" componentes não de fala, como canto de pássaros ou sirenes.
• A duração máxima de dados de áudio em uma única instrução é de 9,5 horas. O Gemini não limita o número de arquivos de áudio em uma única instrução.No entanto, a duração total combinada de todos os arquivos de áudio em uma única instrução não pode exceder 9,5 horas.
• O Gemini reduz os arquivos de áudio para uma resolução de dados de 16 Kbps.
• Se a fonte de áudio tiver vários canais, o Gemini vai combiná-los em um único canal.

Antes de começar: configure o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e a chave de API.

Disponibilizar um arquivo de áudio para o Gemini

É possível disponibilizar um arquivo de áudio para o Gemini de duas maneiras:

• Faça upload do arquivo de áudio antes de fazer a solicitação de comando.
• Forneça o arquivo de áudio como dados inline para a solicitação de comando.

Fazer upload de um arquivo de áudio e gerar conteúdo

É possível usar a API File para fazer upload de um arquivo de áudio de qualquer tamanho. Sempre use a API File quando o tamanho total da solicitação (incluindo arquivos, comando de texto, instruções do sistema etc.) for maior que 20 MB.

Chame media.upload para fazer upload de um arquivo usando a API File. O código abaixo faz upload de um arquivo de áudio e o usa em uma chamada para models.generateContent.

from google import genai

client = genai.Client()

myfile = client.files.upload(file='media/sample.mp3')

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=['Describe this audio clip', myfile]
)

print(response.text)

Receber metadados de um arquivo

É possível verificar se a API armazenou o arquivo enviado e acessar os metadados dele chamando files.get.

myfile = client.files.upload(file='media/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)

Listar arquivos enviados

Você pode fazer upload de vários arquivos de áudio (e outros tipos de arquivos). O código abaixo gera uma lista de todos os arquivos enviados:

print('My files:')
for f in client.files.list():
    print(' ', f.name)

Excluir arquivos enviados

Os arquivos são excluídos automaticamente após 48 horas. Você também pode excluir manualmente um arquivo enviado. Exemplo:

myfile = client.files.upload(file='media/sample.mp3')
client.files.delete(name=myfile.name)

Fornecer o arquivo de áudio como dados inline na solicitação

Em vez de fazer upload de um arquivo de áudio, transmita dados de áudio na mesma chamada que contém o comando.

Em seguida, transmita esse pequeno arquivo de áudio baixado com o comando para o Gemini:

from google.genai import types

with open('media/small-sample.mp3', 'rb') as f:
    audio_bytes = f.read()

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[
    'Describe this audio clip',
    types.Part.from_bytes(
      data=audio_bytes,
      mime_type='audio/mp3',
    )
  ]
)

print(response.text)

Observe o seguinte sobre o envio de áudio como dados inline:

• O tamanho máximo da solicitação é de 20 MB, incluindo comandos de texto, instruções do sistema e arquivos fornecidos inline. Se o tamanho do arquivo ultrapassar 20 MB, o tamanho total da solicitação será maior que esse valor. Nesse caso, use a API File para fazer upload de arquivos para uso em solicitações.
• Se você estiver usando um sample de áudio várias vezes, será mais eficiente usar a API File.

Mais formas de trabalhar com áudio

Esta seção apresenta algumas outras maneiras de aproveitar melhor o áudio.

Receber uma transcrição do arquivo de áudio

Para receber uma transcrição, basta pedir no comando. Exemplo:

myfile = client.files.upload(file='media/sample.mp3')
prompt = 'Generate a transcript of the speech.'

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[prompt, myfile]
)

print(response.text)

Consultar carimbos de data/hora no arquivo de áudio

Um comando pode especificar carimbos de data/hora do formulário MM:SS para se referir a seções específicas em um arquivo de áudio. Por exemplo, o comando a seguir solicita uma transcrição que:

• Começa 2 minutos e 30 segundos após o início do arquivo.
• Termina em 3 minutos e 29 segundos do início do arquivo.

# Create a prompt containing timestamps.
prompt = "Provide a transcript of the speech from 02:30 to 03:29."

Contar Tokens

Chame o método countTokens para conferir a contagem de tokens no arquivo de áudio. Exemplo:

response = client.models.count_tokens(
  model='gemini-2.0-flash',
  contents=[myfile]
)

print(response)

A seguir

Este guia mostra como fazer upload de arquivos de áudio usando a API File e gerar saídas de texto de entradas de áudio. Para saber mais, consulte os seguintes recursos:

• Estratégias de solicitação de arquivo: a API Gemini oferece suporte a solicitações com dados de texto, imagem, áudio e vídeo, também conhecidas como solicitações multimodais.
• Instruções do sistema: as instruções do sistema permitem orientar o comportamento do modelo com base nas suas necessidades e casos de uso específicos.
• Orientações de segurança: às vezes, os modelos de IA generativa produzem resultados inesperados, como respostas imprecisas, parciais ou ofensivas. O pós-processamento e a avaliação humana são essenciais para limitar o risco de danos causados por essas saídas.