Começar: acesse a API Gemini usando a estrutura de modelos de base da Apple

Pré-lançamento: o uso de Firebase AI Logic para acessar a Gemini API pelo framework Foundation Models da Apple está atualmente em pré-lançamento público. Isso significa que ele não está sujeito a SLAs nem a políticas de descontinuação e pode mudar de maneira incompatível com versões anteriores.
Além disso, essa integração depende de APIs Beta. Portanto, os apps que a usam não podem ser enviados à App Store até que a próxima versão do Xcode atinja a disponibilidade geral (GA, na sigla em inglês) e ofereça suporte a envios de produção.

Na WWDC 2026, a Apple abriu o framework Foundation Models para adaptadores de modelos de terceiros . Isso significa que você pode acessar modelos hospedados na nuvem (como o Gemini) pelo framework Foundation Models usando a mesma API que usaria para acessar modelos no dispositivo.

No seu app, é possível trocar a instância do modelo para encaminhar as solicitações à inferência no dispositivo ou na nuvem para se adequar ao seu caso de uso:

• Os modelos no dispositivo oferecem máxima privacidade, custo zero e suporte off-line.
• Os modelos Gemini hospedados na nuvem oferecem grandes janelas de contexto, recursos avançados e mais capacidade de raciocínio.

É possível acessar os modelos Gemini hospedados na nuvem pelo framework Foundation Models da Apple usando o SDK Firebase para plataformas Apple, especificamente a biblioteca Firebase AI Logic. Este guia mostra como começar.

Para proteger o acesso aos modelos Gemini, este guia também mostra como configurar Firebase App Check, que é essencial mesmo durante o desenvolvimento.

Pré-requisitos

• Instale a versão Beta mais recente do Xcode 27.

• Um simulador de plataforma da Apple ou um dispositivo físico, ambos executando a versão Beta correspondente do SO (por exemplo, o iOS 27 Beta).

• Um novo projeto do Xcode de um app de plataformas da Apple usando uma interface SwiftUI.

Observação: Para esta versão inicial, as seguintes plataformas da Apple são compatíveis: iOS e macOS.

Modelos com suporteGemini

A integração com o framework Foundation Models da Apple oferece suporte aos seguintes Gemini modelos.

• Modelos de uso geral

  • gemini-3.1-pro-preview
  • gemini-3.5-flash
  • gemini-3.1-flash-lite

• Modelos de geração de imagens

  • gemini-3-pro-image (também conhecido como "Nano Banana Pro")
  • gemini-3.1-flash-image (também conhecido como "Nano Banana 2")
  • gemini-3.1-flash-lite-image (também conhecido como "Nano Banana 2 Lite")

Gemini Live API modelos e Imagen modelos não são compatíveis. Os modelos Gemini 2.5 têm suporte técnico, mas não são recomendados para novos projetos e exigem uma configuração especial que não é abordada nestes guias.

Etapa 1: criar um projeto do Firebase

Recomendamos começar com um novo projeto do Firebase para testar essa integração.

1. Faça login no Firebase console.

2. Clique em Criar um novo projeto do Firebase.

3. Siga as instruções na tela. Não é necessário ativar o Google Analytics.

Etapa 2: conectar seu app ao Firebase

Para conectar seu app ao Firebase, é necessário registrá-lo no projeto do Firebase e adicionar um arquivo de configuração ao código.

1. No centro da página de visão geral do projeto, clique no ícone iOS+ para iniciar o fluxo de trabalho de configuração.

2. Registre seu app:

   1. Insira o ID do pacote do seu app. Verifique se ele corresponde ao ID do pacote do projeto que você está criando no Xcode.

   2. Clique em Registrar app.

3. Adicione o arquivo de configuração do Firebase. Esse arquivo contém as configurações do SDK do Firebase para se conectar ao seu projeto do Firebase.

   1. Clique em Fazer o downloadGoogleService-Info.plist para receber o arquivo de configuração.

   2. Mova GoogleService-Info.plist para a raiz do seu projeto Xcode e adicione a todas as metas.

   3. Clique em Próxima no Firebase console.

4. O fluxo de trabalho no console fornece instruções genéricas para adicionar o SDK do Firebase ao seu app. Portanto, avance para a próxima etapa deste guia para instruções específicas sobre Firebase AI Logic.

Etapa 3: adicionar bibliotecas do Firebase e inicializar o Firebase no seu app

1. Use o Swift Package Manager para adicionar as bibliotecas necessárias do Firebase:

   1. No Xcode, com seu projeto do app aberto, selecione File > Add Packages.

   2. Insira o URL do repositório do SDK do Firebase para Apple:

      https://github.com/firebase/firebase-ios-sdk
      

   3. Selecione a regra de dependência como Branch e insira wwdc26-preview.

   4. Clique em Add Package. O Xcode vai resolver e fazer o download das dependências.

   5. Quando solicitado, adicione as bibliotecas FirebaseAILogic e FirebaseAppCheck ao destino do seu app.

