chatgpt接口文档核心读者是后端、前端、测试及第三方开发者，需聚焦请求/响应/错误调试；主干用真实curl与完整响应构建，参数必标必填性与典型值，错误码按http升序排列（401置顶），提供含异常处理的可运行代码片段。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
明确接口文档的核心读者和使用场景
写ChatGPT接口文档不是为了展示技术深度，而是让后端开发、前端联调、测试同学或第三方集成方能快速看懂怎么发请求、传什么参数、收什么响应、错在哪——如果文档里堆满Transformer原理或token计数公式，联调卡在第一步。
先问自己三个问题：谁会打开这份文档？他们最常卡在哪一步？上一次线上报错日志里反复出现的是哪个字段？答案直接决定文档的章节权重。
用真实请求-响应对构建主干结构
从OpenAI官方文档学来的最有效方法：每类接口都以一个可复制粘贴的curl命令开头，紧接原始HTTP响应体（含status code），再逐字段解释。
比如/chat/completions接口，第一行必须是：curl -X POST https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer sk-xxx" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4-turbo","messages":[{"role":"user","content":"你好"}]}'
紧接着贴出完整的200响应JSON，【不要删减任何字段，包括usage、system_fingerprint等看似无关的键】。删减等于埋雷——当测试同学发现文档没写finish_reason字段却实际返回了，就会怀疑整个文档可信度。
参数说明必须标注“是否必填”与“典型值示例”
方法一：表格化呈现关键参数
| 参数名 | 类型 | 必填 | 示例 | 说明 |
|--------|------|------|------|------|
| model | string | 是 | gpt-4-turbo | 不支持别名，必须用API文档明确列出的模型ID |
| temperature | number | 否 | 0.7 | 范围0~2，值越低输出越确定；设为0不等于关闭随机性，仍可能因token截断产生差异 |
方法二：对易错参数单独加警示段落
【max_tokens字段不是“最多生成这么多字”，而是“最多消耗这么多token”——中文平均1.5字≈1 token，英文1 word≈1 token。设为100却收到截断响应？先检查输入message是否已占去85 token。】
错误码列表按HTTP状态码升序排列
第一步：只列4xx和5xx中你真实返回过的状态码，删掉所有“理论上可能但从未触发”的条目。
用于在用户想通过浏览器自动化与 Google Gemini 或 ChatGPT 交互时。触发短语包括“ask Gemini”“ask ChatGPT”“ask GPT”“让...”。
第二步：每个错误码下必须包含——
① 触发条件（精确到字段）：例如400错误，不是写“请求格式错误”，而是写“当messages数组为空或首个message.role不为system/user/assistant时返回”；
② 响应体中的error.type值：如invalid_request_error；
③ 可立即验证的自查项：比如429错误，要求文档里明确写出“检查响应头X-RateLimit-Remaining是否为0，而非仅依赖body内message”。
第三步：把401 Unauthorized放在第一位——因为90%的首次调用失败源于密钥失效或权限不足，把它压到底部等于强迫用户滚动查找。
提供可运行的调试片段而非伪代码
方法一：Python requests片段（带异常分支）
```python
import requests
url = "https://api.openai.com/v1/chat/completions"
headers = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}
data = {"model": "gpt-4-turbo", "messages": [{"role": "user", "content": "列出三个调试API的技巧"}]}
try:
res = requests.post(url, headers=headers, json=data, timeout=10)
res.raise_for_status()
print(res.json()["choices"][0]["message"]["content"])
except requests.exceptions.Timeout:
print("请求超时，请检查网络或增大timeout值")
except requests.exceptions.HTTPError as e:
if res.status_code == 401:
print("API密钥无效或已过期")
else:
print(f"HTTP错误: {e}")
```
方法二：Postman环境变量配置提示
在Postman中创建环境，预置变量：{{api_base}} = https://api.openai.com/v1，{{api_key}} = sk-xxx；所有请求URL写成{{api_base}}/chat/completions，Headers里Authorization值设为Bearer {{api_key}}——这样团队成员导入集合后无需改任何URL或密钥就能跑通。
