Perguntas frequentes e solução de problemas

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Por que o nome mudou de "Vertex AI no Firebase" para "Firebase AI Logic"?

Em 2024, lançamos um conjunto de SDKs de cliente do Firebase que podiam usar o Vertex AI Gemini API e um gateway de proxy do Firebase para proteger essa API contra abuso e permitir integrações com outros produtos do Firebase. Chamamos nosso produto de "Vertex AI no Firebase", e esse nome descreveu com precisão os casos de uso disponíveis na época.

Desde então, ampliamos os recursos do nosso produto. Por exemplo, a partir de maio de 2025, agora oferecemos suporte ao Gemini Developer API, incluindo a capacidade de proteger o Gemini Developer API contra abuso usando nossa integração com o Firebase App Check.

Como resultado, o nome "Vertex AI no Firebase" não representa mais com precisão o escopo expandido do nosso produto. Por isso, um novo nome, Firebase AI Logic, reflete melhor nosso conjunto de recursos em evolução e nos permite continuar expandindo nossas ofertas no futuro.

Confira o guia de migração para ter acesso a todos os recursos mais recentes do Firebase AI Logic e, se quiser, comece a usar o Gemini Developer API.

Quais são as diferenças entre o uso do Gemini Developer API e do Vertex AI Gemini API?

Confira algumas diferenças entre os dois provedores "Gemini API" em geral, independentemente de como você os acessa:

• Preços

  • O Gemini Developer API oferece um "nível sem custo financeiro" com preço de pagamento por utilização.

  • O Vertex AI Gemini API, quando usado com Firebase AI Logic, sempre exige o plano de preços Blaze de pagamento por uso.

  Os dois provedores de API têm preços diferentes para o modelo de pagamento conforme o uso. Saiba mais na documentação de cada um deles.

• Limites de taxa (cota)

  • O Gemini Developer API tem limites de taxa explícitos.

  • O Vertex AI Gemini API usa a "cota compartilhada dinâmica (DSQ)" que todos que usam esse modelo na região compartilham. Também é possível configurar o throughput provisionado (PT).

• Como especificar o local para acessar o modelo

  • Somente o Vertex AI Gemini API permite escolher o local em que você acessa o modelo.

A tabela a seguir lista a disponibilidade de perguntas frequentes sobre recursos para os dois provedores "Gemini API". Esta tabela se aplica especificamente ao uso dos SDKs do cliente Firebase AI Logic.

¹ A API Files para o Gemini Developer API não tem suporte nos SDKs Firebase AI Logic.

Posso usar Gemini Developer API e Vertex AI Gemini API?

Sim, é possível ativar os provedores "Gemini API" no seu projeto do Firebase e usar as duas APIs no próprio app.

Para alternar entre provedores de API no código, basta configurar o serviço de back-end corretamente no código.

Quais são as APIs necessárias? E como faço para ativá-los?

Para usar os SDKs do Firebase AI Logic com o Gemini Developer API, seu projeto precisa ter as duas APIs ativas:

• Gemini Developer API (generativelanguage.googleapis.com)
• API Firebase AI Logic (firebasevertexai.googleapis.com)

Ative estas duas APIs usando o console Firebase:

1. No console Firebase, acesse a página Firebase AI Logic.

2. Clique em Começar.

3. Selecione para começar a usar o Gemini Developer API.

   Isso inicia um fluxo de trabalho guiado que ativa as duas APIs para você. O console também vai gerar uma chave de API Gemini e adicionar a API Firebase AI Logic à lista de permissões da chave de API do Firebase.

Quais modelos podem ser usados com os SDKs Firebase AI Logic?

• É possível usar qualquer um dos modelos de base Gemini e Imagen 3 com os SDKs Firebase AI Logic, incluindo versões de pré-lançamento e experimentais. Confira uma lista desses modelos em Saiba mais sobre os modelos compatíveis.

• Não é possível usar modelos Gemini sem base (como modelos PaLM, modelos ajustados ou modelos baseados em Gemma) com os SDKs Firebase AI Logic.

  O Firebase AI Logic também não oferece suporte a modelos Imagen mais antigos ou imagen-3.0-capability-001.

