1. Canvas 验证码识别到底难在哪：从浏览器指纹绘制到 OCR 接口调用

Canvas 验证码识别这件事，很多人第一次接触会以为只是「把图片丢给 OCR 就完事」。真正动手才发现，前端 Canvas 画出来的东西不是一张现成的 PNG，而是一堆绘图指令叠加出来的像素结果；你拿到的可能是toDataURL()的 base64，也可能是带干扰线、噪点、随机字距的合成图。识别链路里任何一环没对齐，结果就是「人眼看着是 8F3K，模型返回 8F3K 但置信度 0.3」这种尴尬局面。

先把概念说清楚：Canvas 验证码，指的是用 HTML5<canvas>元素的 2D 上下文动态绘制的图形验证码。它和传统<img src="captcha.php">的最大区别在于——图像在浏览器端生成，服务端不一定存图。典型实现就是getContext("2d")拿到上下文，然后fillRect铺底色、fillText写字、moveTo/lineTo画干扰线、随机撒点。你看到的「验证码」本质是这些指令执行后的像素快照。

它能做什么？对开发者来说，Canvas 验证码识别通常出现在三类场景：一是自动化测试里需要绕过自家测试环境的验证码；二是数据采集/表单填写流程中，需要把验证码环节自动化；三是做 OCR 能力验证，拿验证码当练手数据集。适合谁？适合已经会写 JavaScript、懂一点 HTTP 请求、想快速搭一个「能跑起来」的识别验证环境的同学。不适合想直接拿去做恶意撞库的人——那是另一回事，本文只讨论技术验证链路。

我试过的坑主要集中在三块。第一块是图像预处理：Canvas 默认抗锯齿，字边缘是灰阶过渡，直接二值化容易把细笔画吃掉。第二块是坐标系：fillText(text, x, y)的 y 是基线，不是顶部，裁剪时容易切掉下半部分。第三块是接口鉴权：很多 OCR 服务要单独申请 Key、单独配 Base URL，散落在不同平台，管理成本高。这也是为什么本文会用 TaoToken 的统一 API 通道来做鉴权——一个 Key、一个 Base URL，把模型调用收敛到一处。

下面这张表先帮你建立整体认知，后面每一节都会落到可复制的代码。

理解了这个链路，你就知道为什么「只调一个 OCR 接口」往往不够——前后处理决定了上限。接下来先把 TaoToken 的前置准备做掉，再进入可复制配置。

2. TaoToken 统一 API 前置准备：一个 Key 打通验证码识别调用链

在写识别脚本之前，得先把「通道」搭好。所谓通道，就是你的请求从本地发出去、到模型、再回来的这条路。传统做法是每个 OCR 服务商一个域名、一套鉴权头、一份额度管理，验证码识别这种需要反复调试的场景，切换成本很高。TaoToken 的思路是把模型调用统一到一套 OpenAI 兼容的接口上，你只需要记住一个 Base URL 和一个 Key。

先明确两个地址，别混：

• 官网入口（注册、看文档、进控制台）：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 基地址（代码里填的）：https://taotoken.net/api

注意 API 地址后面不加任何 UTM 参数，代码里写干净就行。UTM 只用于官网跳转的归因，别把它拼进base_url，否则请求路径会变成/api?utm_source=...这种奇怪的东西，直接 404。

前置准备分三步，我按顺序说。

第一步，拿到 Key。进控制台创建 API Key，路径是 console 页面。创建后立刻复制保存，很多平台只显示一次。这个 Key 就是你后面所有请求的Authorization: Bearer sk-xxx。

第二步，确认模型 ID。验证码识别属于视觉理解任务，你要选支持图像输入的模型。在模型对话页面可以先手动传一张图试试，确认这个模型能读图。模型 ID 要原样填进代码，别自己改大小写。

第三步，想清楚调用方式。如果你只是偶尔验证几张图，用模型对话页面手动传图最快；如果你要写脚本批量跑，就用 API；如果你打算长期做编码类 Agent 或自动化流程，可以考虑 Coding Plan，把额度集中管理。三条路径对应三个入口：

