跳到主要内容

4.5 API 接入 AI 能力

什么是 API？用餐厅比喻彻底搞懂​

上一章我们说前端是前厅，后端是厨房。那 API 是什么？API 就是菜单 + 服务员 + 点餐规则的完整体系。

让我们把这个比喻展开，一步步走完：

第 1 步：走进餐厅（客户端发起请求）——你不会直接冲进厨房喊"给我做份红烧肉"。服务器也一样，它只通过 API 跟你对话。

第 2 步：看菜单（查阅 API 文档）——菜单告诉你有什么菜可点（可用的接口）、每道菜多少钱（计费）、需要等多久（响应时间）、有什么特殊要求可以提（请求参数）。

第 3 步：点菜（发送请求）——你跟服务员说"来一份红烧肉，不要辣，米饭换成面条"，相当于发一个请求附带参数。

第 4 步：厨房做菜（服务器处理）——你不知道有几个厨师、用什么锅、食材从哪来，你只需要等。

第 5 步：端菜（返回响应）——要么你收到想要的结果，要么告诉你"今天的鱼卖完了"（错误响应）。

你（客户端）→ 看菜单（API文档）→ 点菜（发送请求）→ 厨房做菜（服务器处理）→ 端菜（返回响应）

AI API 调用完整流程图​

HTTP 方法：请求的"语气"​

方法类比实际用途
GET"给我看看菜单"获取数据，查天气、获取用户列表
POST"我要点一份新菜"创建数据，发聊天消息、提交表单
PUT"我的菜改成不要辣"更新数据，修改用户信息
DELETE"这道菜我不要了"删除数据

调用 AI API 用的是 POST——因为你是在"提交"一个请求让 AI 生成内容。

AI API：给你的产品加上大脑​

你不需要训练自己的 AI 模型，直接调用现成的能力就行。主流选择：

  • OpenAI API —— GPT-4o 系列，文档最齐全，社区资源最多
  • Anthropic Claude API —— 长文本处理强，最高 200K Token
  • 通义千问 API（阿里）—— 中文理解好，价格便宜
  • 文心一言 API（百度）—— 百度生态集成方便
  • 智谱 API（清华系）—— GLM 系列，性价比高

学会一个，其他的也就会了。

实战：调用 OpenAI Responses API​

新项目优先使用 Responses API。Chat Completions 仍常见，但不要把某个模型名和价格永久写死在业务代码里。

Python 版本​

# 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.responses.create(
        model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
        instructions="你是一个资深的电商文案专家。",
        input=f"请为以下产品写一段 100 字左右的营销文案：{product}",
        max_output_tokens=500,
    )
    return response.output_text

print(generate_copywriting("蓝牙降噪耳机"))

JavaScript 版本​

// 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.responses.create({
    model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
    instructions: '你是一个资深的电商文案专家。',
    input: `请为以下产品写一段 100 字左右的营销文案：${product}`,
    max_output_tokens: 500,
  })
  return response.output_text
}

console.log(await generateCopywriting('蓝牙降噪耳机'))

实战：调用 Claude API​

Python 版本​

# 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": "用简单的语言解释什么是量子计算"}],
)
print(response.content[0].text)

JavaScript 版本​

// 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: '用简单的语言解释什么是量子计算' }],
})
console.log(response.content[0].text)

注意格式差异：OpenAI 用 choices[0].message.content，Claude 用 content[0].text。

错误处理与重试​

API 调用可能失败：网络超时、速率限制、额度用完。你需要优雅地处理：

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

def call_with_retry(func, max_retries=3, base_delay=1):
    """带指数退避重试"""
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, APITimeoutError):
            wait_time = base_delay * (2 ** attempt)
            print(f"请求失败，等待 {wait_time} 秒后重试...")
            time.sleep(wait_time)
        except APIError as e:
            if attempt < max_retries - 1:
                time.sleep(base_delay * (2 ** attempt))
            else:
                raise
    raise Exception("重试次数用完")

# 使用
result = call_with_retry(lambda: client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[{"role": "user", "content": "你好"}],
))

指数退避：第一次等 1 秒，第二次 2 秒，第三次 4 秒。不要疯狂重试，否则 API 会把你拉黑。

环境变量：保护你的密钥​

API Key 就像银行密码——绝对不能写在代码里。

.env 文件（不提交到 Git）：

