Foundry VTT

KiteFrost gives your Foundry NPCs a voice: right-click an Actor, type what the players say, and the NPC answers in character in chat. There are three ways to wire it up. Most GMs only need the first; module and macro authors will want the second.

	1. Module - point and click	2. Module - scripting API	3. Direct REST / SDK
Who it’s for	GMs	Macro and module authors	Developers with their own tooling
Setup	Install the module, paste 3 settings	Same as 1	None in Foundry; your own code
Code needed	None	A few lines of JavaScript	Your own HTTP / SDK code
Runs where	Foundry (GM’s browser)	Foundry (GM’s browser)	Dialogue: a Foundry macro. Everything else: Node.js / a server, outside the browser
Reaches	NPC dialogue, issue reports	NPC dialogue, issue reports, a hook on every reply	The whole KiteFrost API (from Node / a server)
Pros	Nothing to write; posts to chat as the NPC; uses the Actor’s sheet for context	Automate: triggers, batch lines, custom UI; same behaviour as the menu	Full API; your own error handling, storage and UI
Cons	Manual, one NPC at a time	Only what the module exposes	You build request bodies and chat output yourself; in a browser only the dialogue endpoints are allowed

Alpha access runs on staging. Use https://api-staging.kitefrost.ai as the API URL until your invite says otherwise. The module is a testing build during the alpha.

Before you start: an API key and your project

Sign in to your KiteFrost dashboard and open your project (or create one: Projects -> New Project).
Copy the project ID from the address bar - the part after /projects/ (for example https://.../projects/my-campaign -> my-campaign).
Open the project’s API Keys page -> New API Key. Choose Secret (sk_) and Full Access, give it a name such as foundry, then Create Key.
Copy the key right away - it is shown only once. Treat it like a password.

The key is stored in your browser only (Foundry’s client setting), never in the world data your players can see. The project’s API Keys page shows when each key was last used - handy to confirm Foundry is really using the key you made.

1. The module, point and click

Foundry v13 or v14, logged in as the Gamemaster.

Install

Foundry setup screen -> Add-on Modules -> Install Module. Paste into Manifest URL:

https://gitlab.com/kitefrost/foundry-vtt-sdk-testing/-/releases/permalink/latest/downloads/module.json

Click Install. It appears as KiteFrost (Testing). Foundry offers each new testing build as a normal module update.

Enable it in your world

Launch your world -> Game Settings (gear icon, right sidebar) -> Manage Modules -> tick KiteFrost (Testing) -> Save Module Settings.

Configure

Game Settings -> Configure Settings -> KiteFrost:

API URL: https://api-staging.kitefrost.ai
API Key: the sk_... key
Project ID: from the address bar (step 2 above)

Save Changes.

Talk to an NPC

Actors tab -> right-click an Actor -> AI: Generate Dialogue. Type what the player says, optionally the situation and tone, and submit. The reply is posted to chat as that NPC, with its mood and suggested follow-ups. Use Report Issue on the message if a reply is off.

Give an NPC a personality. Anything stored on the Actor in the kitefrost.personality flag is sent with every request (run once, as a macro):

await game.actors.getName("Grognard the Innkeeper").setFlag("kitefrost", "personality", {
  personality_traits: "Gruff exterior, secretly kind-hearted",
  motivation: "Protect the village from outsiders",
  secret: "Was once an adventurer before a bad injury",
});

2. The module’s scripting API (macros and modules)

With the module installed and configured as above, everything the menu does is available from code at game.modules.get("kitefrost").api.

const kf = game.modules.get("kitefrost").api;
try {
  const r = await kf.generateDialogue(game.actors.getName("Grognard the Innkeeper"), {
    playerMessage: "Any rooms free tonight?",
    situation: "late evening, the common room is packed", // optional
    tone: "friendly",                                      // optional
  });
  console.log(r.dialogue, r.mood, r.suggested_actions);   // also posted to chat
} catch (e) {
  ui.notifications.error(e.message);                       // bad key, missing setting, ...
}

Member	What it does
`generateDialogue(actorOrId, { playerMessage, situation?, tone?, postToChat? })`	Generates a line (no dialog). Resolves `{ npc_name, dialogue, mood, stage_direction, suggested_actions, message }`; posts to chat unless `postToChat: false` (then `message` is `null`).
`extractActorContext(actorOrId)`	Shows exactly which NPC details are sent for an Actor.
`reportIssue({ category, severity, description, npcName?, dialogue?, mood? })`	Sends an issue report; resolves `{ feedback_id }`.
`version`	The installed module version.

Every call rejects on a problem - wrap it in try / catch. React to every reply - from the menu or the API:

Hooks.on("kitefrost.dialogueGenerated", ({ actor, result, message }) => {
  // e.g. speak it with your TTS module, or log it to a journal
});

Example - a greeting for every selected token:

const kf = game.modules.get("kitefrost").api;
for (const token of canvas.tokens.controlled) {
  await kf.generateDialogue(token.actor, { playerMessage: "The party walks in.", tone: "curious" });
}

3. Direct REST or the KiteFrost SDKs

Skip the module and call the API yourself. From a Foundry macro (browser) - the NPC dialogue endpoint accepts calls from any site, so plain fetch works:

const API = "https://api-staging.kitefrost.ai";
const KEY = "sk_...";          // better: read from a client setting, not the macro text
const PROJECT = "my-campaign";

const res = await fetch(`${API}/v1/projects/${PROJECT}/quick-dialogue`, {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    npc_name: "Old Mara",
    player_message: "What do you know about the ruined tower?",
    tone: "mysterious",
    npc_context: { personality_traits: "cryptic, fond of riddles" },
  }),
});
if (!res.ok) throw new Error(`KiteFrost ${res.status}`);
const { dialogue, mood } = await res.json();
ChatMessage.create({ speaker: { alias: "Old Mara" }, content: `<p><em>[${mood}]</em> ${dialogue}</p>` });

