# 认证与请求约定

## API Key

使用 Authorization 请求头，密钥只保存在自己的服务端或 Agent 配置中。

```http
Authorization: Bearer YOUR_JISU_API_KEY
Content-Type: application/json
```

密钥权限分为 read 和 create。撤销后不能新建任务，已有任务继续由服务端收尾。

## 幂等请求

创建任务时必须提供 8 至 150 字符的 Idempotency-Key。同一键、相同请求恢复原任务；同一键、不同参数返回 409。

## 金额

所有用户金额使用 CNY 十进制字符串，最多六位小数。不要用二进制浮点运算计算账单。

## 请求追踪

响应中的 X-Request-Id 可以在开发页调用记录中查询。反馈问题时附上 request_id 或 task_id，不要发送完整密钥。

## 配置 API 地址

以下 shell 示例使用当前环境地址。将占位密钥替换为控制台创建的凭证；不要把实际值提交到代码仓库。

```sh
export JISU_API='https://api.jisu.fun'
export JISU_KEY='YOUR_JISU_API_KEY'

curl --fail-with-body "$JISU_API/v1/wallet" \
  -H "Authorization: Bearer $JISU_KEY"
```

## 调用记录与任务费用

在控制台的开发页查看调用记录，可按请求 ID、任务 ID、MCP 工具名和错误码搜索。记录关联的任务费用随结算与退款更新，显示预留或实付 CNY；多条记录可能指向同一任务，不应累加这些费用判断总支出，汇总应以账单为准。删除作品仍保留对应账单关联。

MCP 的 HTTP 200 只表示传输成功。工具返回 isError 时，记录会显示对应错误码，并归入“工具调用失败”。旧版未记录执行结果的 MCP 请求标为“工具结果未记录”，不能据此判断创作成功。未知 API 路径返回 HTTP 404 与 NOT_FOUND。

调用记录不保存请求正文、提示词、上传令牌或供应商凭证；反馈问题时提供 Request ID 即可。

## 公开目录请求

模型与价格目录无需认证。空 data 数组表示当前没有已发布模型，不能自行补造模型 ID。

```sh
curl --fail-with-body 'https://api.jisu.fun/v1/models'
```