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


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 Gemini) pelo framework Foundation Models usando a mesma API que usaria para acessar modelos no dispositivo.

No app, é possível trocar a instância do modelo para encaminhar as solicitações para a inferência no dispositivo ou na nuvem, de acordo com 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 usando o framework Foundation Models da Apple com o SDK Firebase para plataformas Apple, mais 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 o Firebase App Check, que é fundamental mesmo durante o desenvolvimento.

Pré-requisitos

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

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

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

Modelos de Gemini compatíveis

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

  • Modelos de uso geral

    • gemini-3.1-pro-preview
    • gemini-3.6-flash (e a gemini-3.5-flash mais antiga)
    • gemini-3.5-flash-lite (e a gemini-3.1-flash-lite mais antiga)

  • Modelos de geração de imagens

    • gemini-3-pro-image (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")

Os modelos Gemini Live API e Imagen não são compatíveis. Os modelos Gemini 2.5 são tecnicamente compatíveis, 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 conhecer essa integração.

  1. Faça login no console do Firebase.

  2. Clique em Criar um novo projeto do Firebase.

  3. Siga as instruções na tela. Você não precisa ativar o Google Analytics.

Etapa 2: conectar o app ao Firebase

Para conectar seu app ao Firebase, é necessário registrá-lo no projeto do Firebase e adicionar um arquivo de configuração à sua base de 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 o 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 download GoogleService-Info.plist para receber o arquivo de configuração.

    2. Mova GoogleService-Info.plist para a raiz do seu projeto Xcode e adicione a todos os destinos.

    3. Clique em Próxima no console Firebase.

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

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

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

    1. No Xcode, com seu projeto de 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 Ramificação e insira wwdc26-preview.

    4. Clique em Adicionar pacote. O Xcode vai resolver e baixar as dependências.

    5. Quando solicitado, adicione as bibliotecas FirebaseAILogic e FirebaseAppCheck à meta do app.

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

    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 serviço Firebase AI Logic 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 for solicitado a escolher um "provedor da API Gemini", recomendamos selecionar a API Gemini Developer, que permite começar rapidamente sem custos financeiros.

    A qualquer momento depois, você pode configurar o Vertex AI Gemini API (e o requisito de faturamento dele).

  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 Firebase App Check para AI Logic de forma automática, que é um serviço essencial para proteger o Gemini API quando ele é acessado diretamente do seu app. Como parte do processo de início (consulte as etapas mais adiante neste guia), você precisará configurar o provedor de depuração do App Check para o desenvolvimento local quando o App Check for aplicado.

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

Para desenvolvimento local, é necessário configurar o provedor de depuração do App Check para ignorar o atestado, mas ainda manter a aplicação do App Check.

  1. No projeto do 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 seu token de depuração:

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

    2. Abra o console do Xcode e procure o token de depuração App Check. 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 seu 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 seu token de depuração.

Para detalhes sobre o provedor de depuração, incluindo como conseguir um novo token de depuração, consulte a documentação oficial do App Check.

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

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

Com o Firebase e o App Check configurados, agora você pode inicializar o serviço Firebase AI Logic 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.6-flash")

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

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

O exemplo a seguir mostra o tipo mais básico de solicitação: gerar texto com base em 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.6-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)

Os modelos Gemini também são compatíveis com 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.

Mostrar composição da resposta

Para ter interações mais rápidas, não espere 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.6-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


Envie feedback sobre o acesso ao Gemini API usando a estrutura de modelos básicos da Apple