Ai Unicode C Reference Documentation
Ai
Current Version: 11.2.0
Chilkat’s AI API acts as a unified interface for working with multiple AI providers.
Instead of learning and coding separately for OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), XAi (Grok), DeepSeek, and Perplexity, etc., developers can use Chilkat’s consistent set of functions. Chilkat takes care of the differences between each provider’s REST API—such as authentication, request formatting, and response handling.
This has two main benefits:
- Cross-platform and multi-language support – The same Chilkat API works in many programming languages (C#, C++, Python, VB6, Delphi, etc.) and across Windows, Linux, macOS, etc.
- Simplified development – Developers can write code once and easily switch providers, or even support multiple providers, without rewriting everything for each vendor’s unique API.
In short: Chilkat provides a common wrapper over many AI REST APIs, making them uniform and portable across languages and operating systems.
Includes features such as:
- Conversation Handling Create, save, and select conversations to be stored locally. Conversations are automatically updated with responses, and the conversation history is provided in each request in a multi-turn conversation.
- Multimodal Inputs You can add text, image data, files, image URLs, file URLs etc. to requests.
- Streaming Support Instead of waiting for the full response, the Chilkat API can return partial results in real time (usually token by token or chunk by chunk). This is a faster perceived response (user sees text as it’s generated, like typing).
- Markdown to HTML Conversion method added to the Chilkat
StringBuilderclass to help with AI responses. Includes the ability to dostreaming markdown to HTML conversion.
Create/Dispose
HCkAiW instance = CkAiW_Create(); // ... CkAiW_Dispose(instance);
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.
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.
Callback Functions
Provides the opportunity for a method call to be aborted. If TRUE is returned, the operation in progress is aborted.
Return FALSE to allow the current method call to continue.
This callback function is called periodically based on the value of the HeartbeatMs property.
(If HeartbeatMs is 0, then no callbacks are made.) As an example, to make 5 AbortCheck callbacks per second, set the HeartbeatMs property equal to 200.
Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This callback is only called when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For methods that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).
This callback counts as an AbortCheck callback, and takes the place of the AbortCheck event when it fires.
The return value indicates whether the method call should be aborted, or whether it should proceed. Return TRUE to abort, and FALSE to proceed.
This is a general callback that provides name/value information about what is happening at certain points during a method call. To see the information provided in ProgressInfo callbacks, if any, write code to handle this event and log the name/value pairs. Most are self-explanatory.
Called in the background thread when an asynchronous task completes. (Note: When an async method is running, all callbacks are in the background thread.)
Properties
ApiKey
void CkAiW_putApiKey(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_apiKey(HCkAiW cHandle);
DebugLogFilePath
void CkAiW_putDebugLogFilePath(HCkAiW cHandle, const wchar_t *newVal);
const wchar_t *CkAiW_debugLogFilePath(HCkAiW cHandle);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
FullTranscript
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.
HeartbeatMs
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.
HostedConvo
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.
IdleTimeoutMs
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). This is not a total timeout, but the maximum time allowed when data transmission has paused.
topLastErrorHtml
const wchar_t *CkAiW_lastErrorHtml(HCkAiW cHandle);
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
const wchar_t *CkAiW_lastErrorText(HCkAiW cHandle);
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
const wchar_t *CkAiW_lastErrorXml(HCkAiW cHandle);
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
void CkAiW_putLastMethodSuccess(HCkAiW cHandle, BOOL newVal);
Indicates the success or failure of the most recent method call: TRUE means success, FALSE means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
Model
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.
topProvider
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, and xai.
The default value is openai.
ResponseStatusCode
The HTTP response status code for the last Ask is as follows:
0indicates an error occurred before receiving an HTTP response.200indicates a successful response.- A failed response has a status code of
400or higher.
SelectedConvo
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.
topStreaming
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.
UncommonOptions
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.
topVerboseLogging
void CkAiW_putVerboseLogging(HCkAiW cHandle, BOOL newVal);
If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
const wchar_t *CkAiW_version(HCkAiW cHandle);
Methods
Ask
Sends the current potentially multimodal input within the context of the selected conversation and receives the model's output. Currently, the desired outputType can only be text. Future versions of Chilkat will support image, audio, or a JSON schema to tell the model to return data in the specified JSON structured 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.
AskAsync (1)
Creates an asynchronous task to call the Ask method with the arguments provided.
Returns NULL on failure
DeleteConvo
Deletes the conversation by its name. If name equals * then all conversations are deleted.
ExportConvo
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.
GetLastJsonData
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 .
GetModels
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.
GetModelsAsync (1)
Creates an asynchronous task to call the GetModels method with the arguments provided.
Returns NULL on failure
GetOutputText
const wchar_t *CkAiW_getOutputText(HCkAiW cHandle);
Returns the text output from the last call to Ask.
Returns TRUE for success, FALSE for failure.
GetOutputTextSb
Returns the text output, appended to sb, from the last call to Ask.
Returns TRUE for success, FALSE for failure.
ImportConvo
Imports the conversation from json and assigns it the name in name.
topInputAddFileData
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.
InputAddFileUrl
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.
InputAddImageData
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.
InputAddImageUrl
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.
InputAddText
Adds text to the potentially multimodal input that will be sent in the next call to Ask.
Returns TRUE for success, FALSE for failure.
topInputAddTextSb
Adds text to the potentially multimodal input that will be sent in the next call to Ask.
Returns TRUE for success, FALSE for failure.
topInputClear
ListConvos
Returns the full list of conversation names in st.
topNewConvo
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 *.
NextAiEvent
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.
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.
PollAi
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.
Returns TRUE for success, FALSE for failure.
SetConnectionSettings
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.
topSleepMs
This method is provided for convenience. It causes the calling thread to sleep for a number of milliseconds.
Returns TRUE for success, FALSE for failure.
top