零基础读懂 HTTP 与 API一篇文章打通你的第一次接口调用适合读者刚学编程、想调用大模型或其他在线服务但看到 curl、JSON、API Key 就发懵的新手。读完你会看得懂 curl、认得出状态码、会解析嵌套 JSON、理解 REST 风格、会带认证、会处理限流。先记住一句话API 就是一个「会办事的网址」。你向它发一个 HTTP 请求它返回一个 HTTP 响应响应里通常装着 JSON。所谓「调 API」就是把请求四要素拼对再把返回的 JSON 按路径取出来。很多人第一次接触 API 时会被一堆术语吓退URL、Header、Bearer Token、JSON、REST……其实每个词单独看都很简单只是堆在一起显得可怕。这篇文章把整个过程拆成六步每一步都带一个能直接运行的例子。跟着走完你就能完成第一次真实的接口调用。1. HTTP 请求四要素任何一个 HTTP 请求都由下面四样东西组成要素是什么一句话例子URL你要访问的地址https://api.example.com/users?page2方法你想干什么GET读取、POST创建Headers附加说明和身份Authorization、Content-TypeBody随请求发送的数据JSON 字符串比如用户信息1.1 URL 长什么样https://api.example.com/v1/users/42?page2size10 │ │ │ │ │ │ │ │ │ └── query 查询参数问号后面 │ │ │ └────── 路径里的变量用户 id42 │ │ └─────────────── 路径path │ └──────────────────────────────── 域名哪台服务器 └────────────────────────────────────── 协议走 HTTP 还是 HTTPS1.2 四种常用方法方法含义常见场景Body 用不用GET读数据查天气、查用户列表一般不写POST创建数据 / 触发动作发消息、提交表单、调用大模型经常写PUT整体替换更新更新一个用户写DELETE删除删除一条记录一般不写1.3 Headers 里最常看的三个Header作用Authorization放认证信息最常见的是Bearer 你的keyContent-Type声明 Body 是什么格式发 JSON 时写application/jsonAccept声明你想要什么格式一般写application/json2. 第一次调用从 curl 到 Python下面这段是调用大模型 chat API 的标准写法我们一行一行拆开看curl-XPOSThttps://api.deepseek.com/chat/completions\-HAuthorization: Bearer sk-你的key\-HContent-Type: application/json\-d{ model: deepseek-chat, messages: [ {role: user, content: 你好} ] }curl 片段翻译成人话curl用命令行发 HTTP 请求-X POST方法用 POSThttps://...目标 URL-H Authorization: Bearer sk-你的keyHeader 里带 Bearer Token 认证-H Content-Type: application/jsonBody 是 JSON-d {...}Body 内容用单引号包起来的 JSON用 Python 的requests写同一件事importrequests resprequests.post(https://api.deepseek.com/chat/completions,headers{Authorization:Bearer sk-你的key,Content-Type:application/json,},json{model:deepseek-chat,messages:[{role:user,content:你好}],},timeout30,)print(resp.status_code)print(resp.json())注意用requests时传json{...}会自动把 Python 字典转成 JSON并帮你加Content-Type: application/json不需要手动声明。3. 看状态码再决定下一步状态码是服务器给你的「一句话结论」。看到任何响应先看状态码再决定要不要解析 Body。状态码含义新手该怎么做200成功正常解析 JSON400客户端参数错检查 URL、参数、Body 字段名和文档逐字对401未认证立刻检查 API key没填、填错、格式不对、过期了403无权限key 是对的但没有权限访问这个资源404资源不存在检查 URL 路径拼写尤其{id}有没有写对429限流降低请求频率等一下再试500服务器错误问题大概率在对方服务器稍后再试把 4xx 和 5xx 分开记4xx 是你的问题5xx 是服务器的问题。处理错误的最小框架ifresp.status_code401:print(认证失败检查 API key 和 Authorization 头)elifresp.status_code429:print(限流了等 1 秒再试或者降低频率)elifresp.status_code500:print(服务器出问题稍后重试)elifresp.status_code200:print(resp.json())4. JSON一棵嵌套的字典/列表树JSON 只有两种容器对象字典用{}表示数组列表用[]表示。它们可以任意嵌套所以任何 JSON 都是一棵树。{user:{name:小明,skills:[Python,API],profile:{city:Shanghai,level:1}}}解析 JSON 就是「按路径取值」像在文件系统里找文件一样dataresp.json()namedata[user][name]# 小明first_skilldata[user][skills][0]# Pythoncitydata[user][profile][city]# Shanghai对应路径写法想取的值路径用户名user-name第一个技能user-skills- 第 0 项城市user-profile-city调试 JSON 最实用的两句importjson# 第一次看到新 API先原样打印整棵树print(json.dumps(data,ensure_asciiFalse,indent2))三个常见翻车点忘了调resp.json()直接对resp.text取下标会报错或取到字符串。字段名打错会KeyError此时打印整棵树对照文档。API 返回的是列表而不是字典先data[0]再看。5. REST 风格路径、参数和 Body 的分工REST 是一种常见的 API 设计风格不是强制规范但绝大多数现代 API 都长这样。5.1/users/{id}是什么意思大括号{id}是「变量」的意思表示把{id}替换成真实的值文档写法真实请求GET /users/{id}GET /users/42GET /repos/{owner}/{repo}GET /repos/octocat/Hello-WorldDELETE /messages/{id}DELETE /messages/10015.2 query 参数怎么拼URL 里?后面的部分是 query 参数用连接多个GET https://api.example.com/search?qpythonpage2size10 │ │ │ └─────┴──────┴── 三个参数用requests时不要手拼字符串用paramsresprequests.get(https://api.example.com/search,params{q:python,page:2,size:10},timeout15,)5.3 Body 什么时候用规则很简单GET 一般不写 BodyPOST / PUT / PATCH 要写 Body因为你要往服务器传数据。Body 通常传 JSON也可以传表单或文件具体看文档里的Content-Type。5.4 一个能立刻动手的 REST 例子GitHub APIresprequests.get(https://api.github.com/users/octocat,timeout15)print(resp.status_code)dataresp.json()print(data[login])print(data[public_repos])6. 认证三种最常见的姿势6.1 Bearer Token大多数大模型 API 用这种curlhttps://api.example.com/v1/chat/completions\-HAuthorization: Bearer sk-xxxxheaders{Authorization:Bearer sk-xxxx}6.2 Basic Auth把用户名:密码做 Base64 编码后放进 Header。requests里直接传auth即可resprequests.get(https://api.example.com/private,auth(user,password),timeout15,)6.3 API Key 放在 Header 里有些 API 用自定义 Header常见名字有X-Api-Key、api-key、x-api-keyheaders{X-Api-Key:你的key}List item三种方式对比方式Header 长什么样谁常用Bearer TokenAuthorization: Bearer sk-xxxDeepSeek、通义千问、豆包、OpenAIBasic AuthAuthorization: Basic base64(用户名:密码)老系统、内部工具API Key in HeaderX-Api-Key: xxxTavily 等各类 SaaS6.4 Key 永远不要硬编码用 .env在项目根目录建.envDEEPSEEK_API_KEYsk-你的真实key代码里读取fromdotenvimportload_dotenvimportos load_dotenv()api_keyos.getenv(DEEPSEEK_API_KEY)headers{Authorization:fBearer{api_key}}安装依赖uv pip install requests python-dotenv最后在.gitignore里加一行.env防止把 key 提交到 GitHub。看到 401 的第一反应key 没传对。检查顺序.env里有没有值、变量名拼写、Authorization格式、key 有没有过期。7. 限流遇到 429 怎么办API 不是无限服务通常有 QPS每秒请求数限制。超过限制就会返回 429。别慌这是最常见的「正常报错」。最简单的重试逻辑遇到 429 就等一下再试。importtimedefpost_with_retry(url,headers,payload,max_tries3):forattemptinrange(1,max_tries1):resprequests.post(url,headersheaders,jsonpayload,timeout30)ifresp.status_code429:waitattempt*2# 第 1 次等 2 秒第 2 次等 4 秒依次递增print(f第{attempt}次遇到 429{wait}秒后重试)time.sleep(wait)continueresp.raise_for_status()returnrespraiseRuntimeError(多次重试仍然被限流)三个原则重试要有上限不要无限循环。等待时间递增2 秒、4 秒、8 秒这叫退避。服务器返回Retry-After头时优先按它给的秒数等。8. 新手最容易踩的八个坑把 key 写死在代码里或提交到 git。用.env.gitignore换台电脑也能迁移。手拼 URL 参数。用params{page: 2}让 requests 处理编码。不看状态码直接解析。先print(resp.status_code)再决定下一步。不设timeout。网络卡住时脚本会一直挂住请求都加timeout30之类。429 后无限重试。设max_tries加递增等待。把resp.text当字典用。先resp.json()得到 Python 结构。忽略Content-Type。Body 是 JSON 时用json发表单时才用data。看文档跳着读。文档顺序应该是认证 - Base URL - 端点 - 参数 - 示例 - 错误码。9. 常见报错速查报错 / 现象含义解决401 Unauthorized认证没通过检查 key、Header 格式、key 是否过期429 Too Many Requests请求太频繁sleep 后退避重试KeyError: xxxJSON 里没有这个字段打印整棵树和文档对照字段名IndexError: list index out of range数组是空的或取的位置不对先打印长度再取值JSONDecodeError响应不是 JSON打印resp.text可能返回了错误页面ConnectionError连不上服务器检查网络、URL、是否需要代理ReadTimeout服务器响应太慢调大 timeout 或换更快的端点No module named dotenv没装 python-dotenvuv pip install python-dotenv10. 30 分钟完成第一次调用安装依赖uv pip install requests python-dotenv5 分钟调https://httpbin.org/json打印slideshow.title。5 分钟调https://httpbin.org/post用json{name: 我}看它原样返回什么。5 分钟在 DeepSeek 平台创建 key写进.env跑通第一句「你好」。10 分钟把第 7 节的重试函数接进去故意连续发 20 次请求观察 429。5 分钟打开 GitHub API 文档只靠文档完成GET /users/{username}。完成这 6 步你就真正掌握了调 API 的主干流程。之后再去看任何 API 文档都会觉得只是换了 URL 和字段名。总结调 API 拼对请求四要素 解析 JSON。看到响应先看状态码4xx 检查自己5xx 等待服务器。key 放进.env管理429 用退避重试。下一步建议选一个免费 API比如 GitHub API按「认证 - Base URL - 端点 - 参数 - 示例 - 错误码」的顺序读一遍文档独立完成一次调用。第一次跑通之后你再看大模型的 chat API会发现它和 GitHub API 只是长得不同规则完全一样。想继续深入可以看这两个免费视频1 小时全面入门 HTTP 协议B 站免费课先建立整体感觉DeepSeek API 的 Python 调用小白详细教程直接对应本文的认证 POST JSON 解析