• 模型对话（手动验证模型能不能读图）：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
• Coding Plan（长期编码/Agent 场景）：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

这里有个细节很多人踩：把官网地址当成 API 地址填进base_url。官网是给人看的页面，API 是给程序调的接口，两者路径不同。你代码里永远填https://taotoken.net/api，浏览器里打开的永远是带 UTM 的官网链接。

再强调一次安全边界：本文所有操作都在你自己的本地环境和合法测试范围内进行，验证码识别用于能力验证和自动化测试，不要用于任何未授权的系统。

前置做完，你手里应该有三样东西：一个 Key、一个模型 ID、一个 Base URL。下一节直接上可复制配置。

3. 可复制配置：Canvas 绘图参数 + 识别请求 JSON + 本地脚本

这一节是全文的核心，目标是让你复制粘贴就能跑。分三块：前端 Canvas 怎么画、识别请求怎么发、本地验证脚本怎么写。

3.1 Canvas 绘图参数配置

先给一份精简但完整的 Canvas 验证码绘制代码。相比原始版本，我做了几处调整：字符间距拉开、干扰线数量可控、导出 base64 方便后续识别。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="utf-8" /> <title>canvas-captcha-demo</title> <style> #captchaCanvas { cursor: pointer; border: 1px solid #ddd; } </style> </head> <body> <canvas id="captchaCanvas" width="120" height="40"></canvas> <input id="userInput" type="text" placeholder="输入验证码" /> <button id="refreshBtn">刷新</button> <button id="exportBtn">导出base64</button> <script> const canvas = document.getElementById('captchaCanvas'); const ctx = canvas.getContext('2d'); const CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'; let currentCode = ''; function randomInt(min, max) { return Math.floor(Math.random() * (max - min + 1)) + min; } function drawCaptcha() { // 1. 铺底色 ctx.fillStyle = '#F2F4F8'; ctx.fillRect(0, 0, canvas.width, canvas.height); // 2. 生成 4 位字符 currentCode = ''; for (let i = 0; i < 4; i++) { currentCode += CHARS[randomInt(0, CHARS.length - 1)]; } // 3. 逐字符绘制，带随机旋转和偏移 ctx.font = '26px "Microsoft YaHei", Arial'; ctx.textBaseline = 'middle'; for (let i = 0; i < currentCode.length; i++) { const x = 12 + i * 26 + randomInt(-3, 3); const y = canvas.height / 2 + randomInt(-4, 4); const angle = (randomInt(-20, 20) * Math.PI) / 180; ctx.save(); ctx.translate(x, y); ctx.rotate(angle); ctx.fillStyle = `rgb(${randomInt(0, 120)},${randomInt(0, 120)},${randomInt(0, 120)})`; ctx.fillText(currentCode[i], 0, 0); ctx.restore(); } // 4. 干扰线 for (let i = 0; i < 4; i++) { ctx.beginPath(); ctx.moveTo(randomInt(0, canvas.width), randomInt(0, canvas.height)); ctx.lineTo(randomInt(0, canvas.width), randomInt(0, canvas.height)); ctx.lineWidth = 0.8; ctx.strokeStyle = `rgba(${randomInt(0, 200)},${randomInt(0, 200)},${randomInt(0, 200)},0.6)`; ctx.stroke(); } // 5. 噪点 for (let i = 0; i < 30; i++) { ctx.fillStyle = `rgba(${randomInt(0, 255)},${randomInt(0, 255)},${randomInt(0, 255)},0.5)`; ctx.fillRect(randomInt(0, canvas.width), randomInt(0, canvas.height), 1, 1); } } document.getElementById('refreshBtn').onclick = drawCaptcha; canvas.onclick = drawCaptcha; document.getElementById('exportBtn').onclick = () => { const dataUrl = canvas.toDataURL('image/png'); console.log('base64 长度:', dataUrl.length); console.log(dataUrl); // 真值仅用于本地验证，生产环境不要暴露 console.log('当前真值:', currentCode); }; drawCaptcha(); </script> </body> </html>

