面向開發者的 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 密鑰。密鑰保存在插件設定中，而非代碼裏。