从零完成第一次 AI API 调用：一份可落地的接入指南

接入 AI API 的第一步，是把接口地址、模型名称和请求格式对齐。先用一个简短的文本请求跑通链路，再逐步加入多轮对话、流式输出或业务数据，排错会容易得多。

开始前准备三项信息#

在控制台准备 API 密钥，并在模型页面确认当前账号可用的模型及其接入协议。本文使用本站提供的聊天补全接口；并非所有模型都支持这一协议，图片、视频与部分专用模型应按对应文档接入。

• 接口根地址：使用站点文档提供的 API 地址，区分网站首页地址与实际 API 地址。
• 模型标识：复制完整的模型 ID，不能只填写页面展示名称。
• API 密钥：由你的服务端读取，不要放进网页代码、公开仓库或分享截图。

本文约定环境变量 AI_API_BASE 已包含 /v1，结尾不带斜杠。如果文档给出的完整地址已经是 /v1/chat/completions，就不要再次拼接相同路径。

用 Python 发出一个最小请求#

先在自己的运行环境设置 AI_API_BASE、AI_API_KEY、AI_MODEL 三个环境变量。下面只依赖 Python 标准库，可以保存为 hello_ai.py 后运行。

import json
import os
import urllib.request

base = os.environ["AI_API_BASE"].rstrip("/")
payload = {
    "model": os.environ["AI_MODEL"],
    "messages": [
        {"role": "user", "content": "请用一句话解释什么是 API。"}
    ],
    "stream": False,
}
request = urllib.request.Request(
    base + "/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["AI_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=60) as response:
    result = json.load(response)
print(result["choices"][0]["message"]["content"])

这段示例只读取普通文本回答，目的是验证连通性。使用工具调用或其他输出类型时，必须根据模型文档解析对应字段，不能假设每次都有可显示的文本。示例中的 60 秒是网络操作超时设置，不代表生产系统的完整任务截止时间。

成功返回后检查什么#

首先确认返回内容对应这次问题，其次在控制台查看本次调用记录，核对模型、状态和时间。不要把 HTTP 请求成功等同于业务完成：输出为空、结构不符合约定或回答被截断，都需要单独处理。

在应用中保存必要的请求标识与耗时，方便定位问题。调试日志应过滤密钥，并根据数据敏感程度决定是否记录输入与输出，不应默认保存完整用户内容。

逐步接入真实业务#

建议按顺序增加复杂度：先固定问题，再替换为用户输入，然后增加上下文，最后启用流式输出。每一步都保留一个可以重复运行的最小请求。

多轮对话通常需要按接口约定重新提交必要的历史消息。历史越来越长时，优先保留当前任务相关信息；对于旧消息可以做摘要，但订单号、金额、用户明确约束等关键事实应保持原值。

上线前的检查清单#

• 为外部请求设置超时，并区分失败、处理中和完成状态。
• 确认模型与协议匹配，测试空输入、长输入和异常响应。
• 将密钥留在服务端，生产环境使用 HTTPS。
• 对并发和重试设置上限，避免故障时形成请求风暴。
• 在控制台核对调用记录，确保能从业务请求追踪到 API 请求。

下一步可以阅读流式输出接入指南和API 报错排查指南。