API Prompt

Thomas Steiner

Alexandra Klepper

Publicado em: 20 de maio de 2025

Explicação	Web	Extensões	Status do Chrome	Intenção
GitHub	Em Teste de origem	Chrome 138	Ver	Intenção de experimentar

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

Há muitas maneiras de usar a API Prompt. Em um aplicativo da Web ou site, é possível 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 artigos dinamicamente com categorias e permita que os usuários filtrem esse conteúdo.

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

Usar a API Prompt

Antes de usar essa API, leia e aceite a Política de uso proibido da IA generativa do Google.

Há duas funções disponíveis no namespace LanguageModel:

• availability() para verificar o que o modelo pode fazer e se ele está disponível.
• create() para iniciar uma sessão de modelo de linguagem.

Download do modelo

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 a função assíncrona LanguageModel.availability(). Isso vai retornar uma das seguintes respostas:

• "unavailable" significa que a implementação não é compatível com as opções solicitadas ou não é compatível com a solicitação de um modelo de linguagem.
• "downloadable" significa que a implementação oferece suporte às opções solicitadas, mas precisa baixar algo (por exemplo, o próprio modelo de linguagem ou um ajuste refinado) antes de criar uma sessão usando essas opções.
• "downloading" significa que a implementação oferece suporte às opções solicitadas, mas precisa concluir uma operação de download em andamento antes de criar uma sessão usando essas opções.
• "available" significa que a implementação oferece suporte às opções solicitadas sem exigir novos downloads.

Para acionar o download do modelo e criar a sessão do modelo de linguagem, chame a função assíncrona LanguageModel.create(). Se a resposta a availability() foi 'downloadable', a prática recomendada é ouvir o progresso do download. Assim, você pode informar o usuário caso o download demore.

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

Recursos de modelo

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

• defaultTopK: o valor padrão top-K (padrão: 3).
• maxTopK: o valor máximo de top-K (8).
• defaultTemperature: a temperatura padrão (1.0). O valor da temperatura precisa estar entre 0.0 e 2.0.
• maxTemperature: a temperatura máxima.

await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 8, 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(). É possível enviar comandos ao modelo com as funções prompt() ou promptStreaming().

Personalizar sua sessão

Cada sessão pode ser personalizada com topK e temperature usando um objeto de opções opcional. Os valores padrão desses parâmetros são retornados de LanguageModel.params().

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

O objeto de opções opcional 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,
})

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. [...]' }
  ]
});

Limites de sessão

Uma determinada sessão de modelo de linguagem tem um número máximo de tokens que pode processar. Para verificar o uso e o progresso em relação a esse limite, use as seguintes propriedades no objeto de sessão:

console.log(`${session.inputUsage}/${session.inputQuota}`);

Persistência da sessão

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

const session = await LanguageModel.create({
  initialPrompts: [{
    role: "system",
    content: "You are a friendly, helpful assistant specialized in clothing choices."
  }]
});

const result1 = await session.prompt(
  "What should I wear today? It is sunny. I am unsure between a t-shirt and a polo."
);
console.log(result1);

const result2 = await session.prompt(
  "That sounds great, but oh no, it is actually going to rain! New advice?"
);
console.log(result2);

Clonar uma sessão

Para preservar recursos, é possível clonar uma sessão atual com a função clone(). O contexto da conversa é redefinido, mas o comando inicial permanece intacto. 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,
});

Comandar o modelo

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

Saída não transmitida

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 {defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();

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 chegam do modelo. A função promptStreaming() retorna um ReadableStream.

const {defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();
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 executar um comando

As funções prompt() e promptStreaming() aceitam um segundo parâmetro opcional com um campo signal, que permite interromper a execução de solicitações.

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

const result = await session.prompt(
  'Write me a poem!',
  { 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 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 unsure between a
  t-shirt and a polo."
);

Recursos multimodais

A API Prompt é compatível com entradas de áudio e imagem do Chrome 138 Canary para testes locais. A API retorna uma saída de texto.

Com esses recursos, é possível:

• Permite 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.

const session = await LanguageModel.create({
  // { type: "text" } is not necessary to include explicitly, unless
  // you also want to include expected input languages for text.
  expectedInputs: [
    { type: "audio" },
    { type: "image" }
  ]
});

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 audioBlob = await captureMicrophoneInput({ seconds: 10 });

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

Demonstrações multimodais

Consulte a demonstração Mediarecorder Audio Prompt (em inglês) para usar a API Prompt com entrada de áudio e a demonstração Canvas Image Prompt (em inglês) para usar a API Prompt com entrada de imagem.

Estratégia de performance

A API de solicitação para a Web ainda está em desenvolvimento. Enquanto criamos essa API, consulte nossas práticas recomendadas sobre gerenciamento de sessões para ter uma performance ideal.

Feedback

Seu feedback ajuda a definir o futuro dessa API e as melhorias do Gemini Nano. Isso pode até resultar em APIs de tarefas dedicadas (como APIs para transcrição de áudio ou descrição de imagens), para que possamos atender às suas necessidades e às necessidades dos seus usuários.

Participe e compartilhe feedback

Sua opinião pode afetar diretamente a forma como criamos e implementamos versões futuras dessa API e de todas as APIs de IA integradas.

• Participe do Programa de prévia antecipada.
• 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 um problema atual ou abrindo um novo no repositório do GitHub da API Prompt.
• Participe do esforço de padrões entrando no Web Incubator Community Group (em inglês).