Kunci API

Kaedah, medan permintaan dan respons.

Panduan lengkap

Bahagian ini mengandungi 5 kaedah. Buka kaedah untuk melihat syarat akses, medan permintaan dan respons.

Kaedah dan laluan	Penerangan	Akses
`GET /api/v1/keys`	Senarai — kunci API	Token panel pengguna
`POST /api/v1/keys`	Penciptaan kunci API	Token panel pengguna
`DELETE /api/v1/keys/:id`	Pemadaman — kunci API	Token panel pengguna
`GET /api/v1/keys/:id`	Dapatkan mengikut pengecam — kunci API	Token panel pengguna
`PUT /api/v1/keys/:id`	Pengubahan kunci API	Token panel pengguna

GET /api/v1/keys — Senarai — kunci API

Akses: Token panel pengguna

GET/api/v1/keys

Baca sahaja; ID diambil daripada respons anda yang terdahulu

curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

Parameter pertanyaan

Medan	Jenis	Wajib	Pengesahan / penerangan
`sort_by`	`string`	tidak	; nilai lalai: created_at
`sort_order`	`string`	tidak	; nilai lalai: desc
`search`	`string`	tidak
`status`	`string`	tidak
`page`	`integer`	tidak	; nilai lalai: 1; positive; page_size/limit <=1000
`page_size`	`integer`	tidak	; nilai lalai: 20; positive; page_size/limit <=1000
`limit`	`integer`	tidak	; nilai lalai: 20; positive; page_size/limit <=1000

Badan permintaan tidak diperlukan. Hantar parameter yang dinyatakan di atas dalam URL.

Respons

Respons JSON mengandungi code, message dan data. Kandungan data diterangkan dalam skema di bawah.

Skema data respons: APIKey. Medan dan jenisnya terdapat pada halaman “Skema data”.

Skema respons, nilai hanyalah contoh

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Nota khusus: Semua data peribadi dan objek dihadkan kepada subjek JWT.

Nota khusus: Respons mengandungi key rahsia; jangan dedahkan nilai sebenar.

POST /api/v1/keys — Penciptaan kunci API

Akses: Token panel pengguna

POST/api/v1/keys

Medan JSON / borang

Medan	Jenis	Wajib	Pengesahan / penerangan
`name`	`string`	ya	required
`custom_key`	`string`	tidak	; Nilai kunci tersuai pilihan; boleh bernilai null
`ip_whitelist`	`array`	tidak	; Senarai IP yang dibenarkan
`ip_blacklist`	`array`	tidak	; Senarai IP yang disekat
`quota`	`number`	tidak	; Had perbelanjaan kunci dalam USD; boleh bernilai null
`expires_in_days`	`integer`	tidak	; Tempoh sah dalam hari; boleh bernilai null
`rate_limit_5h`	`number`	tidak	; boleh bernilai null
`rate_limit_1d`	`number`	tidak	; boleh bernilai null
`rate_limit_7d`	`number`	tidak	; boleh bernilai null

Templat badan permintaan

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

PLACEHOLDER mewakili input anda dan jenisnya. Gantikan nilai dan kekalkan hanya medan pilihan yang diperlukan; penanda rentetan tidak boleh dihantar sebagai ganti nombor, boolean, objek atau tatasusunan.

Skema permintaan: CreateAPIKeyRequest

Respons

Respons JSON mengandungi code, message dan data. Kandungan data diterangkan dalam skema di bawah.

Skema data respons: APIKey. Medan dan jenisnya terdapat pada halaman “Skema data”.

Skema respons, nilai hanyalah contoh

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Nota khusus: Semua data peribadi dan objek dihadkan kepada subjek JWT.

Nota khusus: Operasi mengubah keadaan atau meneruskan pengesahan sekali guna; contoh ini menerangkan kontrak dan tidak dijalankan.

Nota khusus: Idempotency-Key disokong; penghantaran semula mengembalikan respons yang disimpan dengan X-Idempotency-Replayed.

Nota khusus: Respons mengandungi key rahsia; jangan dedahkan nilai sebenar.

DELETE /api/v1/keys/:id — Pemadaman — kunci API

Akses: Token panel pengguna

