JustGemini

Simple Gemini API package for Node.js.

``shell
npm install @jnode/gemini
`

Basic Usage

$3


`js
const gemini = require('@jnode/gemini');
`

$3

`js
const client = new gemini.Client('YOUR_API_KEY');
`

$3

`js
const model = client.model('gemini-pro');

async function generateText() {
const result = await model.generate('Hello');
console.log(result.text);
}

generateText();
`

Class: GeminiClient

The main class for interacting with the Gemini API.

$3


`js
new gemini.Client(key, options = {})
`
- key: Your Gemini API key.
- options: An optional object for setting various client options:
- apiBase: The base URL of the Gemini API. Default is generativelanguage.googleapis.com.
- apiThrowError: Whether to throw errors when the API status code is not 2xx. Default is true.
- fileUnsupportError: Whether to throw errors when the file type is not supported. Default is true.
- fileActiveCheckDelay: Delay in milliseconds between file status checks. Default is 1500.
- fileMaxActiveCheck: Maximum number of file status checks. Default is 15.

$3

- apiUrl(path = '/', query = ''): Returns the full API URL with the base, path, and API key.
- path: API endpoint path.
- query: Query string.
- Returns: string - The full API URL.

- async apiRequest(method = 'GET', path = '/', query = '', body): Makes an HTTP request to the Gemini API.
- method: HTTP method (e.g., GET, POST, PUT, DELETE). Default is GET.
- path: API endpoint path. Default is /.
- query: Query string.
- body: Request body data (will be stringified).
- Returns: Promise - A promise that resolves to a RequestResponse object.

- model(model, options): Returns a GeminiModel instance for interacting with a specific model.
- model: The name of the model (e.g., gemini-pro).
- options: Model options.
- Returns: GeminiModel - A GeminiModel instance.

- fileManager: An instance of GeminiFileManager for managing files.

Class: GeminiModel

Represents a specific Gemini model.

$3

`js
new gemini.Model(client, model, options = {})
`

- client: A GeminiClient instance.
- model: The name of the model.
- options: An optional object for setting model options:
- tools: Custom tools to be used by the model.
- functions: An array of GeminiFunction instances.
- functionMode: Function calling mode ('NONE', 'AUTO', 'ANY').
- allowedFunctions: Allowed function names for function calling.
- safetySettings: Safety settings for the model.
- systemInstruction: System instruction text.
- jsonMode: Enable JSON mode (boolean or object with response schema).
- jsonMode: Enable image generate (boolean).
- stopSequences: Stop sequences for generation.
- candidateCount: Number of candidate responses.
- maxOutputTokens: Maximum number of output tokens.
- temperature: Temperature for generation.
- topP: Top-p value for generation.
- topK: Top-k value for generation.
- generationConfig: Overwrite the config with original format.
- imageGenerate: Boolean. Use image generate.

$3

- optionsToApiFormat(options = {}): Converts simple options to API format.
- options: Model options.
- Returns: object - Options in API format.

- async contentToApiFormat(content): Converts simple content to API format.
- content: Content string, array, or object.
- Returns: Promise - Content in API format.

- apiRequest(method, action, body): Makes an API request for this model.
- method: HTTP method.
- action: API action.
- body: Request body.
- Returns: Promise - A promise that resolves to a RequestResponse object.

- generate(content, optionsOverwrite = {}): Generates content using the model.
- content: Input content, which can be one of the following formats:
- String: A single-turn text input.
- Example: 'What is the meaning of life?'
- Array of strings: A multi-turn conversation where each string represents a turn. The turns alternate between user and model.
- Example: ['What is the capital of France?', 'Paris.', 'And what about Spain?']
- Array of arrays/objects: A multi-turn conversation with more complex inputs, including text, booleans (to set the role), and file data.
- String: a text part.
- Boolean: (Optional, default true which means is a "user" turn) set role to "user" (true) or "model" (false).
- Object: can be one of the following:
- { text: string }: A text part.
- Example: { text: 'What is the weather like today?' }
- { filePath: string }: A local file to be uploaded and used as input. The file will be automatically uploaded if it hasn't been uploaded already.
- Example: { filePath: './image.png' }
- { fileUrl: string }: A web file URL to be used as input. The file will be automatically uploaded if it hasn't been uploaded already.
- Example: { fileUrl: 'https://example.com/image.jpg' }
- { file: { mimeType: string, data: Buffer } }: File data directly provided as input.
- Example: { file: { mimeType: 'image/png', data: imageBuffer } }
- Other objects will be treated as original API part format.
- Example: [['What is in this image?', true, { filePath: './image.png' }], false, 'This is a picture of a cat.', ['And this one?', { filePath: './image2.jpg' }]]
- Array of objects: A multi-turn conversation in the original API content format. Each object should have role and parts properties.
- Example: [{ role: 'user', parts: [{ text: 'Hello' }] }, { role: 'model', parts: [{ text: 'Hi there!' }] }]
- optionsOverwrite: Optional options to overwrite model options.
- Returns: Promise - A promise that resolves to a GeminiContents instance.

Class: GeminiContents

Represents the contents generated by a model.

$3

`js
new gemini.Contents(model, contents)
`

- model: A GeminiModel instance.
- contents: Initial contents array.

$3

- async generate(content, optionsOverwrite): Generates content and updates the GeminiContents instance.
- content: Input content.
- optionsOverwrite: Optional options to overwrite model options.
- Returns: Promise - The updated GeminiContents instance.

- async runFunctions(extraData): Executes function calls and continues generation.
- extraData: Extra data to be passed to functions.
- Returns: Promise - A promise that resolves to a new GeminiContents instance with the function responses.

$3

- model: The GeminiModel instance.
- contents: The full contents array.
- text: The generated text.
- functionCalls: An array of function calls.
- usage: Usage metadata.
- feedback: Prompt feedback.
- status: Finish reason.
- attachments: An array of inline data respond by model.

Class: GeminiFileManager

Manages file uploads and retrieval for the Gemini API.

$3

`js
new gemini.FileManager(client)
`

- client: A GeminiClient instance.

$3

- async uploadFile(file, isWebFile = false, displayName): Uploads a local or web file to Gemini API.
- file: File path or URL.
- isWebFile: Whether the file is a web file. Default is false.
- displayName: Optional display name for the file.
- Returns: Promise