CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

AIAssistantConfig (ai)

@ckeditor/ckeditor5-ai/src/aiassistant

interface

The configuration of the AI assistant feature.

ClassicEditor
	.create( editorElement, {
		aiAssistant: ... // AI assistant options.
	} )
	.then( ... )
	.catch( ... );

See all editor options.

Filtering

Properties

  • apiUrl : string | undefined

    The URL to which the API request will be sent.

    Defaults to 'https://api.openai.com/v1/chat/completions'.

  • authKey : string | () => Promise<string> | undefined

    A key used to authorize the request to the AI service.

    If you are connecting directly to the OpenAI API, use your OpenAI API key as authKey.

    Important: use your API key ONLY in a development environment or for testing purposes! In the production environment, pass your request through a proxy.

    If you are using a proxy service to send requests to the AI service, authKey can be used to implement authorization for your requests.

    If the key is provided, it is added to the Authorization header of the request call, using the bearer scheme:

    Authorization: Bearer <authKey>

    If the provided value is a string, it is simply used as provided.

    If the provided value is a function, it should be a function that returns a Promise which resolves with the authorization token. This way, you can perform an authorization request to your application and receive the authorization token (and also implement any custom logic that you need). The authorization token is then used to make the actual call to the AI service.

    {
	aiAssistant: {
		authKey: async () => {
			return await fetch( 'https://example.com/jwt-endpoint' );
		}
		// ...
	}
}

    If the authorization request fails, the promise should be rejected. In this case, the feature will display an error notification.

  • commands : Array<GroupDefinition> | undefined

    A list of all AI commands groups definitions to be displayed in the 'aiCommands' UI dropdown.

    Setting this property will overwrite the default list of predefined commands.

    The default configuration is as follows:

    {
	groupId: 'editOrReview',
	groupLabel: 'Edit or review',
	commands: [
		{
			id: 'improveWriting',
			label: 'Improve writing',
			prompt: 'Rewrite this content with no spelling mistakes, proper grammar, ' +
				'and with more descriptive language, using best writing practices without losing the original meaning.'
		},
		{
			id: 'makeShorter',
			label: 'Make shorter',
			prompt: 'Remove any repetitive, redundant, or non-essential writing in this content ' +
				'without changing the meaning or losing any key information.'
		},
		{
			id: 'makeLonger',
			label: 'Make longer',
			prompt: 'Expand upon this content with descriptive language and more detailed explanations, ' +
				'to make the writing easier to understand and increase the length of the content.'
		},
		{
			id: 'simplifyLanguage',
			label: 'Simplify language',
			prompt: 'Rewrite this content with simplified language ' +
				'and reduce the complexity of the writing, so that the content is easier to understand.'
		}
	]
},
{
	groupId: 'generate',
	groupLabel: 'Generate from selection',
	commands: [
		{
			id: 'summarize',
			label: 'Summarize',
			prompt: 'Provide the key points and concepts in this content in a succinct summary.'
		},
		{
			id: 'continue',
			label: 'Continue',
			prompt: 'Continue this text.'
		}
	]
},
{
	groupId: 'changeTone',
	groupLabel: 'Change tone',
	commands: [
		{
			id: 'professional',
			label: 'Professional',
			prompt: 'Rewrite this content using polished, formal, and respectful language ' +
				'to convey professional expertise and competence.'
		},
		{
			id: 'casual',
			label: 'Casual',
			prompt: 'Rewrite this content with casual, informal language to convey a casual conversation with a real person.'
		},
		{
			id: 'direct',
			label: 'Direct',
			prompt: 'Rewrite this content with direct language using only the essential information.'
		},
		{
			id: 'confident',
			label: 'Confident',
			prompt: 'Rewrite this content using compelling, optimistic language to convey confidence in the writing.'
		},
		{
			id: 'friendly',
			label: 'Friendly',
			prompt: 'Rewrite this content using friendly, comforting language, to convey understanding and empathy.'
		}
	]
},
{
	groupId: 'changeStyle',
	groupLabel: 'Change style',
	commands: [
		{
			id: 'business',
			label: 'Business',
			prompt: 'Rewrite this content as a business professional with formal language.'
		},
		{
			id: 'legal',
			label: 'Legal',
			prompt: 'Rewrite this content as a legal professional using valid legal terminology.'
		},
		{
			id: 'journalism',
			label: 'Journalism',
			prompt: 'Rewrite this content as a journalist using engaging language to convey the importance of the information.'
		},
		{
			id: 'poetic',
			label: 'Poetic',
			prompt: 'Rewrite this content as a poem using poetic techniques without losing the original meaning.'
		}
	]
},
{
	groupId: 'translate',
	groupLabel: 'Translate',
	commands: [
		{
			id: 'translateEnglish',
			label: 'Translate to English',
			prompt: 'Translate to English language.'
		},
		{
			id: 'translateSpanish',
			label: 'Translate to Spanish',
			prompt: 'Translate to Spanish language.'
		},
		{
			id: 'translatePortuguese',
			label: 'Translate to Portuguese',
			prompt: 'Translate to Portuguese language.'
		},
		{
			id: 'translateGerman',
			label: 'Translate to German',
			prompt: 'Translate to German language.'
		},
		{
			id: 'translateFrench',
			label: 'Translate to French',
			prompt: 'Translate to French language.'
		},
		{
			id: 'translateChinese',
			label: 'Translate to Simplified Chinese',
			prompt: 'Translate to Simplified Chinese language.'
		},
		{
			id: 'translateHindi',
			label: 'Translate to Hindi',
			prompt: 'Translate to Hindi language.'
		},
		{
			id: 'translateArabic',
			label: 'Translate to Arabic',
			prompt: 'Translate to Arabic language.'
		}
	]
}

  • contentAreaCssClass : string | undefined

    An additional CSS class name (or names) added to the AI assistant content area (model response area).

    Because the content area is usually detached from the flow of the document, this configuration allows for better integration with application's stylesheets and improves the consistency of content styles.

  • disabledElements : Array<string> | undefined

    The AI assistant feature will be disabled if the document selection includes any of these elements.

    Use this property if AI assistant does not work properly with your custom features.

    Currently, by default, AI assistant is disabled for following model elements:

    • Media embed ('media') -- does not display in response area,
    • HTML embed ('rawHtml') -- sometimes does not display in response area, security uncertainty,
    • Table of contents ('tableOfContents') -- does not display properly in response area, long processing time.

    You can set this list to include more model elements or clear it to enable the above features.

    Note, that all or some of these features may become enabled in the future.

    Defaults to [ 'media', 'rawHtml', 'tableOfContents' ]

  • extraCommandGroups : Array<GroupDefinition> | undefined

    A list of additional AI commands groups definitions that will extend default commands.

    You can define new AI commands groups or add new AI commands to existing groups. If you add AI commands to an existing group, you do not need to specify groupLabel property. Use the (optional) order property to control the position of new groups and commands.

    An example configuration:

    {
	aiAssistant: {
		extraCommandGroups: [
			// Add an AI command to an existing group:
			{
				groupId: 'changeTone',
				commands: [
					{
						id: 'sad',
						label: 'Sad',
						prompt: 'Rewrite this text to make it sound sad and depressing.',
						// You can specify the position of this command among existing ones. Commands use zero-based numbering.
						order: 2
					}
				]
			},
			// Create a new AI commands group:
			{
				groupId: 'transformations',
				groupLabel: 'Transformations',
				// You can specify the position of this group among existing ones. Groups use zero-based numbering.
				order: 3,
				commands: [
					{
						id: 'addEmojis',
						label: 'Add emojis',
						prompt: 'Analyze each sentence of this text. After each sentence add an emoji that summarizes the sentence.'
					},
					// ...
				]
			},
		],
		// ...
	}

  • removeCommands : Array<string> | undefined

    A list of ids of AI commands to be removed.

    Learn more about command definition and its id.

    An example configuration:

    {
	aiAssistant: {
		removeCommands: [
			'improveWriting',
			// ...
		],
		// ...
	}

  • requestParameters : RequestParameters | undefined

    Additional configuration parameters for the AI request. Use it to customize how the AI service generates responses.

    See OpenAI API reference to learn more.

    Defaults to:

    {
	model: 'gpt-3.5-turbo',
	max_tokens: 2000,
	temperature: 1,
	top_p: 1
}

  • useTheme : boolean | undefined

    Enables or disables the AI assistant UI theme.

    • Leaving this property unset will preserve the default theme on AI Assistant UI elements.
    • Setting this property to false will remove the default theme from AI assistant UI elements.

    Learn more about AI assistant UI customization.

    Defaults to true