Kappapps SDK

Appearance

Class: AiService ​

Artificial intelligence service: enrich a text, generate a sound, translate, moderate, draw an image, generate structured content or proofread a text. Each method delegates to an AI endpoint of the Kappapps backend.

Remarks ​

Accessible everywhere via k.ai. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

Example ​

ts
// Translate a chat message into English before displaying it again
const en = await k.ai.translate('Welcome to the stream!', 'en');
await k.chat.say(en);

Implements ​

Methods ​

draw() ​

ts
draw(
   prompt, 
   image_urls?, 
options?): Promise<string>;

Generates an image from a text prompt, optionally guided by reference images.

Parameters ​

prompt ​

string

Description of the image to generate.

image_urls? ​

string[] = null

URLs of reference images to provide to the AI. null or an empty array to generate without a reference.

options? ​

GeneratedMediaOptions = {}

save defaults to false: only a temporary delivery file is created. With save: true, title is required; the backend saves one named media for seven days (app scope file:write). The authenticated app slug prefixes the title; no upload is needed.

Returns ​

Promise<string>

The URL of the generated image, or null if no URL was returned.

Remarks ​

Available to widgets and all apps, including third-party apps. Apps require the ai:draw scope from manifest contract 4; older versions remain exempt until their next newly created version. Widgets do not declare app scopes. The channel's AI reserve and request limits still apply. Permission and reserve failures reject the promise (403 / 429).

Default Value ​

null

Example ​

ts
const url = await k.ai.draw('an astronaut penguin, pixel art style');
if (url) {
    // display the image
}

enrich() ​

ts
enrich(text): Promise<string>;

Enriches / rephrases a text via the AI (e.g. to make it livelier).

Parameters ​

text ​

string

The text to enrich.

Returns ​

Promise<string>

The text enriched by the AI, or the original text if the AI returned nothing.

Example ​

ts
const phrase = await k.ai.enrich('Thanks for the follow');

generate() ​

ts
generate(prompt, format?): Promise<Record<string, any>>;

Generates structured content from a prompt, in an optional format.

Parameters ​

prompt ​

string

Instruction describing the content to produce.

format? ​

string = null

Expected format of the content (interpreted by the generator). null for the default format.

Returns ​

Promise<Record<string, any>>

An object containing the generated content (structure depends on the format).

Default Value ​

null

Example ​

ts
const data = await k.ai.generate('3 mini-game ideas for the chat');

moderate() ​

ts
moderate(message): Promise<boolean>;

Submits a message to AI moderation.

Parameters ​

message ​

string

The message to analyze.

Returns ​

Promise<boolean>

true if the message is flagged by moderation, false otherwise.

Example ​

ts
if (await k.ai.moderate(event.getMessage())) {
    // problematic message: we ignore it
}

proofread() ​

ts
proofread(text, additional_instructions?): Promise<{
  text: string;
}>;

Proofreads / corrects a text (spelling, grammar), with optional instructions.

Parameters ​

text ​

string

The text to correct.

additional_instructions? ​

string = null

Additional instructions for the proofreading (e.g. "keep a casual tone"). null for no instructions.

Returns ​

Promise<{ text: string; }>

An object containing the corrected text in its text field.

Default Value ​

null

Example ​

ts
const { text } = await k.ai.proofread('i has winned the gaem');

sound() ​

ts
sound(
   prompt, 
   duration?, 
   prompt_influence?, 
   traduce?, 
options?): Promise<string>;

Generates a sound effect from a text description (text-to-sound).

Parameters ​

prompt ​

string

Description of the sound to generate (e.g. "rain falling on a roof").

duration? ​

number = null

Desired length of the sound, in seconds. null lets the AI decide.

prompt_influence? ​

number = null

How closely to adhere to the prompt (depends on the engine). null for the engine's default value.

traduce? ​

boolean = true

If true, the prompt is translated first before generation.

options? ​

GeneratedMediaOptions = {}

save defaults to false. With save: true, title is required; the backend saves one media named with the authenticated app slug for seven days (app scope file:write). No upload is needed.

Returns ​

Promise<string>

The URL of the generated sound.

Default Value ​

null

Default Value ​

null

Default Value ​

true

Example ​

ts
const url = await k.ai.sound('distant explosion', 3);
new Audio(url).play();

translate() ​

ts
translate(text, language): Promise<string>;

Translates a text into the target language via the AI.

Parameters ​

text ​

string

The text to translate.

language ​

string

The target language (e.g. 'en', 'fr', 'es').

Returns ​

Promise<string>

The translated text.

Example ​

ts
const es = await k.ai.translate('Hello everyone', 'es');