几个参数说明：textBaseline = 'middle'解决基线偏移问题；save/restore保证旋转不影响后续绘制；toDataURL('image/png')导出的是data:image/png;base64,xxx，识别时要截掉前缀。

3.2 识别请求配置（JSON 片段）

下面这份 JSON 是发给 TaoToken 兼容接口的请求体结构，路径和字段名按 OpenAI 兼容格式来。注意image_url里放的是完整 data URL。

{ "model": "your-vision-model-id", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "这是一张验证码图片，请只输出图中的字符，不要任何解释、标点或空格。" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." } } ] } ], "max_tokens": 32, "temperature": 0 }

temperature设 0 是为了让输出稳定，验证码识别不需要创造性。max_tokens给 32 足够，4 位字符用不了多少。

3.3 本地验证脚本（Python）

import base64 import json import re import requests BASE_URL = "https://taotoken.net/api" API_KEY = "sk-你的Key" MODEL_ID = "your-vision-model-id" def image_to_data_url(path: str) -> str: with open(path, "rb") as f: b64 = base64.b64encode(f.read()).decode("utf-8") return f"data:image/png;base64,{b64}" def recognize_captcha(image_path: str) -> str: payload = { "model": MODEL_ID, "messages": [ { "role": "user", "content": [ {"type": "text", "text": "只输出验证码字符，不要解释。"}, {"type": "image_url", "image_url": {"url": image_to_data_url(image_path)}}, ], } ], "max_tokens": 32, "temperature": 0, } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } resp = requests.post( f"{BASE_URL}/v1/chat/completions", headers=headers, json=payload, timeout=30, ) resp.raise_for_status() data = resp.json() raw = data["choices"][0]["message"]["content"] return re.sub(r"[^0-9A-Za-z]", "", raw).upper() if __name__ == "__main__": result = recognize_captcha("captcha.png") print("识别结果:", result)

三件套对齐检查：Base URL 是https://taotoken.net/api，Key 是sk-开头，Model ID 是你在模型对话里验证过能读图的那个。三者缺一，请求必挂。

4. 验证请求与成功结果：从 401 到正确识别 8F3K 的完整过程

配置写完，下一步是验证。验证不是「跑一次看有没有报错」，而是分层确认：网络通不通、鉴权过不过、模型读不读图、输出格式对不对。我按这个顺序拆。

第一层，网络连通性。先用 curl 打一个最简请求，确认域名可达：

curl -i https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的Key"

如果返回 200 和模型列表，说明 Base URL 和 Key 都对。如果返回 401，跳到第 5 节排障。

第二层，鉴权。401 是最常见的错误，原因通常是 Key 复制时带了空格、或者用了官网地址当 Base URL。检查Authorization头格式必须是Bearer sk-xxx，中间一个空格。

第三层，模型读图。把 3.1 导出的 base64 存成captcha.png，跑 3.3 的脚本。成功时你会看到类似输出：

识别结果: 8F3K

如果模型返回的是「这是一张验证码图片，图中字符是 8F3K」，说明 prompt 没约束好，把text改成「只输出字符，不要任何其他内容」再试。

第四层，准确率验证。单张成功不代表稳定。写一个批量脚本，生成 50 张图，记录真值和识别值，算准确率：

import os from recognize import recognize_captcha # 复用 3.3 的函数 def batch_test(folder: str): total, correct = 0, 0 for name in os.listdir(folder): if not name.endswith(".png"): continue truth = name.split("_")[0].upper() # 文件名格式: 8F3K_xxx.png pred = recognize_captcha(os.path.join(folder, name)) total += 1 if pred == truth: correct += 1 else: print(f"错判: 真值={truth} 预测={pred} 文件={name}") print(f"准确率: {correct}/{total} = {correct/total:.2%}") if __name__ == "__main__": batch_test("./captchas")

