API Prompt

Thomas Steiner

Alexandra Klepper

Publicado em: 20 de maio de 2025, última atualização: 21 de outubro de 2026

Explicação	Web	Extensões	Status do Chrome	Intenção
GitHub	Chrome 148	Chrome 138	Ver	Intent to Ship
GitHub	Teste de origem para parâmetros de amostragem	Chrome 148	Ver	Intent to Experiment

Com a API Prompt, é possível enviar solicitações em linguagem natural para o modelo de fundação no Chrome.

Há muitas maneiras de usar a API Prompt. Por exemplo, você pode criar:

• Pesquisa com tecnologia de IA: responda a perguntas com base no conteúdo de uma página da Web.
• Feeds de notícias personalizados: crie um feed que classifique dinamicamente os artigos com categorias e permita que os usuários filtrem esse conteúdo.
• Filtros de conteúdo personalizados. Analisar notícias e desfocar ou ocultar automaticamente o conteúdo com base em temas definidos pelo usuário.
• Criação de eventos da agenda. Desenvolver uma extensão do Chrome que extraia automaticamente detalhes de eventos de páginas da Web para que os usuários possam criar itens da agenda em poucas etapas.
• Extração de contatos sem complicações. Crie uma extensão que extraia informações de contato de sites, facilitando o contato dos usuários com uma empresa ou a adição de detalhes à lista de contatos.

Essas são apenas algumas possibilidades, e estamos ansiosos para ver o que você vai criar.

Usar a API Prompt

A API Prompt usa o modelo Gemini Nano no Chrome. Embora a API seja integrada ao Chrome, o modelo é baixado separadamente na primeira vez que uma origem usa a API.

Para determinar se o modelo está pronto para uso, chame LanguageModel.availability().

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});

Para acionar o download e instanciar o modelo de linguagem, verifique se há atividade do usuário. Em seguida, chame a função create().

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

Se a resposta para availability() foi downloading, acompanhe o progresso do download e informe o usuário, já que o download pode demorar.

Criar uma sessão

Depois que a API Prompt puder ser executada, crie uma sessão com a função create().

const session = await LanguageModel.create();

O objeto de opções opcional da função create() usa um campo signal, que permite transmitir um AbortSignal para destruir a sessão.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const session = await LanguageModel.create({
  signal: controller.signal,
});

Parâmetros de amostragem

Ao controlar a amostragem, é possível ajustar o nível de previsibilidade (determinismo) ou criatividade (variabilidade) das respostas do modelo. A disponibilidade dos parâmetros de amostragem é diferente entre a plataforma da Web e as extensões do Chrome:

• Web: use a opção samplingMode, que usa valores de tipo enumerado descritivos em vez de números brutos para ajustar a previsibilidade da saída.
• Extensões do Chrome: parâmetros numéricos legados (topK, temperature) e o método LanguageModel.params() são aceitos.

Modo de amostragem da Web

Transmita a opção samplingMode para LanguageModel.create() (ou LanguageModel.availability()).

Os valores de tipo enumerado samplingMode aceitos são:

• "most-predictable": maior determinismo e previsibilidade.
• "predictable": saída mais previsível com variação mínima.
• "slightly-predictable": saída um pouco previsível.
• "balanced": um equilíbrio entre previsibilidade e criatividade (comportamento padrão típico).
• "slightly-creative": saída um pouco variada e criativa.
• "creative": saída criativa e variada.
• "most-creative": variabilidade e criatividade máximas.

// Available on the web with the Sampling Parameters Origin Trial enabled
const session = await LanguageModel.create({
  samplingMode: 'creative',
});

// The configured sampling mode is exposed on the session instance
console.log(session.samplingMode);
// "creative"

Parâmetros de amostragem para extensões do Chrome

Ao usar a API Prompt nas extensões do Chrome, cada sessão ainda pode ser personalizada com topK e temperature usando o objeto de opções.

A função estática LanguageModel.params() informa os limites de parâmetros padrão e máximo do modelo de linguagem:

• defaultTopK: o valor padrão de top-K.
• maxTopK: o valor máximo de top-K.
• defaultTemperature: a temperatura padrão.
• maxTemperature: a temperatura máxima.

// Only available in Chrome Extensions
const params = await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

// Initializing a new session in extensions must either specify both `topK` and
// `temperature` or neither of them.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.min(params.defaultTemperature * 1.2, params.maxTemperature),
  topK: params.defaultTopK,
});

console.log(slightlyHighTemperatureSession.temperature);
console.log(slightlyHighTemperatureSession.topK);

Adicionar contexto com comandos iniciais

Com os comandos iniciais, você pode fornecer ao modelo de linguagem o contexto sobre interações anteriores, por exemplo, para permitir que o usuário retome uma sessão armazenada após uma reinicialização do navegador.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    {
      role: 'assistant',
      content: 'The official language of Italy is Italian. [...]',
    },
  ],
});

Restringir respostas com um prefixo

É possível adicionar um papel "assistant", além dos papéis anteriores, para elaborar as respostas anteriores do modelo. Exemplo:

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant",
    content: "Presentations are tough!"
  }
]);

