AI API

DMHub’s AI API allows access to OpenAI services for generating text and image responses. A user account has a limited number of tokens which can be used to access AI services. Calls to this API will consume tokens, and will result in an error once the user’s account has no more tokens, so use this API carefully.

Interface

ai.NumberOfAvailableTokens

function ai.NumberOfAvailableTokens() : number

This returns the number of tokens the current user’s account currently has available. It is expressed as a decimal. Generating an image may cost 1-2 tokens and chatting costs a token for every few thousand words. This function is most likely called to display the number of tokens the user has available in a UI.

Example:

--display a label showing the number of tokens the user has remaining.
gui.Label{
    text = string.format("Tokens Remaining: %d", round(ai.NumberOfAvailableTokens()))
}

ai.Chat

function ai.Chat{ messages = , temperature = (number?), success = function(string) : nil, error = function(string) : nil}} : nil

Sends a chatbot request with a history of messages. An asynchronous call which will call success() with the response string, or error() if an error occurs.

The ‘role’ string must be “system”, “user”, or “assistant”. You can provide a history of chat so far or you can pre-fill the chat with examples for the AI to learn off of.

The temperature guides how much variance there will be in the AI’s responses. A temperature of 0 means the responses will be close to deterministic, and a temperature of 1 means the responses will be very random.

Note that the total contents of the request and response may not exceed about 3000 words. The number of words also increases the number of tokens consumed.

Example:

ai.Chat{
	messages = {
		{
			role = "system",
			text = "You are an AI assistant in a vtt where people are playing D&D."
		},
		{
			role = "system",
			text = "The campaign takes place in the Dark Sun setting. The player's party consists of Eldrith, a level 2 Human fighter, Delm, a level 2 Dwarvish Cleric, and Amelia, a level 2 Elvish Wizard."
		},
		{
			role = "user",
			text = "Suggest a name for my player's party."
		}
	},

	temperature = 0.8, --high level of randomness in responses.
	success = function(response)
		printf("The bot responded: %s", response)
	end,
	error = function(message)
		printf("An error occurred: %s", message)
	end,
}

ai.Image

function ai.Image{ prompt = string, size = string?, removeBackground = string? imageLibrary = string? success = function(string) : nil, error = function(string) : nil }

Sends a request to generate an image with the given prompt. The resulting image will be automatically added to the user’s image library and the imageid it is assigned in DMHub provided, allowing it to be directly displayed in DMHub, or used as an icon or image for items, avatars, etc.

The size parameter may be “256x256”, “512x512”, or “1024x1024”. If specified, “removeBackground” gives a HTML color which will be replaced by transparency. Note that the AI will not generate transparency itself.

imageLibrary specifies the DMHub image library the new image will be placed in, and defaults to “Avatars”, the image library for character avatars.

success() is called with the imageid of the created image on success, or error() is called if an error occurs. Either success() or error() will be called exactly once at some point after this function is called.

Calling this function will consume 1-2 of the current user’s tokens.

Example:

--make a UI element which will start off as a white square, but once an image is generated will display the image.
gui.Panel{
	bgimage = "panels/square.png",
	bgcolor = "white",
	width = 256,
	height = 256,
	create = function(element)
		ai.Image{
			prompt = "An icon of a flaming sword in a photorealistic style with a solid white background",
			size = "256x256",
			removeBackground = "#ffffffff",
			imageLibrary = "Avatars",
			success = function(imageid)
				--display the generated image on this panel.
				element.bgimage = imageid
			end,
			error = function(message)
				printf("Error generating image: %s", message)
			end,
		}
	end
}