---
product: Chilkat
product_version: 11.7.0
language: wc
language_label: Unicode C
class: Ai
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wc_CkAiWRef.html
---
# Chilkat Ai — Unicode C — v11.7.0

> Chilkat 11.7.0 · language=wc · class=Ai
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Ai.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/guide.md`.

## Purpose

**Use one consistent API for multiple AI providers.**

`Chilkat.Ai` provides a unified interface for sending prompts, multimodal input, conversations, streaming requests, tool calls, and file references to many AI providers. Instead of writing separate REST integrations for each vendor, applications can use one Chilkat API while Chilkat handles provider-specific differences in authentication, request formatting, response parsing, streaming events, and tool-calling workflows.

OpenAI Google Gemini Anthropic Claude xAI Grok Mistral DeepSeek Perplexity Custom Providers

**Portable provider access**

Write code once and switch providers by changing settings such as `Provider`, `Model`, `ApiKey`, `BaseUrl`, and `ApiSpec`.

**Conversations**

Create, select, export, import, list, and delete named conversations. Chilkat can maintain local transcripts or use provider-hosted conversation state where supported.

**Multimodal input**

Add text, image data, image URLs, file data, file URLs, and uploaded file references to the next request.

**Streaming responses**

Use `Streaming`, `PollAi`, and `NextAiEvent` to receive incremental output and standardized streaming events.

**Tool calling**

Supports manual function tool calling and automatic JavaScript tool calling, including safeguards such as tool timeouts and iteration limits.

**File upload and reuse**

Upload files once, receive a file ID or URI, and reference that file in later requests when supported by the provider.

**Starting in v11.4.0:** `Chilkat.Ai` adds manual tool function calling, automatic JavaScript tool calling, file uploads for later reference by file ID, and conversational image output for providers that support it.

AI responses are often returned as Markdown. Chilkat also provides Markdown to HTML support in the `StringBuilder` class, including streaming Markdown-to-HTML conversion for applications that display AI output as it is generated.

Also see [Markdown to HTML Overview](https://www.chilkatsoft.com/markdown_to_html_overview.asp). For an extended overview, see [Ai Class Overview](https://www.chilkatsoft.com/ai_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkAiW instance = CkAiW_Create();
// ...
CkAiW_Dispose(instance);
```

`HCkAiW CkAiW_Create(void);`

