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 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 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 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, a versão Beta do iOS 27).

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

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.6-flash (e o gemini-3.5-flash mais antigo)
    • gemini-3.5-flash-lite (e o gemini-3.1-flash-lite mais antigo)

  • 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. 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 Baixar GoogleService-Info.plist para receber o arquivo de configuração.

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

    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 de 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 do app aberto, selecione Arquivo > Adicionar pacotes.

    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 Adicionar pacote. O Xcode vai resolver e fazer o download das dependências.

    5. Quando solicitado, adicione as bibliotecas FirebaseAILogic e FirebaseAppCheck ao destino 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 Firebase AI Logic serviço e proteger o acesso às APIs associadas usando Firebase App Check.

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

  1. No console 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 que você escolha um "provedor da API Gemini", recomendamos selecionar a API Gemini Developer, que permite começar rapidamente sem custo financeiro.

    Mais tarde, você sempre poderá configurar Agent Platform Gemini API (formerly Vertex AI) (e o requisito de faturamento).

  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), você precisará configurar o App Check provedor de depuração para desenvolvimento local quando o 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 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 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 Firebase console, 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.

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

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

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.6-flash")

Etapa 6: enviar uma solicitação para 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.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)

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"). Consulte 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.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 pelo framework Foundation Models da Apple