DELETE/api/v1/keys/:id

Parameter laluan

Medan	Jenis	Wajib	Pengesahan / penerangan
`id`	`integer`	ya

Badan permintaan tidak diperlukan.

Respons

Respons JSON mengandungi code, message dan data. Kandungan data diterangkan dalam skema di bawah.

Skema respons, nilai hanyalah contoh

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

Nota khusus: Semua data peribadi dan objek dihadkan kepada subjek JWT.

Nota khusus: Operasi mengubah keadaan atau meneruskan pengesahan sekali guna; contoh ini menerangkan kontrak dan tidak dijalankan.

Nota khusus: Respons mengandungi key rahsia; jangan dedahkan nilai sebenar.

GET /api/v1/keys/:id — Dapatkan mengikut pengecam — kunci API

Akses: Token panel pengguna

GET/api/v1/keys/:id

Baca sahaja; ID diambil daripada respons anda yang terdahulu

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

Parameter laluan

Medan	Jenis	Wajib	Pengesahan / penerangan
`id`	`integer`	ya

Badan permintaan tidak diperlukan. Hantar parameter yang dinyatakan di atas dalam URL.

Respons

Respons JSON mengandungi code, message dan data. Kandungan data diterangkan dalam skema di bawah.

Skema data respons: APIKey. Medan dan jenisnya terdapat pada halaman “Skema data”.

Skema respons, nilai hanyalah contoh

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Nota khusus: Semua data peribadi dan objek dihadkan kepada subjek JWT.

Nota khusus: Respons mengandungi key rahsia; jangan dedahkan nilai sebenar.

PUT /api/v1/keys/:id — Pengubahan kunci API

Akses: Token panel pengguna

PUT/api/v1/keys/:id

Parameter laluan

Medan	Jenis	Wajib	Pengesahan / penerangan
`id`	`integer`	ya

Medan JSON / borang

Medan	Jenis	Wajib	Pengesahan / penerangan
`name`	`string`	tidak
`status`	`string`	tidak	omitempty,oneof=active inactive
`ip_whitelist`	`array`	tidak	; IP yang dibenarkan: null tidak mengubah senarai, tatasusunan kosong mengosongkannya; boleh bernilai null
`ip_blacklist`	`array`	tidak	; IP yang disekat: null tidak mengubah senarai, tatasusunan kosong mengosongkannya; boleh bernilai null
`quota`	`number`	tidak	; Had perbelanjaan kunci dalam USD; 0 — tanpa had; boleh bernilai null
`expires_at`	`string`	tidak	; Masa tamat tempoh dalam format ISO 8601; boleh bernilai null
`reset_quota`	`boolean`	tidak	; Tetapkan semula bahagian had perbelanjaan yang sudah digunakan; boleh bernilai null
`rate_limit_5h`	`number`	tidak	; boleh bernilai null
`rate_limit_1d`	`number`	tidak	; boleh bernilai null
`rate_limit_7d`	`number`	tidak	; boleh bernilai null
`reset_rate_limit_usage`	`boolean`	tidak	; Tetapkan semula penggunaan had mengikut tetingkap masa; boleh bernilai null

Templat badan permintaan

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

Skema permintaan: UpdateAPIKeyRequest

Respons

Respons JSON mengandungi code, message dan data. Kandungan data diterangkan dalam skema di bawah.

Skema data respons: APIKey. Medan dan jenisnya terdapat pada halaman “Skema data”.

Skema respons, nilai hanyalah contoh

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Nota khusus: Semua data peribadi dan objek dihadkan kepada subjek JWT.

Nota khusus: Operasi mengubah keadaan atau meneruskan pengesahan sekali guna; contoh ini menerangkan kontrak dan tidak dijalankan.

Nota khusus: Respons mengandungi key rahsia; jangan dedahkan nilai sebenar.

Nota khusus: Selagi kunci mempunyai permintaan yang belum selesai dengan rizab, had perbelanjaannya tidak boleh dikurangkan atau ditetapkan semula. Hantar hanya medan yang anda ubah.

Masih ada soalan? Hantar Request ID dan penerangannya — kami akan membantu menyiasatnya.Hubungi sokongan