gemini-best-practices

Gemini API Best Practices

When reviewing or modifying Gemini API integration code, ensure compliance with Google's official best practices from google-gemini/gemini-skills.

SDK and Package

• Correct SDK: @google/genai (npm)
• NEVER use deprecated: @google/generative-ai (old package)
• Prefer environment variables for API keys over hard-coding

Safety Settings

All API calls (generateContent, generateContentStream, chats.create) MUST include safetySettings in the config:

import { HarmCategory, HarmBlockThreshold, type SafetySetting } from "@google/genai";

const DEFAULT_SAFETY_SETTINGS: SafetySetting[] = [
  { category: HarmCategory.HARM_CATEGORY_HARASSMENT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
];

Response Validation (finishReason)

Always check finishReason on response candidates:

• SAFETY - Response blocked by safety filters; inform user to rephrase
• RECITATION - Blocked due to potential copyrighted content recitation
• MAX_TOKENS - Output truncated; consider informing user
• STOP - Normal completion

import { FinishReason } from "@google/genai";

// Check candidates[0].finishReason after each response
if (candidate.finishReason === FinishReason.SAFETY) {
  // Handle blocked response
}

For non-streaming: check response.candidates[0].finishReason before using response.text. For streaming: check finishReason in chunk candidates.

System Instructions

• Pass via systemInstruction in config (not as a chat message)
• System instructions are interaction-scoped; re-specify on each chat session creation

Tool / Function Calling