Gemini Class

Properties   Methods   Events   Config Settings   Errors  

Provides an easy way to generate content with, create embeddings from, and list models of the Google Gemini API.

Syntax

ipworksllm.gemini()

Remarks

The Gemini class provides a simple way to communicate with the Google Gemini API, the native API used by the Gemini family of models.

The class models the Gemini protocol directly rather than translating it into another vendor's shape, so every concept the API defines, such as content parts, the top level system instruction, generation configuration, and safety settings, is exposed as it actually appears on the wire.

Selecting an Endpoint

Unlike providers that name the model in the request body, the Gemini API names it in the request path, together with the operation being invoked. The ServerURL property supplies the base of that path, and a request URL is built as {ServerURL}/models/{Model}:{operation}.

By default, the class uses the official Google Gemini endpoint, https://generativelanguage.googleapis.com/v1beta. In most cases, the default endpoint is the correct choice. The ServerURL property should only be changed when connecting through a gateway or proxy that implements the Gemini API. No part of ServerURL is rewritten or normalized.

// Official Google service. The request URL becomes // https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent gemini.ServerURL = "https://generativelanguage.googleapis.com/v1beta"; gemini.APIKey = "..."; gemini.Model = "gemini-2.0-flash"; // A local or corporate gateway that exposes the same API. gemini.ServerURL = "https://llm-gateway.example.com/gemini/v1beta";

The APIKey property is sent as an x-goog-api-key header. When it is left empty, no x-goog-api-key header is sent at all, which supports gateways that inject credentials of their own.

Generating Content

A conversation is built up in the Contents collection, which holds a list of GeminiContent items. The AddContent method is a convenient way to append an item with a given Role (user or model) and Text.

The Gemini API does not accept a content item whose role is system. A system instruction is instead supplied through the SystemInstruction property, which is sent as a top level systemInstruction field alongside the conversation.

gemini.APIKey = "..."; gemini.Model = "gemini-2.0-flash"; gemini.SystemInstruction = "You are a concise assistant."; gemini.AddContent("user", "What is the capital of France?"); gemini.GenerateContent(); // The model's reply is now the last item in Contents. string reply = gemini.Contents[gemini.Contents.Count - 1].Text; Console.WriteLine(reply);

Content Parts

The Gemini API carries the content of every conversation item as an array of parts, each of which holds one member such as text, inlineData, functionCall, or functionResponse. For the common case, the Text field of a GeminiContent simply holds plain text, and the class wraps it in a single part automatically.

