利用curl调用Gemini API实现严格JSON输出：responseSchema实战

1. 先说清楚：这个接口到底能干什么，适合谁来用

做后端或者写自动化脚本的朋友，应该都有过这种经历：调一个 AI 模型的接口，返回结果五花八门，你想让它输出一份规规矩矩的 JSON，结果它给你来一段散文，气得人想把键盘拆了。

gemini-1.5-pro-001 这个模型，是 Google Gemini 系列里比较能打的一个版本。它支持长上下文，多模态输入，最关键的是它提供了一个"JSON 输出模式"，可以让模型严格按你定义的结构返回数据。这篇文章要讲的，就是如何用最朴素的方式——curl 命令行——把这个 JSON 输出功能调通，并且在实际项目里真正用起来。

适合谁看？三类人。第一类是刚接触 Gemini API、想快速验证一下能力的开发者；第二类是写脚本、写自动化工具、不想为了调一次接口就引入一整套 SDK 的人；第三类是已经在用 Gemini、但被非结构化输出折磨过的朋友。无论你是哪种，跟着这篇文章一步步走完，你至少能写出一个稳定返回 JSON 的 curl 调用，并且知道报错之后怎么排查。

我在文章里不会用任何代码框架，只讲 curl、JSON 和 Gemini 1.5 Pro 接口之间的配合逻辑。因为说白了，你理解了 HTTP 层面的请求和响应，后面不管换什么语言、什么 SDK，原理都是通的。JSON 格式也好，curl 的用法也好，本质上都是通用技能，学会了换到别的模型接口同样适用。

2. 调用前的准备工作：API Key 与 curl 环境

2.1 拿到 API Key 才能上路

调用 Gemini API 需要 API Key。这个 Key 在 Google AI Studio 页面里申请，申请之后是一串类似 AIzaSy 开头的字符串。流程不复杂，跟着官方指引填几个表单就行，这里不展开讲，重点说说 Key 的使用习惯。

第一，不要把 Key 硬编码在脚本里。尤其是你打算把脚本分享出去、或者提交到代码仓库的时候，Key 一旦泄露，别人就能拿你的额度去调用。我个人的做法是存在环境变量里，调用的时候用 $GEMINI_API_KEY 引用，这样既安全，换 Key 的时候也不用改代码。

第二，Key 是有配额的。免费 Key 能调用的次数和每分钟请求数都有限制，生产环境需要另外开通计费。如果某天突然返回 403 或者 429，先查一下是不是 Key 的额度用完了，别一上来就怀疑是代码写错了。

第三，Key 是通过 URL 参数方式传递的，不是放在 Header 里。这一点跟很多其他 API 不一样，容易搞混。Gemini API 的请求格式是这样的：

code复制https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key=你的API_KEY

有些人习惯把认证信息往 Authorization Header 里塞，然后发现返回 400 或者 401，其实就是因为认证参数放错了位置。这个坑我见过不止一次，提醒一句：Gemini API 的 REST 接口认的是 URL 上的 key 参数。

2.2 curl 环境的三个注意点

curl 是现代操作系统里的标配工具。Windows 10 以上版本自带 curl.exe，macOS 和 Linux 更是天生就有。你真要在各种环境里用 curl 调接口，有几个细节值得注意。

第一是版本。Windows 自带的 curl 版本可能比较旧，某些新特性用不了。比如 --json 这个快捷参数是 curl 7.82.0 才有的功能，它会自动帮你设置 Content-Type: application/json，同时把请求体里的 JSON 原样发出去。如果版本太旧，就老老实实用 -H 和 -d 的组合。

第二是引号问题。在 Windows 的 CMD 或者 PowerShell 里写 JSON，单双引号的处理跟 Linux 完全不同。CMD 里 JSON 字符串里的双引号需要转义成 \"，写起来非常痛苦。我踩过不少次这个坑，后来干脆把小 JSON 请求体写成一份 .json 文件，用 -d @request.json 的方式提交，既避免了转义地狱，又方便维护。

第三是单文件版 curl。有些老系统（比如网上经常有人提到的 32 位 Win7 环境）不自带 curl，需要自己下载一个独立的 curl.exe。这个单文件版本不需要安装，解压之后直接丢到 PATH 里就能用，对临时调试来说非常方便。下载时认准 curl 官网的官方版本就行，别去那些来路不明的下载站，否则容易拿到被植入广告或者恶意行为的假 curl。

注意：无论是哪种系统，调用 HTTPS 接口都需要 openssl 相关依赖。如果你遇到 curl: (35) TCP connection reset by peer 或者 SSL 相关报错，优先检查系统时间、证书链和网络安全策略。

3. 最基础的 curl 调用：一次完整的 JSON 请求

3.1 请求 URL 的结构拆解

Gemini 1.5 Pro 的生成接口路径是固定的，本质上我们只需要关心四个部分：

• v1beta：API 版本号。目前稳定的是 v1beta，v1 也有，但部分新功能只在 beta 里有。
• models/gemini-1.5-pro-001：模型 ID。注意这里的 001 是版本后缀，不是随便写的。如果你用的是新版本，模型 ID 可能变成 gemini-1.5-pro-002，但 gemini-1.5-pro-001 在很长一段时间内都是可用的稳定版本。
• :generateContent：这是核心操作，表示"生成内容"。如果只要普通生成，就走这个路径；如果要流式输出，把冒号后面的动作改成 streamGenerateContent。
• ?key=...：认证参数。

所以一次最基础调用的完整 URL 长这样：

code复制https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key=${GEMINI_API_KEY}

把这四个部分拆开理解之后，你会发现这个接口的用法其实很直白。