Creates an instance of the HCkAiW object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkAiW_Dispose(HCkAiW handle);`

Objects created by calling CkAiW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkAiW_Dispose.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Unicode C.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `void CkAiW_getDebugLogFilePath(HCkAiW cHandle, HCkString retval); void CkAiW_putDebugLogFilePath(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_debugLogFilePath(HCkAiW cHandle);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `void CkAiW_getLastErrorHtml(HCkAiW cHandle, HCkString retval); const wchar_t *CkAiW_lastErrorHtml(HCkAiW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkAiW_getLastErrorText(HCkAiW cHandle, HCkString retval); const wchar_t *CkAiW_lastErrorText(HCkAiW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkAiW_getLastErrorXml(HCkAiW cHandle, HCkString retval); const wchar_t *CkAiW_lastErrorXml(HCkAiW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkAiW_getLastMethodSuccess(HCkAiW cHandle); void CkAiW_putLastMethodSuccess(HCkAiW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkAiW_getVerboseLogging(HCkAiW cHandle); void CkAiW_putVerboseLogging(HCkAiW cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkAiW_getVersion(HCkAiW cHandle, HCkString retval); const wchar_t *CkAiW_version(HCkAiW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `ApiKey` | property, read/write | `void CkAiW_getApiKey(HCkAiW cHandle, HCkString retval); void CkAiW_putApiKey(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_apiKey(HCkAiW cHandle);` |
| `ApiKeyHeader` | property, read/write | `void CkAiW_getApiKeyHeader(HCkAiW cHandle, HCkString retval); void CkAiW_putApiKeyHeader(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_apiKeyHeader(HCkAiW cHandle);` |
| `ApiSpec` | property, read/write | `void CkAiW_getApiSpec(HCkAiW cHandle, HCkString retval); void CkAiW_putApiSpec(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_apiSpec(HCkAiW cHandle);` |
| `BaseUrl` | property, read/write | `void CkAiW_getBaseUrl(HCkAiW cHandle, HCkString retval); void CkAiW_putBaseUrl(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_baseUrl(HCkAiW cHandle);` |
| `EnableSecrets` | property, read/write | `BOOL CkAiW_getEnableSecrets(HCkAiW cHandle); void CkAiW_putEnableSecrets(HCkAiW cHandle, BOOL newVal);` |
| `FullTranscript` | property, read/write | `BOOL CkAiW_getFullTranscript(HCkAiW cHandle); void CkAiW_putFullTranscript(HCkAiW cHandle, BOOL newVal);` |
| `HasFunctionCalls` | property, read-only | `BOOL CkAiW_getHasFunctionCalls(HCkAiW cHandle);` |
| `HeartbeatMs` | property, read/write | `int CkAiW_getHeartbeatMs(HCkAiW cHandle); void CkAiW_putHeartbeatMs(HCkAiW cHandle, int newVal);` |
| `HostedConvo` | property, read/write | `BOOL CkAiW_getHostedConvo(HCkAiW cHandle); void CkAiW_putHostedConvo(HCkAiW cHandle, BOOL newVal);` |
| `IdleTimeoutMs` | property, read/write | `int CkAiW_getIdleTimeoutMs(HCkAiW cHandle); void CkAiW_putIdleTimeoutMs(HCkAiW cHandle, int newVal);` |
| `JsToolTimeout` | property, read/write | `int CkAiW_getJsToolTimeout(HCkAiW cHandle); void CkAiW_putJsToolTimeout(HCkAiW cHandle, int newVal);` |
| `LastResponseRefused` | property, read-only | `BOOL CkAiW_getLastResponseRefused(HCkAiW cHandle);` |
| `Model` | property, read/write | `void CkAiW_getModel(HCkAiW cHandle, HCkString retval); void CkAiW_putModel(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_model(HCkAiW cHandle);` |
| `Provider` | property, read/write | `void CkAiW_getProvider(HCkAiW cHandle, HCkString retval); void CkAiW_putProvider(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_provider(HCkAiW cHandle);` |
| `RefusalText` | property, read-only | `void CkAiW_getRefusalText(HCkAiW cHandle, HCkString retval); const wchar_t *CkAiW_refusalText(HCkAiW cHandle);` |
| `ResponseStatusCode` | property, read-only | `int CkAiW_getResponseStatusCode(HCkAiW cHandle);` |
| `SelectedConvo` | property, read/write | `void CkAiW_getSelectedConvo(HCkAiW cHandle, HCkString retval); void CkAiW_putSelectedConvo(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_selectedConvo(HCkAiW cHandle);` |
| `Streaming` | property, read/write | `BOOL CkAiW_getStreaming(HCkAiW cHandle); void CkAiW_putStreaming(HCkAiW cHandle, BOOL newVal);` |
| `UncommonOptions` | property, read/write | `void CkAiW_getUncommonOptions(HCkAiW cHandle, HCkString retval); void CkAiW_putUncommonOptions(HCkAiW cHandle, const wchar_t *newVal); const wchar_t *CkAiW_uncommonOptions(HCkAiW cHandle);` |
| `Ask` | method | `BOOL CkAiW_Ask(HCkAiW cHandle, const wchar_t *outputType);` |
| `DeleteConvo` | method | `BOOL CkAiW_DeleteConvo(HCkAiW cHandle, const wchar_t *name);` |
| `ExportConvo` | method | `BOOL CkAiW_ExportConvo(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW json);` |
| `GetFunctionCalls` | method | `BOOL CkAiW_GetFunctionCalls(HCkAiW cHandle, HCkJsonObjectW json);` |
| `GetLastJsonData` | method | `void CkAiW_GetLastJsonData(HCkAiW cHandle, HCkJsonObjectW json);` |
| `GetModels` | method | `BOOL CkAiW_GetModels(HCkAiW cHandle, HCkStringTableW st);` |
| `GetOutputBd` | method | `BOOL CkAiW_GetOutputBd(HCkAiW cHandle, HCkBinDataW bd);` |
| `GetOutputJson` | method | `BOOL CkAiW_GetOutputJson(HCkAiW cHandle, HCkJsonObjectW json);` |
| `GetOutputText` | method | `BOOL CkAiW_GetOutputText(HCkAiW cHandle, const wchar_t *outStr); const wchar_t *CkAiW_getOutputText(HCkAiW cHandle);` |
| `GetOutputTextSb` | method | `BOOL CkAiW_GetOutputTextSb(HCkAiW cHandle, HCkStringBuilderW sb);` |
| `GetSearchResults` | method | `BOOL CkAiW_GetSearchResults(HCkAiW cHandle, HCkJsonObjectW json);` |
| `ImportConvo` | method | `BOOL CkAiW_ImportConvo(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW json);` |
| `InputAddFileData` | method | `BOOL CkAiW_InputAddFileData(HCkAiW cHandle, const wchar_t *filename, HCkBinDataW bd, const wchar_t *summary);` |
| `InputAddFileId` | method | `BOOL CkAiW_InputAddFileId(HCkAiW cHandle, const wchar_t *file_id, const wchar_t *mime_type);` |
| `InputAddFileUrl` | method | `BOOL CkAiW_InputAddFileUrl(HCkAiW cHandle, const wchar_t *url, const wchar_t *summary);` |
| `InputAddFnResult` | method | `BOOL CkAiW_InputAddFnResult(HCkAiW cHandle, const wchar_t *call_id, const wchar_t *fnResult);` |
| `InputAddImageData` | method | `BOOL CkAiW_InputAddImageData(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *summary);` |
| `InputAddImageFileId` | method | `BOOL CkAiW_InputAddImageFileId(HCkAiW cHandle, const wchar_t *file_id, const wchar_t *mime_type);` |
| `InputAddImageUrl` | method | `BOOL CkAiW_InputAddImageUrl(HCkAiW cHandle, const wchar_t *url, const wchar_t *summary);` |
| `InputAddText` | method | `BOOL CkAiW_InputAddText(HCkAiW cHandle, const wchar_t *text);` |
| `InputAddTextSb` | method | `BOOL CkAiW_InputAddTextSb(HCkAiW cHandle, HCkStringBuilderW sb);` |
| `InputClear` | method | `void CkAiW_InputClear(HCkAiW cHandle);` |
| `ListConvos` | method | `BOOL CkAiW_ListConvos(HCkAiW cHandle, HCkStringTableW st);` |
| `NewConvo` | method | `BOOL CkAiW_NewConvo(HCkAiW cHandle, const wchar_t *name, const wchar_t *sysMsg, const wchar_t *devMsg);` |
| `NextAiEvent` | method | `BOOL CkAiW_NextAiEvent(HCkAiW cHandle, int maxWaitMs, HCkStringBuilderW sbName, HCkStringBuilderW sbDelta);` |
| `PollAi` | method | `int CkAiW_PollAi(HCkAiW cHandle, BOOL abort);` |
| `RegisterJsTools` | method | `BOOL CkAiW_RegisterJsTools(HCkAiW cHandle, HCkStringBuilderW sb, BOOL evalOnly, BOOL allowAllKeyword);` |
| `RegisterManualTools` | method | `BOOL CkAiW_RegisterManualTools(HCkAiW cHandle, HCkJsonObjectW json);` |
| `SetAskParams` | method | `BOOL CkAiW_SetAskParams(HCkAiW cHandle, HCkJsonObjectW json);` |
| `SetConnectionSettings` | method | `BOOL CkAiW_SetConnectionSettings(HCkAiW cHandle, HCkSocketW sock);` |
| `SetOutputSchema` | method | `BOOL CkAiW_SetOutputSchema(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW schema, BOOL strict);` |
| `SetProviderParams` | method | `BOOL CkAiW_SetProviderParams(HCkAiW cHandle, HCkJsonObjectW json);` |
| `SleepMs` | method | `void CkAiW_SleepMs(HCkAiW cHandle, int millisec);` |
| `StreamingJsToolCall` | method | `BOOL CkAiW_StreamingJsToolCall(HCkAiW cHandle, HCkStringBuilderW sb);` |
| `UploadFile` | method | `BOOL CkAiW_UploadFile(HCkAiW cHandle, const wchar_t *path, const wchar_t *mimeType, const wchar_t *outStr); const wchar_t *CkAiW_uploadFile(HCkAiW cHandle, const wchar_t *path, const wchar_t *mimeType);` |
| `UploadFileBd` | method | `BOOL CkAiW_UploadFileBd(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *filename, const wchar_t *mimeType, const wchar_t *outStr); const wchar_t *CkAiW_uploadFileBd(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *filename, const wchar_t *mimeType);` |
| `UploadFileSb` | method | `BOOL CkAiW_UploadFileSb(HCkAiW cHandle, HCkStringBuilderW sb, const wchar_t *filename, const wchar_t *mimeType, const wchar_t *outStr); const wchar_t *CkAiW_uploadFileSb(HCkAiW cHandle, HCkStringBuilderW sb, const wchar_t *filename, const wchar_t *mimeType);` |
| `UseMcp` | method | `BOOL CkAiW_UseMcp(HCkAiW cHandle, HCkMcpW cMcp, const wchar_t *namePrefix);` |

## Properties

### Ai.ApiKey

`Chilkat 11.7.0 · wc · Ai · ApiKey · property · read/write · since 11.2.0`

```c
void CkAiW_getApiKey(HCkAiW cHandle, HCkString retval);
void CkAiW_putApiKey(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_apiKey(HCkAiW cHandle);
```

This is the API key used for authentication. Use your API key that matches your `Provider` .

**Suggestion**: Use Chilkat's `Secrets` class to store and retrieve API keys in any of the following locations.

- Windows Credentials Manager
- Apple Keychain
- AWS Secrets Manager
- Azure Key Vault
- IBM Cloud Secrets Manager
- Oracle Cloud Secrets
- Doppler Secrets

### Ai.ApiKeyHeader

`Chilkat 11.7.0 · wc · Ai · ApiKeyHeader · property · read/write · since 11.3.0`

```c
void CkAiW_getApiKeyHeader(HCkAiW cHandle, HCkString retval);
void CkAiW_putApiKeyHeader(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_apiKeyHeader(HCkAiW cHandle);
```

For custom `Provider`'s, use this field name for the API key in the HTTP header, but only if the API key is to be placed in a `custom` header field. If the API key is to be provided in an `"Authorization: Bearer"` header, then leave this property empty.

The default value of this property is the empty string.

### Ai.ApiSpec

`Chilkat 11.7.0 · wc · Ai · ApiSpec · property · read/write · since 11.3.0`

```c
void CkAiW_getApiSpec(HCkAiW cHandle, HCkString retval);
void CkAiW_putApiSpec(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_apiSpec(HCkAiW cHandle);
```

Specifies the API specification to be used. Possible choices are `ChatCompletions`, `Responses`, `Gemini`, `Anthropic`. The default value is `Responses` because the default value of the `Provider` property is `openai`. Setting the `Provider` property to a value other than `custom` will also automatically set this property to the correct and needed value.

### Ai.BaseUrl

`Chilkat 11.7.0 · wc · Ai · BaseUrl · property · read/write · since 11.3.0`

```c
void CkAiW_getBaseUrl(HCkAiW cHandle, HCkString retval);
void CkAiW_putBaseUrl(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_baseUrl(HCkAiW cHandle);
```

Specifies the provider's base URL. For example, `http://localhost:11434/v1` or `https://api.together.xyz/v1`. The default value is `https://api.openai.com/v1` because the default value of the `Provider` property is `openai`. Setting the `Provider` property to a value other than `custom` will also automatically set this property to the correct and needed value.

### Ai.EnableSecrets

`Chilkat 11.7.0 · wc · Ai · EnableSecrets · property · read/write · since 11.5.0`

```c
BOOL CkAiW_getEnableSecrets(HCkAiW cHandle);
void CkAiW_putEnableSecrets(HCkAiW cHandle, BOOL newVal);
```

If `TRUE` a secret specifier of the format "!!part1\|part2\|.." can be provided instead of the actual value for the ApiKey property.

The default value is `FALSE`.

### Ai.FullTranscript

`Chilkat 11.7.0 · wc · Ai · FullTranscript · property · read/write · since 11.2.0`

```c
BOOL CkAiW_getFullTranscript(HCkAiW cHandle);
void CkAiW_putFullTranscript(HCkAiW cHandle, BOOL newVal);
```

For multimodal inputs like image data, image URLs, file data, and file URLs, the full data or URL is sent initially. If the property is set to `TRUE`, the full data/URL is re-sent in subsequent interactions. If set to `FALSE`, only the image or file summary is sent thereafter.

By default, this property is `FALSE`.

`Full transcript style:` always send the entire conversation (including files/images). This guarantees the model has all context, but can get expensive.

`Summarized transcript style:` for previously sent multimodal items, sends the summary message (e.g. “Earlier, I uploaded a PDF with account statements”) instead of the raw file or url itself.

### Ai.HasFunctionCalls

`Chilkat 11.7.0 · wc · Ai · HasFunctionCalls · property · read-only · since 11.4.0`

```c
BOOL CkAiW_getHasFunctionCalls(HCkAiW cHandle);
```

`TRUE` if the response output has function calls. Otherwise `FALSE`. This only applies to manual function tool calling, not automatic JS tool calls.

### Ai.HeartbeatMs

`Chilkat 11.7.0 · wc · Ai · HeartbeatMs · property · read/write · since 11.2.0`

```c
int CkAiW_getHeartbeatMs(HCkAiW cHandle);
void CkAiW_putHeartbeatMs(HCkAiW cHandle, int newVal);
```

The interval in milliseconds between each `AbortCheck` event callback, which enables an application to abort certain method calls before they complete. **By default, HeartbeatMs is set to** `0`**, meaning no AbortCheck event callbacks will trigger.**

### Ai.HostedConvo

`Chilkat 11.7.0 · wc · Ai · HostedConvo · property · read/write · since 11.2.0`

```c
BOOL CkAiW_getHostedConvo(HCkAiW cHandle);
void CkAiW_putHostedConvo(HCkAiW cHandle, BOOL newVal);
```

This applies to providers like OpenAI that can maintain conversation state on the server. If set to `TRUE`, only the conversation ID is sent with each query. If set to `FALSE`, the entire conversation transcript is sent with each query, making each query stateless.

This only applies if a conversation is selected.

The default value of this property is `FALSE`.

### Ai.IdleTimeoutMs

`Chilkat 11.7.0 · wc · Ai · IdleTimeoutMs · property · read/write · since 11.2.0`

```c
int CkAiW_getIdleTimeoutMs(HCkAiW cHandle);
void CkAiW_putIdleTimeoutMs(HCkAiW cHandle, int newVal);
```

The maximum amount of time to wait for additional incoming data when receiving a response. The default value is `90000` (90 seconds) in `v11.3.0` and earlier. Starting in `v11.4.0`, the default value is `180000` (180 seconds).

This is not a total timeout, but the maximum time allowed when data transmission has paused.

### Ai.JsToolTimeout

`Chilkat 11.7.0 · wc · Ai · JsToolTimeout · property · read/write · since 11.4.0`

```c
int CkAiW_getJsToolTimeout(HCkAiW cHandle);
void CkAiW_putJsToolTimeout(HCkAiW cHandle, int newVal);
```

The maximum time in seconds allowed for an automatic JavaScript tool function. The default value is 60 seconds to allow for most use cases, but to prevent an tool call that never returns.

### Ai.LastResponseRefused

`Chilkat 11.7.0 · wc · Ai · LastResponseRefused · property · read-only · since 11.6.0`

```c
BOOL CkAiW_getLastResponseRefused(HCkAiW cHandle);
```

Read-only. `TRUE` if the model refused to produce the requested structured output during the most recent `Ask`. When a refusal occurs, `GetOutputJson` returns `FALSE` and the provider's explanation is available in `RefusalText` . This property is reset at the start of each `Ask`.

### Ai.Model

`Chilkat 11.7.0 · wc · Ai · Model · property · read/write · since 11.2.0`

```c
void CkAiW_getModel(HCkAiW cHandle, HCkString retval);
void CkAiW_putModel(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_model(HCkAiW cHandle);
```

The model to be used for AI conversations. For example, `GPT-4o` or `GPT-5`. The list of available models can be obtained by calling `GetModels`.

The default value is the empty string. A model must always be specified. Chilkat won't try to guess or default to a model.

### Ai.Provider

`Chilkat 11.7.0 · wc · Ai · Provider · property · read/write · since 11.2.0`

```c
void CkAiW_getProvider(HCkAiW cHandle, HCkString retval);
void CkAiW_putProvider(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_provider(HCkAiW cHandle);
```

This is the AI provider. Possible values are: `openai`, `google`, `claude`, `deepseek`, `perplexity`, `mistral`, and `xai`.

Starting in Chilkat `v11.3.0`, this property can be set to `custom`, and the `BaseUrl` and `ApiSpec` properties can also be set to fully specify the provider.

Starting in `v11.6.0`, this property can also be set to `openai-compatible`, a convenience alias for a `custom` provider that speaks the OpenAI Chat Completions API. It presets `ApiSpec` to `ChatCompletions`, so you only need to set `BaseUrl` (plus `ApiKey` and `Model`). This is the simplest way to use OpenAI-compatible endpoints such as Ollama, LM Studio, OpenWebUI, and many hosting providers.

**Note:** `mistral` is recognized as a pre-configured known provider starting in `v11.4.0`.

The default value is `openai`.

### Ai.RefusalText

`Chilkat 11.7.0 · wc · Ai · RefusalText · property · read-only · since 11.6.0`

```c
void CkAiW_getRefusalText(HCkAiW cHandle, HCkString retval);
const wchar_t *CkAiW_refusalText(HCkAiW cHandle);
```

Read-only. When `LastResponseRefused` is `TRUE`, this is the model's message explaining why it declined to produce the requested structured output. Otherwise it is the empty string.

### Ai.ResponseStatusCode

`Chilkat 11.7.0 · wc · Ai · ResponseStatusCode · property · read-only · since 11.2.0`

```c
int CkAiW_getResponseStatusCode(HCkAiW cHandle);
```

The HTTP response status code for the last `Ask` is as follows:

- `0` indicates an error occurred before receiving an HTTP response.
- `200` indicates a successful response.
- A failed response has a status code of `400` or higher.

### Ai.SelectedConvo

`Chilkat 11.7.0 · wc · Ai · SelectedConvo · property · read/write · since 11.2.0`

```c
void CkAiW_getSelectedConvo(HCkAiW cHandle, HCkString retval);
void CkAiW_putSelectedConvo(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_selectedConvo(HCkAiW cHandle);
```

The currently selected conversation can be set to your desired conversation name. Once set, all future queries will be part of that conversation, updating its state with each input and output. By default, no conversation is selected, indicated by an empty string, leading to stateless queries. The first conversation created or imported will be automatically selected. If you attempt to select a non-existent conversation, the selection will not change. You can reset this property to an empty string to revert to stateless querying.

### Ai.Streaming

`Chilkat 11.7.0 · wc · Ai · Streaming · property · read/write · since 11.2.0`

```c
BOOL CkAiW_getStreaming(HCkAiW cHandle);
void CkAiW_putStreaming(HCkAiW cHandle, BOOL newVal);
```

When set to `TRUE`, the `Ask` method operates in streaming mode, returning immediately after the request is sent. You can then use the PollAi and NextAiEvent methods to receive streaming events. By default, this property is `FALSE`.

### Ai.UncommonOptions

`Chilkat 11.7.0 · wc · Ai · UncommonOptions · property · read/write · since 11.2.0`

```c
void CkAiW_getUncommonOptions(HCkAiW cHandle, HCkString retval);
void CkAiW_putUncommonOptions(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_uncommonOptions(HCkAiW cHandle);
```

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

## Methods

### Ai.Ask

`Chilkat 11.7.0 · wc · Ai · Ask · method · since 11.2.0`

```c
BOOL CkAiW_Ask(HCkAiW cHandle, const wchar_t *outputType);
```

Sends the current potentially multimodal input within the context of the selected conversation and receives the model's output. Prior to `v11.4.0` the `outputType` is limited to `text`. Starting in `v11.4.0`, the `outputType` can be set to `image` for AI providers that support conversational image output.

Accumulated outputs are cleared on entry to this method. Accumulated inputs are cleared on the successful return of this method.

This method cannot be called while a streaming Ask is in progress. In such a case the return value is `FALSE` and nothing will occur.

Returns TRUE for success, FALSE for failure.

Async variant: `AskAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.DeleteConvo

`Chilkat 11.7.0 · wc · Ai · DeleteConvo · method · since 11.2.0`

```c
BOOL CkAiW_DeleteConvo(HCkAiW cHandle, const wchar_t *name);
```

Deletes the conversation by its `name`. If `name` equals `*` then all conversations are deleted.

Returns TRUE for success, FALSE for failure.

### Ai.ExportConvo

`Chilkat 11.7.0 · wc · Ai · ExportConvo · method · since 11.2.0`

```c
BOOL CkAiW_ExportConvo(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW json);
```

Exports the conversation specified by `name` to `json`, replacing `json`'s contents with the exported transcript. You can later import a conversation using `ImportConvo` . The currently selected conversation can be exported by passing `*` for the `name`.

Returns TRUE for success, FALSE for failure.

### Ai.GetFunctionCalls

`Chilkat 11.7.0 · wc · Ai · GetFunctionCalls · method · since 11.4.0`

```c
BOOL CkAiW_GetFunctionCalls(HCkAiW cHandle, HCkJsonObjectW json);
```

This method returns the function calls in `json` if the output contains any. Returns `TRUE` if one or more function calls were returned, otherwise returns `FALSE`. This only applies to manual function tool calling, not automatic JS tool calls.

### Ai.GetLastJsonData

`Chilkat 11.7.0 · wc · Ai · GetLastJsonData · method · since 11.2.0`

```c
void CkAiW_GetLastJsonData(HCkAiW cHandle, HCkJsonObjectW json);
```

Provides details about the last method called on this object instance. While many methods do not generate information, some allow you to retrieve details by accessing the last JSON data immediately after the method call returns.

Methods that produce last JSON information include: `GetModels` .

### Ai.GetModels

`Chilkat 11.7.0 · wc · Ai · GetModels · method · since 11.2.0`

```c
BOOL CkAiW_GetModels(HCkAiW cHandle, HCkStringTableW st);
```

Returns a list of models available to your account, such as `GPT-4o` and `GPT-5`. The models are listed in `st`, sorted in ascending, case-insensitive order. To access the raw JSON response after calling this method, use `GetLastJsonData` .

Returns TRUE for success, FALSE for failure.

Async variant: `GetModelsAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.GetOutputBd

`Chilkat 11.7.0 · wc · Ai · GetOutputBd · method · since 11.4.0`

```c
BOOL CkAiW_GetOutputBd(HCkAiW cHandle, HCkBinDataW bd);
```

Returns in `bd` the binary output from the last call to `Ask`, such as for an AI generated image.

Returns TRUE for success, FALSE for failure.

### Ai.GetOutputJson

`Chilkat 11.7.0 · wc · Ai · GetOutputJson · method · since 11.6.0`

```c
BOOL CkAiW_GetOutputJson(HCkAiW cHandle, HCkJsonObjectW json);
```

Returns the model's structured JSON output from the most recent `Ask`, parsed into `json`. Use this after setting a schema with `SetOutputSchema` . Returns `TRUE` and populates `json` when the output is valid JSON. Returns `FALSE` if the model refused to produce the output (in which case `LastResponseRefused` is `TRUE` and `RefusalText` contains the explanation), if there is no output, or if the output is not valid JSON. The raw JSON text is also available from `GetOutputText` .

### Ai.GetOutputText

`Chilkat 11.7.0 · wc · Ai · GetOutputText · method · since 11.2.0`

```c
BOOL CkAiW_GetOutputText(HCkAiW cHandle, const wchar_t *outStr);
const wchar_t *CkAiW_getOutputText(HCkAiW cHandle);
```

Returns the text output from the last call to `Ask`.

Returns TRUE for success, FALSE for failure.

### Ai.GetOutputTextSb

`Chilkat 11.7.0 · wc · Ai · GetOutputTextSb · method · since 11.2.0`

```c
BOOL CkAiW_GetOutputTextSb(HCkAiW cHandle, HCkStringBuilderW sb);
```

Returns the text output, appended to `sb`, from the last call to `Ask`.

Returns TRUE for success, FALSE for failure.

### Ai.GetSearchResults

`Chilkat 11.7.0 · wc · Ai · GetSearchResults · method · since 11.6.0`

```c
BOOL CkAiW_GetSearchResults(HCkAiW cHandle, HCkJsonObjectW json);
```

Returns the web search sources the model used in the most recent `Ask`, if web search was enabled via the `web_search` param of `SetAskParams` . Returns `TRUE` if the last `Ask` performed one or more web searches, in which case the normalized results are placed in `json`. Returns `FALSE` if no web search occurred.

Chilkat normalizes the differing citation formats of each AI provider into a single flat structure. `json` is populated as follows:

```
{
  "search_results": [
    {
      "url": "https://example.com/article",
      "title": "Example Article Title",
      "snippet": "The relevant excerpt the model drew from...",
      "page_age": "2025-08-01"
    }
  ]
}
```

The `snippet` and `page_age` members are populated only when the provider supplies them, and may be absent otherwise. Each provider returns a different citation shape (for example, OpenAI returns `url_citation` annotations with character offsets, Anthropic returns `web_search_tool_result` content blocks, Google returns `groundingMetadata`, and Perplexity returns a `search_results` array). The full, unmodified provider response — including any character-offset annotations not represented in the normalized form — remains available via `GetLastJsonData` .

**Streaming:** In streaming mode, a standardized `web_search_call` event is delivered through `NextAiEvent` when the provider begins a search, and the normalized results are available from this method after the `null_terminator` event completes the response.

### Ai.ImportConvo

`Chilkat 11.7.0 · wc · Ai · ImportConvo · method · since 11.2.0`

```c
BOOL CkAiW_ImportConvo(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW json);
```

Imports the conversation from `json` and assigns it the name in `name`.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddFileData

`Chilkat 11.7.0 · wc · Ai · InputAddFileData · method · since 11.2.0`

```c
BOOL CkAiW_InputAddFileData(HCkAiW cHandle, const wchar_t *filename, HCkBinDataW bd, const wchar_t *summary);
```

Adds file data, such as a PDF, to the potentially multimodal input that will be sent in the next call to `Ask`. The `bd` contains the file data.

If `FullTranscript` is \_CKFALSE\_, `summary` is sent in subsequent interactions instead of the file data. If `FullTranscript` is `TRUE`, `summary` is not sent, and the file data is re-sent in each interaction.

This method cannot be used with `DeepSeek`.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddFileId

`Chilkat 11.7.0 · wc · Ai · InputAddFileId · method · since 11.4.0`

```c
BOOL CkAiW_InputAddFileId(HCkAiW cHandle, const wchar_t *file_id, const wchar_t *mime_type);
```

Adds a reference to a previously uploaded file. The `file_id` is the id returned from the provider when originally uploading the file. The `mime_type`, such as "application/pdf", "application/json", "text/xml", etc. is needed for some AI providers such as Google.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddFileUrl

`Chilkat 11.7.0 · wc · Ai · InputAddFileUrl · method · since 11.2.0`

```c
BOOL CkAiW_InputAddFileUrl(HCkAiW cHandle, const wchar_t *url, const wchar_t *summary);
```

Adds a file located at a `url` to the potentially multimodal input that will be sent in the next call to `Ask`.

If `FullTranscript` is \_CKFALSE\_, `summary` is sent in subsequent interactions instead of the file URL. If `FullTranscript` is `TRUE`, `summary` is not sent, and the file URL is re-sent in each interaction.

This method cannot be used with `DeepSeek`.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddFnResult

`Chilkat 11.7.0 · wc · Ai · InputAddFnResult · method · since 11.4.0`

```c
BOOL CkAiW_InputAddFnResult(HCkAiW cHandle, const wchar_t *call_id, const wchar_t *fnResult);
```

Provide a function call result to the model. This only applies to `manual function tool calling`, not automatic JS tool calls.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddImageData

`Chilkat 11.7.0 · wc · Ai · InputAddImageData · method · since 11.2.0`

```c
BOOL CkAiW_InputAddImageData(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *summary);
```

Adds an image to the potentially multimodal input that will be sent in the next call to `Ask`. The `bd` contains the images data. The image data must be jpeg, png, or webp format.

If `FullTranscript` is \_CKFALSE\_, `summary` is sent in subsequent interactions instead of the image data. If `FullTranscript` is `TRUE`, `summary` is not sent, and the image data is re-sent in each interaction.

This method cannot be used with `DeepSeek`. DeepSeek does not appear to expose an OpenAI-compatible vision model (yet). You cannot send image URLs or image data to DeepSeek.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddImageFileId

`Chilkat 11.7.0 · wc · Ai · InputAddImageFileId · method · since 11.4.0`

```c
BOOL CkAiW_InputAddImageFileId(HCkAiW cHandle, const wchar_t *file_id, const wchar_t *mime_type);
```

Adds a reference to a previously uploaded image file. The `file_id` is the id returned from the provider when originally uploading the file. The `mime_type`, such as "image/jpeg" is needed for some AI providers such as Google.

**Note:** At this time, only `OpenAI` and `Google` support the ability to upload once → get file_id → reuse in later requests' workflow for images.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddImageUrl

`Chilkat 11.7.0 · wc · Ai · InputAddImageUrl · method · since 11.2.0`

```c
BOOL CkAiW_InputAddImageUrl(HCkAiW cHandle, const wchar_t *url, const wchar_t *summary);
```

Adds an image located at a `url` to the potentially multimodal input that will be sent in the next call to `Ask`.

If `FullTranscript` is \_CKFALSE\_, `summary` is sent in subsequent interactions instead of the image URL. If `FullTranscript` is `TRUE`, `summary` is not sent, and the image URL is re-sent in each interaction.

This method cannot be used with `DeepSeek`. DeepSeek does not appear to expose an OpenAI-compatible vision model (yet). You cannot send image URLs or image data to DeepSeek.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddText

`Chilkat 11.7.0 · wc · Ai · InputAddText · method · since 11.2.0`

```c
BOOL CkAiW_InputAddText(HCkAiW cHandle, const wchar_t *text);
```

Adds text to the potentially multimodal input that will be sent in the next call to `Ask`.

Returns TRUE for success, FALSE for failure.

### Ai.InputAddTextSb

`Chilkat 11.7.0 · wc · Ai · InputAddTextSb · method · since 11.2.0`

```c
BOOL CkAiW_InputAddTextSb(HCkAiW cHandle, HCkStringBuilderW sb);
```

Adds text to the potentially multimodal input that will be sent in the next call to `Ask`.

Returns TRUE for success, FALSE for failure.

### Ai.InputClear

`Chilkat 11.7.0 · wc · Ai · InputClear · method · since 11.2.0`

```c
void CkAiW_InputClear(HCkAiW cHandle);
```

Clears the inputs to be sent in the next call to `Ask`.

### Ai.ListConvos

`Chilkat 11.7.0 · wc · Ai · ListConvos · method · since 11.2.0`

```c
BOOL CkAiW_ListConvos(HCkAiW cHandle, HCkStringTableW st);
```

Returns the full list of conversation names in `st`.

Returns TRUE for success, FALSE for failure.

### Ai.NewConvo

`Chilkat 11.7.0 · wc · Ai · NewConvo · method · since 11.2.0`

```c
BOOL CkAiW_NewConvo(HCkAiW cHandle, const wchar_t *name, const wchar_t *sysMsg, const wchar_t *devMsg);
```

Creates and initializes a transcript for a new conversation. The `name` is a unique name for the conversation. You can reference the conversation by this name, such as for the `ExportConvo` method.

The `sysMsg` sets the broad behavior, tone, and role of the assistant. Example: `"You are a polite tutor who explains concepts clearly and simply."` Think of it as the high-level persona or instructions the model follows throughout the conversation. The `devMsg` provides more technical or policy-level guidance. Example: `"Always respond in Markdown. Do not reveal internal reasoning. Keep answers under 200 words."` It’s like hidden scaffolding to enforce app rules, formatting, or safety constraints.

**Note:** The first conversation created is automatically set as the `SelectedConvo` . You can use any unique name for a conversation except `*`.

Returns TRUE for success, FALSE for failure.

### Ai.NextAiEvent

`Chilkat 11.7.0 · wc · Ai · NextAiEvent · method · since 11.2.0`

```c
BOOL CkAiW_NextAiEvent(HCkAiW cHandle, int maxWaitMs, HCkStringBuilderW sbName, HCkStringBuilderW sbDelta);
```

Retrieves the next available AI streaming mode response update. Use the `PollAi` method to check if a response update is immediately accessible. The event name is returned in `sbName`. If the event name is `delta`, the text is returned in `sbDelta`.

For the complete raw event JSON, use the `GetLastJsonData` function. Note that the raw JSON format varies by AI provider.

Each AI provider (e.g., OpenAI, Claude, xAI) sends a unique set of events. Some of these events mark the start and end of sections and content parts, while others do not. Chilkat standardizes these events and returns the following event types.

- `response_created` — The server acknowledges the request and has created a response object. Nothing has been streamed yet — it’s just the signal that the response pipeline is open.
- `empty` — Some AI providers send empty heartbeat / keep-alive updates to ensure the stream stays open and proxies don't time out.
- `output_item_added` — A new output item has been added to the response. An “output item” is a top-level container — could be text, tool call, or other structured content.
- `content_part_added` — Within the output item, the model starts a new content part. A content part is typically a segment of a specific type (e.g., text, JSON snippet, or image reference).
- `delta` — These are the incremental text tokens being streamed. Each delta contains the next piece of text (like characters or words). You’ll see many of these in sequence while the model is generating.
- `output_text_done` — Marks the end of the text streaming for that content part. No more deltas will arrive for this part.
- `content_part_done` — Closes the current content part. Tells you the model is finished with that segment (e.g., done streaming a paragraph).
- `output_item_done` — Closes the current output item entirely. Means that item is fully complete (all its parts are done).
- `response_completed` — The entire response object is finished. No more items will be added, and the stream will soon close.
- `null_terminator` — The stream is closed. All streaming responses end with a single null_terminator.
- `function_call` — (starting in **v11.4.0**) The AI model is requesting a function call. This is for **manual tool calling**.
- `js_function_call` — (starting in **v11.4.0**) The AI model is requesting a function call that Chilkat can execute automatically. Call `StreamingJsToolCall` to run it. This covers both **JavaScript** tools (`RegisterJsTools`) and **MCP** tools (`UseMcp`).
- `web_search_call` — (starting in **v11.6.0**) The AI provider is performing a server-side web search while generating the response. This is an informational progress event (useful for showing a "Searching the web…" indicator); the application takes no action. The retrieved sources are available from `GetSearchResults` after the response completes.

`maxWaitMs` defines the maximum wait time to receive the complete event. For instance, if `PollAi` signals an available streaming update but only part of the event JSON has been received, the rest is probably on its way. In such cases, this method must wait to receive the entire JSON.

Returns TRUE for success, FALSE for failure.

### Ai.PollAi

`Chilkat 11.7.0 · wc · Ai · PollAi · method · since 11.2.0`

```c
int CkAiW_PollAi(HCkAiW cHandle, BOOL abort);
```

Returns immediately with one of the following values:

`-1` - Error  
`0` - No streaming event updates are available.  
`1` - A streaming event updates is ready for retrieval via `NextAiEvent`  
`2` - The streaming AI response has already completed, or no streaming response is ongoing.

If `abort` is `TRUE`, then the streaming response is aborted and this method returns the value `2`. Applications should pass in `FALSE` for `abort` to continue streaming.

### Ai.RegisterJsTools

`Chilkat 11.7.0 · wc · Ai · RegisterJsTools · method · since 11.4.0`

```c
BOOL CkAiW_RegisterJsTools(HCkAiW cHandle, HCkStringBuilderW sb, BOOL evalOnly, BOOL allowAllKeyword);
```

Adds JavaScript tool functions to the AI. This function can be called multiple times to add tool functions from multiple JavaScript sources. The JavaScript is passed in `sb`. If `evalOnly` is `TRUE`, then the `sb` contains JavaScript to be run for the purpose of adding supporting functions and does not contain a `toolRegistry`.

The `allowAllKeyword` indicates whether the `all` keyword is allowed in the `toolPermissions`. If multiple JavaScript tool sources are loaded with several calls to RegisterJsTools, we may not want one to clobber the permissions needed by another. The application can ensure this doesn't happen by setting this property to `FALSE`.

Returns TRUE for success, FALSE for failure.

### Ai.RegisterManualTools

`Chilkat 11.7.0 · wc · Ai · RegisterManualTools · method · since 11.4.0`

```c
BOOL CkAiW_RegisterManualTools(HCkAiW cHandle, HCkJsonObjectW json);
```

Sets the tools JSON for AI requests.

Returns TRUE for success, FALSE for failure.

### Ai.SetAskParams

`Chilkat 11.7.0 · wc · Ai · SetAskParams · method · since 11.3.0`

```c
BOOL CkAiW_SetAskParams(HCkAiW cHandle, HCkJsonObjectW json);
```

Sets additional `Ask` params such as:

- `effort` (see below)
- `max_output_tokens` (see below)
- `max_tool_iterations` - `v11.4.0` Applies only to automatic JavaScript tool function calls. Sets a maximum number of AI model tool responses that can be received. The default is `5`. This is to prevent an unlikely and unexpected infinite cycle of AI model tool responses and automatic tool calling.
- `temperature` (see below)
- `web_search` - `v11.6.0` A JSON object that enables provider-hosted web search (also called "grounding") so the model can retrieve live results and answer with citations. See below.
`verbose_ai_logging - v11.4.0 Adds even more detailed logging to the LastErrorText , more than what is added when the VerboseLogging property is enabled.`

---

`effort`

The `effort` can be set to `none`, `minimal`, `low`, `medium`, or `high`.

Chilkat will automatically convert `"effort"` to the correct JSON member name and value based on the AI provider.

| API / Provider | JSON Member for Effort |
| --- | --- |
| OpenAI Responses API | `reasoning.effort` → `none\|minimal\|low\|medium\|high` |
| Anthropic Claude | `output_config.effort` → `low\|medium\|high` |
| Google Gemini | `generationConfig.thinkingConfig.thinkingLevel` → `LOW\|HIGH` |
| OpenAI Chat Completions | `reasoning_effort` → `none\|minimal\|low\|medium\|high` |

---

`max_output_tokens`

Max output tokens simply limit how long the model’s response is allowed to be. It’s just a cap — the model may use fewer, but cannot exceed it.

Chilkat will automatically convert `"max_output_tokens"` to the correct JSON member name based on the AI provider.

| API / Provider | JSON Member for Max Tokens |
| --- | --- |
| OpenAI Responses API | `max_output_tokens` |
| Anthropic Claude | `max_tokens` |
| Google Gemini | `generationConfig.maxOutputTokens` |
| OpenAI Chat Completions | `max_completion_tokens` |

**Typical limits (approximate)**

Different AI providers enforce different maximum *output* sizes:

| Provider / Model | Typical Max Output Tokens |
| --- | --- |
| OpenAI GPT-4, GPT-4 Turbo | ~4,096–8,192 tokens |
| OpenAI GPT-5 / GPT-5.1 | Often ~8,192–16,384 tokens (varies by deployment) |
| OpenAI o-series (o1, o1-mini, o3) | ~4,096–8,192 tokens |
| Anthropic Claude 3 / 3.5 | ~4,096 tokens (fixed; cannot request more) |
| Google Gemini 1.5 | ~8,192–16,384 tokens |
| xAI Grok 1.5 | ~2,048–4,096 tokens |
| Ollama / local models | Usually 1,024–4,096 depending on model size |

---

`temperature`

Most modern AI APIs (including OpenAI’s) allow a `temperature` range from 0.0 to 2.0. Chilkat will ignore and not send a `temperature` having a value outside this range.

Here’s the breakdown:

- **0.0 → 1.0:** Traditional range used by older models and most examples.
- **>1.0 up to 2.0:** Expands randomness even further. Outputs can become highly creative, unusual, or less controlled.

**Practical guidance:**

> | Temperature | Behavior |
> | --- | --- |
> | **0.0** | Fully deterministic. Same prompt → same answer. |
> | **0.1–0.5** | Focused, safe, factual, ideal for coding and instructions. |
> | **0.6–1.0** | Creative but still coherent. Great for writing or brainstorming. |
> | **1.1–2.0** | Very creative, exploratory, sometimes chaotic; useful for idea generation or stylistic experimentation. |

The valid range is technically 0.0 to 2.0, but the commonly useful range is usually 0.0 to ~1.2 for most applications.

---

`web_search` (starting in `v11.6.0`)

The `web_search` param is a JSON object that turns on the AI provider's *server-side* web search tool. The provider performs the search while generating the response, and the model answers using the retrieved results. After the `Ask`, the retrieved sources can be obtained by calling `GetSearchResults` .

Example:

```
{
  "web_search": {
    "enabled": true,
    "max_uses": 3,
    "allowed_domains": [ "wikipedia.org", "nasa.gov" ],
    "blocked_domains": [ ],
    "recency": "week",
    "user_location": {
      "country": "US",
      "city": "Chicago",
      "region": "Illinois",
      "timezone": "America/Chicago"
    }
  }
}
```

Chilkat maps each field to the equivalent option for the selected `Provider` and silently ignores fields the provider does not support. Only `enabled` is required; every other field is optional.

- `enabled` — If `true`, web search is offered to the model for this `Ask`. For `perplexity`, search is always on, so this is a no-op.
- `max_uses` — The maximum number of searches the model may perform while answering. This is the primary cost-control knob (see the billing note below).
- `allowed_domains` — An array of domains. When present, search results are restricted to these domains.
- `blocked_domains` — An array of domains to exclude from results. Do not specify both `allowed_domains` and `blocked_domains` in the same request unless the provider permits it.
- `recency` — Limits results by age. Possible values are `day`, `week`, `month`, or `year`.
- `user_location` — An optional object with `country`, `city`, `region`, and `timezone` members used to localize results.

**Provider support matrix**

| Field | openai | claude | google | xai | perplexity |
| --- | --- | --- | --- | --- | --- |
| `enabled` | web_search tool | web_search tool | google_search | web_search tool | always on |
| `max_uses` | — | ✓ | — | — | — |
| `allowed_domains` | ✓ | ✓ | — | ✓ | ✓ |
| `blocked_domains` | — | ✓ | — | ✓ | ✓ |
| `recency` | — | — | — | — | ✓ |
| `user_location` | ✓ | ✓ | — | — | — |

**xAI (Grok):** Web search uses xAI's Agent Tools API on the Responses endpoint. Chilkat automatically routes a Grok web search request to that endpoint, so a web-search-capable Grok model (for example `grok-4.5`) is required. For Grok, only `allowed_domains` and `blocked_domains` (each limited to 5 domains, and mutually exclusive) are supported. xAI's older chat-completions "Live Search" is deprecated.

**Not supported:** `deepseek` and `mistral` (chat) do not expose a web search tool. If `web_search` is set for these providers, the `Ask` proceeds without search and a note is written to the `LastErrorText` . This keeps provider-switching code working when only the `Provider` property changes.

**Billing note:** Most providers bill web searches separately from tokens (typically per 1,000 searches). Use `max_uses` where supported to bound per-request cost.

**Streaming:** When `Streaming` is enabled, a `web_search_call` event is delivered through `NextAiEvent` while the provider performs a search.

Returns TRUE for success, FALSE for failure.

### Ai.SetConnectionSettings

`Chilkat 11.7.0 · wc · Ai · SetConnectionSettings · method · since 11.2.0`

```c
BOOL CkAiW_SetConnectionSettings(HCkAiW cHandle, HCkSocketW sock);
```

This method copies connection settings, including HTTP proxy, SOCKS proxy, network interface IP address, and other related settings from `sock`. It's optional; if not used, default settings apply. Call this method before sending REST API requests to an AI provider.

Returns TRUE for success, FALSE for failure.

### Ai.SetOutputSchema

`Chilkat 11.7.0 · wc · Ai · SetOutputSchema · method · since 11.6.0`

```c
BOOL CkAiW_SetOutputSchema(HCkAiW cHandle, const wchar_t *name, HCkJsonObjectW schema, BOOL strict);
```

Requests schema-constrained JSON output (structured output) for subsequent calls to `Ask`. `name` is a short schema name (letters, digits, underscores, and hyphens) used as an identifier by some providers. `schema` is the desired output shape as a JSON Schema. `strict` (strict) requests strict conformance where the provider supports it.

Pass an empty string for `name` to clear a previously-set schema, which disables structured output.

When `strict` (strict) is `TRUE`, Chilkat automatically augments the schema for the providers that require it — adding `"additionalProperties": false` and marking every property `required` on each object — so an ordinary JSON Schema can be supplied. For example, `schema` might be:

```
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "age"]
}
```

After `Ask`, the model's JSON is available as text from `GetOutputText` or parsed from `GetOutputJson` .

**Provider support:** OpenAI, Anthropic Claude, Google Gemini, xAI Grok, Mistral, and Perplexity return schema-conforming JSON. DeepSeek supports JSON-object mode only (a valid JSON object is returned, but the schema is not enforced).

Returns TRUE for success, FALSE for failure.

### Ai.SetProviderParams

`Chilkat 11.7.0 · wc · Ai · SetProviderParams · method · since 11.3.0`

```c
BOOL CkAiW_SetProviderParams(HCkAiW cHandle, HCkJsonObjectW json);
```

Sets additional provider params needed for some pre-defined providers. As of this current version, the possible params are:

1. `azure.clientId`, a GUID/UUID such as 17280f2d-f709-4a7b-af1d-9928190e13cf
2. `azure.clientSecret`, such as UZc8Q~YBrRIgfe_zbAOwWV.8ikuHa3JJF7LvCdt.
3. `azure.tenantId`, a GUID/UUID such as aa4b5625-a31f-44dd-94ec-e2f6c0c64d2c
4. `azure.location`, such as `eastus`
5. `azure.subscription`, a GUID/UUID such as 4abd4bf6-5260-4795-90f6-1e91ce4f582c

Returns TRUE for success, FALSE for failure.

### Ai.SleepMs

`Chilkat 11.7.0 · wc · Ai · SleepMs · method · since 11.2.0`

```c
void CkAiW_SleepMs(HCkAiW cHandle, int millisec);
```

This method is provided for convenience. It causes the calling thread to sleep for a number of milliseconds.

### Ai.StreamingJsToolCall

`Chilkat 11.7.0 · wc · Ai · StreamingJsToolCall · method · since 11.4.0`

```c
BOOL CkAiW_StreamingJsToolCall(HCkAiW cHandle, HCkStringBuilderW sb);
```

Handles a `js_function_call` event within a streaming `Ask` response loop by automatically executing the requested tool and adding its result to the conversation. The tool may be a JavaScript tool (registered with `RegisterJsTools`) or an MCP tool (registered with `UseMcp`).

Returns TRUE for success, FALSE for failure.

Async variant: `StreamingJsToolCallAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.UploadFile

`Chilkat 11.7.0 · wc · Ai · UploadFile · method · since 11.4.0`

```c
BOOL CkAiW_UploadFile(HCkAiW cHandle, const wchar_t *path, const wchar_t *mimeType, const wchar_t *outStr);
const wchar_t *CkAiW_uploadFile(HCkAiW cHandle, const wchar_t *path, const wchar_t *mimeType);
```

Uploads a file and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The `mimeType` specifies the MIME type, such as "application/pdf" or "text/plain". If `mimeType` is the emptys string, Chilkat will automatically choose the MIME type based on the filename extension.

Returns TRUE for success, FALSE for failure.

Async variant: `UploadFileAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.UploadFileBd

`Chilkat 11.7.0 · wc · Ai · UploadFileBd · method · since 11.4.0`

```c
BOOL CkAiW_UploadFileBd(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *filename, const wchar_t *mimeType, const wchar_t *outStr);
const wchar_t *CkAiW_uploadFileBd(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *filename, const wchar_t *mimeType);
```

Uploads the contents of `bd` and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The `filename` is mostly informational. The `mimeType` specifies the MIME type, such as "application/pdf" or "text/plain". If `mimeType` is the emptys string, Chilkat will automatically choose the MIME type based on the extension of the filename passed in `filename`.

Returns TRUE for success, FALSE for failure.

Async variant: `UploadFileBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.UploadFileSb

`Chilkat 11.7.0 · wc · Ai · UploadFileSb · method · since 11.4.0`

```c
BOOL CkAiW_UploadFileSb(HCkAiW cHandle, HCkStringBuilderW sb, const wchar_t *filename, const wchar_t *mimeType, const wchar_t *outStr);
const wchar_t *CkAiW_uploadFileSb(HCkAiW cHandle, HCkStringBuilderW sb, const wchar_t *filename, const wchar_t *mimeType);
```

Uploads the contents of `sb` and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The `filename` is mostly informational. The `mimeType` specifies the MIME type, such as "application/pdf" or "text/plain". If `mimeType` is the emptys string, Chilkat will automatically choose the MIME type based on the extension of the filename passed in `filename`. It is the utf-8 byte representation of the string that is uploaded.

Returns TRUE for success, FALSE for failure.

Async variant: `UploadFileSbAsync` — same arguments, returns a `Task` (see Async variants below).

### Ai.UseMcp

`Chilkat 11.7.0 · wc · Ai · UseMcp · method · since 11.6.0`

```c
BOOL CkAiW_UseMcp(HCkAiW cHandle, HCkMcpW cMcp, const wchar_t *namePrefix);
```

Registers the tools provided by the connected MCP (Model Context Protocol) server `cMcp` so the AI model can call them during a conversation. This lists the server's tools (a network operation) and namespaces each tool name using the prefix in `namePrefix` (to avoid collisions between servers and with JavaScript tools).

When the model requests one of these tools, Chilkat automatically routes the call to the MCP server via `Mcp.CallTool`, adds the result to the conversation, and continues the `Ask`. An informational `ProgressInfo` event named `McpToolCall` (value = the qualified tool name) is emitted for each automatic call. MCP tools may be mixed with JavaScript tools (`RegisterJsTools`) in the same conversation.

The `cMcp` `Mcp` object must already be connected (see `Mcp.Connect`) and must remain valid for as long as its tools are in use. Tool use requires a conversation; it cannot be used with a stateless query.

Returns TRUE for success, FALSE for failure.

Async variant: `UseMcpAsync` — same arguments, returns a `Task` (see Async variants below).

## Events and callbacks

This binding delivers progress information through callbacks (AbortCheck, PercentDone, ProgressInfo, TaskCompleted) rather than events. See `guide.md` for how to attach them in Unicode C.

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```c
HCkTaskW CkAiW_AskAsync(HCkAiW cHandle, const wchar_t *outputType);
HCkTaskW CkAiW_GetModelsAsync(HCkAiW cHandle, HCkStringTableW st);
HCkTaskW CkAiW_StreamingJsToolCallAsync(HCkAiW cHandle, HCkStringBuilderW sb);
HCkTaskW CkAiW_UploadFileAsync(HCkAiW cHandle, const wchar_t *path, const wchar_t *mimeType);
HCkTaskW CkAiW_UploadFileBdAsync(HCkAiW cHandle, HCkBinDataW bd, const wchar_t *filename, const wchar_t *mimeType);
HCkTaskW CkAiW_UploadFileSbAsync(HCkAiW cHandle, HCkStringBuilderW sb, const wchar_t *filename, const wchar_t *mimeType);
HCkTaskW CkAiW_UseMcpAsync(HCkAiW cHandle, HCkMcpW cMcp, const wchar_t *namePrefix);
```

## Related classes

[`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/BinData.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/JsonObject.md), [`Mcp`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/Mcp.md), [`Socket`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/Socket.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/StringBuilder.md), [`StringTable`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/StringTable.md)