When richer content is needed, set Text to a raw JSON array of parts. If the value begins with [ after leading whitespace is ignored, the class sends it verbatim as the item's parts. This allows any part type supported by the API to be used without modeling each type separately.

The same rule applies in the opposite direction. When a reply consists of a single text part, the appended item holds just that text. When a reply contains multiple parts, or any part that is not text, the appended item holds the raw parts array, so that sending the conversation back to the model reproduces the model turn. For a streamed reply, all of the text that arrived is coalesced into a single leading text part, so the original ordering of text relative to interleaved parts such as functionCall is not preserved.

Note that a reply which carries no parts at all produces an appended item whose Text is empty. Such an entry should be removed, or filled in, before the conversation is sent again, because the API may reject a content item with no parts.

// Supplying an image alongside text, using the raw parts form. gemini.AddContent("user", "[{\"text\":\"What is in this picture?\"}," + " {\"inlineData\":{\"mimeType\":\"image/jpeg\"," + " \"data\":\"" + base64Image + "\"}}]"); gemini.GenerateContent();

Streaming

Setting the Stream property to True before calling GenerateContent sends the request to the streamGenerateContent operation, with the alt=sse query parameter that selects server-sent events. The ContentDelta event then fires once for each incremental fragment of text, reporting the fragment in Delta.

Once the stream completes, the fully assembled reply is appended to Contents and the FunctionCall event fires for any function call the reply contained, exactly as in the non streaming case.

gemini.Stream = true; gemini.OnContentDelta += (s, e) => { Console.Write(e.Delta); }; gemini.AddContent("user", "Write a short poem about the sea."); gemini.GenerateContent();

Function Calling

Tools give the model an opportunity to request that the calling application execute a function on its behalf. A tool is declared by first queuing its parameters with one or more calls to AddToolParam, then calling AddTool to consume the queued parameters and append a new GeminiTool item to the Tools collection. Each item is sent as one function declaration of the request's tools array.

When the model decides to call a function, its reply contains a functionCall part and the FunctionCall event fires once per part, providing the function Name and the ArgsJson arguments object the model produced.

To return the function's result, append an item with role user whose Text is a raw parts array holding a functionResponse part, then call GenerateContent again so the model can incorporate the result. The class does not build that part for the application, because the shape of a function's result is defined by the application, not by the API; the raw parts form is what makes it expressible.

gemini.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); gemini.AddTool("get_weather", "Gets the current weather for a location."); bool functionCalled = false; gemini.OnFunctionCall += (s, e) => { // Execute the requested function and append its result as a // 'functionResponse' part. string result = GetWeather(e.ArgsJson); gemini.AddContent("user", "[{\"functionResponse\":{\"name\":\"" + e.Name + "\"," + " \"response\":{\"result\":\"" + result + "\"}}}]"); functionCalled = true; }; gemini.AddContent("user", "What is the weather like in Boston?"); gemini.GenerateContent(); // If a function was called, FunctionCall fired and a 'functionResponse' item // was appended above. Calling GenerateContent again lets the model produce a // final answer. if (functionCalled) gemini.GenerateContent();

Safety Settings

The SafetySettings property holds the request's safetySettings array as raw JSON text, which is sent verbatim. Each element pairs a category with a threshold. Because the value is passed through untouched, every category and threshold the API defines is reachable, and categories added by the API later require no change to the class.

gemini.SafetySettings = "[{\"category\":\"HARM_CATEGORY_HARASSMENT\"," + " \"threshold\":\"BLOCK_ONLY_HIGH\"}," + " {\"category\":\"HARM_CATEGORY_HATE_SPEECH\"," + " \"threshold\":\"BLOCK_MEDIUM_AND_ABOVE\"}]";

When this property is left empty, the safetySettings field is omitted from the request entirely and the server's own defaults apply.

Embeddings and Listing Models

The CreateEmbedding method creates an embedding vector for every item of the Embeddings collection. All of the texts are sent to {ServerURL}/models/{selected model}:batchEmbedContents in a single request, and the OutputVector field of each item is set to the vector created for that item's InputText, as JSON text containing an array of floating point numbers. Because Google publishes models dedicated to embeddings, the EmbeddingModel configuration setting may be used to select one without disturbing the Model property used for generation.

gemini.Config("EmbeddingModel=gemini-embedding-001"); gemini.Embeddings.Add(new GeminiEmbedding("What is the meaning of life?")); gemini.Embeddings.Add(new GeminiEmbedding("How much wood would a woodchuck chuck?")); gemini.CreateEmbedding(); foreach (GeminiEmbedding embedding in gemini.Embeddings) { Console.WriteLine(embedding.OutputVector); }

The ListModels method sends a request to {ServerURL}/models and fires the ModelList event once for each model reported by the server. The Gemini API reports each model under its resource name, which carries a models/ prefix; either that value or the bare identifier that follows it may be assigned to Model. Note that the endpoint returns a single page of results; the class reports the models on that first page and does not follow the page token to subsequent pages.

gemini.OnModelList += (s, e) => { Console.WriteLine(e.Name + " (" + e.DisplayName + ")"); }; gemini.ListModels();

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

Gemini.APIKey Property

The API key used to authenticate with the endpoint.

Syntax

getAPIKey(): string | null;
setAPIKey(APIKey: string | null): void;

Default Value

""

Remarks

This property specifies the API key used to authenticate requests. When set, it is sent as an x-goog-api-key header.

When this property is left empty, no x-goog-api-key header is sent at all. This supports gateways placed in front of the API that supply credentials of their own.

This property is not available at design time.

Gemini.Contents Property

The conversation history sent to and returned from the model.

Syntax

getContents(): GeminiContentList;

Default Value

Remarks

This collection holds the list of GeminiContent items making up the conversation. Calling GenerateContent sends the entire collection and appends the model's reply to it.

The Gemini API accepts only the roles user and model here. A system instruction is supplied through the SystemInstruction property instead.

The AddContent method is a convenient way to append a new item to this collection without constructing a GeminiContent item directly.

This property is not available at design time.

Gemini.Embeddings Property

The texts to create embeddings for, and the vectors created for them.

Syntax

getEmbeddings(): GeminiEmbeddingList;

Default Value

Remarks

This collection holds the GeminiEmbedding items that CreateEmbedding sends to the server. Add one item for each piece of text and set its InputText; CreateEmbedding then sends all of the texts in a single request and sets the OutputVector of each item to the embedding vector created for its text.

CreateEmbedding never adds, removes, or reorders items, so the vector created for a text is always found in the same item as the text.

gemini.Embeddings.Add(new GeminiEmbedding("What is the meaning of life?")); gemini.Embeddings.Add(new GeminiEmbedding("How much wood would a woodchuck chuck?")); gemini.CreateEmbedding(); foreach (GeminiEmbedding embedding in gemini.Embeddings) { Console.WriteLine(embedding.OutputVector); }

Calling Reset clears this collection. Items of this collection are never added to Contents.

This property is not available at design time.

Gemini.Firewall Property

A set of properties related to firewall access.

Syntax

getFirewall(): Firewall | null;
setFirewall(firewall: Firewall | null): void;

Default Value

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the class will attempt to connect.

Gemini.MaxOutputTokens Property

The maximum number of tokens the model may generate in a reply.

Syntax

getMaxOutputTokens(): number;
setMaxOutputTokens(maxOutputTokens: number): void;

Default Value

0

Remarks

This property specifies an upper bound on the number of tokens the model may produce for a single reply. When the bound is reached, generation stops and the FinishReason configuration setting reports MAX_TOKENS.

When this property is left at 0 (the default), the maxOutputTokens field is omitted from the request's generationConfig object and the server's own default is used.

This property is not available at design time.

Gemini.Model Property

The model used when generating content.

Syntax

getModel(): string | null;
setModel(model: string | null): void;

Default Value

""

Remarks

This property specifies the identifier of the model that will process the request, for example gemini-2.0-flash. This property must be set before calling GenerateContent, and before calling CreateEmbedding unless the EmbeddingModel configuration setting supplies a model of its own.

The Gemini API names the model inside the request path, as {ServerURL}/models/{Model}:{operation}. A value that already carries the models/ resource name prefix, which is the form ModelList reports, is accepted as well; the prefix is not duplicated in the request path.

The ListModels method may be used to discover the model identifiers the endpoint accepts.

This property is not available at design time.

Gemini.Proxy Property

A set of properties related to proxy access.

Syntax

getProxy(): Proxy | null;
setProxy(proxy: Proxy | null): void;

Default Value

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

Gemini.SafetySettings Property

The raw JSON array of safety settings sent with the request.

Syntax

getSafetySettings(): string | null;
setSafetySettings(safetySettings: string | null): void;

Default Value

""

Remarks

This property holds the request's safetySettings array as raw JSON text, which is sent verbatim. Each element of the array is an object with a category and a threshold, which together adjust how aggressively the model blocks a category of content.

The value is passed through untouched, so every category and threshold the API defines is reachable without the class having to model each one.

gemini.SafetySettings = "[{\"category\":\"HARM_CATEGORY_HARASSMENT\"," + " \"threshold\":\"BLOCK_ONLY_HIGH\"}]";

In the Async Edition (nsoftware.async.IPWorksLLM), the property is set the same way and the request is awaited:

gemini.SafetySettings = "[{\"category\":\"HARM_CATEGORY_HARASSMENT\"," + " \"threshold\":\"BLOCK_ONLY_HIGH\"}]"; await gemini.GenerateContent();

When this property is left empty (the default), the safetySettings field is omitted from the request entirely and the server's own defaults apply.

This property is not available at design time.

Gemini.ServerURL Property

The base URL of the Gemini API endpoint.

Syntax

getServerURL(): string | null;
setServerURL(serverURL: string | null): void;

Default Value

"https://generativelanguage.googleapis.com/v1beta"

Remarks

This property specifies the base URL used to build request URLs. The Gemini API names the model inside the request path, so a request URL is formed as {ServerURL}/models/{Model}:{operation}, for example https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent.

No part of this value is rewritten, so endpoints that include or omit a version segment (such as /v1beta) are both supported.

By default, the class uses the official Google Gemini endpoint, https://generativelanguage.googleapis.com/v1beta. In most cases, the default endpoint is the correct choice. This property should only be changed when connecting through a gateway or proxy that implements the Gemini API.

This property is not available at design time.

Gemini.SSLAcceptServerCert Property

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

getSSLAcceptServerCert(): Certificate | null;
setSSLAcceptServerCert(SSLAcceptServerCert: Certificate | null): void;

Default Value

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

NOTE: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Gemini.SSLCert Property

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

getSSLCert(): Certificate | null;
setSSLCert(SSLCert: Certificate | null): void;

Default Value

Remarks

This property includes the digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Gemini.SSLProvider Property

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

getSSLProvider(): GeminiSSLProviders;
setSSLProvider(SSLProvider: GeminiSSLProviders): void;


enum GeminiSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, the platform implementation will be used by default in all cases in the JavaScript edition.

NOTE: The internal provider is not support at this time.

Gemini.SSLServerCert Property

The server certificate for the last established connection.

Syntax

getSSLServerCert(): Certificate | null;

Default Value

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Gemini.StopSequences Property

A comma-separated list of sequences where the model should stop generating.

Syntax

getStopSequences(): string | null;
setStopSequences(stopSequences: string | null): void;

Default Value

""

Remarks

This property specifies up to a handful of sequences, separated by commas, at which the model will stop generating further tokens. For example, setting this to END,STOP causes generation to stop as soon as either END or STOP is produced.

When this property is left empty (the default), the stopSequences field is omitted from the request's generationConfig object.

This property is not available at design time.

Gemini.Stream Property

Whether the reply should be streamed.

Syntax

isStream(): boolean;
setStream(stream: boolean): void;

Default Value

false

Remarks

When this property is set to True, GenerateContent sends its request to the streamGenerateContent operation and the ContentDelta event fires once for each incremental fragment of the reply as it is received.

In both cases, once the reply has been fully received it is appended to Contents as a new item with role model, and the FunctionCall event fires for each function the model called.

The default value is False.

This property is not available at design time.

Gemini.SystemInstruction Property

The system instruction sent alongside the conversation.

Syntax

getSystemInstruction(): string | null;
setSystemInstruction(systemInstruction: string | null): void;

Default Value

""

Remarks

This property specifies the system instruction, which gives the model context and instructions that apply to the whole conversation, such as a role to adopt or a goal to pursue.

The Gemini API does not accept a content item whose role is system. The system instruction is instead a top level systemInstruction field of the request, which is what this property supplies.

When this property is left empty (the default), the systemInstruction field is omitted from the request entirely.

This property is not available at design time.

Gemini.Temperature Property

The sampling temperature to use for the reply.

Syntax

getTemperature(): string | null;
setTemperature(temperature: string | null): void;

Default Value

""

Remarks

This property specifies the amount of randomness injected into the response. Higher values make the output more varied, while lower values make it more focused and deterministic.

When this property is left empty (the default), the temperature field is omitted from the request's generationConfig object and the server's own default is used.

This property is not available at design time.

Gemini.Timeout Property

The timeout for operations in seconds.

Syntax

getTimeout(): number;
setTimeout(timeout: number): void;

Default Value

60

Remarks

This property specifies the timeout period in seconds for operations performed by the class.

If this is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If this is set to a positive value, the class will wait for the operation to complete before returning control. If the timeout expires before the operation completes, the class throws an exception.

Note that all timeouts are inactivity timeouts, meaning the timeout period is extended by value specified in this property when any amount of data is successfully sent or received.

This property is not available at design time.

Gemini.Tools Property

The list of tools the model may use.

Syntax

getTools(): GeminiToolList;

Default Value

Remarks

This collection holds the list of GeminiTool items that are made available to the model when GenerateContent is called. Each item becomes one function declaration of the request's tools array. When this collection is empty, no tools field is sent in the request.

The AddToolParam and AddTool methods are a convenient way to append a new tool to this collection without constructing a GeminiTool item directly.

This property is not available at design time.

Gemini.TopK Property

The number of top choices the model samples from.

Syntax

getTopK(): number;
setTopK(topK: number): void;

Default Value

0

Remarks

This property specifies that the model should sample only from the given number of most likely tokens at each step, which removes long tail low probability responses.

When this property is left at 0 (the default), the topK field is omitted from the request's generationConfig object and the server's own default is used.

This property is not available at design time.

Gemini.TopP Property

The nucleus sampling cutoff to use for the reply.

Syntax

getTopP(): string | null;
setTopP(topP: string | null): void;

Default Value

""

Remarks

This property specifies the cumulative probability cutoff used for nucleus sampling. The model considers only the most likely tokens whose probabilities sum to this value.

When this property is left empty (the default), the topP field is omitted from the request's generationConfig object and the server's own default is used.

This property is not available at design time.

Gemini.addContent Method

Appends an item to the Contents collection.

Syntax

async gemini.addContent(role : string | null, text : string | null): Promise<void>

Remarks

This method appends a new item with the given Role (user or model) and Text to the Contents collection. It is a convenience equivalent to adding an item to the collection directly.

Text normally holds plain text, which is sent as a single part holding a text field. When Text instead begins with [, it is treated as a raw JSON parts array and sent verbatim, which is how parts such as inlineData or functionResponse are supplied.

A system instruction cannot be added through this method; use the SystemInstruction property instead.

Gemini.addTool Method

Appends a tool to the Tools collection.

Syntax

async gemini.addTool(name : string | null, description : string | null): Promise<void>

Remarks

This method appends a new GeminiTool item, with the given Name and Description, to the Tools collection.

Any parameters queued by prior calls to AddToolParam are consumed and used to build the new tool's parameter schema; the parameter queue is then cleared.

Example: gemini.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); gemini.AddTool("get_weather", "Gets the current weather for a location.");

In the Async Edition (nsoftware.async.IPWorksLLM), both calls are awaited:

await gemini.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); await gemini.AddTool("get_weather", "Gets the current weather for a location.");

