图像输入（视觉）

给 Claude Code 喂图：粘贴、拖拽、引用文件路径，让模型看懂截图、设计稿、架构图与图表。基于 QCode.cc 的视觉模型，所有接入域共用一份 API Key。

更新于 2026-10-15

本页目录

三种喂图方式
- 引用文件路径示例
典型用法
哪些模型能看图
实用建议
图片格式、尺寸与 token 消耗
在 Claude Code 里贴图的细节
常见报错与排查
常见问题
相关文档

Claude Code 不仅能读代码，还能看图。把截图、设计稿、报错画面、架构图丢给它，具备视觉能力的模型会直接「读」图里的内容，再结合你的提示词干活——把 mockup 还原成 UI、对着报错截图定位 bug、解释一张架构图或数据图表。

本文讲的是图像输入：你提供图片、模型理解图片。这和「文生图」是两回事。

⚠️ 别和图像生成搞混了 本文是把图片喂给模型让它理解（视觉输入）。如果你想让 AI 生成 / 编辑图片（海报、配图、UI mockup、抠图换背景），那是另一个能力，用 gpt-image-2，请看 gpt-image-2 图像生成。一句话区分：看图 = 本文；画图 = image-2。

三种喂图方式¶

在 Claude Code 会话里，给模型提供图片有三种方式：

方式	操作	适用场景
粘贴	复制图片后按 `Ctrl+V` 粘贴进输入框	截图工具截的图、剪贴板里的图
拖拽	把图片文件直接拖进终端窗口	文件管理器里现成的图片文件
引用路径	在提示词里写出图片文件路径	项目里已有的图片、脚本批量处理

macOS 截图后默认进剪贴板，直接 Ctrl+V 即可；如果截图存成了文件，用拖拽或写路径更稳。终端 / 系统不同，粘贴与拖拽的支持程度会有差异，遇到不识别就改用「引用文件路径」这种最稳的方式。

引用文件路径示例¶

> 看一下 ./design/dashboard.png 这张设计稿，用 React + Tailwind 把它实现出来
> 这个报错截图 @screenshots/build-error.png 是什么原因？怎么修？
> 解释一下 docs/architecture.png 里的系统架构，各组件是怎么交互的

引用路径的好处是可复现：写进脚本、放进提示词模板，每次都能精确指向同一张图，不依赖手动粘贴。

典型用法¶

1. 设计稿 / 截图 → UI 代码¶

把一张 mockup 或现有页面的截图给 Claude Code，让它还原成可运行的前端代码。

> 这是设计稿 @mockups/pricing-page.png，用 Next.js + Tailwind 实现，
  布局、间距、配色尽量还原，组件拆分要合理

模型会读出图里的布局、文案、配色，生成对应的组件代码。还原度取决于图的清晰度和你提示词里的约束（框架、样式系统、命名规范等）。

2. 报错截图 → 定位与修复¶

IDE、浏览器控制台、终端里红彤彤的报错，截图丢给它即可，不用手敲长长的堆栈。

> @screenshots/ts-error.png 这个 TypeScript 报错怎么解决？相关代码在 src/api/client.ts

模型从截图里读出错误信息和堆栈，结合你指出的代码文件给出修复建议。

3. 架构图 / 数据图表 → 理解与说明¶

把架构图、时序图、流程图、监控面板、数据图表交给它，让它解释、提取数据、或据此写代码 / 文档。

> 解释 @diagrams/data-flow.png 这张数据流图，并据此写一份接口文档草稿
> 读一下这张监控截图 @screenshots/latency.png，p95 延迟在什么区间？有没有异常尖峰？

哪些模型能看图¶

视觉能力由模型决定，不是所有模型都能读图。通过 QCode.cc 接入、具备视觉能力的模型：

模型	说明
`claude-opus-5`	旗舰，视觉 + 推理俱强，复杂设计稿 / 图表首选
`claude-sonnet-5`	均衡之选，日常看图 / 还原 UI 性价比高
GPT 系（`gpt-6-sol`）	OpenAI 系视觉模型，多模态理解能力强

纯文本 / 代码向的轻量模型可能不支持图像输入。把图喂给不支持视觉的模型时，图片会被忽略或报错——选模型时认准上面这几款。4.x 视觉型号（如 claude-sonnet-4-6、claude-opus-4-8）仍在售。模型切换见模型选择。

