面向開發者的 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 金鑰。金鑰儲存在外掛設定中，而非程式碼裡。