Chilkat.Ai Class Overview
Chilkat.Ai provides a unified interface for sending prompts, multimodal inputs, conversations, streaming requests, file references, and tool calls to AI providers such as OpenAI, Google Gemini, Claude, DeepSeek, Perplexity, Mistral, xAI, and custom OpenAI-compatible or provider-specific endpoints.
What the Class Is Used For
Use Chilkat.Ai when an application needs a single API for interacting with different AI providers. The class manages provider selection, API keys, model selection, conversations, accumulated inputs, multimodal content, streaming events, manual function tools, automatic JavaScript tools, uploaded files, and provider-specific request parameters.
Unified Provider API
Use one class with providers such as openai,
google, claude,
deepseek, perplexity,
mistral, and xai.
Text and Multimodal Input
Add text, images, image URLs, file data, file URLs, and uploaded file references
before calling Ask.
Conversation Management
Create, select, export, import, list, and delete named conversations.
Streaming and Tools
Stream model output, process events, handle manual function calls, or register
automatic JavaScript tools.
Typical Workflow: Simple Ask
- Set Provider to the desired AI provider, or set it to custom and configure BaseUrl and ApiSpec.
- Set ApiKey, or enable EnableSecrets and provide a secret specifier.
- Set Model. Chilkat does not guess or default to a model.
- Add input with InputAddText or InputAddTextSb.
- Call Ask with an output type such as text. Starting in v11.4.0, image may be used with providers that support conversational image output.
- Retrieve the response using GetOutputText, GetOutputTextSb, or GetOutputBd.
- Check ResponseStatusCode and LastErrorText when troubleshooting.
Provider Configuration
| Member | Purpose | Guidance |
|---|---|---|
| Provider | Selects the AI provider. | Supported values include openai, google, claude, deepseek, perplexity, mistral, xai, and custom. The default is openai. |
| Model | Specifies the model to use. | Must be set explicitly. Use GetModels to list models available to the account. |
| ApiKey | API key used for authentication. | Use the API key matching the selected provider. Consider storing it with Chilkat.Secrets. |
| EnableSecrets | Allows a secret specifier to be used instead of the raw API key. | When true, ApiKey may contain a secret specifier such as !!part1|part2|.... |
| BaseUrl | Provider base URL. | Automatically set for known providers. For custom, set this explicitly. |
| ApiSpec | API specification used for request formatting. | Possible choices include ChatCompletions, Responses, Gemini, and Anthropic. |
| ApiKeyHeader | Custom API key header name. | For custom providers only, use this when the API key belongs in a custom header rather than an Authorization: Bearer header. |
| SetProviderParams | Sets provider-specific parameters. | Supports additional provider values such as Azure client, tenant, location, and subscription parameters where needed. |
Conversations and Transcript Style
The class can be used statelessly, or it can maintain named conversations. A selected conversation is updated with each input and output. Conversations can also be exported and imported as JSON.
| Member | Purpose | Important Details |
|---|---|---|
| NewConvo | Creates and initializes a named conversation. | Accepts a system message and developer message. The first created conversation is automatically selected. |
| SelectedConvo | Selects the active conversation. | Empty string means stateless querying. Selecting a non-existent conversation does not change the current selection. |
| HostedConvo | Uses provider-hosted conversation state when available. | If true, only the conversation ID is sent with each query. If false, the full transcript is sent with each query. |
| FullTranscript | Controls how previous multimodal inputs are represented. | If false, later turns send summaries for prior files/images. If true, the full file data, image data, URLs, or file URLs are re-sent. |
| ExportConvo | Exports a conversation to JSON. | Pass * to export the currently selected conversation. |
| ImportConvo | Imports a conversation from JSON. | Assigns the imported transcript to the provided conversation name. |
| ListConvos | Lists conversation names. | Returns names in a StringTable. |
| DeleteConvo | Deletes one or more conversations. | Pass * to delete all conversations. |
Cost and context tradeoff:
FullTranscript = true guarantees the model receives
prior multimodal data again, but it can be more expensive. The default summarized
style is usually more efficient.
Adding Input
| Input Type | Methods | Notes |
|---|---|---|
| Text | InputAddText, InputAddTextSb | Adds text to the accumulated input for the next Ask. |
| Image data | InputAddImageData | Adds JPEG, PNG, or WebP image data from BinData. Not usable with DeepSeek. |
| Image URL | InputAddImageUrl | Adds an image URL. Not usable with DeepSeek. |
| Uploaded image reference | InputAddImageFileId | References a previously uploaded image. At the documented time, OpenAI and Google support the upload-once and reuse workflow for images. |
| File data | InputAddFileData | Adds file data such as a PDF from BinData. Not usable with DeepSeek. |
| File URL | InputAddFileUrl | Adds a file located at a URL. Not usable with DeepSeek. |
| Uploaded file reference | InputAddFileId | References a previously uploaded file by provider file ID and MIME type. |
| Function result | InputAddFnResult | Supplies the result of a manual function call back to the model. |
| Clear pending input | InputClear | Clears inputs that would be sent in the next call to Ask. |
Input lifecycle:
Accumulated outputs are cleared when Ask begins.
Accumulated inputs are cleared after Ask returns
successfully.
Asking and Reading Output
| Method / Property | Purpose | Guidance |
|---|---|---|
| Ask | Sends the current input and receives the model output. | Use text for text output. Starting in v11.4.0, image may be used with providers that support conversational image output. |
| GetOutputText | Returns text output from the last Ask. | Use for ordinary text responses. |
| GetOutputTextSb | Appends text output to a StringBuilder. | Use when accumulating output into an existing text buffer. |
| GetOutputBd | Returns binary output from the last Ask. | Use for binary outputs such as AI-generated images. |
| ResponseStatusCode | HTTP status code for the last Ask. | 0 means no HTTP response was received, 200 means success, and 400+ indicates a failed provider response. |
Streaming Responses
When Streaming is true, Ask returns immediately after sending the request. The application then uses PollAi and NextAiEvent to receive streaming updates.
| Member | Purpose | Important Details |
|---|---|---|
| Streaming | Enables streaming mode. | Default is false. When true, use polling and event retrieval to receive the response. |
| PollAi | Checks whether a streaming update is available. | Returns 1 when an event is ready, 0 when none is ready, 2 when streaming has completed or no stream is ongoing, and -1 on error. |
| NextAiEvent | Retrieves the next streaming event. | Returns the standardized event name and delta text when the event is delta. |
| StreamingJsToolCall | Handles a streaming JavaScript tool call event. | Used when a streaming response includes a js_function_call event. |
Standardized Streaming Event Types
| Event | Meaning |
|---|---|
| response_created | The provider has created a response object and opened the response pipeline. |
| empty | Heartbeat or keep-alive update. |
| output_item_added | A new top-level output item has been added. |
| content_part_added | A new content part has started within an output item. |
| delta | Incremental streamed text. |
| output_text_done | Text streaming for the current content part has ended. |
| content_part_done | The current content part is complete. |
| output_item_done | The current output item is complete. |
| response_completed | The entire response is complete. |
| null_terminator | The stream is closed. |
| function_call | Manual tool-calling request from the model. |
| js_function_call | Automatic JavaScript tool-calling request from the model. |
Tools and Function Calling
| Tool Mode | Members | Workflow |
|---|---|---|
| Manual function tools | RegisterManualTools, HasFunctionCalls, GetFunctionCalls, InputAddFnResult | Register tool definitions, ask the model, inspect returned function calls, execute the function in application code, and send the result back with InputAddFnResult. |
| Automatic JavaScript tools | RegisterJsTools, StreamingJsToolCall, JsToolTimeout | Register JavaScript tool functions and allow Chilkat to handle JavaScript tool execution, subject to permissions and timeout settings. |
Manual vs automatic tools:
HasFunctionCalls and
GetFunctionCalls apply to manual function tool
calling, not automatic JavaScript tool calls.
File Upload and Reuse
| Method | Uploads | Use With |
|---|---|---|
| UploadFile | A local file path. | Returns a file ID or URI that can be referenced later with InputAddFileId. |
| UploadFileBd | File contents from BinData. | Returns a file ID or URI. The filename is mostly informational. |
| UploadFileSb | UTF-8 byte representation of StringBuilder content. | Returns a file ID or URI for later reference. |
Supported upload providers:
File uploads are supported for openai,
gemini, claude, and
grok. If the MIME type is empty, Chilkat chooses one
based on the filename extension.
Ask Parameters
Use SetAskParams to supply additional model request parameters. Chilkat maps common parameter names to the correct provider-specific JSON structure.
| Parameter | Purpose | Guidance |
|---|---|---|
| effort | Controls reasoning or thinking effort where supported. | Values may include none, minimal, low, medium, and high, depending on provider support. |
| max_output_tokens | Caps the length of the model response. | The provider may use fewer tokens, but cannot exceed the requested cap if accepted. |
| temperature | Controls output randomness. | Values from 0.0 to 2.0 are allowed. Values outside this range are ignored and not sent. |
| max_tool_iterations | Limits automatic JavaScript tool-call iterations. | Applies to automatic JavaScript tool calls. Default is 5. |
| verbose_ai_logging | Adds more AI request/response logging to diagnostics. | Starting in v11.4.0, adds more detail to LastErrorText than normal verbose logging. |
Connection, Timeout, and Diagnostics
| Member | Purpose | Guidance |
|---|---|---|
| SetConnectionSettings | Copies proxy and network settings from a Socket. | Use before sending provider API requests when HTTP proxy, SOCKS proxy, network interface IP, or related socket settings are needed. |
| IdleTimeoutMs | Maximum wait for additional incoming response data after transmission pauses. | This is not a total timeout. The default is 90 seconds in v11.3.0 and earlier, and 180 seconds starting in v11.4.0. |
| HeartbeatMs | Interval between AbortCheck callbacks. | Default is 0, meaning callbacks are disabled. |
| ResponseStatusCode | HTTP status code for the last Ask. | Use with LastErrorText to troubleshoot provider errors. |
| GetLastJsonData | Retrieves JSON details produced by selected methods. | For example, after GetModels, use this to access the raw JSON response. |
| LastErrorText | Diagnostic text for the last method or property access. | Check after failed or unexpected provider, model, streaming, tool, upload, or conversation behavior. |
Method Summary by Category
| Category | Members | Purpose |
|---|---|---|
| Provider setup | Provider, Model, ApiKey, BaseUrl, ApiSpec, SetProviderParams | Select the provider, endpoint, API style, model, and provider-specific options. |
| Input | InputAddText, InputAddImageData, InputAddImageUrl, InputAddFileData, InputAddFileUrl, InputAddFileId, InputClear | Add text, image, file, URL, and uploaded-file inputs for the next request. |
| Ask and output | Ask, GetOutputText, GetOutputTextSb, GetOutputBd | Send the model request and retrieve text or binary output. |
| Conversation management | NewConvo, SelectedConvo, ListConvos, ExportConvo, ImportConvo, DeleteConvo | Create, select, persist, restore, list, or delete conversation transcripts. |
| Streaming | Streaming, PollAi, NextAiEvent, StreamingJsToolCall | Receive incremental model output and streaming tool-call events. |
| Tools | RegisterManualTools, GetFunctionCalls, InputAddFnResult, RegisterJsTools | Register and handle manual function tools or automatic JavaScript tools. |
| File upload | UploadFile, UploadFileBd, UploadFileSb | Upload files once and reference them in later requests. |
| Parameters and diagnostics | SetAskParams, GetModels, GetLastJsonData, ResponseStatusCode, LastErrorText | Control request behavior, inspect available models, and diagnose failures. |
Diagnostics and Troubleshooting
| Problem Area | Member | What to Check |
|---|---|---|
| No model response | Provider, Model, ApiKey, ResponseStatusCode | Confirm the provider, model, and API key are correct. A status code of 0 means no HTTP response was received. |
| Custom provider fails | Provider, BaseUrl, ApiSpec, ApiKeyHeader | Set Provider = "custom" and verify the endpoint, API specification, and API-key placement. |
| Streaming does not produce events | Streaming, PollAi, NextAiEvent | Make sure streaming mode is enabled before calling Ask, then poll for available events. |
| Images or files are rejected | InputAddImageData, InputAddFileData, Provider | Confirm the provider supports the input type. DeepSeek is documented as not supporting these image/file multimodal methods. |
| Function calls are not visible | HasFunctionCalls, GetFunctionCalls | These apply to manual function tools, not automatic JavaScript tools. |
| Tool loop continues too long | SetAskParams, JsToolTimeout | Use max_tool_iterations and JsToolTimeout to limit automatic JavaScript tool execution. |
| Need raw provider details | GetLastJsonData | Some methods, such as GetModels, provide raw JSON details through last JSON data. |
| Need operation details after failure | LastErrorText | Check diagnostic text after failed or unexpected ask, upload, streaming, model-listing, tool, conversation, or provider behavior. |
Common Pitfalls
| Pitfall | Better Approach |
|---|---|
| Forgetting to set Model. | Always set the model explicitly. Chilkat does not guess or default to a model. |
| Calling Ask again while a streaming request is still in progress. | Finish or abort the streaming response first. A new Ask cannot start while streaming is active. |
| Assuming every provider supports every input type. | Check provider support before using images, files, uploaded file references, tools, or image output. |
| Using raw API keys directly in code. | Store API keys with Chilkat.Secrets and enable EnableSecrets when appropriate. |
| Expecting HasFunctionCalls to apply to JavaScript tools. | Use it only for manual function tool calling. JavaScript tool calls follow the automatic JS tool workflow. |
| Sending large multimodal content repeatedly without considering cost. | Leave FullTranscript false unless full re-sending of prior files/images is required. |
| Ignoring provider HTTP status codes. | Check ResponseStatusCode and LastErrorText. |
Best Practices
| Recommendation | Reason |
|---|---|
| Set Provider, Model, and ApiKey explicitly. | These are the core settings needed for reliable provider requests. |
| Use GetModels to discover available models. | Model availability depends on the account and provider. |
| Use named conversations when context should persist across turns. | SelectedConvo allows future queries to update the same transcript. |
| Use summarized multimodal transcripts unless full resending is required. | This avoids repeatedly sending large file or image data. |
| Use streaming for responsive applications. | PollAi and NextAiEvent allow incremental response handling. |
| Limit automatic JavaScript tool behavior. | JsToolTimeout and max_tool_iterations prevent runaway tool loops. |
| Use SetConnectionSettings when proxies or network-interface settings are required. | It copies HTTP proxy, SOCKS proxy, network interface IP, and related settings from a Socket. |
| Check LastErrorText after failures. | It provides useful diagnostic detail for provider, network, streaming, tool, upload, and conversation failures. |
Summary
Chilkat.Ai is a unified AI client class for provider setup, model selection, text and multimodal input, conversations, streaming, manual function calling, automatic JavaScript tools, file upload and reuse, provider-specific request parameters, and detailed diagnostics.
The most important practical guidance is to set the provider, model, and API key deliberately; use Chilkat.Secrets for key storage when possible; choose stateless or named-conversation behavior intentionally; understand provider support for multimodal input and tools; use streaming for responsive output; and inspect ResponseStatusCode, GetLastJsonData, and LastErrorText when troubleshooting.