LanguageModel: create() static method

Syntax

LanguageModel.create()
LanguageModel.create(options)

Parameters

options Optional

An object representing the options for creating a LanguageModel session. Properties include:

expectedInputs

An array of objects representing the required input modalities and languages. Each object can include the following properties:

type

An enumerated value indicating the content type. Must be one of:

text

Plain text content.

image

Image content.

audio

Audio content.

tool-call

A tool invocation issued by the model.

tool-response

The result of a tool invocation.

languages Optional

An array of strings containing BCP 47 language tags (for example, en, fr, ja) that the session is expected to handle for this content type. The user agent uses this list to determine whether the model supports the specified languages and to select appropriate model components or fine-tunings.

expectedOutputs

An array of objects representing the required output modalities and languages. Each object can include the following properties:

type

An enumerated value indicating the content type. Must be one of:

text

Plain text content.

image

Image content.

audio

Audio content.

tool-call

A tool invocation issued by the model.

tool-response

The result of a tool invocation.

languages Optional

An array of strings containing BCP 47 language tags (for example, en, fr, ja) that the session is expected to handle for this content type. The user agent uses this list to determine whether the model supports the specified languages and to select appropriate model components or fine-tunings.

initialPrompts

An array of objects representing messages passed during the creation of a language model session. This allows the model to "remember" instructions or previous dialogue without resending them with every new query. Each object can include the following properties:

role

A string indicating the point of view the message is phrased from. Must be one of:

system

A system-level instruction that guides the model's overall behavior. This must be the first instruction passed to the model.

user

A message from the user, which the API should respond to.

assistant

An input that provides context for the AI assistant, such as its persona or the format of its responses. Such messages mainly serve to provide context/history, and further shape how the model responds.

content

A string representing a textual prompt, or an array of objects. Each object includes the following properties:

type

An enumerated value representing the type of content. This can be one of:

audio

Audio content.

image

Image content.

text

Textual content.

tool-call

A tool invocation issued by the model.

tool-response

The result of a tool invocation.

value

The content of the message. If the type is text, this is always a string. If the type is audio or image, the value can be one of several different object types; see What data types are accepted?.

prefix Optional

A boolean, defaulting to false. When true, the message is treated as a prefix for the model's next generated response rather than a complete turn.

monitor

A reference to a CreateMonitor callback function to receive download progress events.

signal

An AbortSignal to cancel session creation.

tools

An array of objects representing tools available to the AI. Each object can include the following properties:

name

A string giving the tool a unique name the model uses to refer to it when issuing a tool call.

description

A string describing what the tool does. The model uses this description to decide if and when to invoke the tool.

inputSchema

A JSON Schema that describes the tool's input parameters. The model uses this schema to construct the arguments it passes to the tool's execute function.

execute

A callback function that the user agent invokes when the model calls this tool. Its arguments are specific to the model being used. It must return a Promise that resolves with a String representing the tool's result.

Return value

A Promise that resolves with a new LanguageModel instance.

Exceptions

AbortError DOMException

Thrown if the operation was aborted via the signal option.

InvalidStateError DOMException

Thrown if the calling document is not fully active.

NotAllowedError DOMException

Thrown if usage of the method is blocked by a language-model Permissions-Policy.

NotSupportedError DOMException

Thrown if:

• A message's role is assistant and its type is anything other than text.
• A message's type is text and its value is not a string.
• The input or output text is in a language the user agent doesn't support for prompting.
• A message's type is image or audio but the type was not listed in expectedInputs, or the value is not an accepted data type.

OperationError DOMException

Thrown if creation fails for any other reason not listed in the other exception types.

QuotaExceededError DOMException

Thrown if the content provided in initialPrompts exceeds the model's LanguageModel.contextWindow.

SyntaxError DOMException

Thrown if:

• No messages are included in the messages array.
• A message's prefix property is set to true and:
  • The message's role is not assistant.
  • The message is not the last item in the messages array.

TypeError DOMException

Thrown if:

• A message's role is system but it was not the first message passed to the context.

Description

The create() method constructs a new language model session, automatically downloading the model if it is not already available. You can monitor progress of a model download using the monitor option.

