AI API

The kittl.ai API provides methods for AI-related operations: spending credits, starting AI generations, and listening for generation status updates.

Spending Credits

Use spendCredits to prompt the user with a confirmation dialog before spending AI credits. This is typically used when your extension performs AI operations (e.g. image generation) that consume credits.

const result = await kittl.ai.spendCredits({
    amount: 5,
    message: 'Generate an AI image',
    onAccept: () => {
        console.log('User accepted — starting generation...');
    },
    onDecline: () => {
        console.log('User declined the credit spend.');
    },
});

if (result.isOk) {
    console.log('Credits spent:', result.result.success);
}

Starting a Generation

Use startGeneration to kick off an AI generation (image or video). You provide a generatorId that uniquely identifies your generator, input settings describing the prompt/model, and output settings describing the desired dimensions.

const result = await kittl.ai.startGeneration(
    'my-image-generator',
    {
        prompt: 'A sunset over a mountain lake',
        model: { id: 'stable-diffusion-xl' },
        type: 'image',
        taskType: 'TEXT_TO_IMAGE',
    },
    {
        dimensions: { width: 1024, height: 1024 },
    },
);

if (result.isOk) {
    console.log('Generation started:', result.result.generationId);
} else {
    console.error('Failed to start generation:', result.error);
}

Listening for Status Updates

Use registerHandler to subscribe to generation status updates for a specific generator. The callback fires whenever the generation transitions between states: CREATED → STARTED → COMPLETE or FAILED.

const handlerResult = await kittl.ai.registerHandler(
    'my-image-generator',
    (update) => {
        switch (update.status) {
            case 'CREATED':
                console.log('Generation created:', update.generationId);
                break;
            case 'STARTED':
                console.log('Generation started, ETA:', update.result.generationEndsAt);
                break;
            case 'COMPLETE':
                console.log('Generation complete:', update.result);
                if (update.result.type === 'image') {
                    console.log('Image object name:', update.result.objectName);
                }
                break;
            case 'FAILED':
                console.error('Generation failed:', update.result.message);
                break;
        }
    },
);

// When you're done, unsubscribe:
if (handlerResult.isOk) {
    const unsubscribe = handlerResult.result;
    // Later…
    unsubscribe();
}

Full Example: Generate an Image

Below is a complete example that spends credits, starts a generation, and tracks its progress:

window.kittl.onReady(async () => {
    // 1. Request credit spend (optional step, you can generate without it, steps 2 and 3 are enough)
    const creditResult = await kittl.ai.spendCredits({
        amount: 5,
        message: 'Generate an AI image',
    });

    if (!creditResult.isOk || !creditResult.result.success) {
        console.log('User declined or credit spend failed');
        return;
    }

    // 2. Register a handler before starting the generation
    const handlerResult = await kittl.ai.registerHandler(
        'my-image-generator',
        (update) => {
            if (update.status === 'COMPLETE' && update.result.type === 'image') {
                console.log('Image ready:', update.result.objectName);
            }
            if (update.status === 'FAILED') {
                console.error('Generation failed:', update.result.message);
            }
        },
    );

    // 3. Start the generation
    const genResult = await kittl.ai.startGeneration(
        'my-image-generator',
        {
            prompt: 'A sunset over a mountain lake',
            model: { id: 'stable-diffusion-xl' },
            type: 'image',
            taskType: 'TEXT_TO_IMAGE',
        },
        {
            dimensions: { width: 1024, height: 1024 },
        },
    );

    if (genResult.isOk) {
        console.log('Generation started:', genResult.result.generationId);
    }
});

See AI API Reference for full parameter and return type details.