max message tokens 到底指哪条消息

🔧 API 最佳实践max messagetokens…openstarry.com

先看这条报错:

400 Total tokens of image and text exceed max message tokens. Request id: 02177xxxxxxx

直接给答案:没有 “那一条”。这条报错约束的不是你刚发的那条消息,而是这次请求的整包 token—— 而这次请求里装着全部对话历史。你以为的 “单条消息上限”,在 400 这一类报错里并不存在。

但字面意义上的 “单条消息上限” 确实有,它在 413 RequestTooLarge,不在 400。这两类后面会拆开讲。

这个混淆在客服场景里很常见。一条典型回复是:

该报错属于单次请求中的图片、文本、附件等内容合计超过模型的消息 Token 上限,不是 /compact 命令没有执行。

这句话本身没错,但 “消息 Token 上限” 这个措辞会让用户继续去找一个并不存在的数值。翻译过来应该是:这是上下文长度上限(错误码就叫 OutofContextError),历史图片也计入,所以只压文本不够、清会话才彻底。

一、请求里其实没有 “一条消息”

max message tokens 这个措辞容易误解。它不是说 “你这条消息的 token 不能超过 X”,而是说 “这次请求的 token 总量不能超过模型的上下文长度”。 原因在接口形态。Chat Completions 和 Messages 都是无状态的,服务端不保存你的对话,每一轮请求都要把「系统提示 + 全部历史 + 本轮新增」整包重发一遍。你眼里的 “一条消息”,在服务端是这次请求的完整载荷 —— 历史上三轮对话、二十张截图,全都在里面,全都要重新计数。你发的那一条只占其中一小块,但触发了对整包的检查。

二、错误码的名字比文案诚实

火山方舟的错误码表里,这条 400 对应的 code 写得很直白:

400 BadRequest OutofContextError

含义一栏是:“当请求中包含图片时,文本和图片编码后的总 token 数超过了模型上下文长度限制。”

OutofContextError—— 上下文超限。ArkClaw 官方 FAQ 同一口径,原因写 “单次对话内容过长,超出推理模型上下文限制”,解法是 /new 压缩会话或新建会话;开发者社区的接入指南把链路写得更细:/status 看占用,/compact 压缩,压不动再 /new,还不行用 /context detail 看明细。

所以第一判断不该是 “单条消息上限是多少”,而是 “这次请求的水位超了,水从哪来”。

三、水主要从图片来,而图片不参与文本压缩

/compact 常常压不出效果,这是真的。原因不在命令失效,在它的作用对象:压缩做的是把文本轮次摘要化,图片 token 不一定跟着走。

Claude 的文档在讲图片数量阈值时写得很明确:请求里所有 image block 都计入,“包括你在后续轮次重发的历史轮次图片”。历史图片随每轮请求反复回传,这块体积压缩根本不碰。

于是典型场景是:会话里堆了二十几张手机截图,/compact 把文本压到三千 token,图片那两三万照旧,一发送还是 400。用户体感是 “压缩没用”,技术事实是 “压缩只管文本”。这种情况直接 /new 反而更快 —— 新会话是唯一能把历史图片一起清掉的动作。

四、省 token 的关键是档位和张数,不是分辨率

各家图片计费公式都带封顶,这里的直觉常常反着来。以下数值取自 2026 年 11 月各平台公开文档,随版本可能调整,引用时以文末链接为准。

火山方舟是 min(宽×高÷784, 单图上限)。detail:low 封顶 1312,detail:high 封顶 5120。低细节档下,只要图片超过约 103 万像素(1312×784),无论多大都是 1312—— 手机长截图 1179×2556 是 1312,4K 截图还是 1312。

所以把 4K 截图缩成 1080P 并不省 token:1920×1080 算出 2645,本来就被压到 1312。真要省,只有缩到 103 万像素以下(960×720 约 882 token),或者减少张数。

OpenAI 更极端,detail:low 固定 85,与尺寸无关;高细节档是 85 加每个 512px 瓦片 170,最多 8 个瓦片,上限 1445。Claude 会把超过约 1.15 兆像素的图先缩到该量级,单图大致 1600 封顶。

按 detail:high 单图 5120 封顶估算,128K 窗口下二十张图就是十万 token,一次撑掉八成 —— 这只是量级示意,实际取决于图片尺寸和档位。所以优化的性价比排序是:先减张数,再把不需要看小字的图降到低档,最后才动分辨率,而且只在你确实低于封顶阈值时才有意义。

五、动手前先量一下水位

排查顺序上,先测量再操作。支持命令的客户端里,/status 看当前占用,/context detail 看逐项明细,重点看图片占了多少 —— 这个数字通常让用户意外,文本往往只占零头。

