foil enginedocs
← Home

SDK Quickstart

Go from zero to a working NPC conversation in under 5 minutes.

This guide gets you to a working chat as fast as possible. You need: an API key (from the API Keys page) and an LLM provider key (e.g., OpenAI).

ℹNote
Before using the SDK, you need at least one published persona. Create and publish one from the web editor first.

Python

pip install foilengine
from foilengine import FoilEngineClient

client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-...",
    llm_model="gpt-4o",
)

# 1. Find your persona
personas = client.personas.list()
persona_id = personas[0].id

# 2. Start a conversation
session = client.chat.init_session(
    persona_id=persona_id,
    user_session_id="player-001",
    player_name="Alex",
    player_gender="non-binary",
)
print(f"NPC: {session.message}")

# 3. Send a message
response = client.chat.send_message(
    persona_id=persona_id,
    message="Hello! What's your name?",
    user_session_id="player-001",
)
print(f"NPC: {response.message}")

TypeScript / Node.js

npm install @foilengine/sdk
import { FoilEngineClient } from '@foilengine/sdk';

const client = new FoilEngineClient({
  apiKey: 'pk_live_...',
  llmApiKey: 'sk-...',
  llmModel: 'gpt-4o',
});

// 1. Find your persona
const personas = await client.personas.list();
const personaId = personas[0].id;

// 2. Start a conversation
const session = await client.chat.initSession(personaId, {
  userSessionId: 'player-001',
  playerName: 'Alex',
  playerGender: 'non-binary',
});
console.log(`NPC: ${session.message}`);

// 3. Send a message
const response = await client.chat.sendMessage(personaId, {
  message: "Hello! What's your name?",
  userSessionId: 'player-001',
});
console.log(`NPC: ${response.message}`);

Unity (C#)

Install via UPM: Window → Package Manager → + → Add package from git URL:

https://github.com/py1218/foilengine-unity.git
using FoilEngine;
using FoilEngine.Models;

var client = new FoilEngineClient(
    "pk_live_...",
    llmApiKey: "sk-...",
    llmModel: "gpt-4o"
);

// 1. Find your persona
Persona[] personas = await client.Personas.ListAsync();
string personaId = personas[0].Id;

// 2. Start a conversation
SessionInit session = await client.Chat.InitSessionAsync(
    personaId: personaId,
    userSessionId: "player-001",
    playerName: "Alex",
    playerGender: "non-binary"
);
Debug.Log($"NPC: {session.Message}");

// 3. Send a message
ChatResponse response = await client.Chat.SendMessageAsync(
    personaId: personaId,
    message: "Hello! What's your name?",
    userSessionId: "player-001"
);
Debug.Log($"NPC: {response.Message}");

What's Next?

Previous← Game SDKNextGetting Started →