Gemini.addToolParam Method

Queues a parameter to be included in the next tool added via AddTool.

Syntax

async gemini.addToolParam(name : string | null, paramType : string | null, description : string | null, required : boolean): Promise<void>

Remarks

This method queues a parameter to be included in the JSON Schema of the next tool appended via AddTool.

Name specifies the parameter's name.

ParamType specifies the parameter's JSON Schema type, such as string, number, boolean, or object.

Description specifies a natural language description of the parameter, which helps the model determine appropriate values for it.

Required specifies whether the model must supply a value for this parameter whenever it calls the function.

Queued parameters are consumed, and the queue is cleared, the next time AddTool is called.

Gemini.config Method

Sets or retrieves a configuration setting.

Syntax

async gemini.config(configurationString : string | null): Promise<string | null>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Gemini.createEmbedding Method

Creates an embedding vector for each item of the Embeddings collection.

Syntax

async gemini.createEmbedding(): Promise<void>

Remarks

This method sends the InputText of every item in the Embeddings collection to {ServerURL}/models/{selected model}:batchEmbedContents in a single request, and sets the OutputVector of each item to the embedding vector the server created for its text, as JSON text containing an array of floating point numbers. Each item becomes one request of the batch, so every text receives its own vector.

The model specified by the EmbeddingModel configuration setting is used, or, when that setting is empty, the model specified by Model. Google publishes models dedicated to embeddings, such as gemini-embedding-001, which is what EmbeddingModel is normally set to. The EmbeddingDimensions and EmbeddingTaskType configuration settings, when set, are sent with every item of the batch.

