AI API

The AI.* group lets a script call your world's configured AI directly — send a prompt to the language model and get its reply, or generate an image from a prompt and get its URL. These are raw, one-shot provider calls: no NPC persona, no memory, no tools. They work from any NexusScript — the object does not have to be an NPC.

Everything routes through the provider you registered off-world, so there are no keys in your script. You set that up once in the Provider Manager — see Providers & keys.

These run on the game server

The provider and its API key live on the server (they never ship in your world bundle), so AI.* calls execute there. Run them from server-side logic — an NPC action/callback (which already runs on the server) or a server script. Called where no provider is available, they return an error string (e.g. Error: No text provider) rather than a reply.

Each call blocks until the model answers

AI.Chat, AI.ChatWithSystem, and AI.GenerateImage are synchronous — the script waits for the model, which can take a second or more (image generation, longer). Call them on purpose — in response to an action or event — never every frame in Update. Each call also bills your provider account.

Chat — one prompt, one reply

AI.Chat(message) sends a single user message to the world's text (LLM) provider and returns the model's reply as a string:

string reply = AI.Chat("In one word, is 'I love it here' positive or negative?");
NPC.Say(reply);       // -> "Positive"

Use it for the small, scripted jobs a language model is good at — classify a line of text, summarize, translate, or make a piece of flavor text — where you don't need a full conversational NPC.

There's no separate success flag: on failure the call returns an error string (often beginning Error:) in place of a reply. Check for it when a failure would matter:

string reply = AI.Chat(prompt);
if (reply.StartsWith("Error")) reply = "…the oracle is silent.";   // fallback
NPC.Say(reply);

Steer the reply with a system prompt

AI.ChatWithSystem(systemPrompt, message) is the same one-shot call, but you set a system prompt first — a standing instruction that fixes the model's role, tone, or output format before it sees the user message:

string system = "You are a terse medieval town crier. Reply in ONE short sentence, in character.";
string line   = AI.ChatWithSystem(system, "Announce that the market opens at dawn.");
NPC.Say(line);        // -> "Hear ye! The market throws wide its gates at first light!"

The system prompt is where you pin down format ("reply with only a number", "answer in JSON") or persona for a one-off call. To weave in who's talking, build the message from context you already hold — see Player.GetSpeakerId:

string who  = Player.GetName(Player.GetSpeakerId());
string line = AI.ChatWithSystem("You are a friendly shopkeeper. One sentence.",
                                "Greet " + who + " as they walk in.");

Generate an image

AI.GenerateImage(prompt) generates an image with the world's image provider and returns the finished image's URL as a string (or an error string on failure):

string url = AI.GenerateImage("a watercolor fox on a plain white background");
Debug.Log(url);       // the provider's image URL, or a string starting with "Error:"

This is the low-level call — it hands you a URL and nothing else. To actually show a generated image in your world, use AI.GenerateImageOnto instead: it downloads the image, streams it to every player, and paints it onto a surface (or into a gallery feed) for you. That whole flow — surfaces, feeds, reading the texture back — is covered on AI images. Reach for AI.GenerateImage only when you want the raw URL itself — to hand to a backend over HTTP, log it, or store it.

An optional aspect ratio is accepted

The current runtime also accepts an optional aspect ratio as a second argument — AI.GenerateImage(prompt, "16:9") — defaulting to 1:1, the same ratios AI.GenerateImageOnto takes (1:1, 16:9, 9:16, 4:3, 3:4). The published signature is AI.GenerateImage(prompt); treat the ratio argument as a bonus and confirm it in-world if you depend on it.

Raw AI vs. an NPC's own brain

AI.* is a bare provider call — the model sees only the prompt you pass, with none of an NPC's personality, knowledge, or registered actions. When you want an NPC to reason in character, using everything it knows, use NPC.Think(prompt) (or just let the NPC converse) — see NPC & Self API. Rule of thumb:

You want…	Use
a one-off completion with no persona (classify, summarize, translate, flavor text)	AI.Chat / AI.ChatWithSystem
the NPC to reason with its personality + knowledge + tools	NPC.Think (NPC & Self API)
to generate + display an image on a surface or feed	AI.GenerateImageOnto (AI images)

Quick reference

Call	Returns	What it does
AI.Chat(message)	string	send one user message to the world's LLM; returns its reply (or an error string)
AI.ChatWithSystem(systemPrompt, message)	string	same, but systemPrompt sets the model's role/tone/format up front
AI.GenerateImage(prompt)	string	generate an image with the world's image provider; returns the image URL (or an error string)

Related pages

Painting a generated image onto a surface or feed → AI images. Configuring the text/voice/image providers and keys → Providers & keys. An NPC's spoken voice → AI NPCs › Voice. Persona-aware reasoning → NPC & Self API.