📊 View Lecture Slides Full-screen presentation with navigation

Session 7: API Integration & Cloud Models

Session Duration: 2 Hours     Block: 2 — AI-Assisted Engineering & Integration

Note on Stack as of August 2026: We use the npm package @google/genai and the model gemini-2.5-flash. If AI Studio interfaces or model IDs change over time, follow the official documentation at ai.google.dev.

Session clock

Minutes Mode Focus
0–50 Lecture Theoretical Foundation & Concepts
50–110 Core lab Replace Mock with Real Gemini API
110–120 Checkpoint Pair share / show artifact

Note: Stretch work starts only after the Core checkpoint is completed.

Learning Objectives

By the end of this session, students will be able to:

  • Explain the structure of a standard AI API request (payload) and response, and how state is managed across calls.
  • Authenticate securely using an API key loaded from environment variables on the Node.js server.
  • Integrate the Gemini SDK into an Express application, replacing a mock /query handler with a real API call.
  • Implement robust error handling for API failures, rate limits, and response parsing.

Part 1: Theoretical Foundation — How Cloud AI APIs Work

1.1 The Anatomy of an API Call

An API (Application Programming Interface) call is a structured, programmatic request from your application to a remote cloud service. When integrating an AI like Gemini, the fundamental architecture is:

Request → Process in Cloud → Response

Unlike a human chatting in a web interface, your Express application must send a highly structured JSON object to the API. When using the @google/genai SDK, it abstracts some of this JSON wrapping, but under the hood, your application is sending:

  • Authentication: The API key (the SDK reads this from process.env.GEMINI_API_KEY).
  • Model Identifier: Which specific model to route the request to (e.g., gemini-2.5-flash for fast text tasks, or a Pro model for complex reasoning).
  • The Contents: The actual message, document, or image.
  • Configuration (Optional): Parameters like temperature, maxOutputTokens, and systemInstruction.

The API processes this and returns a structured response object containing:

  • The generated text.
  • Usage statistics (how many tokens were billed for the prompt and the response).
  • Metadata (e.g., finishReason which tells you if the model finished naturally or hit a length limit).

1.2 Understanding Temperature and Generation Config

Language models are probabilistic. They select the next word based on a probability distribution. The temperature parameter controls the “randomness” or “creativity” of this selection process.

Temperature Value Behaviour Ideal Use Case
0.0 - 0.1 Highly Deterministic. Always picks the most likely next word. Same input usually yields the exact same output. Extracting structured JSON, classification, factual summarization.
0.3 - 0.7 Balanced. Introduces slight variety while remaining highly coherent and grounded. General question answering, drafting professional emails.
1.0+ Creative/Random. Flattens the probability curve, making less likely words more possible. Brainstorming, poetry, creative writing. (Can cause hallucinations if used for facts).

Best Practice: For almost all AI product engineering applications where reliability is prioritized over creativity, start with a temperature of 0.2 to 0.4.

1.3 API Authentication Security (Critical)

Your API key acts as both your password and your credit card for the Google AI platform. Securing it is non-negotiable.

The Golden Rules of API Keys:

  • ❌ NEVER hardcode an API key directly in your server.js or utils.js files.
  • ❌ NEVER commit an API key to a git repository (e.g., pushing it to GitHub).
  • ❌ NEVER expose an API key in client-side JavaScript (e.g., in a <script> tag in your HTML) where anyone can open DevTools and steal it.

The Correct Way (Environment Variables):

  1. Store keys in a file named .env located at the root of your project.
  2. Ensure .env is listed inside your .gitignore file so it is never uploaded to GitHub.
  3. Load the key into your Node environment using a package like dotenv or Node’s native env loader, accessing it via process.env.GEMINI_API_KEY.

Example SDK Initialization:

import { GoogleGenAI } from '@google/genai';

const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) {
  // Fail fast. Do not try to run the app if the key is missing.
  throw new Error('FATAL: GEMINI_API_KEY is not set in the environment.');
}
const ai = new GoogleGenAI({ apiKey });

1.4 Making Your First Real API Call (Gemini)

