如果你正在用 curl 调 gemini-1.5-pro-001 的接口第一次跑通后大概率会愣一下命令没报错终端里也吐回了一坨巨大的 JSON但里面塞满了 candidates、content、parts、finishReason 这些字段翻半天才能找到模型真正回复的那句话。这篇文章就从零开始把“用 curl 从 gemini-1.5-pro-001 获取干净 JSON 输出”这条链路完全讲透包括请求地址怎么写、请求体怎么构造、响应结构怎么解析、如何让模型直接输出合法 JSON 数据最后再附上一批我在实际调试中踩过的坑。适合正在做 API 集成、写自动化脚本、或者只想快速验证 Gemini 模型能力的开发者参考。1. 整体设计思路curl、Gemini 与 JSON 三者如何串起来1.1 先搞懂 Gemini API 的请求模型Gemini 1.5 Pro 的接口走的是标准的 HTTPS POST 请求所有交互都围绕一个核心概念展开你把一段或多段文本也可以包括图片、音频包装成一个contents数组发到 Google 的生成式语言模型服务端点服务端再把模型生成的文本通过 JSON 响应返回给你。这个设计其实和现在主流的大模型 API 基本一致区别在于字段名和嵌套层级。这里最值得先理解的是contents数组的结构。一个最基本的请求体长这样{ contents: [ { parts: [ { text: 用一句话解释什么是JSON } ] } ] }contents表示对话中的一条消息parts是这条消息具体包含的内容块。你可能会问为什么搞这么深的嵌套直接在 JSON 里放一个prompt字段不行吗原因在于 Gemini 从设计之初就定位成多模态模型一个parts里既可以放文本也可以放inline_data图片字节、或者file_data已上传文件的引用。统一用数组结构才能在同一个请求里混合文字和多媒体为后续扩展留出空间。1.2 为什么响应天然就是 JSONGemini API 的响应体本身就是严格合法的 JSON这一点很多人一开始没意识到。你用 curl 请求成功后终端里打印出来的那一大段花括号嵌套结构其实就是标准的 JSON 数据。这意味着你不需要做任何格式转换只要想办法从这段 JSON 里提取出模型生成的文本就能直接使用。响应体的核心结构大致如下{ candidates: [ { content: { parts: [ { text: 模型实际生成的回复 } ], role: model }, finishReason: STOP, index: 0, safetyRatings: [] } ], usageMetadata: { promptTokenCount: 12, candidatesTokenCount: 15, totalTokenCount: 27 } }candidates数组表示候选回复绝大多数情况下只有一项content.parts[0].text就是模型输出的明文字符串finishReason用于判断生成是否正常结束常见值是STOP正常结束、MAX_TOKENS超出长度限制被截断、SAFETY被安全策略拦截。usageMetadata则告诉你了这次请求消耗了多少 token做成本核算和限额管理时非常有用。所以问题从来不是“怎么让 Gemini 返回 JSON”而是“返回的 JSON 里我该怎么精准拿到自己需要的那段内容”。这也是我在这篇文章里最想帮你解决的核心痛点。1.3 方案选型为什么用 curl 而不是写代码直接用 curl 调试 API 的好处用过的都懂。第一零依赖只要是装了 curl 的机器就能跑不需要初始化 Node 项目、不需要装 Python requests 库第二排查问题快请求体和响应都直接打印在终端里一眼就能看出是参数写错还是返回异常第三方便沉淀成脚本片段把一段写好的 curl 命令丢进 Shell 脚本或 CI 流程里比维护一段语言 SDK 代码轻量得多。当然curl 的缺点也很明显没有类型提示不能自动补全解析 JSON 时需要额外配合jq工具。我的建议是正式项目里用官方 SDK 或你自己熟悉的 HTTP 客户端但在环境验证、快速原型、临时排查这几个场景下curl 永远是第一选择。下面所有示例都基于 Linux/macOS 的 bash 环境Windows 用户建议使用 Git Bash 或 WSL后面我会单独讲 Windows 下容易踩的坑。2. 环境准备与关键参数解析2.1 获取 API Key 与安全保存调用 gemini-1.5-pro-001 需要先在 Google AI Studioaistudio.google.com创建一个 API Key。创建时它会让你选择项目推荐直接选默认项目或者单独建一个测试项目避免和生产环境混在一起。拿到 Key 之后我的习惯是把这串东西写进环境变量而不是直接硬编码在命令行里防止 Shell 历史记录泄露。export GEMINI_API_KEY你的API Key这样后续所有 curl 命令里只需要通过$GEMINI_API_KEY引用它就行。如果你用的是 zsh可以把这一行追加到~/.zshrc如果是 bash就追加到~/.bashrc。每次打开新终端后环境变量自动生效省去反复粘贴 Key 的麻烦。另外强烈建议给 API Key 设置额度上限防止测试时手滑发了个超长 prompt 产生意外费用。2.2 接口地址的两种写法gemini-1.5-pro-001 的生成接口地址有固定格式以generateContent结尾https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY需要注意的有两点。第一v1和v1beta两个版本目前都在用v1更稳定v1beta可能会先上线一些新功能一般推荐用v1beta。第二API Key 放在 URL 的key参数里这是 Gemini 接口和很多其他云服务 API 不一样的地方其他服务通常把鉴权信息放在Authorization: Bearer头里。虽然 Gemini 也支持x-goog-api-key头但最简单粗暴的方案就是拼在 URL 后面curl 直接就能跑通。如果你不想让 Key 出现在进程列表里也可以用-H x-goog-api-key: $GEMINI_API_KEY的方式。两种方式我都试过功能上没有区别看个人习惯。2.3 请求头与请求体核心字段拆解一个完整的 curl 请求通常长这样curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 用JSON格式列一份三天的训练计划 } ] } ], generationConfig: { temperature: 0.7, maxOutputTokens: 1024, responseMimeType: application/json } }逐个字段拆开看-s静默模式不显示 curl 的下载进度条输出的内容干净。-X POST显式指定请求方法虽然加了-d后 curl 会自动用 POST但写出来能让命令意图更明确。-H Content-Type: application/json声明请求体是 JSON 格式这个不能省。-d请求体内容。这里用的是单引号包裹的 JSON 字符串注意 JSON 里不能有单引号转义问题。generationConfig是整个请求里最值得研究的字段。temperature控制随机性数值越大回答越发散处理代码、数据提取等确定性任务时建议调低到 0.2 左右maxOutputTokens限制最大输出长度1.5 Pro 理论上支持 8192 个 token但如果只是闲聊或者提取结构化数据1024 足够用responseMimeType是我后面会重点讲的字段把它设成application/json模型就会尽力让输出内容本身成为合法 JSON。2.4 generationConfig 里那些影响输出的参数大多数人第一次用 Gemini API 时只会简单传一个contents发现输出结果不太可控。其实generationConfig里还藏着几个非常实用的开关。topP和topK是另外两个采样参数。topK会让模型只在概率最高的 K 个 token 里做选择topP限制累计概率超过 P 的候选集合。很多教程建议只用temperature就够了但在实际测试中做结构严格的 JSON 输出时把topP调到 0.8 左右明显能减少格式错乱。stopSequences可以设置停止词例如告诉模型遇到某个特定字符串就停止生成适合做模板化输出。还有一个容易被忽略的candidateCount它表示返回几个候选结果。目前 1.5 Pro 只支持填 1填大于 1 的值会报错这个坑我已经踩过写脚本时别想着一次拿多个答案供选择。从 2025 年开始Gemini API 还逐步增强了结构化输出能力。除了responseMimeType还支持responseSchema字段你可以在请求里描述一个期望的 JSON Schema模型会严格按照这个结构生成内容。这部分比较高级我放到第 3 章详细演示。3. 实操从基础 POST 到结构化 JSON 输出3.1 基础版本一条 curl 拿到完整响应先跑通最小可用的请求。打开终端执行curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 你好请简单介绍一下你自己 } ] } ] }正常情况下你会看到一长串 JSON 输出。别急着关终端仔细观察这串输出的结构找到candidates[0].content.parts[0].text这个路径下的内容那就是 Gemini 的自我介绍。我第一次跑通时也愣了半天明明只是想让模型说句话返回却带着这么多包裹层。这其实是所有大模型 API 的统一做派把“模型说了什么”和“这次调用消耗了多少资源、是否安全合规”这些元信息打包在一起返回。如果你在这一步就收到了报错优先检查两件事API Key 是否正确以及 URL 里的模型名是不是gemini-1.5-pro-001。模型名拼写错误会直接返回 404这个非常常见。3.2 用 jq 精准提取模型回复文本直接看原始 JSON 不够优雅尤其是当你想把 Gemini 的回复进一步交给其他程序处理时。这时候就需要jq出场它相当于 JSON 界的 grep能让你用一行命令从 JSON 里精准提取字段。curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 用一句话解释什么是JSON } ] } ] } | jq -r .candidates[0].content.parts[0].text这条命令在 curl 后面接了一个管道把响应内容直接传给jq-r表示输出原始字符串去掉 JSON 的双引号后面的过滤器.candidates[0].content.parts[0].text会准确取出模型生成的文本。实测下来这个组合是调试 Gemini API 时最高频的操作。我还习惯在取完文本后加一个jq .把整个响应格式化后再看这样嵌套关系一目了然。如果你机器上还没装jqmacOS 用brew install jqUbuntu 用sudo apt install jqWindows 在 Git Bash 里同样能用。安装省下的时间绝对会在你一次次的调试中加倍赚回来。3.3 进阶让模型强制输出指定结构的 JSON现在回到标题那个核心诉求get JSON output。前面说的 JSON 是 Gemini API 的响应包装但很多时候我们真正想要的是“模型生成的内容本身就是一段可直接解析的 JSON”——比如你想让模型输出一份配置、一个数据数组、或者一个对象结构方便你的程序直接JSON.parse消费。Gemini 1.5 Pro 对此有原生支持关键就在generationConfig里加一个字段curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 给一个包含三个学习JSON资源的JSON数组每个元素包含name和url字段 } ] } ], generationConfig: { responseMimeType: application/json } }注意看我只额外加了responseMimeType: application/json模型的回复就会被约束成一段合法的 JSON。比如它可能会输出[ { name: JSON官方文档, url: https://www.json.org/json-zh.html }, { name: MDN JSON教程, url: https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/JSON }, { name: JSON Schema入门, url: https://json-schema.org/ } ]如果你觉得一个responseMimeType还不够希望模型绝对按你的字段和类型来输出可以再配上responseSchemagenerationConfig: { responseMimeType: application/json, responseSchema: { type: ARRAY, items: { type: OBJECT, properties: { name: { type: STRING }, url: { type: STRING } }, required: [name, url] } } }有了responseSchema模型的输出会严格对齐你声明的结构基本不会出现缺字段或者类型错乱的情况。这个功能在我做数据清洗、批量抽取、自动化脚本时帮了大忙等于把“模型生成的字符串”和“程序能直接消费的数据结构”之间的缝隙焊死了。3.4 流式输出 streamGenerateContent 的使用有些场景下等模型完整生成完再一次性返回体验不够好。比如做聊天机器人用户希望看到文字一个字一个字蹦出来。Gemini API 为此提供了流式版本把generateContent改成streamGenerateContent并在 URL 上加altssecurl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:streamGenerateContent?altssekey$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 写一段关于JSON数据格式发展历史的300字介绍 } ] } ] }返回内容会变成 Server-Sent EventsSSE格式每行以data:开头后面跟着一段 JSON。需要注意的是每个data:块之间是独立的每条里都可能包含部分生成结果你需要把所有块里的candidates[0].content.parts[0].text拼起来才是完整回复。实际使用中流式模式配合jq有一点麻烦因为每一行都是独立 JSON没法像非流式那样一次jq搞定。我建议这种情况直接用grep简单过滤或者写个几行脚本逐行解析。如果你只是临时测试非流式就够用真正做产品时再上流式也不迟。3.5 批处理封装把 curl 写成一个可复用脚本一旦你验证完单条请求就可以把 curl 命令封装成 Shell 函数或脚本方便批量调用。我常用的一个最小脚本长这样#!/bin/bash gemini_json() { local prompt$1 local schema$2 local payload{\contents\:[{\parts\:[{\text\:\$prompt\}]}],\generationConfig\:{\responseMimeType\:\application/json\}} if [ -n $schema ]; then payload{\contents\:[{\parts\:[{\text\:\$prompt\}]}],\generationConfig\:{\responseMimeType\:\application/json\,\responseSchema\:$schema}} fi curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d $payload | jq -r .candidates[0].content.parts[0].text } gemini_json 列出三本JSON相关的书籍返回JSON数组字段为title和author这里的关键点是-d后面的 JSON 字符串需要手工拼引号很容易出错。更好的做法是用 Python 或 Node 先构造好 payload再传给 curl但那就绕回了“为什么用 curl”的讨论。我的建议是简单 prompt 用 Shell 脚本复杂结构化输出则切换到 Python requests不要在一个顺手的小工具上投入过多复杂度。4. 常见问题与排查技巧实录4.1 400 Bad Request请求体格式问题这是我最常遇到的错误。返回 400 时响应里通常附有一段 JSON 描述问题比如error: {code: 400, message: Invalid JSON payload received...}。排查步骤按顺序来检查-d参数里的 JSON 是否合法。可以用python3 -m json.tool管道校验或者干脆把 JSON 复制到任意在线格式化工具里看一眼。检查字段名是否拼写正确。contents、parts、text这三个最容易写错比如content少了个 s。检查是否有多余的逗号或注释。JSON 标准不允许注释也不允许尾随逗号手写大段 JSON 时极易犯这个毛病。如果用了responseSchema检查类型名称是否用的大写STRING、INTEGER、ARRAY、OBJECT这些必须是官方枚举值写小写会直接报错。我在本地调试时会把请求体先写到一个文件里然后用curl -d body.json方式请求这样既能复用又能避免 Shell 转义造成 JSON 变形。4.2 403 和 429API Key 与配额问题403 通常是 API Key 无效、权限不足或者 Key 被删除了。先把环境变量echo $GEMINI_API_KEY确认一下是否真的设置成功再确认 Key 是不是从 Google AI Studio 复制完整了。还有一个隐蔽问题有些团队账号开启了限制只允许特定 IP 调用这种情况换到公司网络环境下就会出现 403。429 表示请求频率或配额超限。Gemini 1.5 Pro 免费额度有每分钟请求数RPM和每天 token 数TPM两重限制。遇到 429最简单的办法是等几十秒再试或者降低请求频率如果是为了跑批量任务建议在代码里加退避重试逻辑指数退避比固定间隔更有效。4.3 JSON 解析失败jq 总是报错有时候你照着命令抄jq却报null (null) cannot be matched或者Cannot index array with string。这类问题的根源通常是响应里根本没有你写的那个路径。排查思路先去掉jq过滤直接看原始响应。是不是返回了错误 JSON是不是candidates是空数组是不是字段名大小写不对看finishReason是不是SAFETY。如果请求触发了安全过滤candidates[0].content可能为空导致路径取不到值。这种情况换一个更中性的 prompt 通常就能解决。如果用了流式接口记住每条data:前都有前缀。用jq直接读整段会报错必须先把data:前缀去掉。4.4 Windows 下 curl 的坑Windows 自带 curl但跟 Git Bash 里那个不是一回事而且默认终端处理单引号和反斜杠的方式跟 Linux 差别很大。最典型的坑是把 Linux 上能跑的 curl 命令原样丢到 CMD 或 PowerShell 里单引号包住的 JSON 直接变成普通字符串接口收到一堆非法内容。我的建议是别在 Windows 原生终端里折腾直接装 Git Bash或者用 WSL 的 Linux 子系统。Git Bash 里 curl 命令的行为跟 Ubuntu 下基本一致单引号、管道、jq都能正常运作。如果你不得不在 PowerShell 里跑就要把 JSON 的双引号全部换成两个双引号转义非常痛苦能不上就不上。另外网上流传的“32位win7版curl单文件”这类说法劝你别花时间去研究。老版本 Windows 的自带 curl 功能老旧直接用当前官方维护的静态编译版或者干脆用 Git Bash 内置的 curl省心得多。4.5 网络超时与连接重置curl 调 Gemini API 时偶尔会出现超时或者 TCP 连接重置。这类问题大部分不是接口本身的问题而是本地网络环境不稳定或者某个节点暂时不可用。我的处理方法是给 curl 加上--connect-timeout 10和--max-time 30避免命令一直挂着不返回。重试一次大概率就能通过。如果是写自动化脚本把重试逻辑写进去不要指望单次请求百发百中。如果持续不通先确认你是否能正常访问其他 HTTPS 网站把“API 问题”和“网络问题”区分开。这一步排查清楚比盲目改代码高效得多。5. 一些想了很久的实用建议最后分享几个我从实际调试中总结出来的经验不一定写在官方文档里但对效率提升很有帮助。第一个经验是永远先最小化验证再逐步加参数。很多人第一次调 Gemini API 时喜欢一次性把 temperature、maxOutputTokens、responseSchema 全写上一旦报错根本不知道问题出在哪个字段。我的习惯是先用最简请求体跑通确认 Key 和网络没问题再一层层加参数每加一个就验证一次定位问题的成本会低很多。第二个经验是把常用的优质 curl 命令沉淀成自己的工具集。我在本地维护了一个 shell 脚本目录里面按场景分好了gemini-text.sh、gemini-json.sh、gemini-stream.sh每次调 API 直接复用不用重新敲一大段命令。时间长了你会发现这种“脚手架”积累起来的速度比看十篇教程都管用。第三个经验是关于 prompt 的想让 Gemini 输出合格的 JSON光靠responseMimeType还不够prompt 里最好直接描述清楚你要的字段名、类型和示例。模型毕竟是概率生成同一个字段叫title还是name它可能根据你的描述选择不同叫法。有了responseSchema之后这个情况改善了很多但 prompt 写清楚依然能显著降低返工概率。第四个经验是别小看usageMetadata。刚开始我只是把它当成响应的附属品后来做成本分析和性能优化时才发现每个请求的 prompt 和输出 token 数都在这。把每次调用的totalTokenCount记录到日志里月底对账、排查瓶颈都方便。按我的经验curl 加 gemini-1.5-pro-001 这套组合只要把请求体结构吃透、把jq用熟基本能覆盖日常 80% 以上的调试需求。如果后续你开始做更复杂的结构化抽取、多轮对话、或者需要把结果直接入库再考虑切换到官方 SDK 也不迟。但不管用什么工具理解“请求有结构、响应有结构、你希望模型输出也有结构”这条逻辑主线永远是最重要的。
如果你正在用 curl 调 gemini-1.5-pro-001 的接口第一次跑通后大概率会愣一下命令没报错终端里也吐回了一坨巨大的 JSON但里面塞满了 candidates、content、parts、finishReason 这些字段翻半天才能找到模型真正回复的那句话。这篇文章就从零开始把“用 curl 从 gemini-1.5-pro-001 获取干净 JSON 输出”这条链路完全讲透包括请求地址怎么写、请求体怎么构造、响应结构怎么解析、如何让模型直接输出合法 JSON 数据最后再附上一批我在实际调试中踩过的坑。适合正在做 API 集成、写自动化脚本、或者只想快速验证 Gemini 模型能力的开发者参考。1. 整体设计思路curl、Gemini 与 JSON 三者如何串起来1.1 先搞懂 Gemini API 的请求模型Gemini 1.5 Pro 的接口走的是标准的 HTTPS POST 请求所有交互都围绕一个核心概念展开你把一段或多段文本也可以包括图片、音频包装成一个contents数组发到 Google 的生成式语言模型服务端点服务端再把模型生成的文本通过 JSON 响应返回给你。这个设计其实和现在主流的大模型 API 基本一致区别在于字段名和嵌套层级。这里最值得先理解的是contents数组的结构。一个最基本的请求体长这样{ contents: [ { parts: [ { text: 用一句话解释什么是JSON } ] } ] }contents表示对话中的一条消息parts是这条消息具体包含的内容块。你可能会问为什么搞这么深的嵌套直接在 JSON 里放一个prompt字段不行吗原因在于 Gemini 从设计之初就定位成多模态模型一个parts里既可以放文本也可以放inline_data图片字节、或者file_data已上传文件的引用。统一用数组结构才能在同一个请求里混合文字和多媒体为后续扩展留出空间。1.2 为什么响应天然就是 JSONGemini API 的响应体本身就是严格合法的 JSON这一点很多人一开始没意识到。你用 curl 请求成功后终端里打印出来的那一大段花括号嵌套结构其实就是标准的 JSON 数据。这意味着你不需要做任何格式转换只要想办法从这段 JSON 里提取出模型生成的文本就能直接使用。响应体的核心结构大致如下{ candidates: [ { content: { parts: [ { text: 模型实际生成的回复 } ], role: model }, finishReason: STOP, index: 0, safetyRatings: [] } ], usageMetadata: { promptTokenCount: 12, candidatesTokenCount: 15, totalTokenCount: 27 } }candidates数组表示候选回复绝大多数情况下只有一项content.parts[0].text就是模型输出的明文字符串finishReason用于判断生成是否正常结束常见值是STOP正常结束、MAX_TOKENS超出长度限制被截断、SAFETY被安全策略拦截。usageMetadata则告诉你了这次请求消耗了多少 token做成本核算和限额管理时非常有用。所以问题从来不是“怎么让 Gemini 返回 JSON”而是“返回的 JSON 里我该怎么精准拿到自己需要的那段内容”。这也是我在这篇文章里最想帮你解决的核心痛点。1.3 方案选型为什么用 curl 而不是写代码直接用 curl 调试 API 的好处用过的都懂。第一零依赖只要是装了 curl 的机器就能跑不需要初始化 Node 项目、不需要装 Python requests 库第二排查问题快请求体和响应都直接打印在终端里一眼就能看出是参数写错还是返回异常第三方便沉淀成脚本片段把一段写好的 curl 命令丢进 Shell 脚本或 CI 流程里比维护一段语言 SDK 代码轻量得多。当然curl 的缺点也很明显没有类型提示不能自动补全解析 JSON 时需要额外配合jq工具。我的建议是正式项目里用官方 SDK 或你自己熟悉的 HTTP 客户端但在环境验证、快速原型、临时排查这几个场景下curl 永远是第一选择。下面所有示例都基于 Linux/macOS 的 bash 环境Windows 用户建议使用 Git Bash 或 WSL后面我会单独讲 Windows 下容易踩的坑。2. 环境准备与关键参数解析2.1 获取 API Key 与安全保存调用 gemini-1.5-pro-001 需要先在 Google AI Studioaistudio.google.com创建一个 API Key。创建时它会让你选择项目推荐直接选默认项目或者单独建一个测试项目避免和生产环境混在一起。拿到 Key 之后我的习惯是把这串东西写进环境变量而不是直接硬编码在命令行里防止 Shell 历史记录泄露。export GEMINI_API_KEY你的API Key这样后续所有 curl 命令里只需要通过$GEMINI_API_KEY引用它就行。如果你用的是 zsh可以把这一行追加到~/.zshrc如果是 bash就追加到~/.bashrc。每次打开新终端后环境变量自动生效省去反复粘贴 Key 的麻烦。另外强烈建议给 API Key 设置额度上限防止测试时手滑发了个超长 prompt 产生意外费用。2.2 接口地址的两种写法gemini-1.5-pro-001 的生成接口地址有固定格式以generateContent结尾https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY需要注意的有两点。第一v1和v1beta两个版本目前都在用v1更稳定v1beta可能会先上线一些新功能一般推荐用v1beta。第二API Key 放在 URL 的key参数里这是 Gemini 接口和很多其他云服务 API 不一样的地方其他服务通常把鉴权信息放在Authorization: Bearer头里。虽然 Gemini 也支持x-goog-api-key头但最简单粗暴的方案就是拼在 URL 后面curl 直接就能跑通。如果你不想让 Key 出现在进程列表里也可以用-H x-goog-api-key: $GEMINI_API_KEY的方式。两种方式我都试过功能上没有区别看个人习惯。2.3 请求头与请求体核心字段拆解一个完整的 curl 请求通常长这样curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 用JSON格式列一份三天的训练计划 } ] } ], generationConfig: { temperature: 0.7, maxOutputTokens: 1024, responseMimeType: application/json } }逐个字段拆开看-s静默模式不显示 curl 的下载进度条输出的内容干净。-X POST显式指定请求方法虽然加了-d后 curl 会自动用 POST但写出来能让命令意图更明确。-H Content-Type: application/json声明请求体是 JSON 格式这个不能省。-d请求体内容。这里用的是单引号包裹的 JSON 字符串注意 JSON 里不能有单引号转义问题。generationConfig是整个请求里最值得研究的字段。temperature控制随机性数值越大回答越发散处理代码、数据提取等确定性任务时建议调低到 0.2 左右maxOutputTokens限制最大输出长度1.5 Pro 理论上支持 8192 个 token但如果只是闲聊或者提取结构化数据1024 足够用responseMimeType是我后面会重点讲的字段把它设成application/json模型就会尽力让输出内容本身成为合法 JSON。2.4 generationConfig 里那些影响输出的参数大多数人第一次用 Gemini API 时只会简单传一个contents发现输出结果不太可控。其实generationConfig里还藏着几个非常实用的开关。topP和topK是另外两个采样参数。topK会让模型只在概率最高的 K 个 token 里做选择topP限制累计概率超过 P 的候选集合。很多教程建议只用temperature就够了但在实际测试中做结构严格的 JSON 输出时把topP调到 0.8 左右明显能减少格式错乱。stopSequences可以设置停止词例如告诉模型遇到某个特定字符串就停止生成适合做模板化输出。还有一个容易被忽略的candidateCount它表示返回几个候选结果。目前 1.5 Pro 只支持填 1填大于 1 的值会报错这个坑我已经踩过写脚本时别想着一次拿多个答案供选择。从 2025 年开始Gemini API 还逐步增强了结构化输出能力。除了responseMimeType还支持responseSchema字段你可以在请求里描述一个期望的 JSON Schema模型会严格按照这个结构生成内容。这部分比较高级我放到第 3 章详细演示。3. 实操从基础 POST 到结构化 JSON 输出3.1 基础版本一条 curl 拿到完整响应先跑通最小可用的请求。打开终端执行curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 你好请简单介绍一下你自己 } ] } ] }正常情况下你会看到一长串 JSON 输出。别急着关终端仔细观察这串输出的结构找到candidates[0].content.parts[0].text这个路径下的内容那就是 Gemini 的自我介绍。我第一次跑通时也愣了半天明明只是想让模型说句话返回却带着这么多包裹层。这其实是所有大模型 API 的统一做派把“模型说了什么”和“这次调用消耗了多少资源、是否安全合规”这些元信息打包在一起返回。如果你在这一步就收到了报错优先检查两件事API Key 是否正确以及 URL 里的模型名是不是gemini-1.5-pro-001。模型名拼写错误会直接返回 404这个非常常见。3.2 用 jq 精准提取模型回复文本直接看原始 JSON 不够优雅尤其是当你想把 Gemini 的回复进一步交给其他程序处理时。这时候就需要jq出场它相当于 JSON 界的 grep能让你用一行命令从 JSON 里精准提取字段。curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 用一句话解释什么是JSON } ] } ] } | jq -r .candidates[0].content.parts[0].text这条命令在 curl 后面接了一个管道把响应内容直接传给jq-r表示输出原始字符串去掉 JSON 的双引号后面的过滤器.candidates[0].content.parts[0].text会准确取出模型生成的文本。实测下来这个组合是调试 Gemini API 时最高频的操作。我还习惯在取完文本后加一个jq .把整个响应格式化后再看这样嵌套关系一目了然。如果你机器上还没装jqmacOS 用brew install jqUbuntu 用sudo apt install jqWindows 在 Git Bash 里同样能用。安装省下的时间绝对会在你一次次的调试中加倍赚回来。3.3 进阶让模型强制输出指定结构的 JSON现在回到标题那个核心诉求get JSON output。前面说的 JSON 是 Gemini API 的响应包装但很多时候我们真正想要的是“模型生成的内容本身就是一段可直接解析的 JSON”——比如你想让模型输出一份配置、一个数据数组、或者一个对象结构方便你的程序直接JSON.parse消费。Gemini 1.5 Pro 对此有原生支持关键就在generationConfig里加一个字段curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 给一个包含三个学习JSON资源的JSON数组每个元素包含name和url字段 } ] } ], generationConfig: { responseMimeType: application/json } }注意看我只额外加了responseMimeType: application/json模型的回复就会被约束成一段合法的 JSON。比如它可能会输出[ { name: JSON官方文档, url: https://www.json.org/json-zh.html }, { name: MDN JSON教程, url: https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/JSON }, { name: JSON Schema入门, url: https://json-schema.org/ } ]如果你觉得一个responseMimeType还不够希望模型绝对按你的字段和类型来输出可以再配上responseSchemagenerationConfig: { responseMimeType: application/json, responseSchema: { type: ARRAY, items: { type: OBJECT, properties: { name: { type: STRING }, url: { type: STRING } }, required: [name, url] } } }有了responseSchema模型的输出会严格对齐你声明的结构基本不会出现缺字段或者类型错乱的情况。这个功能在我做数据清洗、批量抽取、自动化脚本时帮了大忙等于把“模型生成的字符串”和“程序能直接消费的数据结构”之间的缝隙焊死了。3.4 流式输出 streamGenerateContent 的使用有些场景下等模型完整生成完再一次性返回体验不够好。比如做聊天机器人用户希望看到文字一个字一个字蹦出来。Gemini API 为此提供了流式版本把generateContent改成streamGenerateContent并在 URL 上加altssecurl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:streamGenerateContent?altssekey$GEMINI_API_KEY \ -H Content-Type: application/json \ -d { contents: [ { parts: [ { text: 写一段关于JSON数据格式发展历史的300字介绍 } ] } ] }返回内容会变成 Server-Sent EventsSSE格式每行以data:开头后面跟着一段 JSON。需要注意的是每个data:块之间是独立的每条里都可能包含部分生成结果你需要把所有块里的candidates[0].content.parts[0].text拼起来才是完整回复。实际使用中流式模式配合jq有一点麻烦因为每一行都是独立 JSON没法像非流式那样一次jq搞定。我建议这种情况直接用grep简单过滤或者写个几行脚本逐行解析。如果你只是临时测试非流式就够用真正做产品时再上流式也不迟。3.5 批处理封装把 curl 写成一个可复用脚本一旦你验证完单条请求就可以把 curl 命令封装成 Shell 函数或脚本方便批量调用。我常用的一个最小脚本长这样#!/bin/bash gemini_json() { local prompt$1 local schema$2 local payload{\contents\:[{\parts\:[{\text\:\$prompt\}]}],\generationConfig\:{\responseMimeType\:\application/json\}} if [ -n $schema ]; then payload{\contents\:[{\parts\:[{\text\:\$prompt\}]}],\generationConfig\:{\responseMimeType\:\application/json\,\responseSchema\:$schema}} fi curl -s -X POST \ https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-001:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d $payload | jq -r .candidates[0].content.parts[0].text } gemini_json 列出三本JSON相关的书籍返回JSON数组字段为title和author这里的关键点是-d后面的 JSON 字符串需要手工拼引号很容易出错。更好的做法是用 Python 或 Node 先构造好 payload再传给 curl但那就绕回了“为什么用 curl”的讨论。我的建议是简单 prompt 用 Shell 脚本复杂结构化输出则切换到 Python requests不要在一个顺手的小工具上投入过多复杂度。4. 常见问题与排查技巧实录4.1 400 Bad Request请求体格式问题这是我最常遇到的错误。返回 400 时响应里通常附有一段 JSON 描述问题比如error: {code: 400, message: Invalid JSON payload received...}。排查步骤按顺序来检查-d参数里的 JSON 是否合法。可以用python3 -m json.tool管道校验或者干脆把 JSON 复制到任意在线格式化工具里看一眼。检查字段名是否拼写正确。contents、parts、text这三个最容易写错比如content少了个 s。检查是否有多余的逗号或注释。JSON 标准不允许注释也不允许尾随逗号手写大段 JSON 时极易犯这个毛病。如果用了responseSchema检查类型名称是否用的大写STRING、INTEGER、ARRAY、OBJECT这些必须是官方枚举值写小写会直接报错。我在本地调试时会把请求体先写到一个文件里然后用curl -d body.json方式请求这样既能复用又能避免 Shell 转义造成 JSON 变形。4.2 403 和 429API Key 与配额问题403 通常是 API Key 无效、权限不足或者 Key 被删除了。先把环境变量echo $GEMINI_API_KEY确认一下是否真的设置成功再确认 Key 是不是从 Google AI Studio 复制完整了。还有一个隐蔽问题有些团队账号开启了限制只允许特定 IP 调用这种情况换到公司网络环境下就会出现 403。429 表示请求频率或配额超限。Gemini 1.5 Pro 免费额度有每分钟请求数RPM和每天 token 数TPM两重限制。遇到 429最简单的办法是等几十秒再试或者降低请求频率如果是为了跑批量任务建议在代码里加退避重试逻辑指数退避比固定间隔更有效。4.3 JSON 解析失败jq 总是报错有时候你照着命令抄jq却报null (null) cannot be matched或者Cannot index array with string。这类问题的根源通常是响应里根本没有你写的那个路径。排查思路先去掉jq过滤直接看原始响应。是不是返回了错误 JSON是不是candidates是空数组是不是字段名大小写不对看finishReason是不是SAFETY。如果请求触发了安全过滤candidates[0].content可能为空导致路径取不到值。这种情况换一个更中性的 prompt 通常就能解决。如果用了流式接口记住每条data:前都有前缀。用jq直接读整段会报错必须先把data:前缀去掉。4.4 Windows 下 curl 的坑Windows 自带 curl但跟 Git Bash 里那个不是一回事而且默认终端处理单引号和反斜杠的方式跟 Linux 差别很大。最典型的坑是把 Linux 上能跑的 curl 命令原样丢到 CMD 或 PowerShell 里单引号包住的 JSON 直接变成普通字符串接口收到一堆非法内容。我的建议是别在 Windows 原生终端里折腾直接装 Git Bash或者用 WSL 的 Linux 子系统。Git Bash 里 curl 命令的行为跟 Ubuntu 下基本一致单引号、管道、jq都能正常运作。如果你不得不在 PowerShell 里跑就要把 JSON 的双引号全部换成两个双引号转义非常痛苦能不上就不上。另外网上流传的“32位win7版curl单文件”这类说法劝你别花时间去研究。老版本 Windows 的自带 curl 功能老旧直接用当前官方维护的静态编译版或者干脆用 Git Bash 内置的 curl省心得多。4.5 网络超时与连接重置curl 调 Gemini API 时偶尔会出现超时或者 TCP 连接重置。这类问题大部分不是接口本身的问题而是本地网络环境不稳定或者某个节点暂时不可用。我的处理方法是给 curl 加上--connect-timeout 10和--max-time 30避免命令一直挂着不返回。重试一次大概率就能通过。如果是写自动化脚本把重试逻辑写进去不要指望单次请求百发百中。如果持续不通先确认你是否能正常访问其他 HTTPS 网站把“API 问题”和“网络问题”区分开。这一步排查清楚比盲目改代码高效得多。5. 一些想了很久的实用建议最后分享几个我从实际调试中总结出来的经验不一定写在官方文档里但对效率提升很有帮助。第一个经验是永远先最小化验证再逐步加参数。很多人第一次调 Gemini API 时喜欢一次性把 temperature、maxOutputTokens、responseSchema 全写上一旦报错根本不知道问题出在哪个字段。我的习惯是先用最简请求体跑通确认 Key 和网络没问题再一层层加参数每加一个就验证一次定位问题的成本会低很多。第二个经验是把常用的优质 curl 命令沉淀成自己的工具集。我在本地维护了一个 shell 脚本目录里面按场景分好了gemini-text.sh、gemini-json.sh、gemini-stream.sh每次调 API 直接复用不用重新敲一大段命令。时间长了你会发现这种“脚手架”积累起来的速度比看十篇教程都管用。第三个经验是关于 prompt 的想让 Gemini 输出合格的 JSON光靠responseMimeType还不够prompt 里最好直接描述清楚你要的字段名、类型和示例。模型毕竟是概率生成同一个字段叫title还是name它可能根据你的描述选择不同叫法。有了responseSchema之后这个情况改善了很多但 prompt 写清楚依然能显著降低返工概率。第四个经验是别小看usageMetadata。刚开始我只是把它当成响应的附属品后来做成本分析和性能优化时才发现每个请求的 prompt 和输出 token 数都在这。把每次调用的totalTokenCount记录到日志里月底对账、排查瓶颈都方便。按我的经验curl 加 gemini-1.5-pro-001 这套组合只要把请求体结构吃透、把jq用熟基本能覆盖日常 80% 以上的调试需求。如果后续你开始做更复杂的结构化抽取、多轮对话、或者需要把结果直接入库再考虑切换到官方 SDK 也不迟。但不管用什么工具理解“请求有结构、响应有结构、你希望模型输出也有结构”这条逻辑主线永远是最重要的。
