Python逆向工程库Gemini-API：解锁Google Gemini多模态与深度研究全功能

1. 项目概述与核心价值如果你正在寻找一个能让你在Python项目中无缝接入Google Gemini就是那个以前叫Bard的AI全部能力的库并且希望它能像官方API一样优雅易用同时又能绕过一些官方限制直接使用网页版的高级功能那么你找对地方了。HanaokaYuzu的Gemini-API项目就是一个通过逆向工程实现的、功能强大且异步的Python封装库。它不只是一个简单的API客户端更像是一个为你打开了Gemini网页版所有隐藏功能的“万能钥匙”。我最初接触这个项目是因为在开发一个需要集成多模态AI能力的自动化工具时发现官方的Gemini API虽然稳定但在图像生成、深度研究、使用自定义Gem系统提示词等方面要么不支持要么处于漫长的等待列表中。而这个库直接对接了Gemini的网页端接口这意味着只要你的Google账户在网页版上能用的功能在这里几乎都能通过代码调用。从基础的文本对话到生成和编辑图片再到调用Gmail、YouTube等扩展甚至进行自主的深度网络研究它都能搞定。对于开发者、研究人员或者任何想自动化利用Gemini高级功能的用户来说这无疑是一个宝藏工具。2. 核心特性深度解析这个库之所以强大在于它不仅仅实现了基础的聊天功能而是将Gemini网页版的完整交互逻辑都封装了进来。下面我们来拆解一下它的几个核心特性看看它们在实际应用中能解决什么问题。2.1 持久化Cookie与自动刷新机制这是保障服务长期稳定运行的基石。与许多需要频繁手动更新Token的API不同Gemini-API设计了一套后台自动刷新Cookie的机制。你只需要在初始化时提供从浏览器获取的__Secure-1PSID和__Secure-1PSIDTS这两个Cookie值库就会在后台默默维护它们的有效性。注意__Secure-1PSIDTS这个Cookie的寿命相对较短。库的自动刷新功能主要就是针对它。当它即将过期时库会自动发起请求更新它确保你的客户端不会因为认证失效而中断。这对于部署在服务器上、需要7x24小时运行的聊天机器人或自动化服务至关重要。这个机制背后是模拟了网页端的保活行为。但有一点需要留意自动刷新过程可能会触发Google的安全验证导致你需要在浏览器端重新登录一次账户。这是正常现象不影响API端的功能。为了避免对主用浏览器造成干扰最佳实践是专门创建一个用于获取Cookie的浏览器环境比如无痕模式登录后提取Cookie然后关闭该浏览器。这样API端的自动刷新会在一个独立的会话中进行。2.2 原生多模态生成能力这是区别于官方API的最大亮点之一。官方API可能还在逐步开放这些功能但通过网页版接口这个库可以让你现在就使用。图像生成与编辑直接调用Google的Nano Banana模型用自然语言描述就能生成图片或者对现有图片进行编辑。生成的图片是GeneratedImage对象你可以直接保存到本地。这为内容创作、营销素材生成等场景提供了极大的便利。视频与音频生成同样通过自然语言指令可以生成短视频或音频片段。虽然可能需要Gemini Advanced订阅但这为制作简单的演示视频、背景音乐或语音内容打开了新的大门。文件理解支持上传PDF、图片、文档等多种文件格式Gemini可以读取其中的内容并进行总结、问答或分析关联性。这在处理知识库、自动化文档审核时非常有用。2.3 深度研究Deep Research工作流这是一个“杀手级”功能。你可以向Gemini提出一个复杂的、需要调研的问题例如“对比2024年三大云服务商在AI服务方面的优劣”它会像一个自主的研究助手一样规划步骤、浏览网页、分析信息源最终生成一份结构化的研究报告。库提供了两种使用方式一是简单的“一键研究”函数你只需要等待结果二是分步的工作流你可以创建研究计划、启动研究、轮询状态并获取结果。这为自动化报告生成、竞品分析、市场调研等任务提供了强大的支持。2.4 系统提示词Gemini Gems与扩展支持Gems你可以理解为可定制的、可重复使用的“角色”或“专家模式”。在网页版上你可以创建比如“编程伙伴”、“创意写作教练”这样的Gem。这个库允许你以编程方式获取、创建、更新、删除这些Gem并在对话中应用它们。这意味着你可以为不同的任务预设不同的AI行为模式。扩展通过激活Gmail、YouTube等扩展AI可以直接访问你的个人数据需授权或实时网络信息。例如你可以让AI总结你邮箱的最新邮件或者查找某个YouTube频道的最新视频。这极大地扩展了AI的应用边界使其能成为真正的个人助理。2.5 完整的对话管理库提供了完善的对话状态管理。你可以开启一个新对话进行多轮交互对话历史会被自动维护。更重要的是你可以获取某个对话的元数据chat.metadata将其保存下来比如存入数据库或文件之后在任何时间、任何新的Python进程中通过加载这个元数据来“复活”之前的对话无缝衔接。同时也支持从服务器端读取历史对话列表或删除对话。3. 环境准备与实战入门理论说了这么多我们来点实际的。下面我将带你从零开始完成一次完整的配置和基础使用。3.1 安装与Cookie获取首先确保你的Python版本在3.10或以上。然后通过pip安装库pip install -U gemini_webapi如果你希望库能自动从你电脑的浏览器中读取Cookie省去手动拷贝的麻烦可以安装带有浏览器支持的版本pip install -U gemini_webapi[browser]提示[browser]选项依赖browser-cookie3库它支持从Chrome、Firefox等主流浏览器读取Cookie。但在服务器或无头环境中可能无法使用此时仍需手动获取。手动获取Cookie的步骤这是关键一步用浏览器访问https://gemini.google.com并登录你的Google账号。按F12打开开发者工具切换到Network网络标签页。刷新页面在网络请求列表中点击任意一个请求通常是batchexecute这类。在右侧的Headers标头选项卡中向下找到Request Headers请求头部分。在其中找到名为cookie的字段它的值是一长串字符串。我们需要从中提取两个特定的值__Secure-1PSID__Secure-1PSIDTS复制这两个值对应的整个字符串。它们看起来像ABcd1234...这样的长字符序列。3.2 基础客户端初始化与首次对话拿到Cookie后我们就可以在代码中初始化客户端了。我强烈建议使用异步编程因为网络请求是I/O密集型操作异步能显著提升效率。import asyncio from gemini_webapi import GeminiClient # 替换成你刚刚获取的真实Cookie值 # 如果某些账户没有 __Secure-1PSIDTS可以留空字符串 Secure_1PSID 你的__Secure-1PSID值 Secure_1PSIDTS 你的__Secure-1PSIDTS值 async def main(): # 初始化客户端 # 如果安装了 browser-cookie3可以直接用 client GeminiClient() client GeminiClient(Secure_1PSID, Secure_1PSIDTS, proxyNone) # 初始化连接设置超时30秒不自动关闭自动刷新Cookie await client.init(timeout30, auto_closeFalse, auto_refreshTrue) # 发起一次简单的对话 response await client.generate_content(用Python写一个快速排序函数的示例并加上中文注释。) print(response.text) # 打印AI的回复文本 # 如果你想看到更结构化的回复可以直接打印response对象 # print(response) asyncio.run(main())运行这段代码如果一切顺利你应该能看到Gemini返回的带有中文注释的快速排序代码。恭喜你已经成功迈出了第一步3.3 多轮对话与上下文管理单次问答不够我们来创建一个能记住上下文的聊天会话。async def main(): client GeminiClient(Secure_1PSID, Secure_1PSIDTS) await client.init() # 开启一个新的聊天会话 chat client.start_chat() # 第一轮询问概念 response1 await chat.send_message(什么是Python的装饰器) print(fAI: {response1.text[:200]}...) # 打印前200字符 # 第二轮基于上一轮的上下文进行追问 response2 await chat.send_message(能给我一个记录函数运行时间的装饰器例子吗) print(f\nAI: {response2.text}) # 第三轮继续深入 response3 await chat.send_message(如果我想给这个装饰器加一个参数用来控制是否打印时间该怎么改) print(f\nAI: {response3.text}) asyncio.run(main())你会发现在同一个chat会话中AI能完美地理解我们对话的上下文无需在每次提问时重复之前的内容。ChatSession对象在内部自动维护了对话历史。4. 高级功能实战与避坑指南掌握了基础我们来探索一些更高级的功能这里会包含很多我在实际使用中总结的经验和遇到的坑。4.1 文件上传与多模态理解Gemini不仅能看懂文字还能“看懂”图片和文档。我们试试让它分析一张图表和一个PDF。import asyncio from pathlib import Path from gemini_webapi import GeminiClient async def main(): client GeminiClient(Secure_1PSID, Secure_1PSIDTS) await client.init() # 假设我们有一个销售数据的图表图片和一个产品说明PDF files_to_upload [ Path(data/sales_chart_q3.png), # 图片文件 Path(docs/product_spec.pdf), # PDF文件 ] response await client.generate_content( 请分析这张销售图表并结合产品说明书总结第三季度的市场表现和产品优势。, filesfiles_to_upload ) print(分析报告) print(response.text) # 检查回复中是否引用了图片中的内容例如生成的描述 if response.images: print(f\nAI在回复中提到了 {len(response.images)} 张相关图片。) asyncio.run(main())重要提示上传的文件大小和类型存在限制通常图片不超过20MBPDF不超过50页。在上传前最好对文件进行预处理。另外Gemini对某些复杂格式的PDF如扫描件解析能力有限可能需要先进行OCR。4.2 使用Gems定制AI角色假设我要开发一个代码评审机器人我希望它每次对话都扮演一个严厉的资深工程师。我可以先创建一个对应的Gem。async def main(): client GeminiClient(Secure_1PSID, Secure_1PSIDTS) await client.init() # 首先获取账户下所有已有的Gems包括系统预置和自定义的 await client.fetch_gems(include_hiddenTrue) # include_hiddenTrue 会包含一些隐藏的系统Gem print(f发现 {len(client.gems)} 个Gems。) # 方法一使用现有的系统Gem例如‘编程伙伴’ coding_gem client.gems.get(namecoding partner) # 名字可能因语言设置而异 if coding_gem: response_with_gem await client.generate_content( 帮我检查这段Python代码有什么问题def add(a,b): return ab, gemcoding_gem ) print(f【编程伙伴模式】\n{response_with_gem.text}\n) # 方法二创建一个全新的自定义Gem # 注意频繁创建删除Gem可能会被限制请谨慎操作 try: my_code_reviewer await client.create_gem( name严厉的代码审查员, prompt你是一个经验丰富、要求极其严格的软件工程师。你的任务是审查代码指出任何潜在的错误、性能问题、不良风格和安全漏洞。你的反馈必须直接、犀利并给出具体的改进建议。即使代码看起来没问题也要尝试找出可以优化的地方。, description用于自动化代码审查的严格模式 ) print(f自定义Gem创建成功{my_code_reviewer.name} (ID: {my_code_reviewer.id})) # 使用自定义Gem进行对话 chat_with_reviewer client.start_chat(gemmy_code_reviewer) review_response await chat_with_reviewer.send_message(审查for i in range(len(list)): print(list[i])) print(f【严厉审查员模式】\n{review_response.text}) except Exception as e: print(f创建Gem时出错可能已达上限或功能受限{e}) asyncio.run(main())踩坑记录自定义Gem的创建、更新和删除操作并不是百分之百稳定有时会因网络或服务器限制失败。务必做好异常处理。另外Gem的prompt系统指令是影响其行为的关键需要精心设计。一个常见的技巧是在指令中明确角色、目标和输出格式。4.3 图像生成与保存让我们试试让AI直接创作一幅画。import asyncio from gemini_webapi import GeminiClient async def main(): client GeminiClient(Secure_1PSID, Secure_1PSIDTS) await client.init() # 请求生成图像 response await client.generate_content( 生成一张赛博朋克风格的城市夜景图片要有霓虹灯和飞行汽车画面具有电影感。 ) # 检查回复中的图片 print(f请求生成图片回复中包含 {len(response.images)} 个图片项。) for idx, img in enumerate(response.images): print(f图片 {idx1}: 标题-{img.title}, 描述-{img.alt}) # 保存图片到本地 # save()方法是异步的因为可能需要下载 saved_path await img.save(path./generated_images/, filenamefcyberpunk_{idx}.png, verboseTrue) print(f 已保存至{saved_path}\n) asyncio.run(main())运行后你会看到AI返回了生成的图片信息并且图片文件已经下载到了你指定的目录。verboseTrue参数会让它在下载时打印进度信息。重要限制图像生成功能Nano Banana有地区和服务可用性限制。根据Google官方文档并非所有国家和地区的账户都能使用。如果你的账户无法使用API调用可能不会报错但不会返回生成的图片或者返回的是从网上搜索的图片WebImage对象。判断是否是AI生成的图片可以检查返回的Image对象类型是否为GeneratedImage。4.4 深度研究实战深度研究功能比较耗时但非常强大。我们用一个完整的例子来演示如何控制这个流程。import asyncio import time from gemini_webapi import GeminiClient async def main(): client GeminiClient(Secure_1PSID, Secure_1PSIDTS) await client.init() research_topic 2024年至2025年初在轻量级机器学习模型部署框架方面ONNX Runtime、TensorFlow Lite、PyTorch Mobile和Core ML的最新进展、优缺点对比及主要应用场景是什么 print(f开始深度研究任务{research_topic[:50]}...) # 方法一简单的一键式研究适合快速获取结果 try: print(【方法一一键研究】) start_time time.time() # poll_interval: 轮询间隔(秒) timeout: 总超时时间(秒) result await client.deep_research( research_topic, poll_interval15.0, # 每15秒检查一次进度 timeout300.0 # 最多等待5分钟 ) elapsed time.time() - start_time if result.done: print(f研究完成耗时 {elapsed:.1f} 秒) print(*50) print(result.text[:1000]) # 打印前1000字符预览 print(...\n(完整报告已生成)) # 你可以将 result.text 保存为Markdown或HTML文件 # with open(research_report.md, w, encodingutf-8) as f: # f.write(result.text) else: print(f研究未在超时时间内完成。最后状态{result.state}) except asyncio.TimeoutError: print(研究任务超时。) except Exception as e: print(f研究过程中发生错误{e}) print(\n *50 \n) # 方法二分步控制适合集成到复杂工作流中 print(【方法二分步控制】) try: # 1. 创建研究计划 plan await client.create_deep_research_plan(research_topic) print(f研究计划已创建。标题{plan.title}) print(f预计完成时间{plan.eta_text}) print(研究步骤) for step in plan.steps: print(f - {step}) # 2. 开始研究 await client.start_deep_research(plan) print(研究任务已启动...) # 3. 定义一个回调函数来监控状态 def status_callback(status): print(f 状态更新: {status.state} - {status.progress or N/A}) # 4. 等待研究完成并轮询状态 final_result await client.wait_for_deep_research( plan, poll_interval10.0, timeout240.0, on_statusstatus_callback # 每次轮询时调用 ) if final_result and final_result.done: print(f\n研究成功完成最终报告长度{len(final_result.text)} 字符) # 处理 final_result.text else: print(\n研究未完成或超时。) except Exception as e: print(f分步研究过程中出错{e}) asyncio.run(main())经验分享深度研究非常消耗时间配额且对网络稳定性要求高。务必设置合理的poll_interval和timeout。对于复杂课题超时时间可能需要设置到10分钟甚至更长。另外研究结果的质量很大程度上取决于你提出的问题是否清晰、具体。模糊的问题会导致模糊甚至跑题的报告。5. 生产环境部署与问题排查当你准备把这个库用于实际项目时以下几个方面的考虑至关重要。5.1 配置管理与环境变量永远不要将Cookie等敏感信息硬编码在代码中。推荐使用环境变量或配置文件。# config.py 或从环境变量读取 import os from dotenv import load_dotenv # 需要安装 python-dotenv load_dotenv() GEMINI_PSID os.getenv(GEMINI_PSID) GEMINI_PSIDTS os.getenv(GEMINI_PSIDTS) PROXY_URL os.getenv(HTTPS_PROXY) # 如果需要代理 # 在Docker或K8s中可以通过secrets注入环境变量5.2 异步客户端的最佳实践对于Web服务或机器人你需要一个长期运行的客户端。合理配置auto_close和close_delay可以节省资源。import asyncio from gemini_webapi import GeminiClient import signal class GeminiService: def __init__(self): self.client None async def startup(self): 启动服务时初始化客户端 self.client GeminiClient(GEMINI_PSID, GEMINI_PSIDTS, proxyPROXY_URL) # auto_closeTrue: 启用自动关闭 # close_delay600: 10分钟无活动后自动关闭会话以释放资源 # auto_refreshTrue: 启用Cookie自动刷新 await self.client.init(auto_closeTrue, close_delay600, auto_refreshTrue) print(Gemini 客户端已初始化并启动自动维护。) async def shutdown(self): 关闭服务时清理客户端 if self.client: await self.client.close() print(Gemini 客户端已关闭。) async def ask_question(self, question: str): 包装一个简单的问答方法并处理可能的客户端关闭情况 if not self.client: await self.startup() # 如果客户端因超时自动关闭了init方法会重新连接 if self.client.closed: await self.client.init(auto_closeTrue, close_delay600) try: response await self.client.generate_content(question, timeout60) return response.text except Exception as e: # 记录日志并返回友好错误信息 print(f请求Gemini时出错{e}) return 抱歉AI服务暂时不可用。 # 使用示例 async def main(): service GeminiService() await service.startup() answer await service.ask_question(今天的天气如何) print(answer) # 模拟一段时间无活动... await asyncio.sleep(700) # 超过10分钟客户端应自动关闭 # 再次提问会触发重连 answer2 await service.ask_question(再问一次天气如何) print(answer2) await service.shutdown() asyncio.run(main())5.3 错误处理与重试机制网络请求和第三方API调用总会遇到各种异常。一个健壮的系统必须有完善的错误处理。import asyncio import backoff # 需要安装 backoff 库 from aiohttp import ClientError from gemini_webapi import GeminiClient, GeminiAPIError class RobustGeminiClient: def __init__(self, psid, psidts): self.psid psid self.psidts psidts self._client None backoff.on_exception(backoff.expo, (ClientError, GeminiAPIError, asyncio.TimeoutError), max_tries5, max_time60) async def _get_client(self): 获取客户端带指数退避重试 if not self._client or self._client.closed: self._client GeminiClient(self.psid, self.psidts) await self._client.init(auto_closeFalse, auto_refreshTrue) return self._client async def safe_generate(self, prompt, **kwargs): 安全的生成内容方法包含重试和降级逻辑 try: client await self._get_client() response await client.generate_content(prompt, **kwargs) return response except asyncio.TimeoutError: print(请求超时可能是网络问题或Gemini服务响应慢。) # 可以在这里返回一个缓存的默认回复或更简单的本地模型回复 return None except GeminiAPIError as e: print(fGemini API 返回错误: {e}) # 检查是否是认证错误如果是可能需要重新获取Cookie if cookie in str(e).lower() or auth in str(e).lower(): print(检测到认证错误建议检查Cookie有效性。) self._client None # 强制下次重建客户端 raise # 或者返回降级内容 except Exception as e: print(f未知错误: {e}) return None # 使用示例 async def main(): robust_client RobustGeminiClient(GEMINI_PSID, GEMINI_PSIDTS) try: response await robust_client.safe_generate( 写一首关于春天的诗, timeout30 ) if response: print(response.text) else: print(无法获取AI回复请稍后重试或检查网络。) except Exception as e: print(f最终请求失败: {e}) asyncio.run(main())5.4 常见问题排查速查表在实际使用中你可能会遇到下面这些问题。这里我整理了一个快速排查指南。问题现象可能原因解决方案初始化失败提示Cookie无效1. Cookie值复制错误多了空格、引号2. Cookie已过期3. 账户未登录或登录状态异常1. 重新从浏览器Network标签页精确复制整个Cookie值确保没有多余字符。2. 重新登录Gemini网页获取新的Cookie。3. 尝试在浏览器无痕模式下登录并获取Cookie。请求长时间无响应或超时1. 网络连接问题特别是国内用户2. Gemini服务器端负载高3. 请求内容过于复杂1. 检查网络考虑配置代理proxy参数。2. 增加timeout参数值并实现重试机制。3. 简化提问或将其拆分成多个小问题。generate_content返回空文本或报错1. 提示词触发了安全策略或内容过滤器2. 服务暂时不可用3. 使用了当前区域不支持的功能如图像生成1. 修改提示词避免敏感或违规内容。2. 查看完整错误信息稍后重试。3. 确认你的Google账户所在区域是否支持该功能。图像生成返回WebImage而非GeneratedImage1. 提示词未明确要求“生成”图片2. 账户/地区不支持Nano Banana图像生成功能1. 在提示词中使用“generate an image of...”、“create a picture of...”等明确指令。2. 使用支持图像生成的账户或通过官方渠道确认功能可用性。深度研究任务一直处于“运行中”状态1. 研究主题过于宽泛或复杂2. 网络问题导致结果回传失败3. 达到了使用频率限制1. 设置合理的timeout超时后作为失败处理。2. 检查网络连接和代理设置。3. 减少深度研究的使用频率或尝试更具体的主题。使用扩展如Gmail无效1. 未在Gemini网页版上激活相应扩展2. 账户语言设置不支持3. 扩展服务临时故障1. 访问gemini.google.com/extensions确保所需扩展已开启。2. 将Google账户的偏好语言设置为英语美国。3. 稍后再试。客户端一段时间后自动断开auto_close参数被启用且close_delay时间内无活动这是设计行为。在下次请求时客户端会自动重新初始化。确保你的代码能处理客户端的closed状态。5.5 性能优化与小技巧连接复用对于高频请求务必复用同一个GeminiClient实例而不是每次请求都创建新的。频繁创建销毁连接会带来不必要的开销和认证压力。流式响应当需要处理长文本回复时如生成报告、故事使用generate_content_stream或send_message_stream。它可以边生成边输出提升用户体验感知速度尤其适合聊天机器人场景。合理使用模型通过client.list_models()查看可用的模型。对于简单的分类、总结任务可以使用Model.BASIC_FLASH等轻量模型响应更快、成本更低如果未来有计费。对于复杂推理、创作再使用Model.GEMINI_PRO等高级模型。会话管理对于需要长期记忆的对话如客服机器人妥善保存和加载chat.metadata。对于一次性查询使用temporaryTrue参数避免污染Gemini网页版的历史记录。日志记录在生产环境使用set_log_level(“DEBUG”)来打开详细日志有助于排查问题。但注意DEBUG日志可能包含Cookie等敏感信息切勿输出到公开日志系统。这个库将Gemini网页版的强大能力以编程的方式交到了我们手中。从简单的自动化问答到复杂的多模态内容生成和研究任务它提供了一个极其灵活且功能丰富的接口。当然由于其基于逆向工程需要关注其长期维护性和对Google前端变更的适应性。但在官方API功能追上来之前这无疑是探索和应用Gemini前沿能力的最佳工具之一。在实际项目中结合良好的错误处理、重试机制和资源管理你可以构建出非常稳定和智能的AI应用。