自建应用就在发送前估算。Claude 的 POST /v1/messages/count_tokens 支持 tools、images、documents,返回的是跨 messages + system + tools 的 input_tokens 总量,直接拿去和模型的 context window 比就行,比手工套公式可靠得多;官方注明这是估算值,建议再留 20% 余量,因为系统提示和客户端注入的内容也要占位。把这个调用做成提交前的预检钩子,用户就能在输入框旁看到 “当前约 X token,上限 Y”。

六、什么时候该拆,什么时候不能拆

拆消息有效,但有边界。“把这张截图里的报错贴出来” 这类任务,图与文拆开没有损失;“对比这三张设计稿的差异”“根据这张架构图解释这段代码” 这类任务,图片和文本必须同处一次请求,模型才能建立关联。拆成多轮后上下文是割裂的,回答质量会掉。

这时有三条明确的下一步:把 detail 从 high 降到 low(单图从 5120 掉到 1312)、把同请求的图片张数减到必要数量、换 context window 更大的模型版本。都比硬拆划算。

七、三类超限,一次分清

这条 400 和另外两类长得很像,解法却完全不同。

三类分开看:

报错 400,且带 image and text 字样 —— code 是 OutofContextError,根因是上下文水位,历史图片也计入。有效动作是 /new、减张数、降档;只做 /compact 不够。

报错 413 —— code 是 RequestTooLarge,根因是业务粒度的单件载荷超限,含单条消息、单文件、zip。有效动作是拆分、降规格;压缩和清会话对它零作用。它的官方描述里明写 “单条消息”,这才是字面意义上的单条上限,与上下文窗口无关。

提示像素或尺寸越界 —— code 形如 InvalidArgumentError.InvalidPixelLimit,根因是单图硬限:方舟单图不超 3600 万像素;Claude 单图 8000×8000,请求内超 20 张时降至 2000×2000。有效动作是缩图、减张数;改文本没用。

八、判别路径

把上面压成一条可以直接照着走的路:

报错 400,且含 "image and text"

└─ 上下文水位问题

   /status 看图片占比 → /compact(只压文本)
   → 仍超 → /new(连历史图片一起清)
   → 还超 → 降 detail 档 / 减张数

报错 413,或提示像素、尺寸

└─ 单件载荷问题

   拆分 / 降规格(压缩零作用)

发图之前先问三件事:这批图是不是必须和文本同处一次请求;有几张真的需要看小字;当前会话里是不是还压着一堆旧图。发送前能算就算,留 20% 余量。

FAQ:

Q:这条 400 是不是说明我这条消息太长了?

A:不是。接口无状态,每次请求都会重发系统提示、全部历史与本轮内容,检查对象是整包请求的 token 总量。

Q:已经执行 /compact 了,为什么还报同样的错?

A:压缩处理的是文本轮次,图片 token 不随压缩减少,历史图片仍会被重新发送并计数。若水位主要来自图片,应改用 /new 清空会话。

Q:单条消息的 token 上限到底是多少?

A:400 这一类里没有这个数值,它约束的是上下文长度。真正对应单条消息的上限在 413 RequestTooLarge,属于业务粒度载荷限制。

Q:一张截图大概折多少 token?

A:火山方舟为 min(宽×高÷784, 封顶),detail:low 封顶 1312;OpenAI 低细节档固定 85,高细节档 85 加每瓦片 170,上限 1445;Claude 单图大致 1600 封顶。 Q:报 413 该怎么办? A:拆分请求或降低规格。压缩与清会话对 413 无效。

参考

以下数值与口径对应的文档版本为 2026 年 11 月,平台更新后请以链接页面为准。

火山方舟《错误码》:https://ark.volcengine.com/region:cn-beijing/docs/error-codes?lang=zh

火山方舟《错误码》(413 部分):https://docs.volcengine.com/docs/82379/1299023

火山《ArkClaw 使用 FAQ》:https://www.volcengine.com/docs/87732/2275255?lang=zh

火山开发者社区《OpenClaw 接入火山 CodingPlan 实践指南》: https://developer.volcengine.com/articles/7615528054736945158

火山方舟《图片理解》(图片 token 公式与封顶):https://www.volcengine.com/docs/82379/1362931 Claude《Vision》:https://platform.claude.com/docs/en/build-with-claude/vision

Claude《Token counting》:https://platform.claude.com/docs/en/build-with-claude/token-counting

Azure OpenAI 视觉 token 计算:https://learn.microsoft.com/zh-cn/azure/ai-foundry/openai/overview

以 AI 之力,筑未来之境

现在注册,立即免费获赠 200 次大模型调用权益

免费注册 →