• O Gemini Developer API (independentemente de como ele é acessado) não oferece suporte a imagen-3.0-fast-generate-001 ou ao imagen-3.0-generate-001 mais antigo.

Adicionamos novos recursos aos SDKs com frequência. Por isso, confira as atualizações destas perguntas frequentes, bem como nas notas da versão, blogs e postagens nas redes sociais.

O que fazer quando os modelos são desativados?

Quando lançamos uma versão estável do modelo, nos esforçamos para garantir que ela esteja disponível por pelo menos um ano. Listamos essa "data de desativação" em vários lugares na documentação do Firebase e do Google Cloud (por exemplo, na página"Modelos").

Quando um modelo é desativado, todas as solicitações para ele falham com um erro 404. Por esse motivo, recomendamos configurar e usar Firebase Remote Config para que você possa mudar dinamicamente o modelo e a versão no seu app sem lançar uma nova versão.

Quando você atualiza o app para usar uma nova versão do modelo, recomendamos testar o app para garantir que as respostas ainda sejam as esperadas. Ao usar Firebase AI Logic, geralmente não é necessário fazer nenhuma modificação no código que chama o modelo.

Confira as datas de descontinuação de vários modelos:

• Modelos Gemini 1.5 Pro:

  • gemini-1.5-pro-002 (e gemini-1.5-pro): 24 de setembro de 2025
  • gemini-1.5-pro-001: 24 de maio de 2025

• Modelos Gemini 1.5 Flash:

  • gemini-1.5-flash-002 (e gemini-1.5-flash): 24 de setembro de 2025
  • gemini-1.5-flash-001: 24 de maio de 2025

• Modelos Gemini 1.0 Pro Vision: 21 de abril de 2025 (anteriormente programado para 9 de abril de 2025)

• Modelos Gemini 1.0 Pro: 21 de abril de 2025 (anteriormente programado para 9 de abril de 2025)

Como definir um limite de taxa por usuário?

Por padrão, Firebase AI Logic define o limite de solicitações por usuário em 100 solicitações por minuto (RPM).

Se você quiser ajustar o limite de taxa por usuário, ajuste as configurações de cota da API Firebase AI Logic.

Saiba mais sobre a cota da API Firebase AI Logic. Nela, você também pode aprender a consultar e editar sua cota.

Quais permissões são necessárias para usar os SDKs Firebase AI Logic?

O Firebase AI Logic usa meus dados para treinar modelos?

Consulte Governança de dados e IA responsável.

O tipo MIME é obrigatório nas minhas solicitações multimodais? como imagens, PDFs, vídeos e entrada de áudio.

Sim, em cada solicitação multimodal, é preciso sempre fornecer o seguinte:

• O arquivo é mimeType. Confira uma exceção abaixo.

• O arquivo. Você pode fornecer o arquivo como dados inline ou fornecer o arquivo usando o URL dele.

Saiba mais sobre os tipos de arquivos de entrada aceitos, como especificar o tipo MIME e as duas opções para fornecer o arquivo em Requisitos e arquivos de entrada compatíveis.

Exceção para incluir o tipo MIME na solicitação

Uma exceção para fornecer o tipo MIME são entradas de imagem inline para solicitações de apps nativos da plataforma Android e Apple.

Os SDKs Firebase AI Logic para plataformas Android e Apple oferecem uma maneira simplificada e compatível com a plataforma de processar imagens em solicitações. Todas as imagens (independentemente do formato) são convertidas do lado do cliente para JPEG com 80% de qualidade antes de serem enviadas ao servidor. Isso significa que quando você fornece imagens como dados inline usando os SDKs para plataformas Android e Apple, não precisa especificar o tipo MIME na solicitação.

Esse processamento simplificado é mostrado na documentação do Firebase AI Logic nos exemplos de envio de imagens codificadas em base64 em solicitações.

Confira outras informações específicas da plataforma sobre esse recurso:

