z17code头像
拿到 API Key 和 Base URL 之后怎么用?一文讲透(附 Python / curl / 客户端配置全示例)封面图

拿到 API Key 和 Base URL 之后怎么用?一文讲透(附 Python / curl / 客户端配置全示例)

很多朋友第一次接触大模型 API(或者其他 REST API)时,拿到了平台发给的 API Key 和 Base URL,却不知道下一步该干什么。这篇文章就把这一步到跑通之间的所有坑都讲清楚。

一、先搞懂这两个东西是什么

1. API Key 是什么?

API Key 相当于你的"身份证 + 钱包":

  • 身份认证:服务器通过它确认请求是你发的;
  • 计费依据:你调用接口消耗的 token / 次数都会记在这个 key 上。

所以它和密码一样重要,绝对不要:

  • 硬编码在代码里上传到 GitHub;
  • 发到群里、贴到评论区;
  • 写在前端页面代码中(前端的一切都是公开的)。

2. Base URL 是什么?

Base URL 就是接口服务的根地址。

以 OpenAI 兼容接口为例,完整请求地址通常是:

{base_url}/chat/completions

比如你的服务商文档中给出的地址形如:

https://api.你的服务商域名.com/v1

注意:有的文档给的是带 /v1 的,有的不带,SDK 的填法也不一样,这是新手最容易踩的坑之一,后文会细说。

下文统一用 YOUR_BASE_URL 代表你自己的 Base URL,用 YOUR_API_KEY 代表你自己的 Key,用 your-model 代表平台文档里的模型名。

现在绝大多数模型服务商都兼容 OpenAI 接口格式,也就是说:只要你会用一套代码,换一个 base_url + api_key + model 就能切换任意服务商。


二、第一步:把 Key 存到环境变量里

不要把 key 直接写在代码里。正确做法是放进环境变量。

Windows(PowerShell,临时生效)

$env:API_KEY = "YOUR_API_KEY"
$env:BASE_URL = "YOUR_BASE_URL"

Windows(永久生效)

setx API_KEY "YOUR_API_KEY"
setx BASE_URL "YOUR_BASE_URL"

设置完需要重新打开终端才会生效。

Linux / macOS

# 临时生效
export API_KEY="YOUR_API_KEY"
export BASE_URL="YOUR_BASE_URL"

# 永久生效:写入 ~/.bashrc 或 ~/.zshrc
echo 'export API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc

或者使用 .env 文件(推荐项目内使用)

在项目根目录创建 .env:

API_KEY=YOUR_API_KEY
BASE_URL=YOUR_BASE_URL

再创建 .gitignore,把 .env 加进去:

.env

三、第二步:用代码调通第一个请求

方式一:Python + OpenAI 兼容 SDK(最推荐)

安装:

pip install openai  # OpenAI 兼容接口的通用 SDK

代码:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url=os.environ["BASE_URL"],
)

response = client.chat.completions.create(
    model="your-model",  # 换成你所用平台的模型名
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "你好,介绍一下你自己"},
    ],
)

print(response.choices[0].message.content)

看到回复输出,就说明整条链路已经通了。

流式输出(打字机效果):

stream = client.chat.completions.create(
    model="your-model",
    messages=[{"role": "user", "content": "写一首关于秋天的诗"}],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

方式二:Python + requests(理解底层原理)

不借助 SDK,直接发 HTTP 请求,帮你理解本质:

import os
import requests

url = os.environ["BASE_URL"] + "/chat/completions"

headers = {
    "Authorization": f"Bearer {os.environ['API_KEY']}",
    "Content-Type": "application/json",
}

data = {
    "model": "your-model",
    "messages": [{"role": "user", "content": "你好"}],
}

resp = requests.post(url, headers=headers, json=data)
print(resp.json()["choices"][0]["message"]["content"])

关键点就在这里:

  • API Key 放在请求头 Authorization: Bearer <你的key> 中;
  • Base URL 拼接路径 /chat/completions 构成最终地址。

所有 SDK 都是在替你做这两件事。

方式三:curl 命令行快速验证

拿到 key 后第一件事,建议先用 curl 测一下通不通:

curl YOUR_BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "hello"}]
  }'

Windows 下注意 JSON 里的双引号需要转义,或者把 -d 后面的内容存成文件再用 -d @body.json。


四、第三步:在现成客户端软件里配置

不想写代码?大部分桌面客户端也支持自定义 API:

桌面客户端的通用套路(各类 AI 对话客户端均类似)

打开设置,一般会看到三个输入框:

  1. API Key → 粘贴你的 key;
  2. API Host / API 地址 / Base URL → 粘贴 base url;
  3. 模型名称 → 手动填写平台文档里的模型名。

保存后新建对话即可使用。

常见坑:URL 结尾要不要 /v1?

不同软件要求不一样:

  • 有的会自动帮你拼 /v1/chat/completions,此时你填服务商根域名即可,多写了反而 404;
  • 有的要求填文档中给出的完整 base url。

排查方法:报 404 就去掉或加上 /v1 再试;报 401 说明是 key 的问题而不是 URL 的问题。


五、常见报错与排查

报错含义解决办法
401 UnauthorizedKey 错误或没传对检查 key 是否复制全、是否过期、是否加了 Bearer 前缀
404 Not FoundURL 路径不对检查 base_url 是否多了/少了 /v1
429 Too Many Requests触发限流降低并发、加重试逻辑
402 / 403余额不足或无权限去平台充值或申请权限
insufficient_quota账户余额为零充值
连接超时网络不通国内访问境外 API 需要自行解决网络问题,或改用国内服务

调试建议:先用 curl 验证,再上代码。curl 通了代码不通,就是代码/SDK 配置问题;curl 都不通,就是网络或账号问题。


六、安全提醒(重要)

  1. Key 泄露 = 别人花你的钱。GitHub 上每天都有爬虫扫描泄露的 key,几秒钟就会被盗刷。
  2. 一旦怀疑泄露,立刻去平台后台吊销重置。
  3. 给 key 设置消费限额(多数平台支持),把损失锁死。
  4. 项目上线时,key 只放在服务端环境变量中,前端永远只请求你自己的后端。

总结

拿到 API Key 和 Base URL 后的三步走:

  1. 存环境变量 —— 不要硬编码;
  2. curl 或 SDK 发一个测试请求 —— 确认 key、url、模型名三者都对;
  3. 接入你的应用 —— 代码、第三方客户端均可。

本质上就是一件事:带着 Authorization: Bearer <key> 请求头,向 {base_url}/chat/completions 发一个 JSON。理解了这个,任何 OpenAI 兼容的平台对你来说都是换三个参数的事。

如果这篇文章帮到了你,欢迎点赞收藏,有问题评论区交流~

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/z17code/article/details/163999985

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--