Before calling create(), use LanguageModel.availability() to check whether the desired configuration is supported.

Once a session is created, use its instance methods — LanguageModel.prompt(), LanguageModel.promptStreaming(), LanguageModel.append(), and others — to interact with the model.

Security

Transient user activation is required. The user has to interact with the page or a UI element for this feature to work.

Examples

Creating a basic session

This example creates a default session and then prompts it for the result of summing 2 and 2. Note that text is supported by default, so the downloaded model should be suitable for this case.

const session = await LanguageModel.create();
const answer = await session.prompt("What is 2 + 2?");
console.log(answer);

See also Using the Prompt API > Creating a LanguageModel session.

Creating a session with a system prompt

The following example provides the AI with instructions on the persona to adopt before generating an answer.

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: "system",
      content: "You are a concise assistant. Respond in one sentence.",
    },
  ],
});

const response = await session.prompt("What is photosynthesis?");
console.log(response);

See also Adding context with initial and ongoing prompt inputs > Providing initial prompts during session creation.

Monitoring download progress

This code shows how you can monitor the download progress of a model. Note that if the model is unavailable or already available, the event will never fire.

const session = await LanguageModel.create({
  monitor(monitor) {
    monitor.addEventListener("downloadprogress", ({ loaded, total }) => {
      console.log(`Model download: ${Math.round((loaded / total) * 100)}%`);
    });
  },
});

See also Using the Prompt API > Monitoring download progress.

Providing few-shot prompts

The following example shows how to use a few-shot prompt to ask the API for a specific task (French translation) to be delivered in a specific format, before providing some examples to help it learn the correct output format.

const session = await LanguageModel.create({
  expectedInputs: [{ type: "text", languages: ["en"] }],
  expectedOutputs: [{ type: "text", languages: ["en", "fr"] }],
  initialPrompts: [
    {
      role: "system",
      content:
        "Translate the user's input to French. Use the output format 'English input: French output'",
    },
    { role: "user", content: "Hello" },
    { role: "assistant", content: "Hello: Bonjour" },
    { role: "user", content: "Goodbye" },
    { role: "assistant", content: "Goodbye: Au revoir" },
    { role: "user", content: "The train is late" },
    {
      role: "assistant",
      content: "The train is late: Le train est en retard",
    },
    { role: "user", content: "My shoes are pink" },
    {
      role: "assistant",
      content: "My shoes are pink: Mes chaussures sont roses",
    },
  ],
});

const result = await session.prompt("Window");
console.log(result); // "Window: Fenêtre"

See also Adding context with initial and ongoing prompt inputs > Few-shot prompts.

Defining a tool with a callback

This example creates a session with a hypothetical "get weather" tool. When the model decides to call the tool, the user agent invokes execute() with the arguments the model provides.

async function getWeatherData(location) {
  const response = await fetch(
    `https://api.example.com/weather?city=${location}`,
  );
  const data = await response.json();
  return `${data.temp}°C, ${data.description}`;
}

const session = await LanguageModel.create({
  tools: [
    {
      name: "getWeather",
      description: "Returns the current weather for a given city.",
      inputSchema: {
        type: "object",
        properties: {
          location: { type: "string", description: "The city name." },
        },
        required: ["location"],
      },
      execute: async (...args) => {
        const location = args[0];
        return await getWeatherData(location);
      },
    },
  ],
});

const response = await session.prompt("What's the weather like in Tokyo?");
console.log(response);

Cancelling a session

The following example enables a user to cancel a prompt. It does this by first creating an AbortController and assigning its abort() method to a cancel button's click handler. Next, it calls create() and passes AbortController.signal as the signal property.

const controller = new AbortController();

const cancelButton = document.getElementById("cancel-button");
cancelButton.addEventListener("click", () => controller.abort());

const session = await LanguageModel.create({
  signal: controller.signal,
  initialPrompts: [
    {
      role: "system",
      content: "You are a helpful assistant.",
    },
  ],
});

See also Using the Prompt API > Cancelling operations and destroying instances.

Specifications

Browser compatibility

See also

• LanguageModel.availability()
• Prompt API
• Using the Prompt API
• Adding context with initial and ongoing prompt inputs