图叮 Image-2 任务 ID 为什么要存字符串：避开 JavaScript 数字精度坑

翻看当前仓库在 2026 年 7 月 18 日的静态核对结果，排除博客与测试文件后，task_id_str 仍铺在 471 行代码路径里。这不是用户故障率，而是一个工程信号：任务编号要穿过提交响应、状态仓库、URL、缓存键和取消请求。途中任何一处把它转成 JavaScript Number，后面的查询便可能循着错误编号一路走偏。

图注：长任务编号必须以字符串穿过存储、URL 和轮询。

这份问答只理清一件事：图叮 Image-2 异步任务 ID 在 JavaScript 客户端里该怎样传。图片变形、色偏或提示词效果另有脉络，属于生成质量诊断，不在本文范围。

Q：为什么接口同时返回 task_id 和 task_id_str？

答案不必绕弯：JavaScript 代码以 task_id_str 为准，task_id 只作兼容字段看待。

仓库里的任务合同写得很明白：图叮 Image-2 提交结果会同时带回数字形态的 task_id 和字符串形态的 task_id_str。前者照顾仍在使用整数 ID 的旧调用方，后者专门处理 JavaScript 长整数精度问题。合同已把 task_id_str 定为前端的单一标识，并要求 URL、queryKey、状态仓库和本地存储都沿用它。

不妨把这两个字段看作同一卷宗的两份抄本。数字抄本留给旧系统续读；字符串抄本才把每一个笔画照原样收好。前端若误拿兼容字段当权威字段，眼前仿佛只少一位、变一位，等到轮询，查的却已是另一份卷宗。

提交成功后，第一行代码就该把这件事定下来：

const taskId = response.data.task_id_str;
// 后续只传 taskId，不再读取 response.data.task_id

此处不必对字符串施以 parseInt、一元加号或 Number()。它是标识，贵在一笔不差，并非用来加减乘除的数量。

Q：JavaScript Number 为什么会改掉任务 ID？

JavaScript Number 用的是双精度浮点数。它能连续、精确表示的整数，上限为 Number.MAX_SAFE_INTEGER，也就是 2 的 53 次方减 1。雪花 ID 常常越过这道界线。越界之后，并非每个相邻整数都能各自占住一个位置，运行时只能落到附近一个可表示的值上。

下面这段只为说明机制，是示意，不是真实任务号：

const raw = "9007199254740993";
Number(raw) === Number("9007199254740992"); // true
String(Number(raw)); // "9007199254740992"

这类错最隐蔽之处，是它通常寂然无声。页面照常渲染，日志里也留着一串长数字，只是末位已悄然改了。客户端再去请求任务详情，服务端按完整 ID 查找，便可能得到“任务不存在”；若错误值恰好落在其他记录上，痕迹反而更难察觉。

也别指望“转成 BigInt 再救回来”能补住事后的缺口。输入若已经经过 Number 舍入，BigInt(roundedNumber) 只是把错误值精确封存，原来的末位不会归来。顺序应守正：从起笔处就保留服务端给出的字符串。

Q：任务 ID 应该在哪些位置保持字符串？

要守的是整条链路，并非某一个接口层。契约可以收成一句短规矩：标识从响应进入 JavaScript 后，不再数值化。

具体有五个关口：

1. 提交响应：读取 task_id_str。
2. 状态管理：字段类型写成 string，更稳妥的做法是使用项目里的 TaskIdStr 品牌类型。
3. 请求路径：拼接详情、图片或取消请求时直接使用原字符串。
4. 查询缓存：React Query 等工具的 queryKey 也放字符串，避免同一任务在缓存里分裂成两个键。
5. 持久化与日志：数据库列、本地存储和结构化日志保留十进制字符串，不要让序列化层猜它是普通数字。

TypeScript 的品牌类型值得留下。普通 string 仍可能混入其他字符串，而 TaskIdStr 会把边界写清：这个值只能来自 task_id_str 字段。类型不能代替运行时校验，却能在改代码时，先把不少岔路拦在编译阶段。

团队若正在梳理完整异步链路，可先看GPT Image 2 的三种典型工作流里“提交、等待、精修、交付”的位置关系，再把任务 ID 契约安到每个交接点上。

