LlmAskModel

LlmAskModel Function

BOOL WINAPI LlmAskModel (

DWORD dwProviderId,

LPCTSTR lpszBaseUrl,

LPCTSTR lpszModelName,

LPCTSTR lpszApiKey,

LPCTSTR lpszPrompt,

LPTSTR lpszResponse,

INT nMaxLength

);

The LlmAskModel function sends a single prompt to a model and returns the generated response without requiring the application to manage a client session.

Parameters

dwProviderId

Specifies the service provider. This parameter must be one of the LLM_PROVIDER constants. See the remarks below for more information about service providers.

lpszBaseUrl

A pointer to a null-terminated string that specifies the base URL for the provider endpoint. This parameter may be NULL to use the default endpoint for the selected provider. Some providers, such as Microsoft Foundry or local services, require a specific base URL.

lpszModelName

A pointer to a null-terminated string that specifies the model name to use for the session. This parameter may be NULL to use the provider default model, if one is defined. Providers without a default model require an explicit model name. This typically includes models accessed using the Microsoft Foundry or locally hosted inference providers.

lpszApiKey

A pointer to a null-terminated string that specifies the API key used to authenticate with the provider. The API key may be provided using a literal string, an environment variable, or a value stored in the Windows Credential Manager. Using an environment variable or secure credential storage is recommended for production applications to avoid exposing sensitive information in source code or application binaries.

lpszPrompt

A pointer to a null-terminated string which specifies the prompt which should be sent to the model. This parameter cannot be NULL or a zero-length string. If the string consists only of whitespace characters, or contains invalid Unicode or non-text data, this function will fail.

lpszResponse

A pointer to a string buffer which will contain the model's response to the prompt. The response will always be null terminated and if the buffer is not large enough to store the complete response, the response will be truncated. When the function is called, this buffer is always initialized to an empty string and will contain the response if the function returns successfully.

nMaxLength

An integer which specifies the maximum number of characters which can be copied into the response buffer, including the terminating null character. If the length is an invalid value, such as zero or a negative number, the function will fail.

Return Value

If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call LlmGetLastError.

Remarks

The LlmAskModel function provides a simplified way to send a single prompt to a model and return the generated response. It does not require a client handle. It creates a connection using the default options and timeout period, sends the request and then closes the connection. This function manages the session automatically and is intended for simple request and response operations.

This function does not preserve conversation history between calls. Applications which require conversational context, persistent connections or advanced session management should create a session using the LlmConnect function and then send prompts using the LlmSendMessage function.

The dwProviderId parameter specifies the numeric identifier assigned to a supported provider. Refer to the providers page for a list of supported service providers and their default models.

If the lpszBaseUrl parameter is NULL or a zero-length string, the library will use a provider-specific default endpoint. Some providers, such as Microsoft Foundry services or locally hosted models, require an explicit endpoint and will fail if one is not provided.

If the lpszModelName parameter is NULL or a zero-length string, the library will attempt to use a default model for the selected provider. Not all providers define a default model, and in those cases an explicit model name must be provided when establishing the connection. This typically includes models accessed using the Microsoft Foundry or locally hosted inference providers.

If the service provider requires authentication, the API key can be provided in several formats, allowing applications to provide credentials in a way that balances convenience and security:

Literal string
The API key is provided directly as a string. This is the simplest approach and is convenient for testing or small internal tools, but it is not recommended for production applications. A literal key may be exposed in source code, configuration files, diagnostic logs or the compiled application binary.

Environment variable
The name of an environment variable enclosed in percent symbols, for example "%OPENAI_API_KEY%". The value of the environment variable is used as the API key. This avoids embedding the key directly in the application and is useful for development, scripts and deployment environments. However, environment variables may still be visible to the current user, inherited by child processes or exposed through system configuration, so they should still be protected appropriately.

Windows credential
A credential name enclosed in braces, for example "{MyAppName/OpenAI}". The API key is retrieved from the Windows Credential Manager using the specified name. This is the recommended approach for most Windows applications because the secret is stored outside the application and managed by the operating system. The credential can be created manually using Credential Manager, or programmatically by the application using the Windows Credential Management API. Applications should choose a unique credential name and document it clearly if users or administrators are expected to configure the value themselves.

For production applications, it is recommended that you avoid using literal API key strings and instead use an environment variable or a value stored in the Windows Credential Manager. If you must provide the API key as a literal string, you should take additional steps to protect it, such as storing the key in an encrypted form and limiting access to authorized users or processes. Avoid embedding API keys directly in application source code, configuration files, installers or other content that could be exposed through version control systems, logs or public repositories.

This function will block the calling thread until the server returns a response or the default timeout period has elapsed. Larger or more complex models may take longer to generate a response. Locally hosted models may also take longer to respond than cloud-based models, depending on the model type and size.

Example

#include "cstools12.h"
#include <stdio.h>

int _tmain(void)
{
    // Initialize the SocketTools library
    if (!LlmInitialize(CSTOOLS12_LICENSE_KEY, NULL))
    {
        _tprintf(_T("Initialization failed: %lu\n"), LlmGetLastError());
        return 1;
    }

    LPCTSTR lpszPrompt = _T("What is the capital of the state of California?");
    TCHAR szResponse[4096] = _T("");

    // Use a locally hosted model with LM Studio
    BOOL bResult = LlmAskModel(
            LLM_PROVIDER_LOCAL,              // Local provider
            _T("http://127.0.0.1:1234/v1/"), // Localhost endpoint
            _T("nvidia/nemotron-3-nano-4b"), // Model name
            NULL, 
            lpszPrompt,
            szResponse,
            _countof(szResponse));

    if (bResult)
    {
        _tprintf(_T("The response was %d characters:\n"), lstrlen(szResponse));
        _putts(szResponse);
    }
    else
    {
        DWORD dwError = LlmGetLastError();
        _tprintf(_T("Request failed, error %lu\n"), dwError);
    }

    LlmUninitialize();
    return 0;
}

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools12.h
Import Library: csllmv12.lib
Unicode: Implemented as Unicode and ANSI versions

Parameters

Return Value

Remarks

Example

Requirements

See Also