gemini.Config("EmbeddingModel=gemini-embedding-001"); gemini.Embeddings.Add(new GeminiEmbedding("What is the meaning of life?")); gemini.Embeddings.Add(new GeminiEmbedding("How much wood would a woodchuck chuck?")); gemini.CreateEmbedding(); string firstVector = gemini.Embeddings[0].OutputVector;

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

await gemini.Config("EmbeddingModel=gemini-embedding-001"); gemini.Embeddings.Add(new GeminiEmbedding("What is the meaning of life?")); gemini.Embeddings.Add(new GeminiEmbedding("How much wood would a woodchuck chuck?")); await gemini.CreateEmbedding(); string firstVector = gemini.Embeddings[0].OutputVector;

All items are sent in one request; this method never splits them over several requests. The server limits the size of that request and of each text in it, and a request beyond a limit fails with error 801, which carries the server's own explanation; spread a large set of texts over several calls in that case.

The OutputVector of every item is cleared before the request is sent, so after an error no item holds a vector. When the reply does not hold exactly one embedding for each item, this method fails with error 803. On success, the PromptTokens and TotalTokens configuration settings report the tokens the server counted; both are 0 when the reply carries no token count, which the Gemini API does not always include.

This method fails with error 802 when Embeddings is empty, when an item's InputText is empty, or when neither the EmbeddingModel configuration setting nor Model is set. Nothing is appended to Contents by this method.