Em alguns casos, em vez de solicitar uma nova resposta, talvez você queira preencher previamente parte da mensagem de resposta do papel "assistant". Isso pode ser útil para orientar o modelo de linguagem a usar um formato de resposta específico. Para fazer isso, adicione prefix: true à mensagem final do papel "assistant". Exemplo:

const characterSheet = await session.prompt([
  {
    role: 'user',
    content: 'Create a TOML character sheet for a gnome barbarian',
  },
  {
    role: 'assistant',
    content: '```toml\n',
    prefix: true,
  },
]);

Adicionar entrada e saída esperadas

A API Prompt tem recursos multimodais e é compatível com vários idiomas. Defina as modalidades e os idiomas de expectedInputs e expectedOutputs ao criar sua sessão.

• type: modalidade esperada.
  • Para expectedInputs, pode ser text, image ou audio.
  • Para expectedOutputs, a API Prompt permite apenas text.
• languages: matriz para definir o idioma ou os idiomas esperados. A API Prompt aceita "en", "ja", "es", "de" e "fr". O suporte para outros idiomas está em desenvolvimento.
  • Para expectedInputs, defina o idioma do comando do sistema e um ou mais idiomas esperados para o comando do usuário.
  • Defina um ou mais idiomas de expectedOutputs.

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

Você pode receber uma DOMException "NotSupportedError" se o modelo encontrar uma entrada ou saída incompatível.

Recursos multimodais

Com esses recursos, você pode:

• Permitir que os usuários transcrevam mensagens de áudio enviadas em um aplicativo de chat.
• Descreva uma imagem enviada ao seu site para usar em uma legenda ou texto alternativo.

Confira a demonstração do comando de áudio do Mediarecorder para usar a API Prompt com entrada de áudio e a demonstração do comando de imagem do Canvas para usar a API Prompt com entrada de imagem.

A API Prompt é compatível com os seguintes tipos de entrada:

• Áudio:
  • AudioBuffer
  • ArrayBufferView
  • ArrayBuffer
  • Blob
• Visual:
  • HTMLImageElement
  • SVGImageElement
  • HTMLVideoElement (usa o frame do vídeo na posição atual)
  • HTMLCanvasElement
  • ImageBitmap
  • OffscreenCanvas
  • VideoFrame
  • Blob
  • ImageData

Este snippet mostra uma sessão multimodal que primeiro processa dois recursos visuais (uma imagem Blob e um HTMLCanvasElement) e faz com que a IA os compare. Em seguida, permite que o usuário responda com uma gravação de áudio (como um AudioBuffer).

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en"] },
    { type: "audio" },
    { type: "image" },
  ],
  expectedOutputs: [{ type: "text", languages: ["en"] }],
});

const referenceImage = await (await fetch("reference-image.jpeg")).blob();
const userDrawnImage = document.querySelector("canvas");

const response1 = await session.prompt([
  {
    role: "user",
    content: [
      {
        type: "text",
        value:
          "Give a helpful artistic critique of how well the second image matches the first:",
      },
      { type: "image", value: referenceImage },
      { type: "image", value: userDrawnImage },
    ],
  },
]);
console.log(response1);

const audioBuffer = await captureMicrophoneInput({ seconds: 10 });

const response2 = await session.prompt([
  {
    role: "user",
    content: [
      { type: "text", value: "My response to your critique:" },
      { type: "audio", value: audioBuffer },
    ],
  },
]);
console.log(response2);

Anexar mensagens

A inferência pode levar algum tempo, especialmente ao usar entradas multimodais. Pode ser útil enviar comandos predeterminados com antecedência para preencher a sessão, assim o modelo pode começar o processamento.

Embora os initialPrompts sejam úteis na criação da sessão, o método append() pode ser usado além dos métodos prompt() ou promptStreaming() para fornecer mais comandos contextuais após a criação da sessão.

Exemplo:

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

fileUpload.onchange = async () => {
  await session.append([
    {
      role: 'user',
      content: [
        {
          type: 'text',
          value: `Here's one image. Notes: ${fileNotesInput.value}`,
        },
        { type: 'image', value: fileUpload.files[0] },
      ],
    },
  ]);
};

analyzeButton.onclick = async (e) => {
  analysisResult.textContent = await session.prompt(userQuestionInput.value);
};

A promessa retornada por append() é cumprida quando o comando é validado, processado e anexado à sessão. A promessa será rejeitada se o comando não puder ser anexado.

Transmitir um esquema JSON

Adicione o campo responseConstraint ao método prompt() ou promptStreaming() para transmitir um esquema JSON como o valor. Em seguida, use a saída estruturada com a API Prompt.

