Resposta curta: em 9 de setembro de 2026, a documentação canônica da Gemini API lista dois IDs do Lyria 3.5: lyria-3.5-pro-preview para músicas completas e lyria-3.5-clip-preview para clipes de 30 segundos. Esses mesmos IDs aparecem na lista de modelos compatíveis com a API Interactions. Para projetos novos, a própria documentação do Google recomenda a Interactions API; o generateContent continua disponível, mas sua documentação está marcada como Legacy.
Isso significa que a escolha principal não deve ser “um ID para generateContent e outro para Interactions”. Hoje, o caminho mais seguro é escolher primeiro o modelo (Pro ou Clip) e depois usar esse ID na superfície da API que seu código realmente chama. O que causa confusão são exemplos e páginas que foram atualizados em ritmos diferentes — inclusive trechos Java que ainda mostram lyria-3-generate-001, embora esse identificador não apareça na lista canônica atual de modelos do Lyria 3.5.
Qual ID usar hoje
| Objetivo | ID recomendado | Superfície | Duração e saída | Chamada mínima |
|---|---|---|---|---|
| Música completa em projeto novo | lyria-3.5-pro-preview | Interactions | Alguns minutos, controláveis pelo prompt; MP3 por padrão e opção de WAV no Pro | client.interactions.create(model="lyria-3.5-pro-preview", input="...") |
| Clipe, loop ou prévia rápida | lyria-3.5-clip-preview | Interactions | 30 segundos; MP3 | client.interactions.create(model="lyria-3.5-clip-preview", input="...") |
| Música completa em código legado | lyria-3.5-pro-preview | generateContent (Legacy) | Alguns minutos; MP3 por padrão e opção de WAV no Pro | POST /v1beta/models/lyria-3.5-pro-preview:generateContent |
| Clipe em código legado | lyria-3.5-clip-preview | generateContent (Legacy) | 30 segundos; MP3 | POST /v1beta/models/lyria-3.5-clip-preview:generateContent |
A referência mais forte para os nomes é a página de Lyria 3.5 Pro Preview, a página de Lyria 3.5 Clip Preview e a visão geral da API Interactions. As notas de versão de setembro de 2026 também registram explicitamente os dois IDs.
Por que parece haver IDs diferentes
O Google não publicou, na documentação consultada, uma explicação formal dizendo por que alguns exemplos exibem identificadores diferentes. Portanto, atribuir a diferença a uma migração interna específica seria especulação. O que é verificável é que as páginas não estão perfeitamente sincronizadas.
O guia atual de geração de música usa a Interactions API e, nos exemplos de Python, JavaScript e REST, aponta para lyria-3.5-pro-preview e lyria-3.5-clip-preview. No entanto, alguns exemplos Java da mesma página ainda mostram lyria-3-generate-001. Esse último ID não aparece na tabela atual de modelos compatíveis com Interactions, nem nas páginas canônicas dos modelos Lyria 3.5. Por isso, ele não deve ser tratado como o identificador padrão para copiar em um projeto novo.
Também é possível encontrar snapshots ou resultados de busca que mostram nomes como lyria-3.5. Se o código foi montado a partir de uma versão anterior da documentação, vale conferir novamente a página do modelo antes de concluir que o nome ainda é o recomendado. Em APIs de prévia, aliases e exemplos podem mudar; o fato de um nome aparecer em um trecho antigo não garante que ele seja o identificador de referência atual.
“Legacy” é sobre a API, não sobre o Lyria 3.5
A palavra Legacy no caminho Gemini Generate Content API (Legacy) se refere à superfície generateContent. O guia de introdução dessa API diz que, para novos projetos e aplicações, o Google recomenda a nova Interactions API.
Isso não torna lyria-3.5-pro-preview ou lyria-3.5-clip-preview modelos legados. Pelo contrário: as notas de versão de 3 de setembro de 2026 apresentam os dois como a geração Lyria 3.5 em prévia pública. A página de descontinuações identifica os modelos anteriores lyria-3-pro-preview e lyria-3-clip-preview como a geração anterior e recomenda migrar para os equivalentes 3.5.
Como o mesmo ID muda de lugar entre os endpoints
No REST de generateContent, o ID faz parte do caminho da URL. Para uma música completa, a chamada segue a forma /v1beta/models/lyria-3.5-pro-preview:generateContent. O corpo usa a estrutura contents e parts.
Na Interactions API, o endpoint é genérico: /v1beta/interactions. O modelo vai no corpo da requisição, no campo model, enquanto a entrada fica em input. Portanto, uma diferença visual entre exemplos não significa necessariamente um ID diferente; muitas vezes é apenas a posição em que o mesmo ID aparece.
Exemplo mínimo com Interactions
Python: interaction = client.interactions.create(model="lyria-3.5-pro-preview", input="Uma faixa instrumental cinematográfica de dois minutos.")
Para recuperar o resultado, os exemplos atuais usam propriedades como interaction.output_audio e interaction.output_text. A resposta também pode ser percorrida em steps quando o aplicativo precisa de controle sobre os blocos de texto e áudio.
Exemplo mínimo com generateContent
REST: POST https://generativelanguage.googleapis.com/v1beta/models/lyria-3.5-pro-preview:generateContent
O corpo contém contents, com a instrução dentro de parts. Nos SDKs, o equivalente é chamar client.models.generate_content ou generateContent com o mesmo ID do modelo.
Pro ou Clip: a decisão que realmente muda o comportamento
Lyria 3.5 Clip Preview é voltado a clipes curtos, loops e prévias e gera 30 segundos de áudio estéreo a 44,1 kHz. Lyria 3.5 Pro Preview é otimizado para músicas completas com versos, refrões e pontes e pode produzir alguns minutos, com a duração influenciada pelo prompt e por marcações de tempo.
Os dois aceitam texto e imagem como entrada. A documentação dos modelos descreve saída de áudio MP3 e texto com letras. Para o Pro, o guia também documenta a possibilidade de solicitar WAV. Portanto, trocar Clip por Pro é uma mudança funcional; trocar apenas a API de Interactions para generateContent é uma mudança de superfície e formato de chamada.
Como migrar sem carregar um ID errado
- Identifique a superfície: procure por client.interactions.create ou pelo endpoint /v1beta/interactions; se aparecer models/...:generateContent, você está no fluxo legacy.
- Escolha Pro ou Clip: use lyria-3.5-pro-preview para música completa e lyria-3.5-clip-preview para 30 segundos.
- Não migre só trocando o nome do método: Interactions usa input e uma resposta baseada em interação/steps; generateContent usa contents e candidates/parts.
- Desconfie de IDs que aparecem em apenas um snippet: antes de copiar lyria-3-generate-001, lyria-3.5 ou outro nome divergente, confira se ele aparece na página canônica do modelo e na lista atual da API que você pretende usar.
- Em projeto novo, prefira Interactions: essa é a recomendação explícita do guia de início do generateContent legacy.
O que fazer se um exemplo oficial contradizer outro
Use uma hierarquia de confiança. Primeiro, confira a página do modelo e a lista de modelos compatíveis com a API. Depois, confira as notas de versão e a página de descontinuações. Só então use um snippet específico de linguagem como fonte para o ID.
Essa ordem é especialmente importante em uma prévia recém-lançada. Em 9 de setembro de 2026, as páginas canônicas e as notas de versão convergem em lyria-3.5-pro-preview e lyria-3.5-clip-preview. A divergência residual de alguns exemplos deve ser tratada como inconsistência documental, não como uma regra de que Interactions e generateContent exigem, necessariamente, nomes diferentes.
Em resumo: para código novo, use Interactions com lyria-3.5-pro-preview ou lyria-3.5-clip-preview. Para código existente em generateContent, os mesmos IDs 3.5 aparecem na documentação legacy atual. Ao migrar, altere a estrutura da chamada e da resposta junto com a superfície da API — e não copie um ID isolado de um exemplo antigo sem confirmar na referência do modelo.