Gemini.doEvents Method

This method processes events from the internal message queue.

Syntax

async gemini.doEvents(): Promise<void>

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Gemini.generateContent Method

Sends the current conversation to the model and appends the reply.

Syntax

async gemini.generateContent(): Promise<void>

Remarks

This method sends the entire Contents collection, together with SystemInstruction, Tools, SafetySettings, and every request property that has been set away from its default value, to {ServerURL}/models/{Model}:generateContent. Properties left at their default values are omitted from the request JSON, and the generationConfig object itself is omitted unless at least one of its properties has been set.

On success, the model's reply is appended to Contents as a new item whose role is model. When the reply is a single part of text, that text is stored directly; when the reply holds several parts, or any part that is not text, the raw parts array is stored instead so that the model turn can be reproduced exactly.

A reply the server blocked returns success with no candidate content and raises error 803; the block reason is included in the error message when the server provides one, and the full reply is available via the RawResponse configuration setting.

When Stream is set to True, the request is sent to {ServerURL}/models/{Model}:streamGenerateContent instead, with the alt=sse query parameter that selects server-sent events, and the ContentDelta event fires once for each incremental fragment of the reply as it is received. The fully assembled reply is still appended to Contents once streaming completes.

When the model calls one or more functions, the FunctionCall event fires once for each call. To continue the conversation, append an item with role user whose Text is a raw parts array holding the matching functionResponse parts, then call this method again.