• Para Android:

  • Você pode aproveitar a maneira simplificada de processar tipos de imagem nativas da plataforma (Bitmap) em comandos multimodais que contêm imagens como dados inline (consulte o exemplo).

  • Para ter mais controle sobre os formatos e as conversões de imagens, forneça as imagens como InlineDataPart e informe o tipo MIME específico. Exemplo:

    content { inlineData(/* PNG as byte array */, "image/png") }

• Para plataformas da Apple:

  • Você pode aproveitar a maneira simplificada de processar tipos de imagem nativas da plataforma (UIImage, NSImage, CIImage e CGImage) em comandos multimodais que contêm imagens como dados inline (consulte o exemplo).

  • Para ter mais controle sobre os formatos e as conversões de imagens, forneça as imagens como InlineDataPart e informe o tipo MIME específico. Exemplo:

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

Esses recursos estão disponíveis ao usar Firebase AI Logic? Armazenamento em cache de contexto, Pesquisa como ferramenta, embasamento com a Pesquisa Google, execução de código, ajuste fino de um modelo, geração de embeddings e recuperação semântica?

O armazenamento em cache de contexto, a pesquisa como ferramenta, o embasamento com a Pesquisa Google, a execução de código, o ajuste fino de um modelo, a geração de embeddings e a recuperação semântica são compatíveis com vários modelos ou o Vertex AI Gemini API, mas não estão disponíveis ao usar Firebase AI Logic.

Se você quiser adicionar esses recursos como solicitações ou votar em uma solicitação já existente, acesse o UserVoice do Firebase.

O que é uma chave de API Gemini?

O Gemini Developer API usa uma "chave de API Gemini" para autorizar o autor da chamada. Portanto, se você estiver usando o Gemini Developer API pelos SDKs Firebase AI Logic, vai precisar de uma chave de API Gemini válida no seu projeto do Firebase para fazer chamadas para essa API.

Uma "chave de API Gemini" significa uma chave de API que tem o Gemini Developer API na lista de permissões de API.

Quando você passa pelo fluxo de trabalho de configuração do Firebase AI Logic no console Firebase, criamos uma chave de API Gemini que é restringida apenas ao Gemini Developer API e configuramos o serviço de proxy Firebase AI Logic para usar essa chave de API. Essa chave de API Gemini gerada pelo Firebase tem o nome Chave da API Gemini Developer (criada automaticamente pelo Firebase) na página de credenciais do console Google Cloud.

Saiba mais sobre as restrições de API para chaves de API.

Não adicione a chave de API Gemini à base de código do app ao usar os SDKs Firebase AI Logic. Saiba mais sobre como proteger a chave de API Gemini.

Devo adicionar minha chave de API Gemini à base de código do meu app para dispositivos móveis ou Web?

Ao usar os SDKs do Firebase AI Logic, não adicione a chave de API Gemini à base de código do app.

Na verdade, durante o desenvolvimento com os SDKs Firebase AI Logic, você não interagará diretamente com a chave de API Gemini. Em vez disso, nosso serviço de proxy Firebase AI Logic vai incluir internamente a chave de API Gemini em cada solicitação para o Gemini Developer API, completamente no back-end.

Como posso mudar a chave de API Gemini usada para chamar o Gemini Developer API?

Ao usar os SDKs Firebase AI Logic, é improvável que você precise mudar a chave de API Gemini. No entanto, há dois casos em que você pode precisar:

• Se você vazou a chave por acidente e quer substituí-la por uma nova chave segura.

• Se você excluiu a chave por acidente. É possível cancelar a exclusão da chave até 30 dias após a exclusão.

Veja como mudar a chave de API Gemini usada pelos SDKs Firebase AI Logic:

1. Se a chave de API Gemini gerada pelo Firebase ainda existir, exclua-a.

   É possível excluir essa chave de API no painel APIs e serviços > Credenciais do console Google Cloud. Ela é chamada de:
   Chave da API Gemini Developer (criada automaticamente pelo Firebase).

2. Na mesma página do console do Google Cloud, crie uma nova chave de API. Sugerimos que você nomeie a chave como
   Chave da API Gemini Developer para o Firebase.

