Caution

API Key Security: Avoid exposing API keys in client-side code.Use server-side implementations in production environments.

Code Generation

Prerequisites

The following are required for Vertex AI users (excluding Vertex AI Studio)

Installation

npm install @google/genai

Quickstart

import{GoogleGenAI}from'@google/genai';constGEMINI_API_KEY=process.env.GEMINI_API_KEY;constai=newGoogleGenAI({apiKey:GEMINI_API_KEY});asyncfunctionmain(){constresponse=awaitai.models.generateContent({model:'gemini-2.5-flash',contents:'Why is the sky blue?',});console.log(response.text);}main();

Initialization

Gemini Developer API

import{GoogleGenAI}from'@google/genai';constai=newGoogleGenAI({apiKey:'GEMINI_API_KEY'});

Browser

Caution

API Key Security: Avoid exposing API keys in client-side code.Use server-side implementations in production environments.

import{GoogleGenAI}from'@google/genai';constai=newGoogleGenAI({apiKey:'GEMINI_API_KEY'});

Vertex AI

import{GoogleGenAI}from'@google/genai';constai=newGoogleGenAI({vertexai:true,project:'your_project',location:'your_location',});

(Optional) (NodeJS only) Using environment variables:

export GOOGLE_API_KEY='your-api-key'

export GOOGLE_GENAI_USE_VERTEXAI=trueexport GOOGLE_CLOUD_PROJECT='your-project-id'export GOOGLE_CLOUD_LOCATION='us-central1'

import{GoogleGenAI}from'@google/genai';constai=newGoogleGenAI();

API Selection

constai=newGoogleGenAI({vertexai:true,project:'your_project',location:'your_location',apiVersion:'v1'});

constai=newGoogleGenAI({apiKey:'GEMINI_API_KEY',apiVersion:'v1alpha'});

GoogleGenAI overview

Samples

Streaming

import{GoogleGenAI}from'@google/genai';constGEMINI_API_KEY=process.env.GEMINI_API_KEY;constai=newGoogleGenAI({apiKey:GEMINI_API_KEY});asyncfunctionmain(){constresponse=awaitai.models.generateContentStream({model:'gemini-2.5-flash',contents:'Write a 100-word poem.',});forawait(constchunkofresponse){console.log(chunk.text);}}main();

Function Calling

