3.5 Integrating AI Capabilities via API

What Is an API? The Restaurant Analogy

In the last chapter we said the frontend is the dining room and the backend is the kitchen. So what's an API? An API is the complete system of menus, waiters, and ordering rules.

Let's walk through this analogy step by step:

Step 1: Walk into the restaurant (client sends a request) — You don't barge into the kitchen yelling "make me some steak!" A server works the same way — it only communicates with you through the API.

Step 2: Read the menu (check the API docs) — The menu tells you what's available (endpoints), how much each dish costs (pricing), how long you'll wait (response time), and what special requests you can make (request parameters).

Step 3: Place your order (send a request) — You tell the waiter "one steak, no spice, swap the rice for noodles" — that's like sending a request with parameters.

Step 4: Kitchen prepares (server processes) — You don't know how many cooks there are, what pans they use, or where the ingredients come from. You just wait.

Step 5: Food is served (response returned) — Either you get what you ordered, or you're told "we're out of fish today" (error response).

You (client) → Read menu (API docs) → Place order (send request) → Kitchen prepares (server processes) → Food served (response)

AI API Call Flow

---

HTTP Methods: The "Tone" of Requests

Method	Analogy	Actual Use
GET	"Show me the menu"	Retrieve data — check weather, fetch user lists
POST	"I'd like to order something new"	Create data — send chat messages, submit forms
PUT	"Change my order to no spice"	Update data — modify user info
DELETE	"Cancel that dish"	Delete data

AI API calls use POST — because you're "submitting" a request for the AI to generate content.

---

AI APIs: Add a Brain to Your Product

You don't need to train your own AI model — just call existing capabilities. Main options:

• OpenAI API — GPT-4o series, best documentation, largest community
• Anthropic Claude API — Excellent at long-form text, up to 200K tokens
• Tongyi Qianwen API (Alibaba) — Strong Chinese understanding, affordable
• Wenxin Yiyan API (Baidu) — Easy integration with Baidu ecosystem
• Zhipu API (Tsinghua-affiliated) — GLM series, great value

Learn one, and you'll know them all.

---

Hands-On: Calling the OpenAI ChatGPT API

Python Version

# pip install openai python-dotenv
import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def generate_copywriting(product: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a senior e-commerce copywriting expert."},
            {"role": "user", "content": f"Write a ~100-word marketing copy for this product: {product}"}
        ],
        temperature=0.7,
        max_tokens=500,
    )
    return response.choices[0].message.content

print(generate_copywriting("Bluetooth noise-cancelling headphones"))

JavaScript Version

// npm install openai dotenv
import OpenAI from 'openai'
import 'dotenv/config'

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

async function generateCopywriting(product) {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'You are a senior e-commerce copywriting expert.' },
      { role: 'user', content: `Write a ~100-word marketing copy for this product: ${product}` }
    ],
    temperature: 0.7,
    max_tokens: 500,
  })
  return response.choices[0].message.content
}

console.log(await generateCopywriting('Bluetooth noise-cancelling headphones'))

---

Hands-On: Calling the Claude API

Python Version

# pip install anthropic python-dotenv
import os
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)
print(response.content[0].text)

JavaScript Version

// npm install @anthropic-ai/sdk dotenv
import Anthropic from '@anthropic-ai/sdk'
import 'dotenv/config'

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })

const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain quantum computing in simple terms' }],
})
console.log(response.content[0].text)

Note the format difference: OpenAI uses choices[0].message.content, Claude uses content[0].text.

---

Error Handling and Retries

API calls can fail: network timeouts, rate limits, exhausted quotas. You need to handle them gracefully:

import time
from openai import OpenAI, APIError, RateLimitError, APITimeoutError

def call_with_retry(func, max_retries=3, base_delay=1):
    """Retry with exponential backoff"""
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, APITimeoutError):
            wait_time = base_delay * (2 ** attempt)
            print(f"Request failed, retrying in {wait_time} seconds...")
            time.sleep(wait_time)
        except APIError as e:
            if attempt < max_retries - 1:
                time.sleep(base_delay * (2 ** attempt))
            else:
                raise
    raise Exception("Max retries exceeded")

# Usage
result = call_with_retry(lambda: client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
))

Exponential backoff: Wait 1 second the first time, 2 seconds the second, 4 seconds the third. Don't retry aggressively, or the API will block you.

---

Environment Variables: Protect Your Keys

API keys are like bank passwords — never put them in your code.

.env file (not committed to Git):

OPENAI_API_KEY=sk-xxx...xxxx
ANTHROPIC_API_KEY=sk-ant...xxxx

.env.example file (committed to Git — tells collaborators what variables are needed):

OPENAI_API_KEY=sk-you...here
ANTHROPIC_API_KEY=sk-ant...here

Add to .gitignore:

.env
.env.local

Reading in code:

# Python
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

// Node.js
import 'dotenv/config'
const apiKey = process.env.OPENAI_API_KEY

When deploying to Vercel, configure environment variables in the project settings.

---

API Rate Limits

Every API has rate limits. Exceed them and you'll get 429 Too Many Requests. Simple solution:

import time

