API Prompt

Thomas Steiner

Alexandra Klepper

Publicado em: 20 de maio de 2025, última atualização: 21 de julho 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. 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 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

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(). Se a resposta a availability() for downloadable, aguarde o progresso do download e informe o usuário, já que o download pode levar tempo.

const availability = await LanguageModel.availability();

Para acionar o download e instanciar o modelo de linguagem, verifique a ativação do usuário. Em seguida, chame a função assíncrona LanguageModel.create().

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

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 top-K padrão.
• maxTopK: o valor máximo de top-K.
• defaultTemperature: a temperatura padrão.
• maxTemperature: a temperatura máxima.

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

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,
});

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 uma função "assistant", além das 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 pedir uma nova resposta, talvez você queira preencher previamente parte da mensagem de resposta da função "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 com a função "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,
  },
]);

Anexar mensagens

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

Embora initialPrompts seja útil na criação de sessões, o método append() pode ser usado junto com os métodos prompt() ou promptStreaming() para fornecer mais solicitações contextuais depois que a sessão é criada.

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.

Persistência e limites 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);

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.inputUsage}/${session.inputQuota}`);

Transmitir um esquema JSON

Adicione o campo responseConstraint ao método prompt() ou promptStreaming() para transmitir um esquema JSON como valor. Depois, 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 cota de entrada. Para medir quanto da cota de entrada será usado, transmita a opção responseConstraint para session.measureInputUsage().

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

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 pedir

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 choosing between a t-shirt
  and a polo."
);

Recursos multimodais

O teste de origem da API Prompt aceita entradas de áudio e imagem. 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' } only required when including expected input languages.
  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 an 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 },
    ],
  },
]);

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 Prompt 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.

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

Por padrão, a API Prompt está disponível apenas 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 allow="" da política de permissões:

<!--
  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 e verificar o status da política de permissões.

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.

• 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 Programa de prévia antecipada.