No exemplo a seguir, o esquema JSON garante que o modelo responda com true ou false para classificar se uma determinada mensagem é sobre cerâmica.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended, but that
happens with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(
  `Is this post about pottery?\n\n${post}`,
  {
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

Sua implementação pode incluir um esquema JSON ou uma expressão regular como parte da mensagem enviada ao modelo. Isso usa parte da janela de contexto. É possível medir quanto da janela de contexto será usada transmitindo a opção responseConstraint para session.measureContextUsage().

Para evitar esse comportamento, use a opção omitResponseConstraintInput. Se você fizer isso, recomendamos incluir algumas orientações no comando:

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { responseConstraint: schema, omitResponseConstraintInput: true });

Enviar um comando ao modelo

É possível enviar comandos ao modelo com as funções prompt() ou promptStreaming().

Saída baseada em solicitação

Se você espera um resultado curto, use a função prompt(), que retorna a resposta assim que ela estiver disponível.

// Start by checking if it's possible to create a session based on the
// availability of the model, and the characteristics of the device.
const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});

if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and wait for the whole result to come back.
  const result = await session.prompt('Write me a poem!');
  console.log(result);
}

Saída de streaming

Se você espera uma resposta mais longa, use a função promptStreaming(), que permite mostrar resultados parciais à medida que eles são recebidos do modelo. A função promptStreaming() retorna um ReadableStream.

const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and stream the result:
  const stream = session.promptStreaming('Write me an extra-long poem!');
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

Parar de usar comandos

Tanto prompt() quanto promptStreaming() aceitam um segundo parâmetro opcional com um campo signal, que permite interromper a execução de comandos.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

Gerenciamento de sessões

Cada sessão acompanha o contexto da conversa. As interações anteriores são consideradas para as interações futuras até que a janela de contexto da sessão esteja cheia.

Cada sessão tem um número máximo de tokens que pode processar. Verifique seu progresso em relação a esse limite com o seguinte:

console.log(`${session.contextUsage}/${session.contextWindow}`);

É possível enviar um comando que cause o estouro da janela de contexto. Nesses casos, as partes iniciais da conversa com o modelo de linguagem serão removidas, um par de comando e resposta por vez, até que haja tokens suficientes para processar o novo comando. A exceção é o comando do sistema, que nunca é removido.

Esses estouros podem ser detectados ao detectar o evento contextoverflow na sessão:

session.addEventListener("contextoverflow", () => {
  console.log("We've gone past the context window, and some inputs will be dropped!");
});

Se não for possível remover tokens suficientes do histórico de conversas para processar o novo comando, a chamada prompt() ou promptStreaming() vai falhar com uma exceção QuotaExceededError e nada será removido. O QuotaExceededError tem as seguintes propriedades:

• requested: quantos tokens compõem a entrada
• contextWindow: quantos tokens estavam disponíveis.

Saiba mais sobre o gerenciamento de sessões.

Clonar uma sessão

Para preservar recursos, copie uma sessão atual com a função clone(). Isso cria uma bifurcação da conversa, em que o contexto e o comando inicial são preservados.

A função clone() usa um objeto de opções opcional com um campo signal, que permite transmitir um AbortSignal para destruir a sessão clonada.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const clonedSession = await session.clone({
  signal: controller.signal,
});

Encerrar uma sessão

Chame destroy() para liberar recursos se você não precisar mais de uma sessão. Quando uma sessão é destruída, ela não pode mais ser usada, e qualquer execução em andamento é interrompida. É recomendável manter a sessão se você pretende enviar comandos ao modelo com frequência, já que a criação de uma sessão pode levar algum tempo.

await session.prompt(
  "You are a friendly, helpful assistant specialized in clothing choices."
);

session.destroy();

// The promise is rejected with an error explaining that
// the session is destroyed.
await session.prompt(
  "What should I wear today? It is sunny, and I am choosing between a t-shirt
  and a polo."
);

Demonstrações

Criamos várias demonstrações para mostrar os diversos casos de uso da API Prompt. As seguintes demonstrações são aplicativos da Web:

• Playground da API Prompt
• Comando de áudio do MediaRecorder
• Comando de imagem do Canvas

Para testar a API Prompt nas extensões do Chrome, instale a extensão de demonstração. O código-fonte da extensão está disponível no GitHub.

Estratégia de performance

A API Prompt para a Web ainda está sendo desenvolvida. Enquanto criamos essa API, consulte nossas práticas recomendadas sobre gerenciamento de sessões para otimizar o desempenho.

Política de permissões, iframes e workers da Web

Por padrão, a API Prompt está disponível apenas para janelas de nível superior e os iframes de mesma origem delas. O acesso à API pode ser delegado a iframes entre origens usando o atributo allow="" da política de permissão:

<!--
  The hosting site at https://main.example.com can grant a cross-origin iframe
  at https://cross-origin.example.com/ access to the Prompt API by
  setting the `allow="language-model"` attribute.
-->
<iframe src="https://cross-origin.example.com/" allow="language-model"></iframe>

No momento, a API Prompt não está disponível em Web Workers devido à complexidade de estabelecer um documento responsável para cada worker para verificar o status da política de permissões.

Participar e compartilhar feedback

Sua opinião pode influenciar diretamente como criamos e implementamos versões futuras desta API e de todas as APIs de IA integradas.

• Para enviar feedback sobre a implementação do Chrome, registre um relatório de bug ou uma solicitação de recurso.
• Compartilhe seu feedback sobre o formato da API comentando em um problema atual ou abrindo um novo no repositório do GitHub da API Prompt.
• Participe do programa de pré-lançamento.