The Model property must be set before calling this method.

The following example sends a short conversation and reads the reply back out of Contents.

gemini.APIKey = "..."; gemini.Model = "gemini-2.0-flash"; gemini.SystemInstruction = "You are a concise assistant."; gemini.AddContent("user", "What is the capital of France?"); gemini.GenerateContent(); string reply = gemini.Contents[gemini.Contents.Count - 1].Text;

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

gemini.APIKey = "..."; gemini.Model = "gemini-2.0-flash"; gemini.SystemInstruction = "You are a concise assistant."; await gemini.AddContent("user", "What is the capital of France?"); await gemini.GenerateContent(); string reply = gemini.Contents[gemini.Contents.Count - 1].Text;

Gemini.interrupt Method

This method interrupts the current method.

Syntax

async gemini.interrupt(): Promise<void>

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

Gemini.listModels Method

Retrieves the list of models available from the endpoint.

Syntax

async gemini.listModels(): Promise<void>

Remarks

This method sends a request to {ServerURL}/models. The ModelList event fires once for each model reported by the server.

This method is typically used to discover which model identifiers are valid for the Model property.

The endpoint returns a single page of results. This method reports the models on that first page and does not follow the page token to any subsequent page.

The following example prints every model the endpoint reports.

gemini.OnModelList += (s, e) => { Console.WriteLine(e.Name + " (" + e.DisplayName + ")"); }; gemini.ListModels();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and the request is awaited:

gemini.OnModelList += async (s, e) => { Console.WriteLine(e.Name + " (" + e.DisplayName + ")"); }; await gemini.ListModels();

Gemini.reset Method

This method will reset the class.

Syntax

async gemini.reset(): Promise<void>

Remarks

This method will reset the class's properties to their default values.

Gemini.Connected Event

Fired immediately after a connection completes (or fails).

Syntax

gemini.on('Connected', listener: (e: {readonly statusCode: number, readonly description: string | null}) => void )

Remarks

If the connection is made normally, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

Gemini.ConnectionStatus Event

Fired to indicate changes in the connection state.

Syntax

gemini.on('ConnectionStatus', listener: (e: {readonly connectionEvent: string | null, readonly statusCode: number, readonly description: string | null}) => void )

Remarks

This event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:

Gemini.ContentDelta Event

Fires once for each incremental fragment of a streamed reply.

Syntax

gemini.on('ContentDelta', listener: (e: {readonly delta: string | null}) => void )

Remarks

This event fires when Stream is set to True and GenerateContent is called. It fires once for each incremental fragment of text the server sends as the reply is generated.

Delta holds the fragment itself. Concatenating Delta across every occurrence of this event reconstructs the text of the reply; the assembled reply is also appended to Contents once streaming completes.

Parts of a streamed reply that are not text, such as a function call, do not fire this event; they are reported through FunctionCall once the stream completes.

The following example prints the reply as it arrives.

gemini.Stream = true; gemini.OnContentDelta += (s, e) => { Console.Write(e.Delta); }; gemini.AddContent("user", "Write a short poem about the sea."); gemini.GenerateContent();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and the request is awaited:

gemini.Stream = true; gemini.OnContentDelta += async (s, e) => { Console.Write(e.Delta); }; await gemini.AddContent("user", "Write a short poem about the sea."); await gemini.GenerateContent();

