AI API Reference

kittl.ai — AI generation and credit operations.

Scope: ai:credit:spend

---

spendCredits(options)

Prompts the user with a confirmation dialog before spending AI credits.

Property	Type	Required	Description
amount	number	Yes	Number of credits to spend
message	string	Yes	Message shown to the user explaining the spend
onAccept	() => void	No	Callback invoked when the user accepts
onDecline	() => void	No	Callback invoked when the user declines

Returns: SdkResultAsync<SpendCreditsResult>

SpendCreditsResult

Property	Type	Description
success	boolean	Whether the user confirmed the credit spend

---

startGeneration(generatorId, inputSettings, output)

Starts an AI generation (image or video).

Parameter	Type	Description
generatorId	string	Unique identifier for your generator
inputSettings	AIGenerationInputSettings	Prompt, model, and generation parameters
output	AIGenerationOutputSettings	Desired output dimensions

Returns: SdkResultAsync<StartGenerationResult>

StartGenerationResult

Property	Type	Description
generationId	string	Unique ID for the started generation

---

registerHandler(generatorId, onStatusUpdate)

Subscribes to generation status updates for a specific generator. The callback fires on every status transition.

Parameter	Type	Description
generatorId	string	The generator to listen on (must match the ID passed to startGeneration)
onStatusUpdate	OnGenerationStatusUpdate	Callback invoked on each status change

Returns: SdkResultAsync<() => void> — the result contains an unsubscribe function. Call it to stop receiving updates.

---

unregisterHandler(generatorId)

Unsubscribes from generation status updates for a specific generator. Use this as an alternative to calling the unsubscribe function returned by registerHandler.

Parameter	Type	Description
generatorId	string	The generator to stop listening on

Returns: SdkResultAsync<void>

---

Types

AIGenerationInputSettings

Property	Type	Required	Description
prompt	string	Yes	The text prompt for generation
model	{ id: string }	Yes	Model identifier
type	AIGenerationContentType	Yes	Content type to generate
taskType	AIGenerationModelTaskType	No	Specific task variant
promptStyleId	number	No	Style preset ID
additionalParams	Record<string, unknown>	No	Extra model-specific parameters
actionOrigin	AIGenerationActionOrigin	No	Origin of the generation action

AIGenerationOutputSettings

Property	Type	Required	Description
id	string	No	Optional output target ID
dimensions	{ width: number; height: number }	Yes	Desired output dimensions in pixels

AIGenerationContentType

type AIGenerationContentType = 'image' | 'video';

AIGenerationModelTaskType

type AIGenerationModelTaskType =
    | 'TEXT_TO_IMAGE'
    | 'IMAGE_TO_IMAGE'
    | 'IMAGE_INPAINT'
    | 'IMAGE_TO_VIDEO';

OnGenerationStatusUpdate

type OnGenerationStatusUpdate = (update: GenerationStatusUpdate) => void | Promise<void>;

GenerationStatusUpdate

A discriminated union on the status field. Each variant carries different inputData and result shapes:

Status	inputData	result
'CREATED'	undefined	undefined
'STARTED'	GenerationInputData	StartedGenerationResult
'COMPLETE'	GenerationInputData	SuccessGenerationResult
'FAILED'	GenerationInputData | undefined	ErrorGenerationResult

All variants include generationId: string.

GenerationInputData

Property	Type	Description
prompt	string?	The prompt that was used
style	{ id: number }?	Style preset if any
model	{ id: string }?	Model that was used

StartedGenerationResult

ImageGenerationStartedResult | VideoGenerationStartedResult

Property	Type	Description
type	'image' | 'video'	Content type
generationEndsAt	number?	Estimated completion timestamp (ms)

SuccessGenerationResult

ImageGenerationResult | VideoGenerationResult

ImageGenerationResult

Property	Type	Description
type	'image'	Always 'image'
objectName	string	Name of the generated image object on the canvas

VideoGenerationResult

Property	Type	Description
type	'video'	Always 'video'
status	'PROCESSING' | 'READY' | 'FAILED'	Video processing state
playbackId	string?	Playback identifier
duration	number?	Duration in seconds
aspectRatio	string?	Aspect ratio (e.g. '16:9')
hostingProvider	'MUX'?	Hosting provider

ErrorGenerationResult

Property	Type	Description
type	'error'	Always 'error'
message	string	Human-readable error message
subtitle	string	Secondary message (shorter description)
status	'warning' | 'error'	Severity level of the failure

GenerationMeta

Property	Type	Description
generationEndsAt	number?	Estimated completion timestamp (ms)
pendingGenerationId	string	ID of the pending generation
operation	GenerationOperation?	The operation type (e.g. inpaint)

GenerationOperation

const GenerationOperation = {
    INPAINT: 'inpaint',
} as const;

type GenerationOperation = (typeof GenerationOperation)[keyof typeof GenerationOperation];

GenerationStatus

const GenerationStatus = {
    CREATED: 'CREATED',
    STARTED: 'STARTED',
    COMPLETE: 'COMPLETE',
    FAILED: 'FAILED',
} as const;