实测下来，清晰无强干扰的 Canvas 验证码，识别率能到 90% 以上；干扰线密集、字符重叠的，会掉到 60% 左右。这时候要回到图像预处理：先灰度化、再自适应二值化，把干扰线滤掉再送识别。

一个关键细节：Canvas 导出的 base64 带data:image/png;base64,前缀，有些接口要求纯 base64，有些要求完整 data URL。TaoToken 兼容接口接受完整 data URL，别手动截前缀，否则模型读不到图。

成功结果的判断标准不是「没报错」，而是「识别文本和真值一致，且批量准确率稳定」。单张成功可能是运气，批量稳定才是链路通了。

5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth 逐条对照

这一节按真实报错来。我把验证码识别链路上最容易撞的四个错误列出来，每个都给现象、原因、修法。

错误一：401 Unauthorized

现象：请求返回{"error":{"message":"Invalid API key"}}。

原因通常三种：Key 复制不完整、Key 前后有空格、Base URL 填成了官网地址。修法：重新去 API Keys 页面复制，粘贴后strip()一下；确认base_url是https://taotoken.net/api，不是带 UTM 的官网链接。如果还不行，检查请求头是不是写成了Authorization: sk-xxx，少了Bearer。

错误二：local proxy failed / connection refused

现象：本地脚本报连接失败，或者提示代理相关错误。

原因：本地环境变量里残留了HTTP_PROXY/HTTPS_PROXY，请求被导向一个不存在的本地端口。修法：在脚本里显式禁用代理，或者清掉环境变量：

import os os.environ.pop("HTTP_PROXY", None) os.environ.pop("HTTPS_PROXY", None)

requests 也可以传proxies={"http": None, "https": None}。注意，这里说的是清理本地无效代理配置，不是让你去配什么特殊网络工具，别理解偏。

错误三：reading 'choices' of undefined

现象：TypeError: Cannot read properties of undefined (reading 'choices')。

原因：resp.json()返回的结构里没有choices，通常是请求失败但没抛异常，或者返回了错误对象。修法：先打印完整响应体再取字段：

data = resp.json() if "choices" not in data: print("异常响应:", json.dumps(data, ensure_ascii=False)) raise RuntimeError("接口未返回 choices")

常见触发点是模型 ID 写错，接口返回model not found，你直接取choices就炸了。

错误四：OAuth / 鉴权方式混淆

现象：提示需要 OAuth token，或者鉴权头格式不被识别。

原因：把某些需要 OAuth 流程的客户端配置，直接套到了 API Key 调用上。TaoToken 的 API 调用用 Bearer Key 即可，不需要走 OAuth 授权码流程。如果你在用 Claude Code 这类工具，它的配置文件和纯 API 脚本不同，要分开处理。Claude Code 接入时，Base URL、Key、Model ID 三件套要写全，缺一个都会鉴权失败。

排障顺序建议：先 curl 确认网络和鉴权，再跑单张识别，最后批量。哪一层挂就修哪一层，别跳步。

遇到鉴权类问题，直接去 API Keys 页面重新生成 Key；遇到接入配置问题，看接入文档；想先手动验证模型能不能读图，用模型对话页面传一张图最快。

• API Keys：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
• 模型对话：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

6. 把验证环境跑起来之后：下一步怎么接

链路跑通之后，你手里其实有了一个可复用的验证环境：Canvas 生成、base64 导出、接口识别、批量算准确率。这套东西的价值不只是识别验证码本身，而是它验证了「图像输入 + 模型输出」这条通道是通的。你可以把同样的结构迁移到票据识别、表单截图理解、UI 元素定位这些任务上，只需要换 prompt 和预处理逻辑。

如果你打算长期做这类视觉 + 自动化的活儿，建议把调用方式从临时脚本升级到 Coding Plan，额度集中管理，不用每次手动换 Key。入口在这里：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

最后留一个实用技巧：批量测试时，把识别失败的样本单独存一个文件夹，人工看一眼是预处理问题还是模型问题。大部分准确率上不去的情况，不是模型不行，是二值化阈值把笔画吃掉了。调阈值比换模型便宜得多。