import{GoogleGenAI,FunctionCallingConfigMode,FunctionDeclaration,Type}from'@google/genai';constGEMINI_API_KEY=process.env.GEMINI_API_KEY;asyncfunctionmain(){constcontrolLightDeclaration:FunctionDeclaration={name:'controlLight',parametersJsonSchema:{type:'object',properties:{brightness:{type:'number',},colorTemperature:{type:'string',},},required:['brightness','colorTemperature'],},};constai=newGoogleGenAI({apiKey:GEMINI_API_KEY});constresponse=awaitai.models.generateContent({model:'gemini-2.5-flash',contents:'Dim the lights so the room feels cozy and warm.',config:{toolConfig:{functionCallingConfig:{// Force it to call any functionmode:FunctionCallingConfigMode.ANY,allowedFunctionNames:['controlLight'],}},tools:[{functionDeclarations:[controlLightDeclaration]}]}});console.log(response.functionCalls);}main();

Model Context Protocol (MCP) support (experimental)

import{GoogleGenAI,FunctionCallingConfigMode,mcpToTool}from'@google/genai';import{Client}from"@modelcontextprotocol/sdk/client/index.js";import{StdioClientTransport}from"@modelcontextprotocol/sdk/client/stdio.js";// Create server parameters for stdio connectionconstserverParams=newStdioClientTransport({command:"npx",// Executableargs:["-y","@philschmid/weather-mcp"]// MCP Server});constclient=newClient({name:"example-client",version:"1.0.0"});// Configure the clientconstai=newGoogleGenAI({});// Initialize the connection between client and serverawaitclient.connect(serverParams);// Send request to the model with MCP toolsconstresponse=awaitai.models.generateContent({model:"gemini-2.5-flash",contents:`What is the weather in London in${newDate().toLocaleDateString()}?`,config:{tools:[mcpToTool(client)],// uses the session, will automatically call the tool using automatic function calling},});console.log(response.text);// Close the connectionawaitclient.close();

Generate Content

How to structurecontents argument forgenerateContent

Content

Part

Error Handling

import{GoogleGenAI}from'@google/genai';constGEMINI_API_KEY=process.env.GEMINI_API_KEY;constai=newGoogleGenAI({apiKey:GEMINI_API_KEY});asyncfunctionmain(){awaitai.models.generateContent({model:'non-existent-model',contents:'Write a 100-word poem.',}).catch((e)=>{console.error('error name: ',e.name);console.error('error message: ',e.message);console.error('error status: ',e.status);});}main();

Interactions (Preview)

Basic Interaction

constinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',input:'Hello, how are you?',});console.debug(interaction);

Stateful Conversation

// 1. First turnconstinteraction1=awaitai.interactions.create({model:'gemini-2.5-flash',input:'Hi, my name is Amir.',});console.debug(interaction1);// 2. Second turn (passing previous_interaction_id)constinteraction2=awaitai.interactions.create({model:'gemini-2.5-flash',input:'What is my name?',previous_interaction_id:interaction1.id,});console.debug(interaction2);

Agents (Deep Research)

functionsleep(ms:number):Promise<void>{returnnewPromise(resolve=>setTimeout(resolve,ms));}// 1. Start the Deep Research AgentconstinitialInteraction=awaitai.interactions.create({input:'Research the history of the Google TPUs with a focus on 2025 and 2026.',agent:'deep-research-pro-preview-12-2025',background:true,});console.log(`Research started. Interaction ID:${initialInteraction.id}`);// 2. Poll for resultswhile(true){constinteraction=awaitai.interactions.get(initialInteraction.id);console.log(`Status:${interaction.status}`);if(interaction.status==='completed'){console.debug('\nFinal Report:\n',interaction.outputs);break;}elseif(['failed','cancelled'].includes(interaction.status)){console.log(`Failed with status:${interaction.status}`);break;}awaitsleep(10000);// Sleep for 10 seconds}

Multimodal Input

importbase64// Assuming you have a base64 string// const base64Image = ...;constinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',input:[{type:'text',text:'Describe the image.'},{type:'image',data:base64Image,mime_type:'image/png'},],});console.debug(interaction);

Function Calling

// 1. Define the toolconstgetWeather=(location:string)=>{/* Gets the weather for a given location. */return`The weather in${location} is sunny.`;};// 2. Send the request with toolsletinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',input:'What is the weather in Mountain View, CA?',tools:[{type:'function',name:'get_weather',description:'Gets the weather for a given location.',parameters:{type:'object',properties:{location:{type:'string',description:'The city and state, e.g. San Francisco, CA',},},required:['location'],},},],});// 3. Handle the tool callfor(constoutputofinteraction.outputs!){if(output.type==='function_call'){console.log(`Tool Call:${output.name}(${JSON.stringify(output.arguments)})`);// Execute your actual function here// Note: ensure arguments match your function signatureconstresult=getWeather(JSON.stringify(output.arguments.location));// Send result back to the modelinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',previous_interaction_id:interaction.id,input:[{type:'function_result',name:output.name,call_id:output.id,result:result,},],});console.debug(`Response:${JSON.stringify(interaction)}`);}}

Built-in Tools

Grounding with Google Search

constinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',input:'Who won the last Super Bowl',tools:[{type:'google_search'}],});console.debug(interaction);

Code Execution

constinteraction=awaitai.interactions.create({model:'gemini-2.5-flash',input:'Calculate the 50th Fibonacci number.',tools:[{type:'code_execution'}],});console.debug(interaction);

Multimodal Output

import*asfsfrom'fs';constinteraction=awaitai.interactions.create({model:'gemini-3-pro-image-preview',input:'Generate an image of a futuristic city.',response_modalities:['image'],});for(constoutputofinteraction.outputs!){if(output.type==='image'){console.log(`Generated image with mime_type:${output.mime_type}`);// Save the imagefs.writeFileSync('generated_city.png',Buffer.from(output.data!,'base64'));}}

How is this different from the other Google AI SDKs