Q：URL 和 queryKey 里临时转成数字可以吗？

“只是临时”不能成为安全理由。精度丢失就在转换那一刻发生，与这个数字存了多久无关。下面这种写法，即便下一行立刻转回字符串，错也已经落笔：

const id = String(Number(taskIdStr)); // 错：先舍入，再变回字符串

URL 路径参数本就是文本，直接编码字符串即可。queryKey 只需稳定区分缓存对象，也用不着数值运算。状态仓库若为了“统一类型”把所有 ID 都声明成 number，该改的是仓库模型，不该让正确数据迁就错误模型。

JSON 边界也要留神。若某个中间服务把 19 位整数作为 JSON 数字发给浏览器，JSON.parse 完成之时，精度可能已经散失。前端无法由那个数字倒推出原值。接口合同应直接发送带引号的十进制字符串，浏览器收到后一路沿用。

Q：多图任务和取消任务该用哪个字段？

多图任务不可只盯顶层字段。当前合同中，每个子任务都有自己的 tasks[].task_id_str；列表位置、结果图和后续状态，都应依对应子任务的字符串 ID 关联。若把多个子任务的数字 ID 放进 Set<number> 或对象键，两个不同长整数经舍入后可能碰撞，排查时便如双线缠结，难分来路。

取消请求也沿用 task_id_str。仓库合同明确写着，JavaScript 客户端只发送字符串字段，服务端走到数据库查询边界时再解析为整数。分工由此清楚：网络与前端逐字守存，真正需要整数查询的服务端，则在可控边界完成转换。

await cancelTask({ task_id_str: taskId });

这里同样不能从 task_id 生成字符串。String(response.task_id) 不过是给可能已经舍入的值添上引号，并不等于拿到了 task_id_str。

Q：旧数据已经存成 Number，怎样补救？

先看权威副本是否还在。按下面的次序循线寻找，位置越靠前，凭据越可靠：

• 原始接口响应或网络日志里的 task_id_str；
• 服务端任务记录中的完整 ID；
• 同一提交保存的 client_task_id、时间范围与业务上下文，用于在服务端重新定位；
• 仍保留字符串 ID 的任务列表或详情响应。

找到之后，用权威字符串回填旧记录，读写两端也要同时改成字符串。若只改数据库列类型，客户端却依旧执行 Number(id)，旧患仍会卷土重来。

若只剩一个已经舍入的 JavaScript 数字，不可猜末位，也不可批量加减 1 试探。相邻候选可能不止一个，偶然猜中，也不等于可审计。应先把这条记录标成待重新关联，再回到服务端记录核对；实在无法确认，宁可让用户重新进入任务列表，也不要把结果系在不确定的任务上。

图注：舍入后的数字不能逆推末位，只能回到权威字符串记录。

修复完成后，再做一个小型回归：选一条明确大于安全整数上限的测试 ID，沿响应、状态仓库、本地持久化、URL、queryKey 和取消请求逐段比对，要求每一段的字符完全一致。这里比的是字符串逐字相等，不是数值相等。

Q：这类问题和出图失败是一回事吗？

不是。ID 精度问题落在“客户端怎样找到任务”这一层，模型出图失败则发生在任务本身。两者表面上都可能是“没拿到图”，诊断章法却不同。

先核对提交响应里的 task_id_str，看它与详情请求、缓存键和日志是否逐字一致。不一致，先修标识链路；一致，再查任务状态、错误字段和结果地址。按这个次序走，可免去模型已经完成、客户端却因查错 ID 而反复提交的弯路，也不会平白增加任务与积分记录。

至于图片本身的比例错配、商品变形或边缘伪影，那是另一套诊断脉络。可继续阅读GPT Image 2 常见问题与修复路径，画质问题与任务标识问题，不宜混在同一轮排查里。

这条规矩收拢起来并不繁复：后端给出 task_id_str，前端便让它以字符串走完全程。若还要补齐模型能力边界，可参考GPT Image 2 能做什么、做不到什么。先把编号守真，再谈状态与画面；次序端正，岔路自然少许多。