Chapter 15: Building With AI APIs — From Beginner to Advanced

The AI API Layer: Your Product's Brain

Adding AI capabilities to your product is no longer optional — it is a competitive expectation. Users who experience an intelligent, AI-powered product and then return to a static, rule-based alternative feel the difference immediately.

This chapter walks you from your first AI API call through to the advanced patterns that power production AI products.

---

Level 1: Your First AI API Call

Every AI API call follows the same structure regardless of provider. Let's use the Gemini API (free tier available):

// The simplest possible AI API call
const response = await fetch(
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=' + process.env.GEMINI_API_KEY,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      contents: [{
        role: 'user',
        parts: [{ text: 'Explain what a REST API is in 2 sentences.' }]
      }]
    })
  }
);

const data = await response.json();
const text = data.candidates[0].content.parts[0].text;
console.log(text);

This is the foundation. Every more complex use case is a variation on this pattern.

---

Level 2: System Prompts and Conversation History

A system prompt tells the model how to behave. Conversation history lets the model respond in context.

// Using OpenAI-compatible format (works with OpenAI, Kimi K3, many others)
import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const messages = [
  {
    role: 'system',
    content: 'You are a JavaScript expert. Answer concisely. Always include working code examples.'
  },
  {
    role: 'user',
    content: 'How do I debounce a search input in React?'
  }
];

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages,
  temperature: 0.7,
  max_tokens: 500,
});

// To continue the conversation, append the assistant's response and the new user message:
messages.push(response.choices[0].message);
messages.push({ role: 'user', content: 'Now show me how to add a loading state.' });

---

Level 3: Streaming Responses

Users expect to see AI output appear progressively, not wait 10 seconds for the full response. Streaming is essential for any user-facing AI feature.

```javascript // Next.js API route with streaming export async function POST(request) { const { prompt } = await request.json(); const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); const stream = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: prompt }], stream: true, // Enable streaming

});

// Return a ReadableStream to the client return new Response( new ReadableStream({ async start(controller) { for await (const chunk of stream) { const text = chunk.choices[0]?.delta?.content || ''; if (text) controller.enqueue(new TextEncoder().encode(text)); } controller.close(); }, }), { headers: { 'Content-Type': 'text/plain; charset=utf-8' } } ); }

const reader = response.body.getReader(); const decoder = new TextDecoder(); let result = '';

while (true) { const { done, value } = await reader.read(); if (done) break; result += decoder.decode(value); setOutput(result); // Update React state progressively }

---

## Level 4: Structured Output (JSON Mode)

Instead of parsing freeform text, instruct the model to return structured JSON directly.

const extracted = JSON.parse(response.choices[0].message.content); // { title: "...", salary: "...", requirements: [...], location: "..." }

For Gemini, use `responseMimeType: 'application/json'` in generationConfig.

---

## Level 5: Function Calling (Tool Use)

Function calling lets the AI trigger real actions in your app — searching a database, calling an API, running a calculation.

// First call — model may decide to call a function const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Find me running shoes under $80' }], tools, tool_choice: 'auto', });

if (response.choices[0].finish_reason === 'tool_calls') { const toolCall = response.choices[0].message.tool_calls[0]; const args = JSON.parse(toolCall.function.arguments); // Actually run your search function const results = await searchProducts(args.query, args.max_price); // Second call — give the model the function result const finalResponse = await client.chat.completions.create({ model: 'gpt-4o', messages: [ { role: 'user', content: 'Find me running shoes under $80' }, response.choices[0].message, { role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(results) }, ], }); }

---

## Level 6: Multi-Model Orchestration

Route different parts of a complex task to different models based on their strengths:

This pattern delivers frontier-quality results at 60-70% of the cost of routing everything through the most expensive model.