3. Para essa nova chave, adicione restrições de API e selecione apenas a API Language Generative.
   Às vezes, a Gemini Developer API é chamada de "API de linguagem generativa" no console Google Cloud.

   Não adicione restrições de app. Caso contrário, o serviço de proxy Firebase AI Logic não vai funcionar como esperado.

4. Execute o comando abaixo para definir essa nova chave como a chave de API Gemini que o serviço de proxy Firebase AI Logic vai usar.

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   Saiba mais sobre a gcloud CLI.

Não adicione essa nova chave de API Gemini ao repositório de códigos do app. Saiba mais sobre como proteger a chave de API Gemini.

Posso usar minha "chave de API do Firebase" como chave de API Gemini?

Não. Não use a "chave de API do Firebase" como chave de API Gemini. Recomendamos que você não adicione o Gemini Developer API à lista de permissões da chave de API do Firebase.

A chave de API do Firebase é a chave listada no arquivo ou objeto de configuração do Firebase que você adiciona à base de código do app para conectar o app ao Firebase. É possível incluir a chave de API do Firebase no código quando você usa a chave apenas com APIs relacionadas ao Firebase (como Firebase AI Logic). Saiba mais sobre as chaves de API do Firebase.

No painel APIs e serviços > Credenciais do console Google Cloud, as chaves de API do Firebase têm a seguinte aparência:

Como você precisa adicionar a chave de API do Firebase à base de código do app para que as APIs relacionadas ao Firebase funcionem e porque o Gemini Developer API é autorizado pela chave de API, recomendamos que você NÃO adicione o Gemini Developer API (chamado de "API de linguagem generativa" no console Google Cloud) à lista de permissões de API da chave de API do Firebase. Se você fizer isso, estará expondo o Gemini Developer API a possíveis abusos.

Como manter minha chave de API Gemini segura?

Estas perguntas frequentes descrevem algumas práticas recomendadas para manter a chave de API Gemini segura.

Se você estiver chamando Gemini Developer API diretamente do seu app para dispositivos móveis ou da Web:

• Use os SDKs do cliente Firebase AI Logic.
• Não adicione a chave de API Gemini à base de código do app.

O Firebase AI Logic fornece um serviço de proxy que inclui internamente a chave de API Gemini em cada solicitação para o Gemini Developer API, completamente no back-end.

Além disso, recomendamos o seguinte:

• Assim que você começar a desenvolver seu app, faça a integração com Firebase App Check para ajudar a proteger seus recursos de back-end e as APIs usadas para acessar modelos gerativos.

• Não reutilize a chave de API Gemini gerada pelo Firebase fora do Firebase AI Logic. Se você precisar de uma chave de API Gemini para outro caso de uso, crie uma chave separada.

• Em geral, NÃO modifique a chave de API Gemini gerada pelo Firebase. Essa chave é chamada de chave da API Gemini Developer (criada automaticamente pelo Firebase) no console Google Cloud.

  • Não adicione outras APIs à lista de permissões da chave de API Gemini gerada pelo Firebase. Na lista de permissões de API, a chave de API Gemini deve ter apenas o Gemini Developer API (chamado de "API Generative Language" no console Google Cloud).

  • Não adicione restrições de app. Caso contrário, o serviço de proxy Firebase AI Logic não vai funcionar como esperado.

Minha chave de API Gemini foi comprometida. O que preciso fazer?

Se a chave de API Gemini foi comprometida, siga as instruções para mudar a chave de API Gemini usada para chamar a Gemini Developer API.

Além disso, consulte as práticas recomendadas para proteger a chave de API Gemini.

Como corrigir este erro 404? Firebase AI Logic genai config not found

Se você tentar usar o Gemini Developer API e receber um erro 404 com a mensagem Firebase AI Logic genai config not found, geralmente significa que seu projeto do Firebase não tem uma chave de API Gemini válida para uso com os SDKs de cliente Firebase AI Logic.

Estas são as causas mais prováveis desse erro:

• Você ainda não configurou seu projeto do Firebase para o Gemini Developer API.

  O que fazer:
  No console Firebase, acesse a página Firebase AI Logic. Clique em Começar e selecione Gemini Developer API. Ative a API, e o console vai configurar seu projeto para o Gemini Developer API. Depois de concluir o fluxo de trabalho, tente fazer a solicitação novamente.

