更新于

第一次调用 AI API 完整走一遍：从申请 Key 到看懂返回值

小白入门APIPython新手教程

如果你之前只在网页上和 ChatGPT、Claude 聊过天，第一次要自己写代码调 API，中间那道坎往往不是”代码难写”，而是不知道整个流程有哪些步骤、每一步该看什么。这篇文章把从零到跑通第一次 API 调用的完整过程走一遍，遇到报错时该怎么判断也一并说清楚。

一、先搞清楚你在调用什么

API 调用本质上是你的程序给一个远程服务器发一条 HTTP 请求，服务器跑完模型推理后把结果用 JSON 格式传回来。整个链路只有三个环节：

  1. 你 → 带着密钥和问题内容，发一个 HTTP POST 请求
  2. 服务器 → 验证密钥、跑模型、生成回复
  3. 你 → 收到 JSON 格式的返回值，从里面取出模型的回答文本

网页聊天工具帮你把这三步都包装好了，用 API 就是自己动手做这三步。不复杂，但每一步都有具体格式要求，第一次容易在格式上卡住。

二、准备工作：拿到一个可用的密钥

调用任何 API 之前，你需要一个 API Key（密钥），它的作用是告诉服务器”这次调用算谁的账”。拿密钥的路径通常是：

  • 官方渠道注册账号 → 在控制台生成密钥 → 密钥形如 sk-xxxxxxxxxxxx 这样一串字符
  • 或者通过API 中转服务获取，流程类似，只是接口地址（Base URL）不同

拿到密钥后第一件事：把它当密码一样保管，不要写死在代码里直接提交到 git 仓库，也不要发到聊天群里。推荐存成环境变量：

export API_KEY="sk-你的密钥"

三、第一次调用：用 curl 跑通最简单的请求

不装任何编程环境，用命令行的 curl 就能验证密钥能不能用。以一个通用的 Chat Completions 风格接口为例：

curl https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

这条命令做了三件事：告诉服务器数据格式是 JSON、带上密钥证明身份、在请求体里放入模型名和你要问的问题。如果一切正常，几秒内会收到一段 JSON 文本。

四、看懂返回的 JSON 结构

第一次看到返回值容易被里面的字段绕晕，实际上你只需要关心其中几个关键字段：

{
  "id": "chatcmpl-abc123",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "我是一个 AI 助手，可以帮你回答问题、写代码、整理信息。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 24,
    "total_tokens": 36
  }
}
字段含义什么时候要关心
choices[0].message.content模型的实际回答文本每次都要取这个
finish_reason回答是正常结束还是被截断值不是 stop 时要警惕（比如 length 表示被截断）
usage本次调用消耗的 Token 数关心成本时看这个，Token 概念参考这篇

新手最常犯的错是拿到整个 JSON 就直接展示给用户，正确做法是只提取 content 字段，其余字段是给你调试和统计用的。

五、用 Python 把调用写进程序里

命令行验证通过后，实际项目里通常用代码发起调用。一个最小可运行的 Python 例子：

import os
import requests

api_key = os.environ["API_KEY"]

response = requests.post(
    "https://api.example.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    },
    timeout=30,
)

data = response.json()
print(data["choices"][0]["message"]["content"])

几个新手容易漏掉的细节：

  • timeout=30 一定要加，不加的话网络异常时程序会一直卡住不报错。
  • 用 os.environ 读密钥，而不是把密钥字符串直接写在代码里。
  • response.json() 之前最好先检查 response.status_code，不是 200 就说明出错了，直接解析可能会报字段不存在的异常。

六、第一次调用最容易遇到的报错

按遇到概率从高到低排列：

401 Unauthorized（密钥无效） 最常见原因是密钥前后有多余空格，或者环境变量没有正确加载。检查方法：echo $API_KEY 看输出是否和你复制的密钥完全一致。

429 Too Many Requests（触发限流） 说明短时间内调用次数超过限额，不是密钥的问题。处理方式是加入重试等待，而不是立刻重复请求。

超时或连接失败 国内网络访问境外 API 服务器经常在这一步卡住。如果确认密钥和代码都没问题，大概率是网络链路问题，这也是很多开发者转向国内可直连的中转服务的直接原因。

返回 200 但 content 是空的 检查 finish_reason 字段，如果是因为触发了内容策略过滤，返回内容为空是正常行为，需要在业务逻辑里处理这种情况，而不是当作程序 bug 排查。

七、跑通第一次调用之后

第一次调用成功只是起点，实际项目里还需要考虑：密钥要不要做多把轮换、调用失败要不要自动重试、Token 消耗要不要做监控。这些工程化的问题不需要一开始就想清楚，先跑通、再迭代。

八、相关阅读

如果你在国内调用境外 API 时经常遇到连接超时，YoTradeApi 提供国内可直连的统一接口，密钥申请和调用方式与官方 API 基本一致，不用改代码就能跑通。

相关阅读