> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agicto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 排查 AGICTO API 调用中的认证、余额、限速和任务问题

当请求失败时，先按下面顺序检查。这样通常能最快定位问题。

## 请求无法认证

确认请求 Header 使用 Bearer Token。

```http theme={null}
Authorization: Bearer $API_KEY
```

常见原因：

* API Key 为空、复制不完整或包含多余空格
* Header 写成了 `Token`、`Basic` 或其他格式
* 在 OpenAI SDK 中仍然使用旧的环境变量
* 在浏览器前端直接暴露 API Key

## Base URL 错误

AGICTO API 的 Base URL 是：

```text theme={null}
https://api.agicto.cn/v1/
```

直接复制控制台里显示的 Base URL。不要漏写 `/v1`，也不要重复写成 `/v1/v1`。

## 余额或额度不足

调用前可以查询账户余额。

```bash theme={null}
curl https://api.agicto.cn/v1/enterprise/account \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "uuid": "YOUR_ACCOUNT_UUID"
  }'
```

查看接口细节：<a href="/api-reference/account/balance">账户余额查询</a>

## 模型名不可用

确认 `model` 使用的是你账户支持的模型名。不同接口支持的模型不同，例如：

* Chat completions 使用会话模型
* Embeddings 使用嵌入模型
* Images 使用图片模型
* Videos 使用视频模型

如果你从其他平台迁移，先替换模型名，再复用原来的请求结构。

## 视频任务没有结果

视频任务需要轮询状态。创建任务后，保存响应中的 `id`，再调用查询接口。

```bash theme={null}
curl https://api.agicto.cn/v1/videos/{id} \
  -H "Authorization: Bearer $API_KEY"
```

如果任务还在处理中，请等待后重试。不要在短时间内过高频率轮询。

## 请求体格式不匹配

不同接口使用不同 Content-Type：

| 场景            | Content-Type          |
| ------------- | --------------------- |
| 聊天、嵌入、图片、工具   | `application/json`    |
| OpenAI 兼容视频创建 | `multipart/form-data` |
| 文件或参考图上传      | `multipart/form-data` |

如果你收到参数缺失或解析失败，先检查请求体格式。