API Prompt

Thomas Steiner

Alexandra Klepper

Publicado em 20 de maio de 2025, última atualização em 21 de setembro de 2025

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

Com a API Prompt, você pode enviar solicitações de linguagem natural para Gemini Nano no navegador.

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 artigos com categorias e permita que os usuários filtrem esse conteúdo.
• Filtros de conteúdo personalizados. Analise artigos de notícias e desfoque ou oculte automaticamente o conteúdo com base em temas definidos pelo usuário.
• Criação de eventos da agenda. Desenvolva uma extensão do Chrome que extraia automaticamente os detalhes do evento de páginas da Web para que os usuários possam criar entradas de agenda em apenas algumas etapas.
• Extração de contatos integrada. 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 queremos 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. Antes de usar essa API, reconheça a Política de uso proibido da IA generativa do Google.

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 a ativação do usuário. Em seguida, chame a create() função.

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

Se a resposta a availability() foi downloading, detecte o progresso do download e informe o usuário, já que o download pode levar algum tempo.

Usar no localhost

Todas as APIs de IA integradas estão disponíveis no localhost no Chrome. Defina as seguintes flags como Ativadas:

• chrome://flags/#optimization-guide-on-device-model
• chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

Em seguida, clique em Reiniciar ou reinicie o Chrome. Se você encontrar erros, resolva problemas no localhost.

Parâmetros do modelo

A função params() informa os parâmetros do modelo de linguagem. O objeto tem os seguintes campos:

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

// Only available when using the Prompt API for Chrome Extensions.
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

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();

Criar uma sessão com a API Prompt para extensões do Chrome

Ao usar a API Prompt para extensões do Chrome, cada sessão pode ser personalizada com topK e temperature usando um objeto de opções opcionais. Os valores padrão desses parâmetros são retornados de LanguageModel.params().

// Only available when using the Prompt API for Chrome Extensions.
const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
// Only available when using the Prompt API for Chrome Extensions.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.max(params.defaultTemperature * 1.2, 2.0),
  topK: params.defaultTopK,
});

O objeto de opções opcionais da função create() também 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,
});

Adicionar contexto com comandos iniciais

Com os comandos iniciais, você pode fornecer ao modelo de linguagem contexto sobre interações anteriores, por exemplo, para permitir que o usuário retome uma sessão armazenada após a 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

Você pode adicionar um papel "assistant", além de papéis anteriores, para elaborar as respostas anteriores do modelo. Por 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 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". Por 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 oferece suporte a vários idiomas. Defina as modalidades e os idiomas 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" e "es". O suporte a outros idiomas está em desenvolvimento.
  • Para expectedInputs, defina o idioma do comando do sistema e um ou mais idiomas de comando do usuário esperados.
  • Defina um ou mais idiomas 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 "NotSupportedError" DOMException se o modelo encontrar uma entrada ou saída não compatí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 uso 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 da tela demo para usar a API Prompt com entrada de imagem.

A API Prompt oferece suporte aos seguintes tipos de entrada:

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

Este snippet mostra uma sessão multimodal que primeiro processa dois elementos visuais (uma imagem Blob e um HTMLCanvasElement) e faz com que a IA os compare. Em segundo lugar, ele 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, principalmente ao solicitar com entradas multimodais. Pode ser útil enviar comandos predeterminados com antecedência para preencher a sessão, para que o modelo possa começar a processar.

Embora initialPrompts seja útil na criação de sessões, o método append() pode ser usado além dos métodos prompt() ou promptStreaming() para fornecer comandos contextuais adicionais após a criação da sessão.

Por 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 é 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 valor. Em seguida, você pode usar 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. Você pode medir quanto da janela de contexto ela vai usar transmitindo a opção responseConstraint para session.measureContextUsage().

Você pode evitar esse comportamento com a opção omitResponseConstraintInput. Se você fizer isso, recomendamos que inclua 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 });

Solicitar o modelo

Você pode solicitar o modelo com as funções prompt() ou promptStreaming().

Saída baseada em solicitações

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 transmitida

Se você espera uma resposta mais longa, use a função promptStreaming(), que permite mostrar resultados parciais à medida que eles chegam 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 solicitar

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 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. Confira 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 comandos e respostas por vez, até que tokens suficientes estejam disponíveis para processar o novo comando. A exceção é o comando do sistema, que nunca é removido.

Esses estouros podem ser detectados detectando 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 a entrada consiste
• contextWindow: quantos tokens estavam disponíveis

Saiba mais sobre o gerenciamento de sessões.

Clonar uma sessão

Para preservar recursos, você pode copiar uma sessão existente com a função clone(). Isso cria um fork da conversa, em que o contexto e o comando inicial são preservados.

A função clone() usa um objeto de opções opcionais 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. Talvez você queira manter a sessão se pretende solicitar o 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 explorar os muitos casos de uso da API Prompt. As demonstrações a seguir são aplicativos da Web:

• Playground da API Prompt
• Comando de áudio do Mediarecorder
• Comando de imagem da tela

Para testar a API Prompt em 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á em desenvolvimento. Enquanto criamos essa API, consulte nossas práticas recomendadas sobre gerenciamento de sessões para uma performance ideal.

Política de permissões, iframes e Web Workers

Por padrão, a API Prompt só está disponível para janelas de nível superior e para os iframes de mesma origem. O acesso à API pode ser delegado a iframes de origem cruzada usando o atributo da Política de permissões allow="":

<!--
  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>

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

Participe e compartilhe feedback

Sua entrada pode afetar diretamente a forma como criamos e implementamos versões futuras de essa API e todas as APIs de IA integradas.

• Para feedback sobre a implementação do Chrome, registre um relatório de bugs ou uma solicitação de recurso.
• Compartilhe seu feedback sobre o formato da API comentando um problema existente ou abrindo um novo no repositório da API Prompt no GitHub.
• Participe do programa de testes.