AI学习--用Python调用OpenRouter免费API，把Base URL改到TaoToken统一管理

1. 从一次 401 报错说起Python 调用 OpenRouter 免费 API 的 Key 管理痛点如果你刚开始用 Python 玩 AI 应用大概率会经历这样一个阶段先注册 OpenRouter拿到一个sk-or-v1-开头的 Key写几行requests.post跑通一次对话补全心里挺爽。然后你又听说别家平台也有免费额度于是再注册一个Key 变成sk-开头再后来本地跑 Claude Code、Cline 这类工具又要填一套 Base URL 和 Key。三四个平台下来你的.env文件里躺着一堆变量哪个 Key 对应哪个地址过两周自己都记不清。我试过最狼狈的一次是把 OpenRouter 的 Key 填到了另一个平台的 Base URL 上请求直接返回 401排查了半小时才发现是地址和 Key 配错了对。这种「Key 通道混乱」不是能力问题纯粹是管理问题。OpenRouter 本身很好用它的/api/v1/chat/completions接口兼容 OpenAI 格式模型名带:free后缀的可以白嫖对学习者非常友好。但当你同时用多个平台时每个平台一套鉴权、一套地址、一套模型命名切换成本就上来了。这篇内容面向的就是刚入门 AI 应用开发的 Python 学习者。我会先带你把 OpenRouter 免费模型的调用流程完整跑一遍包括 Base URL、模型名、请求头到底怎么填然后演示一个更省心的做法——把 Base URL 改到 TaoToken用一条统一 Key 通道管理多个模型来源的调用。目标很明确让你亲手跑通一次对话补全请求看到返回结果并且理解为什么统一入口能减少踩坑。先明确几个概念避免后面混淆。Base URL是请求的根地址OpenRouter 的是https://openrouter.ai/api/v1拼接后完整端点就是/chat/completions。API Key是身份凭证放在请求头的Authorization字段里格式是Bearer 你的Key。Model ID是模型标识OpenRouter 上免费模型通常长这样deepseek/deepseek-chat-v3-0324:free带斜杠和冒号。这三样东西——Base URL、Key、Model ID——就是每次调用必须对齐的「三件套」任何一件错位都会报错。为什么强调「统一管理」因为当你的项目从单平台扩展到多平台时代码里如果硬编码了地址和 Key每换一个来源就要改代码、改配置、重新测试。而如果把 Base URL 指向一个兼容 OpenAI 协议的统一入口Key 也只维护一份那么切换模型来源就只是改一个 Model ID 字符串的事。这对学习者尤其重要你现在的重点是学 prompt 设计、学流式输出、学函数调用而不是把时间耗在记各平台的地址差异上。接下来的结构是这样先讲清楚 OpenRouter 直连的完整配置给你可以直接复制的 Python 代码再讲怎么把 Base URL 换到 TaoToken 做统一通道并验证请求成功然后集中排查几个新手最常撞的报错比如 401、local proxy failed、reading choices这类最后给一个按场景分流的入口建议。全程以「能跟做」为标准代码都能直接跑。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套怎么拿在动手改代码之前先把 TaoToken 这边的「三件套」准备好。这一步不复杂但顺序别搞反先拿 Key再确认 Base URL最后挑 Model ID。很多人一上来就复制代码结果 Key 没配好跑出来一堆 401反而更浪费时间。先说 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不带任何多余路径。你拼接完整端点时是在它后面加/v1/chat/completions也就是最终请求地址为https://taotoken.net/api/v1/chat/completions。这一点和 OpenRouter 的https://openrouter.ai/api/v1结构是一致的都是 OpenAI 兼容风格所以你的 Python 代码几乎不用大改只换 Base URL 就行。这个兼容性很关键意味着你之前为 OpenRouter 写的请求逻辑、消息格式、参数名基本可以原样迁移。再说 API Key。你需要到 TaoToken 的控制台里创建一个 Key。创建入口在 API Keys 页面登录后按提示新建即可。Key 生成后只显示一次务必当场复制保存到安全的地方比如本地的.env文件或者密码管理器。这里有个习惯建议不要直接把 Key 写死在 Python 源码里尤其是你打算把代码传到 Git 仓库的时候。用环境变量读取既安全又方便切换。Key 的格式通常是一串较长的字符放在请求头的Authorization字段前面加Bearer前缀注意中间有一个空格。然后是 Model ID。这是最容易让人困惑的一环因为不同平台的模型命名规则不一样。OpenRouter 用deepseek/deepseek-chat-v3-0324:free这种带斜杠和:free后缀的写法而 TaoToken 作为统一入口模型 ID 的写法以平台文档为准通常也是「厂商/模型名」的形式。你在控制台或文档里能看到当前可用的模型列表挑一个对话模型即可。关键点是Model ID 必须和 Base URL 指向的平台匹配。如果你把 OpenRouter 的模型名直接丢给 TaoToken 的地址很可能报「模型不存在」或类似的错误。所以换 Base URL 的同时Model ID 也要换成对应平台支持的。为了让你更直观地对照我把两套配置的差异整理成一张表配置项OpenRouter 直连TaoToken 统一通道Base URLhttps://openrouter.ai/api/v1https://taotoken.net/api/v1完整端点/chat/completions/chat/completionsKey 前缀常见sk-or-v1-以控制台生成为准Model ID 示例deepseek/deepseek-chat-v3-0324:free以平台文档模型列表为准请求头额外字段常带HTTP-Referer、X-Title按平台要求通常只需Authorization和Content-Type看到没真正变的只有 Base URL、Key 和 Model ID 这三样请求体结构、消息数组格式、role/content的写法完全一致。这就是 OpenAI 兼容协议的好处生态里的工具和代码可以低成本迁移。还有一点要提醒如果你后续要用 Claude Code、Cline 这类编码工具它们通常也支持自定义 Base URL 和 Key。这时候统一通道的价值就更明显了——你只需要在工具设置里填一次 TaoToken 的地址和 Key再选一个 Model ID就能让这些工具走同一条通道不用每个工具单独配一套 OpenRouter 的凭证。关于这些工具的具体配置后面章节会展开。现在你手上应该有了三样东西TaoToken 的 Base URL、一个刚创建的 API Key、一个确认可用的 Model ID。把它们记好下一节我们就直接写代码先跑通 OpenRouter 直连版本再改成 TaoToken 版本对比着看差异。3. 可复制配置Python 请求示例与 settings 片段这一节是全文的核心操作部分我会给你两段可以直接复制的 Python 代码第一段走 OpenRouter 直连第二段把 Base URL 换成 TaoToken。两段代码结构几乎一样你可以对照着理解「统一通道」到底改了什么。同时我会给出一份 JSON 格式的配置片段方便你在项目里用配置文件管理这些参数而不是散落在代码各处。先看 OpenRouter 直连版本。这段代码用requests库发一个 POST 请求到/chat/completions请求头里放Authorization、Content-TypeOpenRouter 还习惯带上HTTP-Referer和X-Title用于标识来源。请求体是标准的model加messages结构。你可以把 Key 和模型名替换成自己的import os import requests import json # 从环境变量读取避免硬编码 OPENROUTER_KEY os.getenv(OPENROUTER_API_KEY, sk-or-v1-你的Key) url https://openrouter.ai/api/v1/chat/completions headers { Authorization: fBearer {OPENROUTER_KEY}, Content-Type: application/json, HTTP-Referer: https://example.com, X-Title: python-demo } payload { model: deepseek/deepseek-chat-v3-0324:free, messages: [ {role: user, content: 用一句话解释什么是API} ] } resp requests.post(url, headersheaders, datajson.dumps(payload), timeout60) print(resp.status_code) print(resp.json())跑通之后你会看到返回的 JSON 里有一个choices数组里面message.content就是模型的回答。这一步成功说明你的 Key、地址、模型名三件套对齐了。现在把它改成 TaoToken 统一通道。改动只有三处Base URL 换成https://taotoken.net/api/v1Key 换成 TaoToken 控制台生成的Model ID 换成平台支持的。其余请求头、请求体结构不动。为了让你少改代码我把差异做成变量import os import requests import json # 统一通道配置 BASE_URL https://taotoken.net/api/v1 TAOTOKEN_KEY os.getenv(TAOTOKEN_API_KEY, 你的TaoToken Key) MODEL_ID 你的模型ID # 以平台文档为准 url f{BASE_URL}/chat/completions headers { Authorization: fBearer {TAOTOKEN_KEY}, Content-Type: application/json } payload { model: MODEL_ID, messages: [ {role: user, content: 用一句话解释什么是API} ] } resp requests.post(url, headersheaders, datajson.dumps(payload), timeout60) print(resp.status_code) print(resp.json())注意 TaoToken 版本里我去掉了HTTP-Referer和X-Title因为这两个是 OpenRouter 特有的来源标识字段统一通道通常不需要。如果你不确定保留它们一般也不会报错但干净一点更好。接下来是配置文件片段。与其把 Key 和地址写死在代码里不如用一个config.json管理代码读取它。这样你切换平台时只改配置不动逻辑{ base_url: https://taotoken.net/api/v1, api_key_env: TAOTOKEN_API_KEY, model_id: 你的模型ID, timeout: 60, default_messages: [ {role: user, content: 你好请做个自我介绍} ] }对应的读取代码可以这样写import json import os import requests with open(config.json, r, encodingutf-8) as f: cfg json.load(f) api_key os.getenv(cfg[api_key_env]) url f{cfg[base_url]}/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: cfg[model_id], messages: cfg[default_messages] } resp requests.post(url, headersheaders, datajson.dumps(payload), timeoutcfg[timeout]) print(resp.status_code) print(resp.json())如果你用的是 Claude Code 这类工具它的配置通常是一个settings.json或类似的配置文件里面会有env字段让你填ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN之类的变量。思路是一样的Base URL 填 TaoToken 的地址Token 填你的 Key模型 ID 在工具里选或填。Cline 的 MCP 配置也是类似逻辑在设置里指定自定义端点和凭证。Codex 的auth.json则通常包含OPENAI_API_KEY和OPENAI_BASE_URL两个字段把 Base URL 指向统一通道即可。这三件套——Base URL、Key、Model ID——在任何工具里都是核心记住这个框架换工具就不慌。配置写好后建议先别急着接工具用上面的 Python 脚本单独验证一次请求能通。工具层出问题时你很难判断是工具配置错了还是通道本身有问题。先用最朴素的requests跑通把变量隔离出来这是排障的基本功。4. 验证请求与成功结果一次对话补全的完整过程配置写完了现在来实际跑一次把「请求发出到结果返回」的完整链路走通。这一节我会带你逐段看请求和响应理解每个字段的含义这样以后遇到异常你能自己定位。先确认运行环境。你需要 Python 3.8 以上安装requests库pip install requests然后把上一节的 TaoToken 版本代码保存为demo.py在终端里设置环境变量。Linux 或 macOS 下export TAOTOKEN_API_KEY你的Key python demo.pyWindows PowerShell 下$env:TAOTOKEN_API_KEY你的Key python demo.py运行后终端会先打印 HTTP 状态码再打印返回的 JSON。如果一切正常状态码是200JSON 结构大致长这样{ id: chatcmpl-xxxx, object: chat.completion, created: 1700000000, model: 你的模型ID, choices: [ { index: 0, message: { role: assistant, content: API 是应用程序之间约定好的通信接口…… }, finish_reason: stop } ], usage: { prompt_tokens: 15, completion_tokens: 40, total_tokens: 55 } }重点看几个字段。choices是回答列表通常取第一个元素的message.content那就是模型输出。finish_reason为stop表示正常结束如果是length说明被最大 token 数截断了。usage里是 token 消耗统计免费模型也会显示方便你估算用量。model字段会回显实际使用的模型可以用来确认请求有没有被路由到你指定的模型。如果你想更优雅地提取回答而不是打印整个 JSON可以改成这样data resp.json() if resp.status_code 200: answer data[choices][0][message][content] print(模型回答, answer) print(消耗 tokens, data[usage][total_tokens]) else: print(请求失败, resp.status_code, data)这样输出就干净多了。跑通这一步说明你的统一通道配置是正确的Base URL 指向了 TaoTokenKey 通过了鉴权Model ID 被平台识别请求体格式符合 OpenAI 兼容规范。四个环节缺一不可。再进一步你可以试试多轮对话。messages数组里按顺序放多条消息role可以是system、user、assistant。比如payload { model: MODEL_ID, messages: [ {role: system, content: 你是一个简洁的助手回答不超过两句话。}, {role: user, content: 什么是HTTP状态码}, {role: assistant, content: HTTP状态码是服务器对请求的响应标识。}, {role: user, content: 举三个常见的例子} ] }把这段替换进脚本再跑你会看到模型基于上下文继续回答。这说明统一通道不仅支持单轮也完整支持多轮消息结构和直连 OpenRouter 的体验一致。还有一个实用技巧加超时和重试。网络请求偶尔会抖动timeout60能避免脚本卡死。如果你要做批量调用可以加一个简单的重试逻辑import time def chat(payload, retries3): for i in range(retries): try: resp requests.post(url, headersheaders, datajson.dumps(payload), timeout60) if resp.status_code 200: return resp.json() print(f第{i1}次失败状态码 {resp.status_code}) except requests.exceptions.RequestException as e: print(f第{i1}次异常{e}) time.sleep(2) return None这个函数在失败时重试三次每次间隔两秒。对于免费模型偶尔的限流或网络波动这种简单重试能显著提高成功率。注意不要无限重试否则可能触发平台的频率限制。验证到这一步你已经完成了从「写代码」到「看到结果」的闭环。接下来要做的是把可能出现的报错提前摸清楚这样真出问题时你能快速定位而不是对着屏幕发呆。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth新手跑 API 最容易卡在几个固定报错上。这一节我把最常见的四类错误拆开讲每个都给出原因和排查步骤。你遇到时对照着看基本能自己解决。第一类401 Unauthorized。这是最高频的错误意思是鉴权失败。可能原因有三个Key 写错了、Key 没生效、请求头格式不对。先检查Authorization字段是不是Bearer加 Key中间那个空格不能少。再确认 Key 有没有复制完整有没有多复制了空格或换行。如果你用的是环境变量打印一下os.getenv(TAOTOKEN_API_KEY)看看是不是None环境变量没设置成功也会导致 Key 为空。还有一种情况是 Key 被禁用或额度用尽去控制台确认 Key 状态。排查顺序先看请求头格式再看 Key 值最后看 Key 状态。第二类local proxy failed 或连接超时。这个报错通常和网络环境有关。如果你本地设置了系统代理requests可能会尝试走代理导致连接失败。可以在代码里显式禁用代理proxies {http: None, https: None} resp requests.post(url, headersheaders, datajson.dumps(payload), timeout60, proxiesproxies)或者检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置临时清掉再试。另外确认你的网络能正常访问taotoken.net可以用curl或浏览器打开文档页测试连通性。超时时间设太短也会误报建议至少 30 秒。第三类reading choices 相关报错比如KeyError: choices或list index out of range。这类错误说明你拿到的响应里没有choices字段通常是请求本身失败了但代码直接去取data[choices]就崩了。正确做法是先判断状态码再取字段data resp.json() if resp.status_code ! 200: print(错误详情, data) else: print(data[choices][0][message][content])如果状态码是 200 但choices为空可能是模型名不对或请求被平台拦截。打印完整data看错误信息通常会告诉你具体原因比如「model not found」。这时候回去核对 Model ID 是否和平台文档一致。第四类OAuth 或鉴权方式不匹配。有些工具默认用 OAuth 流程而你填的是 API Key就会报鉴权方式错误。比如 Claude Code 这类工具配置里要区分ANTHROPIC_AUTH_TOKEN和 OAuth 登录。如果你走统一通道应该填 API Key 而不是走 OAuth 登录流程。检查工具的设置项找到「自定义端点」或「API Key」相关字段把 Base URL 和 Key 填对。如果工具强制走 OAuth可能需要看它是否支持自定义 Base URL不支持的话就换用支持的方式。为了让你排查更快我把这几类错误整理成对照表报错关键词可能原因排查动作401 UnauthorizedKey 错误/缺失/格式不对检查Bearer格式、Key 完整性、环境变量local proxy failed本地代理干扰显式禁用 proxies、清理代理环境变量reading choices / KeyError请求失败但代码直接取字段先判断状态码打印完整响应OAuth / 鉴权不匹配工具鉴权方式与 Key 不符改用 API Key 配置确认工具支持自定义端点还有一个通用技巧把请求和响应的原始内容都打印出来。很多人只看状态码不看响应体结果错误信息明明写在 body 里却被忽略。养成打印resp.text的习惯尤其是非 200 的时候。另外用curl命令单独测一次能排除 Python 代码本身的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:你的模型ID,messages:[{role:user,content:hi}]}如果curl能通而 Python 不通问题就在 Python 代码或环境如果curl也不通问题在配置或网络。这个二分法能帮你快速缩小范围。6. 按场景选入口模型对话、接入文档与 Coding Plan 怎么用跑通请求之后你可能会想继续深入有的想验证不同模型的效果有的想把通道接进编码工具长期用有的想系统看一遍接入文档。不同目标对应的入口不一样这一节按场景给你分流建议避免你在首页乱点。如果你只是想快速验证某个模型能不能用、回答质量如何最直接的方式是打开模型对话页面在里面选模型、发消息看返回。这相当于一个在线的调试台不用写代码就能确认 Model ID 是否有效、通道是否通畅。当你拿不准某个模型名对不对时先用对话页面试一次比在代码里反复改要快得多。验证通过后再把同样的 Model ID 填进 Python 脚本成功率会高很多。如果你是要把统一通道接进项目或工具比如 Claude Code、Cline、Codex 这类重点看接入文档。文档里会写清楚 Base URL 怎么填、Key 放哪个字段、Model ID 从哪查以及不同工具的配置示例。前面提到的三件套——Base URL、Key、Model ID——在文档里都有对应说明。遇到配置问题时文档通常也有常见问题章节比你自己摸索快。接入文档的入口在文档页建议收藏配置工具时对着看。如果你是打算长期用 AI 辅助编码或者要跑 Agent 类任务调用量会比偶尔试一次大得多这时候可以了解 Coding Plan。它面向的是持续性的编码场景在用量和通道稳定性上更适合长期使用。你可以在控制台或相关页面看到具体方案根据自己的使用频率选择。对于只是学习 API 调用的阶段先用按量方式跑通流程就够了等你确认要长期依赖再考虑更合适的方案。还有一个入口是 API Keys 管理页。你创建的 Key、查看 Key 状态、必要时重新生成都在这里。建议养成习惯不同用途用不同的 Key比如一个用于本地测试一个用于线上工具这样某个 Key 出问题或需要轮换时不会影响全部场景。Key 泄露了也能快速定位并禁用。最后给一个实操建议把这篇里的 Python 脚本保存成一个可复用的小工具参数从配置文件读。以后你想测新模型只改config.json里的model_id跑一下脚本就知道通不通。这个习惯能让你把精力集中在学 AI 应用本身而不是每次都被配置问题打断。统一通道的价值也在这里体现——你维护的是一套地址和一份 Key切换模型来源只是改一个字符串。