AI 新手入门 05：完成第一次 API 调用

前面几篇文章里，我们已经了解了 API Key、Base URL、模型名称 这些基础概念。

这一篇就开始真正动手：用 curl 完成第一次 AI API 调用。

你不需要一开始就写复杂代码，也不需要先做完整项目。新手第一次调用 API，最重要的目标只有一个：先跑通一次请求，看到 AI 正常返回结果。

说明：本文使用的是通用示例，里面的 Base URL、API Key、模型名称 都是占位符。不同服务商的接口地址、字段名称和请求格式可能不同，实际使用时请以你正在使用的服务商官方文档或控制台为准。

你会学到什么

这篇文章会讲清楚：

• API 调用的基本结构
• 请求和响应是什么
• 如何用 curl 测试 AI API
• 如何看懂返回结果
• 遇到常见报错应该怎么排查

一、什么是一次 API 调用？

一次 API 调用，就是你的程序向 AI 服务发送一段请求，然后 AI 服务返回结果。

可以把它理解成你在外卖软件下单：

换成 AI API 的流程，大概是这样：

你准备请求内容
  ↓
带上 API Key 发送请求
  ↓
AI 服务检查请求
  ↓
模型生成回答
  ↓
服务返回结果
  ↓
你从返回结果中取出 AI 的回答

所以，API 调用不是很神秘。它本质上就是：

你把问题发给 AI 服务，AI 服务把回答发回来。

二、一次请求通常包含什么？

一次 API 请求通常由几个部分组成。

新手可以先记住这句话：

URL 决定请求发到哪里，Headers 负责身份和格式，Body 负责具体任务。

举个很生活化的例子：

URL：我要把快递寄到哪个地址
Headers：我是谁，包裹是什么类型
Body：包裹里面到底装了什么
Model：指定让哪个工作人员处理
Messages/Input：我具体想让对方帮我做什么

三、curl 是什么？

curl 是一个命令行工具，可以用来发送网络请求。

简单说，你可以用它来测试 API。

平时我们访问网站，是在浏览器里打开网页。使用 curl 时，是在命令行里直接向某个接口发送请求。

新手第一次调用 API，建议先用 curl 测试，而不是一上来就写进项目代码里。

原因很简单：

• curl 示例短，容易看懂。
• 出错时更容易排查。
• 可以先确认 API Key、Base URL、模型名称是否可用。
• 跑通之后，再写进 JavaScript、Python 或其他项目里会更稳。

新手第一次调用 API，建议先用 curl 测试，成功后再写进代码里。

四、第一次调用示例

下面是一个通用的 AI API 调用示例。

注意：

• https://api.example.com/v1/chat/completions 是占位地址。
• YOUR_API_KEY 是占位 API Key。
• your-model-name 是占位模型名称。
• 实际使用时，要替换成你服务商控制台或官方文档里提供的内容。

curl https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话解释什么是 API。"
      }
    ]
  }'

如果你是第一次看这段命令，可以先不用急着全部记住。下面逐行拆开看。

1. 请求地址

curl https://api.example.com/v1/chat/completions

这一行表示：向这个地址发送请求。

这里的地址通常由两部分组成：

Base URL + 接口路径

例如：

https://api.example.com + /v1/chat/completions

不同服务商的接口地址可能不一样，所以不要随便复制别人的地址。

Base URL 一定要看你正在使用的平台文档。

2. Content-Type

-H "Content-Type: application/json"

这一行表示：你发送的内容是 JSON 格式。

JSON 是 API 里很常见的数据格式，长得像这样：

{
  "name": "ApiUsPro",
  "type": "AI 教程网站"
}

如果这一行写错，服务商可能看不懂你发过去的内容。

3. Authorization

-H "Authorization: Bearer YOUR_API_KEY"

这一行是身份认证。

你可以把它理解成：

我带着钥匙来请求接口

其中：

YOUR_API_KEY

要替换成你自己的 API Key。

但不要把真实 API Key 写进公开文章、公开仓库、截图或前端代码里。

更安全的做法是放在环境变量里，或者放在服务端配置中。

4. model

"model": "your-model-name"

这一行表示：你要使用哪个模型。

这里的 your-model-name 只是占位符，实际使用时要换成服务商支持的模型名称。

如果模型名称写错，常见报错就是：

model not found
模型不存在
没有权限使用该模型

所以模型名不要自己猜，要看服务商官方文档或控制台。

5. messages

"messages": [
  {
    "role": "user",
    "content": "请用一句话解释什么是 API。"
  }
]

messages 是你发给 AI 的对话内容。

其中：

这段内容的意思是：

用户问 AI：请用一句话解释什么是 API。

AI 收到后，会根据这句话生成回复。

五、如何看懂返回结果？

API 返回的内容通常也是 JSON。

真实返回结果可能会比较长，新手第一次只需要关注 AI 回复的正文内容。

下面是一个简化示例：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "API 是软件之间互相沟通的接口。"
      }
    }
  ]
}

你最需要看的通常是这里：

"content": "API 是软件之间互相沟通的接口。"

也就是 AI 真正返回给你的回答。

不同服务商、不同接口返回结构可能不完全一样，但思路类似：

