想在应用里用上 AI 模型，第一行调用代码怎么写，是每个开发者都会遇到的起点。OpenAI 平台的首次调用其实只有四步：生成 key、把 key 放进环境变量、装官方 SDK（或直接用 curl）、发出第一条请求。但首次上手的人常卡在细节里：key 读不到、请求发不通、装错了第三方封装。这篇按教程的惯例给一条完整链路，每一步都给可照做的动作，最后给三个高频卡点的排查入口。各平台的同款篇目也备着：智谱清言侧见开放平台首次调用，DeepSeek 侧见DeepSeek API 用法，流程同构，可以互相印证。
完整链路：从注册到第一段回复
第一步，注册平台账号并创建一个项目，项目的意义在于隔离资源与用量，后面管 key 时会用到。第二步，在后台的 API keys 页生成一把新 key：系统通常只完整显示一次，当场复制保存；key 管理的完整做法——命名、最小权限、定期轮换——见API key 管理一篇，这里先拿到能用的程度即可。第三步，把 key 写进环境变量 OPENAI_API_KEY，具体写法下一节展开。第四步，装 SDK 发请求，收到第一段回复，链路就走通了。四步里没有一步需要复杂配置，多数卡点出在环境变量没生效与网络不通两处，文末单独讲。
SDK 怎么选：官方库优先，封装在后
SDK 的选择原则很朴素：先用官方库，再考虑封装。官方提供 Python 与 Node.js 两套主力 SDK，分别用 pip install openai 与 npm install openai 安装。官方库的价值在于把鉴权、超时、重试、类型定义这些杂事接管掉，你只管写业务参数。LangChain 一类的上层框架适合搭复杂应用，但首次调用的学习阶段不建议从框架起步：框架的抽象会遮住调用本身，出了问题分不清是模型的、框架的还是你代码的。先裸调成功一次，再上框架，每一层都心里有数。
最简调用：三要素与一条 curl
SDK 侧的最简调用只有三个要素：客户端对象、model 参数、messages 数组。客户端对象默认从环境变量读 key，代码里不出现任何密钥；model 填官方文档当前推荐的轻量款（模型名随版本更新，以官方文档为准）；messages 是一条角色加内容的列表，role 写 user，content 写你的问题。返回结果在响应对象的 choices 里，取第一个元素的 message.content 就是回复文本。curl 侧则是一条 POST 请求：地址是官方 API 域名下的 chat/completions 端点，头部带 Authorization: Bearer 加 key，body 是 model 与 messages 组成的 JSON。两种方式等价，SDK 胜在后续维护，curl 胜在验证连通——排查问题时先用 curl 打一发，能排除 SDK 层的干扰。
环境变量读 key：别让密钥进代码
环境变量这一步有三个常见姿势。终端临时导出：export OPENAI_API_KEY=你的key，当前会话有效，适合快速验证。写入 shell 配置文件：放进 .bashrc 或 .zshrc 一类，长期生效。项目内用 .env 文件：配合 dotenv 一类的加载库读入，记得把 .env 写进 .gitignore，别随仓库提交。共同纪律只有一条：key 不出现在代码、日志、提交历史里。判断环境变量是否生效有个土办法：新开一个终端跑 printenv OPENAI_API_KEY 一类命令，能打印出来才算数——编辑器从图形界面启动时继承的环境变量与终端可能不一致，这正是「本地能跑、编辑器里报鉴权错误」的常见来源。
| 写法 | 生效范围 | 适合的场景 |
|---|---|---|
| 终端临时导出 | 当前会话有效 | 快速验证 |
| 写进 shell 配置文件 | 长期生效 | 本机固定开发 |
| 项目内 .env 文件 | 由加载库读入 | 项目自带配置，需写进 .gitignore |
调不通先查哪：三个高频卡点
首次调用失败的三大来源，按命中率排序。一是 key 没被读到：环境变量没导出、编辑器没重启、变量名拼错，表现是 401 一类的鉴权报错，先确认进程里真的有这个变量。二是额度与限流：收到 You've hit your usage limit 一类提示说明额度用尽，属于账号侧问题，去后台核对额度与用量；限流的机制与应对见接口限流一篇。三是网络不通：公司防火墙或本地网络策略可能拦住请求，先用 curl 验证连通性，再判断是不是环境问题。报错的具体结构怎么读，错误结构一篇有完整拆解，读懂 error.type，排查就从猜变成查。走通第一段回复之后，可以让 DeepSeek 把这套四步链路整理成新人上手清单，再用豆包模拟几个报错场景做演练，第一次部署就能少走弯路。
首次调用速查
- 四步：建项目、生成 key、写环境变量、SDK 发请求
- SDK 先用官方库，学习期不碰上层框架
- key 只走环境变量，代码与提交历史里不出现
- curl 打一发可验证连通性，排除 SDK 干扰
- 401 查 key 读取，额度提示查后台，网络问题先 curl
关于首次调用的三问三答
- curl 和 SDK 要学哪个？两个都留着用：日常开发用 SDK，验证连通与排查问题用 curl，各司其职。
- key 可以直接写在代码里吗？不可以。代码会进版本库、会被分享，key 一旦入库就按泄露处理，永远走环境变量。
- 回复结构看不懂怎么办？先打印完整响应对象，确认 choices 的层级没取错；报错响应的解读见错误结构一篇。
