# 调试指南

1. **Invalid TaskId 错误**
**原因：** 任务一旦超过保留期限，之后再查状态就会返回 InvalidTaskId 错误。想避开这个问题，请在启动 AI 任务后配置 webhook 或实现轮询，并在保留期内持续盯它的状态，直到进入 success 或 error 这两个终态之一。
**解决办法：** 别让任务过期。在保留期内写一个轮询循环，按固定间隔检查任务状态。
2. **调用 AI 接口时出现 404 Not Found 错误**
**答：** ***重点***：只调用 File API 并不会把文件上传上去。您必须亲手把文件传到 File API 响应里给出的那个 URL。那个 URL 就是上传地址，务必确认文件已经成功传过去，再进行下一步。
调用 AI 接口之前，请确认文件已经上传成功。先用 File API 取到一个上传地址，再把文件传到那个位置。上传完成后，响应里会给您一个 ***file_id***，后续访问与该文件相关的 AI 功能，用的就是这个 ID。
3. **在 Postman 里拿到的 API 响应，样式 ID 都一样**
**答：** 这是因为 Postman（Pretty view）和 Chrome 都用 JavaScript 解析 JSON 响应。在 JavaScript 里，大于 9007199254740991（2^53-1）的数字无法精确表示，会被四舍五入到最接近的可表示值，于是不同的 ID 看起来就一模一样了（例如 219691778809271815 → 219691778809271800）。
  * JavaScript/JSON 处理中的精度丢失
    * 原因：JavaScript 的 Number 类型无法安全处理超过 2^53 - 1 的整数，会静默截断或四舍五入。
    * 解决办法：使用 ***json-bigint*** 这类 JSON 解析器，把 ID 当字符串处理，完整保留精度。
4. **胡子（Beard）接口出现鉴权 400 错误**
**答：** 使用 V2 API 时，每个请求都必须带上 API 密钥，也就是加上 Bearer 授权头。没带上就会报鉴权错误。
**合法的请求头格式**

```
Authorization: Bearer YOUR_API_KEY
```
**常见问题**
  1. **漏掉 Bearer 前缀**
`Authorization` 头必须以 `Bearer` 开头，后面跟 API 密钥。
反例：

```
Authorization: YOUR_API_KEY
```
  2. **多带了没用的字符**
API 密钥两侧不要加尖括号 `<` 或 `>`。这些字符不是必需的，加上请求就会失败。
反例：

```
Authorization: Bearer <YOUR_API_KEY>
```
  3. **API 密钥不对**
请确认 `Authorization` 头里给的 API 密钥是正确且仍然有效的。