2. Inicialize o Firebase quando o app for iniciado adicionando o código a seguir ao ponto de entrada principal do app:

   import SwiftUI
   import FirebaseCore
   
   @main
   struct YourApp: App {
     init() {
       FirebaseApp.configure()
     }
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
   

Etapa 4: ativar e proteger os serviços do Firebase

Agora que seu app está configurado para usar o Firebase, é necessário ativar o Firebase AI Logic serviço e proteger o acesso às APIs associadas usando Firebase App Check.

Etapa 4a: configurar Firebase AI Logic no seu projeto do Firebase

1. No console do Firebase, acesse Serviços de IA > Lógica de IA.

2. Clique em Começar para iniciar o fluxo de trabalho de configuração guiada.

3. Quando solicitado a escolher um "provedor da API Gemini", recomendamos selecionar a API Gemini Developer, que permite começar rapidamente sem custo financeiro.

   Você pode configurar a Vertex AI Gemini API (e o requisito de faturamento) a qualquer momento.

4. Continue no fluxo de trabalho para configurar as APIs necessárias e os serviços associados para Firebase AI Logic.

   A partir do início de julho de 2026, essa etapa do fluxo de trabalho vai aplicar automaticamente o Firebase App Check para AI Logic, que é um serviço essencial para ajudar a proteger a Gemini API quando ela é acessada diretamente do seu app. Como parte da introdução (consulte as etapas mais adiante neste guia), será necessário configurar o App Check provedor de depuração para desenvolvimento local quando o App Check for aplicado.

   **Observação**: Para lançar o recurso de IA do seu app para usuários finais, é necessário registrar o app com um provedor de atestação App Check de produção para que ele possa usar o recurso quando App Check for aplicado.

Etapa 4b: configurar o provedor de depuração App Check para desenvolvimento local

Para o desenvolvimento local, é necessário configurar o App Check provedor de depuração para ignorar a atestação, mantendo a aplicação de App Check.

1. No seu projeto Xcode, importe FirebaseAppCheck e inicialize App Check com a fábrica do provedor de depuração antes de configurar Firebase.

   import SwiftUI
   import FirebaseCore
   import FirebaseAppCheck
   
   @main
   struct YourApp: App {
     init() {
       let providerFactory = AppCheckDebugProviderFactory()
       AppCheck.setAppCheckProviderFactory(providerFactory)
       FirebaseApp.configure()
     }
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
   

2. Receba o token de depuração:

   1. Inicie o app no simulador ou no dispositivo de teste.

   2. Abra o console do Xcode e procure o App Check token de depuração. Exemplo:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.
      

   3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

3. Registre o token de depuração com App Check:

   1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

   2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

   3. Siga as instruções na tela para registrar o token de depuração.

Para mais detalhes sobre o provedor de depuração (incluindo como receber um novo token de depuração), consulte a documentação App Check oficial.

Confira alguns pontos importantes sobre o App Check provedor de depuração:

• Mantenha o token de depuração e o build de depuração privados. Não confirme o token de depuração em um repositório público e não envie o token de depuração ou o build de depuração em builds de produção do seu app.
• Registre seu app com um provedor de atestação de produção antes de lançar para usuários finais. Será necessário registrar seu app com um provedor de atestação de produção (por exemplo, App Attest, Play Integrity ou reCAPTCHA Enterprise).App Check Assim, os usuários finais poderão usar o recurso com App Check aplicado.

Etapa 5: inicializar o serviço AI Logic no seu app

Clique no seu provedor Gemini API para conferir o conteúdo específico do provedor e o código nesta página. API Gemini Developer API Gemini da Vertex AI

Com o Firebase e App Check configurados, agora você pode inicializar o Firebase AI Logic serviço no seu app.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.5-flash")

Etapa 6: enviar uma solicitação a um modelo Gemini

Com Firebase AI Logic configurado, protegido e inicializado no seu app, você está pronto para enviar uma solicitação a um modelo Gemini.

O exemplo a seguir mostra o tipo mais básico de solicitação: gerar texto a partir de um comando somente de texto:

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.5-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

Gemini modelos também oferecem suporte a outros tipos de solicitações, como analisar imagens e PDFs , gerar saída JSON estruturada , e gerar imagens (usando modelos "Nano Banana"). Confira exemplos desses tipos de solicitações na documentação ou no app de exemplo.

Transmitir a resposta

É possível conseguir interações mais rápidas sem esperar o resultado completo da geração do modelo. Em vez disso, use o streaming para processar resultados parciais. Para transmitir a resposta, use streamResponse(to:) em vez de respond(to:).

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.5-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

Próximas etapas

• Conheça os recursos disponíveis ao acessar a Gemini API pelo framework Foundation Models da Apple.
• Saiba como configurar o modelo para controlar as respostas, incluindo a definição de um nível de pensamento ("raciocínio").
• Saiba como fornecer ferramentas ao modelo, incluindo a base para informações atualizadas.
• Saiba mais sobre Firebase App Check e como ele protege seus recursos.

Enviar feedback sobre o acesso à Gemini API pelo framework Foundation Models da Apple