QCode.cc 的优势是一份 cr_ 开头的 API Key 通吃所有协议和模型：同一个密钥既能用 Claude 系视觉模型，也能调 GPT-5.x，按需切换不用换账户。接入域和协议路径见接入点与 API 格式（国内用户优先用 asia.qcode.cc）。

实用建议¶

图要清晰：分辨率太低、字糊成一团，模型读不准。设计稿和报错截图尽量原图、别压缩过头。
一次别堆太多图：图越多、越大，消耗的 token 越多、也越容易抓不住重点。一次聚焦一两张关键图。
配文字说清意图：图旁边写明你要它干嘛（「还原成 React」「找出报错原因」「提取表格数据」），比只丢一张图效果好得多。
敏感信息先打码：截图里的密钥、token、内网地址、用户数据等，喂图前先遮挡。
批量场景用路径：要在脚本 / 自动化里处理图片，用「引用文件路径」最可控，配合自动化与 CI/CD 的 headless 模式可批处理。

图片格式、尺寸与 token 消耗¶

截至 2026-10-15，据 Anthropic 官方视觉文档（经 QCode 使用 Claude 时可作参照）：

项目	官方说明
支持格式	JPEG、PNG、GIF、WebP；GIF 不支持动画，只取第一帧
单图尺寸上限	8000×8000 px
单次请求超过 20 张	对每张图适用更严的尺寸上限；文档建议每边缩到 2000 px 以内，或把一次请求控制在 20 张以内
单图体积	直连 Claude API 时 10 MB（base64 编码后）；标准端点整个请求体上限 32 MB
token 消耗	图片按 28×28 像素的块计，约为 ⌈宽/28⌉ × ⌈高/28⌉ 个视觉 token
自动缩放	标准档长边超过 1568 px 会被缩小；Claude 4.7 及更新的模型长边上限为 2576 px
精度提醒	小于 200 像素的图、旋转或低质量的图，模型更容易读错

实际含义：截图别截得过大，4K 屏全屏截图会被缩小，多出来的像素只增加传输体积、不增加清晰度；真正需要看清的区域，裁剪后再给，比整屏截图更准、更省 token。

在 Claude Code 里贴图的细节¶

据 Claude Code 官方文档：可以把图片拖进窗口，或复制后用 Ctrl+V 粘贴（Windows 与 WSL 用 Alt+V，iTerm2 可用 Cmd+V）；粘贴后输入框里会出现 [Image #1] 之类的标记，可以在提示词里按序号引用。

常见报错与排查¶

现象	常见原因	处理
模型说「看不到图」或忽略图片	当前模型不支持视觉，或图片没真正附上	用 `/model` 换成上文列出的视觉模型，确认输入框里有 `[Image #N]` 标记
粘贴没反应	终端或系统不转发剪贴板图片	Windows / WSL 改用 `Alt+V`，仍不行就拖拽或写文件路径
请求被拒，报尺寸相关错误	一次请求带了超过 20 张图，触发更严的尺寸限制	每张图缩到 2000 px 以内，或分批发送
请求过大、被拒	图太多或太大，请求体超限	压缩、降分辨率，或只保留关键几张
文字读不准	分辨率低或压缩过度	提供原图或裁剪出文字区域；重度 JPEG 压缩会让文字难辨
`model_not_available_on_endpoint`	用 OpenAI 接口调了 Claude 模型	Claude 走 `https://api.qcode.cc/api`，见接入点与 API 格式

常见问题¶

截图一定要用 PNG 吗？¶

不必。JPEG、PNG、GIF、WebP 都支持。文字多的界面截图优先用 PNG，避免有损压缩让字模糊。

图片会额外收费吗？¶

图片按 token 计入输入，和文字一起按 token 计费，各模型单价见 qcode.cc/models。图越大，视觉 token 越多，所以先裁剪、再发送。

能让模型识别图里的人是谁吗？¶

不能。Anthropic 官方文档写明 Claude 不能用于指认图中人物，也会拒绝这样做；让它描述画面内容、读文字、解释图表是可以的。

一次最多能发几张图？¶

Anthropic 官方文档给出的 API 单次上限是 100 张（200K 上下文的模型）或 600 张（其他模型），但超过 20 张时尺寸限制更严，请求体上限也可能先到。日常建议一次聚焦一两张关键图。