class RateLimiter:
    def __init__(self, max_calls_per_minute=20):
        self.max_calls = max_calls_per_minute
        self.calls = []

    def wait_if_needed(self):
        now = time.time()
        self.calls = [t for t in self.calls if now - t < 60]
        if len(self.calls) >= self.max_calls:
            sleep_time = 60 - (now - self.calls[0])
            time.sleep(sleep_time)
        self.calls.append(time.time())

limiter = RateLimiter(max_calls_per_minute=20)
for question in questions:
    limiter.wait_if_needed()
    result = ask_claude(question)

---

Streaming Responses: Real-Time Output Like ChatGPT

Normal API calls wait for the entire response before returning. Streaming lets users see content appear in real time.

# Python streaming
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

// JavaScript streaming
const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a joke' }],
  stream: true,
})
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content
  if (content) process.stdout.write(content)
}

For any user-facing AI feature, streaming is strongly recommended.

---

Project: Add an AI Chat Box to Your Website in 10 Lines

Frontend (HTML):

<div id="chat" style="height:300px;overflow:auto;border:1px solid #ccc;padding:10px;"></div>
<input id="input" style="width:70%;" placeholder="Type a question..." />
<button onclick="send()">Send</button>
<script>
async function send() {
  const msg = document.getElementById('input').value
  if (!msg) return
  document.getElementById('input').value = ''
  document.getElementById('chat').innerHTML += `<p><b>You:</b>${msg}</p>`
  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: msg }),
  })
  const data = await res.json()
  document.getElementById('chat').innerHTML += `<p><b>AI:</b>${data.reply}</p>`
}
</script>

Backend (Next.js app/api/chat/route.ts):

import OpenAI from 'openai'
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

export async function POST(request: Request) {
  const { message } = await request.json()
  const response = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: message }],
  })
  return Response.json({ reply: response.choices[0].message.content })
}

A complete AI chat box — 10 lines each for frontend and backend.

---

Cost Management

Pricing Reference

Model	Input	Output	Best For
GPT-4o-mini	$0.15/million tokens	$0.60/million tokens	Everyday chat
GPT-4o	$2.5/million tokens	$10/million tokens	Complex reasoning
Claude Sonnet	$3/million tokens	$15/million tokens	Long text, code
Qwen-turbo	¥0.3/10K tokens	¥0.6/10K tokens	Budget-friendly

1 token ≈ 1-2 Chinese characters. For personal projects, $5-20/month is usually enough.

Cost Control Tips

1. Choose the right model: Use mini for simple tasks, expensive models only for complex ones
2. Set max_tokens: Prevent overly long responses
3. Set spending limits: Configure Usage Limits in the OpenAI dashboard
4. Cache results: Don't re-call for identical requests

import hashlib, json
cache = {}
def cached_call(messages, model="gpt-4o-mini"):
    key = hashlib.md5(json.dumps(messages, ensure_ascii=False).encode()).hexdigest()
    if key in cache:
        return cache[key]
    result = client.chat.completions.create(model=model, messages=messages)
    cache[key] = result
    return result

---

Chinese AI APIs in Practice

Chinese AI models have their own advantages: fast access from China (no VPN needed), strong Chinese language understanding, and competitive pricing. Good news: many are compatible with the OpenAI SDK format.

Tongyi Qianwen (Alibaba)

# pip install openai python-dotenv
from openai import OpenAI
client = OpenAI(
    api_key="your-dashscope-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
response = client.chat.completions.create(
    model="qwen-turbo",
    messages=[{"role": "user", "content": "Explain blockchain in three sentences"}],
)
print(response.choices[0].message.content)

Zhipu AI (GLM Series)

from openai import OpenAI
client = OpenAI(
    api_key="your-zhipu-key",
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)
response = client.chat.completions.create(
    model="glm-4-flash",  # Free model!
    messages=[{"role": "user", "content": "Explain blockchain in three sentences"}],
)
print(response.choices[0].message.content)

Wenxin Yiyan (Baidu)

# pip install qianfan
import qianfan
chat = qianfan.ChatCompletion()
response = chat.do(
    model="ERNIE-Speed-128K",
    messages=[{"role": "user", "content": "Explain blockchain in three sentences"}],
)
print(response["result"])

Both Tongyi Qianwen and Zhipu are compatible with the OpenAI SDK — just swap the base_url and api_key. The code barely changes. Learn one, and you've learned three.

---

Integrating AI into Your Product

Core principle: API keys must stay on the backend. Frontend code is visible to users — a leaked key means someone else runs up your bill.

// Next.js API route: app/api/generate/route.ts
import OpenAI from 'openai'
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

export async function POST(request: Request) {
  const { prompt } = await request.json()
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: prompt }],
  })
  return Response.json({ result: response.choices[0].message.content })
}

The frontend calls /api/generate with a prompt. Users have no idea OpenAI is behind it — it's just a feature of your product.

---

Summary

An API is a bridge to external capabilities. Five key takeaways:

1. API keys always go in environment variables, never in code
2. Backend calls the AI API, frontend never touches keys directly
3. Add error handling and retries so your code doesn't break easily
4. Use streaming responses for a dramatically better user experience
5. Choose the right model to control costs — cheap models for simple tasks

A few lines of code, and your product has AI capabilities. That's pretty cool, isn't it?