AI编程 API接口调用教程｜附源码

随着大模型技术的快速发展，越来越多的应用开始接入 AI 能力，例如智能客服、AI 写作助手、代码生成工具、知识库问答系统、自动摘要、数据分析助手等。对于开发者来说，掌握 AI API 接口调用 是进入 AI 应用开发的第一步。

本文将以“AI 编程 API 调用”为主题，系统讲解如何从零开始完成接口调用，包括接口基本概念、请求流程、参数说明、Python 调用示例、Node.js 调用示例、流式输出、错误处理、重试机制以及一个简单的可运行项目源码示例。

本教程采用通用的“大模型 API 调用方式”进行讲解，适用于大多数兼容 Chat Completions 风格的 AI 接口。实际使用时，你只需要根据自己所使用的平台替换 API_KEY、BASE_URL 和模型名称即可。

一、什么是 AI API 接口？

AI API 接口可以理解为开发者与大模型服务之间的通信入口。

开发者不需要自己训练模型，也不需要部署复杂的 GPU 环境，只需要通过 HTTP 请求把用户的问题发送给 AI 服务，AI 服务处理后返回结果，应用程序再把结果展示给用户。

一个典型的 AI API 调用流程如下：

用户输入问题
    ↓
前端或后端接收问题
    ↓
后端调用 AI API
    ↓
AI 模型生成回答
    ↓
后端接收结果
    ↓
返回给前端展示

例如，用户输入：

请帮我写一段 Python 爬虫代码

程序将该内容通过 API 发送给大模型，大模型会返回类似下面的结果：

当然可以，下面是一个使用 requests 和 BeautifulSoup 的简单爬虫示例……

二、调用 AI API 前需要准备什么？

在正式编写代码前，通常需要准备以下内容。

1. API Key

API Key 是调用接口的身份凭证，相当于访问 AI 服务的“钥匙”。

一般可以在 AI 服务商的控制台中创建，例如：

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

在项目中，不建议直接把 API Key 写死在源码里，尤其不要提交到 GitHub。更推荐使用环境变量进行管理。

例如在 Linux / macOS 中：

export AI_API_KEY="你的API Key"

在 Windows PowerShell 中：

setx AI_API_KEY "你的API Key"

2. API Base URL

Base URL 是接口请求地址，例如：

https://api.example.com/v1

不同平台地址不同，使用时需要查看对应平台的官方文档。

3. 模型名称

调用大模型时通常需要指定模型名称，例如：

gpt-4o-mini
deepseek-chat
qwen-plus
glm-4

不同模型在能力、价格、上下文长度、响应速度等方面有所区别。开发阶段建议选择成本较低、速度较快的模型，正式上线后再根据业务场景选择合适模型。

三、AI API 请求结构说明

常见的聊天类 API 请求一般使用 POST 方法，请求体通常是 JSON 格式。

一个典型请求结构如下：

{
  "model": "your-model-name",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的 AI 编程助手"
    },
    {
      "role": "user",
      "content": "请用 Python 写一个快速排序"
    }
  ],
  "temperature": 0.7
}

四、核心参数详解

1. model

指定调用哪个模型。

"model": "your-model-name"

不同模型适合不同场景：

2. messages

messages 是对话消息数组，用来描述上下文。

常见角色包括：

示例：

[
  {
    "role": "system",
    "content": "你是一个资深后端工程师，回答要清晰、严谨。"
  },
  {
    "role": "user",
    "content": "请解释什么是 RESTful API。"
  }
]

在多轮对话中，可以把之前的用户问题和 AI 回答继续放入 messages 中，让模型理解上下文。

3. temperature

temperature 用于控制回答的随机性。

"temperature": 0.7

一般规律如下：

如果你在做代码生成、SQL 生成、配置文件生成，建议设置为 0.2 或 0.3。

4. max_tokens

max_tokens 用于限制模型最大输出长度。

"max_tokens": 1000

如果不设置，平台一般会使用默认值。对于摘要、标题生成等短文本任务，可以适当设置较小值；对于长文章、代码生成，可以设置较大值。

5. stream

stream 用于控制是否开启流式输出。

"stream": true

如果开启流式输出，模型会像打字一样逐步返回内容。适合聊天机器人、AI 写作工具、网页实时输出等场景。