先找到返回结果
  ↓
找到 AI 回复所在字段
  ↓
取出正文内容
  ↓
显示到网页或保存到程序里

返回结果常见字段

新手第一次测试时，不用把所有字段都研究明白。

先确认这件事就可以：

有没有正常返回 AI 的回答。

六、常见错误排查

第一次调用 API，很可能不会一次成功。

这很正常。API 报错并不一定说明你不会，很多时候只是配置写错了。

下面把几个常见问题单独说一下。

1. 401 Unauthorized

这个错误一般和身份认证有关。

你可以检查：

• API Key 有没有复制完整。
• Bearer 后面有没有空格。
• API Key 前后有没有多余空格。
• 这个 Key 是否已经删除或失效。
• 当前请求是否使用了正确的服务商地址。

示例：

-H "Authorization: Bearer YOUR_API_KEY"

这里的格式不要随便改。

2. 404 Not Found

这个错误一般说明地址不对。

你可以检查：

• Base URL 是否写错。
• 接口路径是否写错。
• 是否多写或少写了 /v1。
• 当前服务商是否支持这个接口路径。

新手常见错误是：

把 A 平台的 Base URL 和 B 平台的接口路径混在一起用

这种情况很容易报错。

3. Model not found

这个错误一般说明模型名称不对，或者当前账号没有权限使用这个模型。

你可以检查：

• 模型名称是否拼写正确。
• 是否用了别的平台的模型名称。
• 当前服务商是否支持这个模型。
• 当前 API Key 是否有权限调用这个模型。

不要靠猜模型名。

模型名称以服务商官方文档或控制台显示为准。

4. JSON error

JSON 格式错误很常见。

比如：

• 少了逗号
• 多了逗号
• 引号不成对
• 大括号没有闭合
• 中文引号和英文引号混用

错误示例：

{
  "model": "your-model-name"
  "messages": []
}

这里 "your-model-name" 后面少了一个逗号。

正确写法：

{
  "model": "your-model-name",
  "messages": []
}

写 JSON 时，建议使用代码编辑器检查格式，不要在普通聊天窗口里随手改一大段。

七、新手调试顺序

如果请求失败，可以按下面顺序排查。

先检查 API Key
  ↓
再检查 Base URL
  ↓
再检查模型名称
  ↓
再检查 JSON 格式
  ↓
最后检查网络环境

不要一上来就怀疑代码整体错了。

新手排查 API 问题时，可以先用最小请求测试。

比如先只问一句：

请用一句话解释什么是 API。

不要一开始就发送很长的文章、很多参数或复杂业务逻辑。

建议第一次测试遵循这个顺序：

简单说：

先让接口跑通，再逐步加复杂内容。

八、不要直接复制陌生人的配置

网上很多教程可能已经过期。

特别是这些内容，可能会变化：

• Base URL
• 接口路径
• 模型名称
• 请求字段
• 返回格式
• 认证方式
• SDK 写法

所以你可以参考别人的教程，但不要完全照抄。

更稳的做法是：

先看教程理解思路
  ↓
再打开服务商官方文档
  ↓
复制官方示例
  ↓
替换成自己的 API Key 和模型名称
  ↓
用 curl 测试
  ↓
成功后再写进项目

重点记住这句话：

最终以你正在使用的服务商官方文档或控制台显示为准。

尤其是模型名和 Base URL，不要混用。

九、新手可复制测试模板

下面这个模板可以作为你第一次测试 API 的通用检查清单。

你可以先把占位符替换成自己的内容，再运行。

curl YOUR_BASE_URL/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话解释什么是 API。"
      }
    ]
  }'

替换说明：

注意：

不要把真实 API Key 发给别人，也不要放到公开代码里。

十、跑通以后下一步做什么？

当你用 curl 成功拿到 AI 回复后，就可以继续做这些事：

不要急着一口气做完整项目。

先完成一个最小流程：

用户输入问题
  ↓
后端调用 AI API
  ↓
拿到返回结果
  ↓
把 AI 回复显示到页面

这个流程跑通以后，你就真正完成了 AI API 的入门第一步。

本篇总结

• 一次 API 调用，就是你向 AI 服务发送请求，然后拿到返回结果。
• 请求通常包含 URL、Method、Headers、Body、Model 和 Messages/Input。
• 新手第一次调用 API，建议先用 curl 测试。
• 代码示例里不要使用真实 API Key，真实项目中也不要把 Key 放到前端。
• 看返回结果时，先找到 AI 回复的正文内容，不需要一开始研究所有字段。
• 遇到报错时，按 API Key、Base URL、模型名称、JSON 格式、网络环境的顺序排查。
• 网上教程可以参考，但最终以服务商官方文档或控制台为准。

下一步学习建议

下一篇建议阅读：

AI 新手入门 06：用 Codex、Claude Code 和 CC Switch 做项目

下一篇可以继续学习：

• AI 编程工具分别适合什么场景
• Codex、Claude Code、Cursor、CC Switch 有什么区别
• 怎么把 API 配置用到实际项目里
• 怎么让 AI 工具帮你修改代码
• 新手做项目时怎么减少报错和返工