Here is the standard pattern for a basic, stateless API call using the modern SDK. Notice how we wrap it in a try/catch block.

async function askAi(userQuery, systemInstruction = '') {
  try {
    const response = await ai.models.generateContent({
      model: 'gemini-2.5-flash',
      contents: userQuery,
      config: {
        systemInstruction: systemInstruction || undefined,
        temperature: 0.3,
      },
    });
    // The SDK conveniently extracts the primary text response
    return response.text;
  } catch (err) {
    console.error('AI API Call Failed:', err);
    throw new Error(`AI Service Unavailable: ${err.message}`);
  }
}

1.5 Anticipating API Failures (Error Handling)

Cloud APIs fail. Networks drop. Rate limits are exceeded. Your application must handle these gracefully rather than crashing.

HTTP Error Code Typical Cause Application Response Strategy
401 Unauthorized Invalid, expired, or missing API key. Check your .env file and restart the Express server.
429 Too Many Requests You hit the rate limit (requests per minute). Implement exponential backoff, or inform the user to wait 30 seconds.
500 Internal Server The AI provider’s servers are down. Retry once with a delay; if it fails again, show a friendly error to the user.
Timeout The request was too large, or the generation took too long. Reduce the input context size, or use a smaller/faster model (like Flash instead of Pro).

Never let an API error crash your Express server silently. Always catch the error and return a properly formatted JSON error to your front-end.

Part 2: Practical Labs — Replace the Mock with Real AI

Lab 7.1 — Set Up Your Secure Environment (Core)

  1. In your starter kit, locate the .env.example file. Duplicate it and rename the copy to strictly .env.
  2. Open .env and paste the API key you generated in AI Studio back in Session 1: GEMINI_API_KEY=AIzaSy...
  3. Open your terminal in the project root and run npm install to ensure the @google/genai package is installed.
  4. Restart your development server (npm run dev).

Lab 7.2 — Replace the Mock Backend (Core)

In Session 6, you built a mock /query route that returned a hardcoded string. It’s time to make it real.

  1. Open server.js.
  2. At the top of the file, import GoogleGenAI and initialize the ai client using the code snippet from section 1.3.
  3. Inside your app.post('/query', ...) route, delete the mock response logic.
  4. Call ai.models.generateContent using the req.body.query as the contents.
  5. Await the response, and return it to the frontend via res.json({ response: response.text }).

Crucial Architecture Check: The API call must happen inside Express (the server). The browser UI should only talk to your Express /query route.

Lab 7.3 — Integrate Your System Prompt (Core)

Retrieve the System Prompt you drafted in Session 2 (from your prompts.md library). In your generateContent configuration block, add the systemInstruction parameter and paste your prompt. Set the temperature to 0.3.

Lab 7.4 — Test and Observe (Core)

  1. Open your custom UI in the browser (http://localhost:3000).
  2. Send five different queries.
  3. Observe the latency (how long it takes). Note if the AI obeys the persona dictated by your system prompt.
  4. Log your observations in prompts.md. Does the AI break character? Does it format the output as requested?

Stretch Goal: Explore adding a temperature slider to your UI that sends a temperature value in the JSON payload, allowing you to dynamically adjust the creativity of the model from the browser. (Note: Only do this for prototyping/testing, not in a production app where users could break structured outputs by setting temp to 2.0).

Key Takeaways

  • AI API calls follow a strict Request → Process in Cloud → Response cycle.
  • Temperature dictates output randomness. Use low values (0.1–0.3) when you need reliable, structured, or factual outputs.
  • Security is paramount: API keys must never be hardcoded, committed to version control, or exposed in client-side code. Use .env variables.
  • Robust error handling (try/catch blocks and returning HTTP 500s safely) prevents your application from crashing when the cloud service hiccups.
  • Your application is now a true AI-powered prototype, bridging your custom UI to a world-class foundation model.

Further Reading & Resources

  • Google Gen AI JS SDK Docs: ai.google.dev - Review the documentation for advanced configuration options.
  • The Twelve-Factor App Methodology (Config): 12factor.net/config - Read why storing config (like API keys) in the environment is an industry standard.