gemini-api-integration – skill Lập trình cho agent AI

Gemini API Integration

Overview

This skill guides AI agents through integrating Google Gemini API into applications — from basic text generation to advanced multimodal, function calling, and streaming use cases. It covers the full Gemini SDK lifecycle with production-grade patterns.

When to Use This Skill

• Use when setting up Gemini API for the first time in a Node.js, Python, or browser project
• Use when implementing multimodal inputs (text + image/audio/video)
• Use when adding streaming responses to improve perceived latency
• Use when implementing function calling / tool use with Gemini
• Use when optimizing model selection (Flash vs Pro vs Ultra) for cost and performance
• Use when debugging Gemini API errors, rate limits, or quota issues

Step-by-Step Guide

1. Select the supported SDK and model

Use the Google GenAI SDK (@google/genai for JavaScript, google-genai for Python), pin a tested package version, and select an available model for the account. The older @google/generative-ai / google-generativeai APIs and historical 1.5/2.0 model table are not current setup guidance. Check model availability, deprecations, pricing and feature support in official documentation before choosing; do not assume a universal cheapest or most capable model.

2. Server-side generation

Set GEMINI_API_KEY through a secret manager or protected environment and GEMINI_MODEL to the verified model ID. Never ship a long-lived key in browser code.

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
  model: process.env.GEMINI_MODEL,
  contents: "Explain async/await in JavaScript"
});
console.log(response.text);

import os
from google import genai
with genai.Client(api_key=os.environ["GEMINI_API_KEY"]) as client:
    response = client.models.generate_content(
        model=os.environ["GEMINI_MODEL"], contents="Explain async/await")
    print(response.text)

3. Streaming and multimodal inputs

Use the pinned SDK's models.generateContentStream / models.generate_content_stream interfaces and handle partial output, cancellation and empty/blocked responses. Verify MIME types, model limits and file retention before transmitting images/audio/video. Obtain permission for sensitive content; do not put private inputs or access URLs in logs. File uploads and generation may incur charges.

4. Function calling and chat

A model's function call is an untrusted proposal. Validate the name against a fixed allowlist and arguments against a schema, enforce user authorization, and limit calls/time/cost before dispatch. Return actual tool results through the pinned SDK's documented function-response format; never fabricate results. Preserve the required conversation turns and function-call identifiers. A chat history entry is not a privileged system instruction; use the supported configuration field for system instructions.

5. Failure handling

Inspect structured errors, block reasons and finish reasons without assuming every response has text. Retry only transient errors with bounded exponential backoff, jitter and any retry-after guidance; enforce deadlines and a retry budget. A failed network request may already have incurred usage. Do not retry invalid credentials or malformed requests indefinitely, and do not weaken safety settings merely to bypass a blocked response.

Examples

For a production integration, first run a small non-sensitive prompt against a test project, record the SDK/model version and response status, then test streaming cancellation, blocked output, quota exhaustion and rejected tool arguments. Report what was actually exercised.

Sources

• [Google GenAI migration guide](https://ai.google.dev/gemini-api/docs/migrate)
• [Content generation API](https://ai.google.dev/api/generate-content)

Limitations

SDK syntax, model availability, quotas and pricing change. These examples are unexecuted integration templates and do not establish account access, model quality or production readiness.