OPENAI_API_KEY=***
ANTHROPIC_API_KEY=***

.env.example 文件（提交到 Git，告诉协作者需要哪些变量）：

OPENAI_API_KEY=***
ANTHROPIC_API_KEY=***

.gitignore 加上：

.env
.env.local

代码中读取：

# 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

部署到 Vercel 时，在项目设置里配置环境变量即可。

API 速率限制​

每个 API 都有速率限制。超限会返回 429 Too Many Requests。简单应对：

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)

流式响应：像 ChatGPT 一样实时输出​

普通调用要等全部生成完才返回。流式响应（Streaming）让用户实时看到内容逐渐出现。

# Python 流式
stream = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[{"role": "user", "content": "讲一个笑话"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
// JavaScript 流式
const stream = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL,
  messages: [{ role: 'user', content: '讲一个笑话' }],
  stream: true,
})
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content
  if (content) process.stdout.write(content)
}

任何面向用户的 AI 功能，强烈建议都用流式。

实战项目：10 行代码给网站加个 AI 聊天框​

前端（HTML）：

<div id="chat" style="height:300px;overflow:auto;border:1px solid #ccc;padding:10px;"></div>
<input id="input" style="width:70%;" placeholder="输入问题..." />
<button onclick="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>你：</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>

后端（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()
  if (typeof message !== 'string' || message.length === 0 || message.length > 2000) {
    return Response.json({ error: 'message 长度必须在 1-2000 字之间' }, { status: 400 })
  }
  const response = await client.chat.completions.create({
    model: process.env.OPENAI_MODEL,
    messages: [{ role: 'user', content: message }],
  })
  return Response.json({ reply: response.choices[0].message.content })
}

这是最小演示，不是可直接上线的接口。生产环境还要加身份验证、限流、超时和错误监控。

成本管理​

价格参考方式​

模型价格和上下文限制变化很快。上线前建立一张自己的成本表，记录“模型、输入单价、输出单价、一次典型请求的 Token 数、每日请求量”，并链接到供应商官方价格页。不要依据教程里的历史价格做预算。

Token 与中文字数不是固定换算关系，应使用目标模型对应的 tokenizer 或控制台用量统计测量真实请求。

控制成本的技巧​

  1. 选对模型：简单分类用 mini，复杂任务才用贵模型
  2. 设 max_tokens：防止回复过长
  3. 设消费上限：OpenAI 后台可设置 Usage Limits
  4. 缓存结果：相同请求不重复调用
import hashlib, json, os
cache = {}
def cached_call(messages, model=os.environ["OPENAI_MODEL"]):
    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

接入其他 AI 供应商​

部分供应商提供 OpenAI 兼容接口，但“兼容”通常只覆盖部分参数。接入前从供应商官方文档确认 base_url、模型 ID、流式格式、结构化输出和限流规则。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url=os.environ["AI_BASE_URL"],
)
response = client.chat.completions.create(
    model=os.environ["AI_MODEL"],
    messages=[{"role": "user", "content": "用三句话解释区块链"}],
)
print(response.choices[0].message.content)

把供应商差异放进环境变量和独立适配层，不要在业务组件里到处判断厂商名称。切换供应商前要重新跑流式输出、错误处理和结构化结果测试。

把 AI 接入你的产品​

核心原则：密钥必须放后端。前端代码用户能看到，密钥暴露 = 被盗刷。

// Next.js API 路由：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()
  if (typeof prompt !== 'string' || prompt.length === 0 || prompt.length > 2000) {
    return Response.json({ error: 'prompt 长度必须在 1-2000 字之间' }, { status: 400 })
  }
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
    input: prompt,
  })
  return Response.json({ result: response.output_text })
}

前端调用 /api/generate 传入 prompt 即可。公开上线前还必须增加用户身份验证、持久化限流、消费上限和滥用监控；只把密钥放到后端并不能防止接口被盗刷。

小结​

API 就是连接外部能力的桥梁。五个关键要点：

  1. API Key 永远放环境变量，不要写在代码里
  2. 后端调用 AI API，前端不直接接触密钥
  3. 加上错误处理和重试，代码不会一碰就碎
  4. 用流式响应，用户体验提升一个档次
  5. 选对模型控成本，简单任务用便宜模型

几行代码，让你的产品拥有 AI 能力。这件事本身就很酷，不是吗？ HEREDOC_END