# 账户、权限与更新

## 查询余额和消耗

| 要查什么 | MCP | 使用 API Key 的 REST | CLI |
| --- | --- | --- | --- |
| 可用美元、预留金额和资金分类 | `get_account` | `GET /api/v1/account` | `balance --json` |
| 结算费用、用量退款和每日净消耗 | `get_usage` | `GET /api/v1/account/usage?range=30d` | `usage --range 30d --json` |

余额和消耗覆盖凭据所属的整个账户，包括 Studio、REST 和 MCP 的活动。同一账户下的多个 API Key 查询相同区间时，会返回相同的总额。`get_account` 还返回 `scopes`。消耗区间可选 `today`、`yesterday`、`7d`、`30d` 或 `90d`，默认 `30d`。区间按 UTC 入账日期计算，结束时间不包含在区间内，近 N 天包含今天已过去的时间。所有金额为八位小数的美元字符串。

净消耗 `net` 等于结算费用 `charged` 减去用量退款 `refunded`，再加上已核实历史净额 `historicalNet`。退款和原扣款可能在不同日期入账，因此某个区间的净消耗可能为负。未结算的预留金额见余额接口。`daily` 包含有入账记录的日期。

在[开发者控制台](/settings/developer)查看任务、账本、付款凭证、素材和回调，也可以启动异步加密导出。导出文件的下载链接需要登录且五分钟后失效，单次导出最多 10,000 条，记录较多时可缩小筛选范围。付款记录为本账户的收据。

## 检查权限与撤销连接

`mcp:read` 可查目录、报价、账户和任务。`mcp:write` 还可上传与提交。客户端需发起写权限申请，用户需在授权页同意。首次生成前，用 `get_account.scopes` 确认权限。客户端无法申请写权限时，可选支持 [API Key](/docs/mcp/api-key) 的接入方式，或使用[本地 stdio](/docs/mcp/local-stdio)。

在[连接管理](/settings/connections)选择对应客户端并撤销 OAuth，相关 access token 和 refresh token 会失效。按需在客户端移除或停用配置。API Key 在[密钥设置](/me?section=api-keys)独立管理。先前已受理的任务会继续运行，再次提交前先检查该任务的记录。

## 排查连接

| 现象 | 检查方法 |
| --- | --- |
| HTTP `401` | 核对地址，重新授权 OAuth 或检查 API Key 是否有效。 |
| 使用 API Key 时收到 HTTP `403` | 对照 IP 白名单和客户端实际来源 IP。 |
| 上传或生成时出现 `insufficient_scope` | 重新授权写权限并查看 `get_account.scopes`。[Codex](/docs/mcp/codex-cli)和 [Claude Code](/docs/mcp/claude-code)指南有明确的权限配置示例。 |
| HTTP `429` | 有 `Retry-After` 时按其等待。提交是否受理不明确时，使用原幂等键恢复。 |
| 工具清单里没有 `get_usage` 或其他新工具 | 刷新远程工具清单或重新连接。本地 stdio 可用 `doctor` 核对版本，更新后重启。 |

## 检查版本与安装更新

```bash
node i2v-cli.mjs doctor --json
```

`doctor` 读取公开发布清单，比较 CLI 版本，并在脚本同包安装时检查 `i2v-models` 的版本。配置 `I2V_API_KEY` 后还会检查远程 MCP 版本，并列出缺少的工作流工具。本地 stdio 建立连接时会检查更新，并可把提示交给客户端。远程 MCP 由 i2v.ai 部署更新。客户端仍显示旧工具时，可刷新工具清单或重新连接。

### 检查和更新已安装的 Skill

通过新版 [Skills CLI](https://www.skills.sh/docs/cli) 安装后，在项目目录运行下面的命令。第一条检查可用更新，第二条按记录的原来源更新指定 Skill，适用于 GitHub 和 i2v.ai 官网安装。

```bash
npx skills@latest check --project
npx skills@latest update i2v-models i2v-integrate --project
```

如果原来是全局安装，把 `--project` 换成 `--global`。更新时填入已安装的 Skill 名称。检查显示来源错误或安装记录缺少来源时，可用[原安装命令](/zh/cli)，沿用原来的范围和客户端。Claude Code 插件包按[插件更新说明](/zh/docs/mcp/claude-code)操作。

单独下载的 CLI 可按需[重新下载脚本](/cli/i2v-cli.mjs)并替换本地文件。替换脚本后重启本地 stdio。

## 保护凭据和素材

通过客户端密钥存储或进程环境提供密钥。OAuth 权限与 i2v.ai MCP 资源绑定，i2v.ai 以哈希存储令牌和授权码。客户端只能访问经授权账户的私有数据。素材保存和删除说明见[数据保留政策](/media-retention)。