In a browser only the NPC dialogue and issue-report endpoints can be called from another site. Everything else (projects, NPCs, quests, sessions, …) is available from Node.js or a server - a companion script, a bot, or a build step - not from a Foundry page. A macro’s text is visible to anyone who can open it: never paste a key into a macro you share.

From Node.js - the TypeScript SDK (npm install @kitefrost/ttrpg-gm@alpha):

import { TtrpgGmClient } from "@kitefrost/ttrpg-gm";

const kf = new TtrpgGmClient({ apiKey: process.env.KITEFROST_API_KEY, baseUrl: "https://api-staging.kitefrost.ai" });
const r = await kf.ttrpg.quick_dialogue("my-campaign", {
  npc_name: "Old Mara",
  player_message: "What do you know about the ruined tower?",
});
console.log(r.dialogue);

From Python (pip install --pre kitefrost-ttrpg-gm):

from kitefrost_core import KiteFrostCore
from kitefrost_ttrpg_gm import TtrpgGmClient

kf = TtrpgGmClient(KiteFrostCore(api_key="sk_...", base_url="https://api-staging.kitefrost.ai"))
r = kf.ttrpg.quick_dialogue("my-campaign", {"npc_name": "Old Mara", "player_message": "What do you know about the ruined tower?"})
print(r["dialogue"])

See TypeScript SDK and Python SDK for the full client, and the API reference for every endpoint.

Troubleshooting

Symptom	Fix
No AI: Generate Dialogue in the menu	The menu item appears only when API Key and Project ID are set. Check Configure Settings -> KiteFrost.
`401` / “API key” error	The key is wrong or revoked - create a new one on the project’s API Keys page.
`404`	The Project ID doesn’t match a project of that key’s account. Copy it again from the address bar.
Nothing happens	Press F12 -> Console and look for a red `[KiteFrost]` line.

Getting Started

Core Concepts

SDKs

Integrations

API Reference

Before you start: an API key and your project

1. The module, point and click

2. The module’s scripting API (macros and modules)

3. Direct REST or the KiteFrost SDKs

Troubleshooting

​Before you start: an API key and your project

​1. The module, point and click

​2. The module’s scripting API (macros and modules)

​3. Direct REST or the KiteFrost SDKs

​Troubleshooting

Before you start: an API key and your project

1. The module, point and click

2. The module’s scripting API (macros and modules)

3. Direct REST or the KiteFrost SDKs

Troubleshooting