五、Python 调用 AI API 示例

下面我们先写一个最简单的 Python 调用示例。

1. 安装依赖

pip install requests

2. Python 基础调用源码

新建文件：

touch ai_chat.py

写入以下代码：

import os
import requests


API_KEY = os.getenv("AI_API_KEY")
BASE_URL = "https://api.example.com/v1"
MODEL = "your-model-name"


def chat_with_ai(prompt: str) -> str:
    """
    调用 AI 聊天接口
    :param prompt: 用户输入内容
    :return: AI 回复文本
    """
    if not API_KEY:
        raise ValueError("请先设置环境变量 AI_API_KEY")

    url = f"{BASE_URL}/chat/completions"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    }

    payload = {
        "model": MODEL,
        "messages": [
            {
                "role": "system",
                "content": "你是一个专业的 AI 编程助手，擅长解释代码、生成代码和排查问题。"
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.3,
        "max_tokens": 1200
    }

    response = requests.post(url, headers=headers, json=payload, timeout=60)

    if response.status_code != 200:
        raise Exception(f"请求失败，状态码：{response.status_code}，响应：{response.text}")

    data = response.json()

    return data["choices"][0]["message"]["content"]


if __name__ == "__main__":
    user_input = input("请输入你的问题：")
    answer = chat_with_ai(user_input)
    print("\nAI 回复：")
    print(answer)

3. 运行代码

设置环境变量后运行：

python ai_chat.py

输入：

请用 Python 写一个冒泡排序，并解释代码逻辑

如果配置正确，你将会得到 AI 返回的代码和解释。

六、Node.js 调用 AI API 示例

如果你使用 Node.js，也可以通过 fetch 或 axios 来调用接口。

1. 初始化项目

mkdir ai-api-demo
cd ai-api-demo
npm init -y

如果你的 Node.js 版本较新，已经内置 fetch，可以直接使用。否则可以安装 node-fetch 或 axios。

这里使用 axios：

npm install axios dotenv

2. 创建环境变量文件

新建 .env 文件：

AI_API_KEY=你的API Key
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=your-model-name

3. Node.js 调用源码

新建 chat.js：

require("dotenv").config();
const axios = require("axios");

const API_KEY = process.env.AI_API_KEY;
const BASE_URL = process.env.AI_BASE_URL;
const MODEL = process.env.AI_MODEL;

async function chatWithAI(prompt) {
  if (!API_KEY) {
    throw new Error("请在 .env 文件中配置 AI_API_KEY");
  }

  const url = `${BASE_URL}/chat/completions`;

  const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`
  };

  const payload = {
    model: MODEL,
    messages: [
      {
        role: "system",
        content: "你是一个专业的 AI 编程助手，回答要准确、清晰，并尽量给出示例代码。"
      },
      {
        role: "user",
        content: prompt
      }
    ],
    temperature: 0.3,
    max_tokens: 1200
  };

  const response = await axios.post(url, payload, {
    headers,
    timeout: 60000
  });

  return response.data.choices[0].message.content;
}

async function main() {
  try {
    const prompt = "请用 JavaScript 写一个防抖函数，并解释使用场景";
    const result = await chatWithAI(prompt);
    console.log("AI 回复：\n");
    console.log(result);
  } catch (error) {
    if (error.response) {
      console.error("接口错误：", error.response.status, error.response.data);
    } else {
      console.error("请求失败：", error.message);
    }
  }
}

main();

运行：

node chat.js

七、如何实现多轮对话？

单轮对话只发送当前问题，多轮对话需要保存历史消息。

例如：

messages = [
    {
        "role": "system",
        "content": "你是一个耐心的编程老师。"
    },
    {
        "role": "user",
        "content": "什么是闭包？"
    },
    {
        "role": "assistant",
        "content": "闭包是指函数可以访问其外部作用域中的变量……"
    },
    {
        "role": "user",
        "content": "能用 JavaScript 举例吗？"
    }
]

这样模型就知道第二个问题中的“它”或“这个概念”指的是前面提到的闭包。

下面是 Python 多轮对话源码：

import os
import requests


API_KEY = os.getenv("AI_API_KEY")
BASE_URL = "https://api.example.com/v1"
MODEL = "your-model-name"


class AIChatSession:
    def __init__(self):
        self.messages = [
            {
                "role": "system",
                "content": "你是一个专业的 AI 编程导师，擅长用通俗语言解释复杂技术。"
            }
        ]

    def ask(self, question: str) -> str:
        self.messages.append({
            "role": "user",
            "content": question
        })

        url = f"{BASE_URL}/chat/completions"

        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {API_KEY}"
        }

        payload = {
            "model": MODEL,
            "messages": self.messages,
            "temperature": 0.4
        }

        response = requests.post(url, headers=headers, json=payload, timeout=60)

        if response.status_code != 200:
            raise Exception(response.text)

        data = response.json()
        answer = data["choices"][0]["message"]["content"]

        self.messages.append({
            "role": "assistant",
            "content": answer
        })

        return answer


if __name__ == "__main__":
    session = AIChatSession()

    while True:
        question = input("\n你：")
        if question.lower() in ["exit", "quit"]:
            break

        answer = session.ask(question)
        print("\nAI：")
        print(answer)

这个示例会持续保存上下文，因此用户可以连续提问。

不过需要注意：上下文越长，请求体越大，消耗的 token 越多，成本也越高。生产环境中一般需要对历史消息进行截断、摘要或压缩。

八、流式输出接口调用

在真实 AI 聊天产品中，我们通常不希望用户等待完整结果生成后再看到内容，而是希望模型一边生成一边展示。这就需要使用流式输出。

Python 流式输出示例

import os
import json
import requests


API_KEY = os.getenv("AI_API_KEY")
BASE_URL = "https://api.example.com/v1"
MODEL = "your-model-name"


def stream_chat(prompt: str):
    url = f"{BASE_URL}/chat/completions"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    }

    payload = {
        "model": MODEL,
        "messages": [
            {
                "role": "system",
                "content": "你是一个专业的 AI 编程助手。"
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.3,
        "stream": True
    }

    with requests.post(url, headers=headers, json=payload, stream=True, timeout=60) as response:
        if response.status_code != 200:
            raise Exception(response.text)

        for line in response.iter_lines():
            if not line:
                continue

            line = line.decode("utf-8")

            if line.startswith("data: "):
                data = line[6:]

                if data == "[DONE]":
                    break

                try:
                    chunk = json.loads(data)
                    delta = chunk["choices"][0].get("delta", {})
                    content = delta.get("content", "")

                    if content:
                        print(content, end="", flush=True)
                except json.JSONDecodeError:
                    continue


if __name__ == "__main__":
    stream_chat("请写一段 Python FastAPI 示例代码")

流式输出的核心是：

stream=True

以及逐行读取服务端返回的数据。

九、封装一个通用 AI API 客户端

在实际项目中，不建议每个地方都手写请求逻辑。更好的方式是封装一个客户端类，统一管理 API Key、请求地址、模型参数、异常处理等。

下面是一个较完整的 Python 封装源码。

import os
import time
import requests
from typing import List, Dict, Optional


class AIClient:
    def __init__(
        self,
        api_key: Optional[str] = None,
        base_url: str = "https://api.example.com/v1",
        model: str = "your-model-name",
        timeout: int = 60
    ):
        self.api_key = api_key or os.getenv("AI_API_KEY")
        self.base_url = base_url.rstrip("/")
        self.model = model
        self.timeout = timeout

        if not self.api_key:
            raise ValueError("API Key 不能为空，请传入 api_key 或设置环境变量 AI_API_KEY")

    def chat(
        self,
        messages: List[Dict[str, str]],
        temperature: float = 0.3,
        max_tokens: int = 1200,
        retries: int = 3
    ) -> str:
        url = f"{self.base_url}/chat/completions"

        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }

        payload = {
            "model": self.model,
            "messages": messages,
            "temperature": temperature,
            "max_tokens": max_tokens
        }

        last_error = None

        for attempt in range(retries):
            try:
                response = requests.post(
                    url,
                    headers=headers,
                    json=payload,
                    timeout=self.timeout
                )

                if response.status_code == 200:
                    data = response.json()
                    return data["choices"][0]["message"]["content"]

                if response.status_code in [429, 500, 502, 503, 504]:
                    last_error = Exception(f"临时错误：{response.status_code}，{response.text}")
                    time.sleep(2 ** attempt)
                    continue

                raise Exception(f"请求失败：{response.status_code}，{response.text}")

            except requests.RequestException as e:
                last_error = e
                time.sleep(2 ** attempt)

        raise Exception(f"请求多次失败：{last_error}")


if __name__ == "__main__":
    client = AIClient(
        base_url="https://api.example.com/v1",
        model="your-model-name"
    )

    messages = [
        {
            "role": "system",
            "content": "你是一个专业的后端架构师。"
        },
        {
            "role": "user",
            "content": "请解释微服务架构的优缺点。"
        }
    ]

    result = client.chat(messages)
    print(result)

这个封装具备以下特点：

1. 支持环境变量读取 API Key；
2. 支持统一配置 Base URL 和模型名称；
3. 支持超时设置；
4. 支持失败重试；
5. 对常见临时错误进行自动重试；
6. 业务代码更简洁。

十、常见错误及解决方法

1. 401 Unauthorized

表示认证失败。

常见原因：

• API Key 错误；
• API Key 没有权限；
• 请求头格式错误；
• 账号余额不足或服务未开通。

正确格式通常是：

Authorization: Bearer 你的APIKey

2. 404 Not Found

表示接口地址不存在。

可能原因：

• Base URL 写错；
• 接口路径写错；
• 服务商不支持该接口格式；
• 模型名称错误。

建议检查：

BASE_URL
/chat/completions
model

3. 429 Too Many Requests

表示请求过于频繁，触发限流。

解决方式：

• 降低请求频率；
• 增加重试和退避机制；
• 升级接口套餐；
• 使用队列削峰；
• 对重复问题做缓存。

4. 500 / 502 / 503

表示服务端错误或网关错误。

这类错误通常是临时问题，可以通过重试解决。生产环境中建议使用指数退避策略，例如第一次等待 1 秒，第二次等待 2 秒，第三次等待 4 秒。

5. 响应很慢

可能原因包括：

• prompt 太长；
• max_tokens 设置太大；
• 模型本身较慢；
• 网络延迟较高；
• 未使用流式输出。

优化方式：

• 缩短上下文；
• 对历史消息做摘要；
• 使用更快的模型；
• 开启流式输出；
• 设置合理超时时间。

十一、生产环境最佳实践

1. 不要在前端暴露 API Key

很多初学者会直接在前端 JavaScript 中调用 AI API，这样会导致 API Key 暴露。任何用户都可以通过浏览器开发者工具看到你的密钥，从而盗用接口额度。

正确做法是：

前端 → 你的后端服务 → AI API

API Key 应该只保存在后端。

2. 对用户输入进行限制

AI API 的费用通常与输入和输出 token 数量有关。如果不限制用户输入，可能导致成本失控。

建议限制：

• 单次输入长度；
• 单个用户每日调用次数；
• 单个 IP 调用频率；
• 最大输出长度；
• 文件上传大小。

3. 增加日志记录

建议记录以下信息：

• 请求时间；
• 用户 ID；
• 模型名称；
• 输入长度；
• 输出长度；
• 响应耗时；
• 错误状态码。

但要注意不要记录敏感信息，例如密码、身份证号、银行卡号等。

4. 设置超时和重试

调用外部 API 一定要设置超时，否则请求可能长期阻塞。

例如 Python 中：

requests.post(url, json=payload, timeout=60)

同时，应对临时错误进行有限次数重试，避免因为短暂网络波动导致业务失败。

5. 做好内容安全与风控

如果你的产品面向公众用户，建议增加内容审核、关键词过滤、敏感信息检测等能力。

特别是在以下场景中更需要注意：

• 用户生成内容平台；
• 教育产品；
• 企业知识库；
• 智能客服；
• 代码执行平台。

十二、完整项目示例：FastAPI 搭建 AI 聊天接口

下面给出一个简单的后端接口示例。前端或其他系统可以调用这个后端接口，由后端再请求 AI API。

1. 安装依赖

pip install fastapi uvicorn requests python-dotenv

2. 项目结构

ai_server/
├── main.py
├── ai_client.py
├── .env
└── requirements.txt

3. .env 文件

AI_API_KEY=你的API Key
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=your-model-name

4. ai_client.py

import os
import requests
from dotenv import load_dotenv

load_dotenv()


class AIClient:
    def __init__(self):
        self.api_key = os.getenv("AI_API_KEY")
        self.base_url = os.getenv("AI_BASE_URL", "https://api.example.com/v1")
        self.model = os.getenv("AI_MODEL", "your-model-name")

        if not self.api_key:
            raise ValueError("缺少 AI_API_KEY")

    def chat(self, prompt: str) -> str:
        url = f"{self.base_url.rstrip('/')}/chat/completions"

        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }

        payload = {
            "model": self.model,
            "messages": [
                {
                    "role": "system",
                    "content": "你是一个专业、严谨、友好的 AI 编程助手。"
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ],
            "temperature": 0.3,
            "max_tokens": 1500
        }

        response = requests.post(url, headers=headers, json=payload, timeout=60)

        if response.status_code != 200:
            raise Exception(f"AI API 调用失败：{response.status_code}，{response.text}")

        data = response.json()
        return data["choices"][0]["message"]["content"]

5. main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from ai_client import AIClient


app = FastAPI(title="AI 编程助手 API")

client = AIClient()


class ChatRequest(BaseModel):
    prompt: str


class ChatResponse(BaseModel):
    answer: str


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    if not request.prompt.strip():
        raise HTTPException(status_code=400, detail="prompt 不能为空")

    if len(request.prompt) > 4000:
        raise HTTPException(status_code=400, detail="prompt 过长")

    try:
        answer = client.chat(request.prompt)
        return ChatResponse(answer=answer)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

6. requirements.txt

fastapi
uvicorn
requests
python-dotenv

7. 启动服务

uvicorn main:app --reload --host 0.0.0.0 --port 8000

访问接口文档：

http://localhost:8000/docs

你可以在 Swagger 页面中测试 /chat 接口。

8. 使用 curl 测试

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"请用 Python 写一个二分查找算法，并解释时间复杂度"}'

返回示例：

{
  "answer": "下面是一个 Python 二分查找示例……"
}

十三、如何设计 Prompt 才能获得更好结果？

API 调用只是基础，真正影响 AI 输出质量的关键还包括 Prompt 设计。

一个好的 Prompt 通常包含：

1. 角色设定；
2. 任务目标；
3. 输入内容；
4. 输出格式；
5. 约束条件；
6. 示例。

例如：

你是一个资深 Python 后端工程师。
请根据下面的需求生成 FastAPI 接口代码。

需求：
1. 接口路径为 /users
2. 支持分页查询
3. 返回 JSON 数据
4. 使用 Pydantic 定义响应模型

要求：
1. 代码可以直接运行
2. 给出必要注释
3. 最后解释核心逻辑

相比只写“帮我写接口代码”，这种提示词会得到更稳定、更可用的结果。

十四、总结

本文完整介绍了 AI 编程中 API 接口调用的基本方法，包括：

• AI API 的基本调用流程；
• API Key、Base URL、模型名称等核心配置；
• 请求参数 model、messages、temperature、max_tokens、stream 的作用；
• Python 调用 AI API 的完整源码；
• Node.js 调用 AI API 的完整源码；
• 多轮对话实现方式；
• 流式输出实现方法；
• 通用 AIClient 封装；
• 常见错误排查；
• 生产环境最佳实践；
• FastAPI 搭建 AI 聊天接口完整项目示例。

对于初学者来说，建议先跑通最简单的单轮调用，再逐步加入多轮上下文、流式输出、错误重试、日志记录、限流和权限控制。对于实际项目来说，千万不要在前端暴露 API Key，也不要忽视成本控制和异常处理。

掌握 AI API 调用后，你就可以进一步开发更多 AI 应用，例如：

• AI 编程助手；
• 智能客服系统；
• 企业知识库问答；
• 自动文档生成；
• 代码审查工具；
• SQL 生成助手；
• AI 写作平台；
• 数据分析机器人。

AI API 是连接传统软件与大模型能力的桥梁。只要理解它的调用方式和工程化实践，就可以快速把 AI 能力集成到自己的产品中。