• Se você passou recentemente pelo fluxo de configuração do Firebase AI Logic no console Firebase, talvez sua chave de API Gemini ainda não esteja disponível para todos os serviços de back-end necessários em todas as regiões.

  O que fazer:
  Aguarde alguns minutos e tente a solicitação novamente.

• Sua chave de API Gemini pode ter sido excluída do seu projeto do Firebase.

  O que fazer:
  Aprenda a mudar a chave de API Gemini usada por Firebase AI Logic.

Como corrigir esse erro 400? Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Se você estiver tentando enviar uma solicitação multimodal com um URL Cloud Storage for Firebase, poderá encontrar o seguinte erro 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Esse erro é causado por um projeto que não tinha os agentes de serviço necessários provisionados automaticamente quando a API Vertex AI foi ativada no projeto. Esse é um problema conhecido em alguns projetos, e estamos trabalhando em uma correção global.

Confira a solução alternativa para corrigir seu projeto e provisionar corretamente esses agentes de serviço para que você possa começar a incluir URLs Cloud Storage for Firebase nas suas solicitações multimodais. Você precisa ser um proprietário do projeto e só precisa concluir esse conjunto de tarefas uma vez.

1. Acesse e faça a autenticação com o gcloud CLI.
   A maneira mais fácil de fazer isso é em Cloud Shell. Saiba mais na documentação da Google Cloud.

2. Se solicitado, siga as instruções exibidas no terminal para executar o gcloud CLI no seu projeto do Firebase.

   Você vai precisar do ID do projeto do Firebase, que pode ser encontrado na parte de cima da página settings Configurações do projeto no console Firebase.

3. Provisione os agentes de serviço necessários no projeto executando o seguinte comando:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. Aguarde alguns minutos para garantir que os agentes de serviço sejam provisionados e tente enviar a solicitação multimodal que inclui o URL Cloud Storage for Firebase novamente.

Se você ainda estiver recebendo esse erro depois de esperar vários minutos, entre em contato com o suporte do Firebase.

Como corrigir esse erro 400? API key not valid. Please pass a valid API key.

Se você receber um erro 400 com a mensagem API key not valid. Please pass a valid API key., geralmente significa que a chave de API no arquivo/objeto de configuração do Firebase não existe ou não está configurada para ser usada com o app e/ou projeto do Firebase.

Verifique se a chave de API listada no arquivo/objeto de configuração do Firebase corresponde à chave de API do app. É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console Google Cloud.

Se você descobrir que elas não correspondem, extraia um novo arquivo/objeto de configuração do Firebase e substitua o que está no app. O novo arquivo/objeto de configuração precisa conter uma chave de API válida para o app e o projeto do Firebase.

Como corrigir este erro 403? Requests to this API firebasevertexai.googleapis.com ... are blocked.

Se você receber um erro 403 com a mensagem Requests to this API firebasevertexai.googleapis.com ... are blocked., geralmente significa que a chave de API no arquivo/objeto de configuração do Firebase não tem uma API necessária na lista de permissões para o produto que você está tentando usar.

Verifique se a chave de API usada pelo app tem todas as APIs necessárias incluídas na lista de permissões "Restrições de API". Para Firebase AI Logic, a chave de API precisa ter pelo menos a API Firebase AI Logic na lista de permissões.

É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console Google Cloud.

Como corrigir este erro 403? PERMISSION_DENIED: The caller does not have permission.

Se você receber um erro 403 com a mensagem PERMISSION_DENIED: The caller does not have permission., geralmente significa que a chave de API no arquivo/objeto de configuração do Firebase pertence a um projeto diferente.

Verifique se a chave de API listada no arquivo/objeto de configuração do Firebase corresponde à chave de API do app. É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console Google Cloud.

Se você descobrir que elas não correspondem, extraia um novo arquivo/objeto de configuração do Firebase e substitua o que está no app. O novo arquivo/objeto de configuração precisa conter uma chave de API válida para o app e o projeto do Firebase.