面向开发者的 ChatGetz API

快速开始

1. 登录并打开 控制台 → API 密钥。
2. 创建具有所需权限的密钥并复制（仅显示一次）。
3. 在 Authorization 请求头中发送：Bearer cgk_…

curl https://www.chatgetz.uz/api/v1/account/balance \
  -H "Authorization: Bearer $CHATGETZ_API_KEY"

curl https://www.chatgetz.uz/api/v1/ai/generate \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6f5e-order-42" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "prompt": "Write a 60-word description for a cotton kids hoodie",
    "instructions": "Answer in Uzbek (Latin script)."
  }'

身份验证与权限

每个请求都需要在 Authorization: Bearer cgk_…（或 X-API-Key）请求头中携带个人 API 密钥。每个密钥有独立的权限（scopes）和限速，并可随时撤销。

请将密钥保存在您的服务器或插件设置中，切勿放在公开的前端代码里。ChatGetz 仅保存每个密钥的 SHA-256 哈希值。

限制与价格

• Global Pro：API 请求不限次数。
• Basic：每月 1,000 次请求（每月 1 日按塔什干时间重置）。
• 未选择套餐的账户无法使用 API。
• 每个密钥都有独立限速（每分钟 10–120 次请求）。超出限制时，API 返回 429 并附带 Retry-After 请求头。
• AI 文本生成按公开价目表计费：先从每月 AI 额度扣除，再从 ChatGetz 余额扣除。
• 在 AI 请求中发送 Idempotency-Key 请求头：使用相同键重试的请求绝不会重复扣费。

接口

• get/api/v1/account/balance套餐、余额、内含 AI 额度和 API 配额account:read
• get/api/v1/models文本模型及其对您密钥的可用性ai:generate
• post/api/v1/ai/generate生成文本；从余额扣费（优先使用内含额度）ai:generate
• get/api/v1/market/listings您在 ChatGetz Market 的信息market:read
• post/api/v1/market/listings在 Market 创建信息（默认为草稿）market:write
• post/api/v1/ingest/events接收来自插件的订单或潜在客户（webhook）ingest:write
• get/api/v1/openapi.json本 API 的 OpenAPI 3.1 规范

插件将新订单和潜在客户推送到 POST /api/v1/ingest/events。以相同的 source、type 和 externalId 重复发送事件是安全的：只会保存一次。

curl https://www.chatgetz.uz/api/v1/ingest/events \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order", "source": "woocommerce", "externalId": "1042",
    "customer": { "name": "Aziza", "phone": "+998901234567" },
    "total": { "amount": "249000", "currency": "UZS" },
    "items": [{ "name": "Hoodie", "quantity": 1, "price": "249000" }]
  }'

错误

错误以 JSON 返回，包含稳定的机器可读代码和英文消息。请基于代码构建您的集成。

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly Basic API quota exhausted. ..."
  }
}

插件

所有插件均为开源（兼容 GPL），并使用您的 API 密钥。密钥保存在插件设置中，而非代码里。