Gemini.Disconnected Event

Fired when a connection is closed.

Syntax

gemini.on('Disconnected', listener: (e: {readonly statusCode: number, readonly description: string | null}) => void )

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. Description contains a description of this code. The value of StatusCode is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

Gemini.EndTransfer Event

Fired when a document finishes transferring.

Syntax

gemini.on('EndTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

This event is fired first when the client finishes sending data to the server (in a POST or PUT request) and then when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Gemini.Error Event

Fired when information is available about errors during data delivery.

Syntax

gemini.on('Error', listener: (e: {readonly errorCode: number, readonly description: string | null}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Gemini.FunctionCall Event

Fires once for each function the model calls.

Syntax

gemini.on('FunctionCall', listener: (e: {readonly name: string | null, readonly argsJson: string | null}) => void )

Remarks

This event fires when the model's reply contains one or more functionCall parts, once per part. It fires for both streamed and non streamed replies.

Name is the name of the function, matching the Name field of the GeminiTool item that declared it. ArgsJson holds the JSON arguments object the model produced for the call.

To continue the conversation, append an item with role user whose Text is a raw parts array holding a functionResponse part whose name is Name and whose response is the function's result, then call GenerateContent again.

The following example returns the function's result as a functionResponse part and lets the model produce a final reply.

bool functionCalled = false; gemini.OnFunctionCall += (s, e) => { gemini.AddContent("user", "[{\"functionResponse\":{\"name\":\"" + e.Name + "\"," + " \"response\":{\"result\":\"" + GetWeather(e.ArgsJson) + "\"}}}]"); functionCalled = true; }; gemini.AddContent("user", "What is the weather like in Boston?"); gemini.GenerateContent(); if (functionCalled) gemini.GenerateContent();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and each request is awaited:

bool functionCalled = false; gemini.OnFunctionCall += async (s, e) => { await gemini.AddContent("user", "[{\"functionResponse\":{\"name\":\"" + e.Name + "\"," + " \"response\":{\"result\":\"" + GetWeather(e.ArgsJson) + "\"}}}]"); functionCalled = true; }; await gemini.AddContent("user", "What is the weather like in Boston?"); await gemini.GenerateContent(); if (functionCalled) await gemini.GenerateContent();

Gemini.Header Event

Fired every time a header line comes in.

Syntax

gemini.on('Header', listener: (e: {readonly field: string | null, readonly value: string | null}) => void )

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

Gemini.Log Event

Fired once for each log message.

Syntax

gemini.on('Log', listener: (e: {readonly logLevel: number, readonly message: string | null, readonly logType: string | null}) => void )

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

Gemini.ModelList Event

Fires once for each model reported by the server.

Syntax

gemini.on('ModelList', listener: (e: {readonly name: string | null, readonly displayName: string | null}) => void )

Remarks

This event fires once for each model returned in response to a call to ListModels.

Name holds the model's resource name, which the Gemini API reports with a models/ prefix, as in models/gemini-2.0-flash. Either that value or the bare identifier that follows the prefix may be assigned to Model. DisplayName holds a human readable name for the model.

Gemini.Redirect Event

Fired when a redirection is received from the server.

Syntax

gemini.on('Redirect', listener: (e: {readonly location: string | null, accept: boolean}) => void )

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The Accept parameter is always True by default, but if you do not want to follow the redirection, Accept may be set to False, in which case the class . Location is the location to which the client is being redirected. Further control over redirection is provided in the FollowRedirects property.

Gemini.SetCookie Event

Fired for every cookie set by the server.

Syntax

gemini.on('SetCookie', listener: (e: {readonly name: string | null, readonly value: string | null, readonly expires: string | null, readonly domain: string | null, readonly path: string | null, readonly secure: boolean}) => void )

Remarks

This event is fired for every Set-Cookie: header received from the HTTP server.

The Name parameter contains the name of the cookie, with the corresponding value supplied in the Value parameter.

The Expires parameter contains an expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, the Expires parameter will be an empty string. In this case, the convention is to drop the cookie at the end of the session.

The Domain parameter contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, the Domain parameter will be an empty string. The convention in this case is to use the server specified in the URL (URLServer) as the cookie domain.

The Path parameter contains a path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the Path parameter will be an empty string. The convention in this case is to use the path specified in the URL (URLPath) as the cookie path.

The Secure parameter specifies whether the cookie is secure. If the value of this parameter is True, the cookie value must be submitted only through a secure (HTTPS) connection.

Gemini.SSLServerAuthentication Event

Fired after the server presents its certificate to the client.

Syntax

gemini.on('SSLServerAuthentication', listener: (e: {readonly certEncoded: string, readonly certEncodedB: Uint8Array | null, readonly certSubject: string | null, readonly certIssuer: string | null, readonly status: string | null, accept: boolean}) => void )

Remarks

This event fires with information about the server certificate. The Status property shows why verification failed (otherwise, Status contains the string OK). To manually accept an untrusted certificate, the SSLAcceptAnyServerCert setting must be set to True before initiating the connection.

Gemini.SSLStatus Event

Fired when secure connection progress messages are available.

Syntax

gemini.on('SSLStatus', listener: (e: {readonly message: string | null}) => void )

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Gemini.StartTransfer Event

Fired when a document starts transferring (after the headers).

Syntax

gemini.on('StartTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

This event is fired first when the client starts sending data to the server (in a POST or PUT request) and then when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Gemini.Status Event

Fired when the HTTP status line is received from the server.

Syntax

gemini.on('Status', listener: (e: {readonly HTTPVersion: string | null, readonly statusCode: number, readonly description: string | null}) => void )

Remarks

HTTPVersion is a string containing the HTTP version string as returned from the server (e.g., "1.1").

StatusCode contains the HTTP status code (e.g., 200), and Description the associated message returned by the server (e.g., "OK").

Gemini.Transfer Event

Fired while a document transfers (delivers document).

Syntax

gemini.on('Transfer', listener: (e: {readonly direction: number, readonly bytesTransferred: number, readonly percentDone: number, readonly text: string, readonly textB: Uint8Array | null}) => void )

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

• EffectiveDate
• ExpirationDate
• ExtendedKeyUsage
• Fingerprint
• FingerprintSHA1
• FingerprintSHA256
• Issuer
• PrivateKey
• PrivateKeyAvailable
• PrivateKeyContainer
• PublicKey
• PublicKeyAlgorithm
• PublicKeyLength
• SerialNumber
• SignatureAlgorithm
• Store
• StorePassword
• StoreType
• SubjectAltNames
• ThumbprintMD5
• ThumbprintSHA1
• ThumbprintSHA256
• Usage
• UsageFlags
• Version
• Subject
• Encoded

Fields

Constructors

public Certificate();

public Certificate(string | null certificateFile);

public Certificate(Uint8Array | null encoded);

public Certificate(CertStoreTypes storeType, string | null store, string | null storePassword, string | null subject);

public Certificate(CertStoreTypes storeType, string | null store, string | null storePassword, string | null subject, string | null configurationString);

public Certificate(CertStoreTypes storeType, string | null store, string | null storePassword, Uint8Array | null encoded);

public Certificate(CertStoreTypes storeType, Uint8Array | null store, string | null storePassword, string | null subject);

public Certificate(CertStoreTypes storeType, Uint8Array | null store, string | null storePassword, string | null subject, string | null configurationString);

public Certificate(CertStoreTypes storeType, Uint8Array | null store, string | null storePassword, Uint8Array | null encoded);

Firewall Type

The firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

• AutoDetect
• FirewallType
• Host
• Password
• Port
• User

Fields

Constructors

public Firewall();

GeminiContent Type

A single item of a conversation.

Remarks

This type represents a single item making up part of a conversation held in the Contents collection.

• Role
• Text

Fields

Constructors

public GeminiContent();

GeminiEmbedding Type

A piece of text and the embedding vector created for it.

Remarks

This type represents one item of the Embeddings collection. Set InputText to the text to embed before calling CreateEmbedding. When that method returns, OutputVector holds the embedding vector the server created for the text.

• InputText
• OutputVector

Fields

Constructors

public GeminiEmbedding();

public GeminiEmbedding(string | null inputText);

GeminiTool Type

A tool the model may use.

Remarks

This type represents a single tool made available to the model via the Tools collection. Each item becomes one function declaration of the request's tools array.

• Description
• Name
• ParametersSchema

Fields

Constructors

public GeminiTool();

Proxy Type

The proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

• AuthScheme
• AutoDetect
• Password
• Port
• Server
• SSL
• User

Fields

Constructors

public Proxy();

public Proxy(string | null server, number port);

public Proxy(string | null server, number port, string | null user, string | null password);

Config Settings (Gemini Class)

Gemini Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (Gemini Class)

Gemini Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors