# การยืนยันตัวตน

ทุกการเรียกใช้ที่รันโมเดลหรืออ่านคำขอของคุณต้องใช้คีย์ API แค็ตตาล็อก (`GET /models`,
`GET /categories`), `POST /quote` และเอกสาร OpenAPI เป็นสาธารณะ

## คีย์ API

สร้างและเพิกถอนคีย์ได้ที่ [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) คีย์จะมีลักษณะ
aคือ `doitong_` ตามด้วยอักขระฐานสิบหก 64 ตัว และจะแสดงเพียงครั้งเดียวเมื่อสร้าง ส่งคีย์ใน
ส่วนหัว `Authorization`:

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

`X-API-Key: <key>` ก็ใช้ได้เช่นกัน

> [!WARNING]
> เก็บคีย์ไว้บนเซิร์ฟเวอร์ของคุณ: ใครก็ตามที่มีคีย์สามารถใช้เครดิต API ที่คีย์นั้นได้รับอนุญาตให้ใช้ได้ หากคีย์รั่วไหล
> ให้เพิกถอนคีย์นั้นและสร้างคีย์ใหม่

คำขอที่ไม่มีคีย์จะได้รับ `401` พร้อมโค้ด `missing_api_key`; คีย์ที่ไม่รู้จัก ถูกเพิกถอน หรือหมดอายุก็จะได้รับ `401` เช่นกัน

## ขอบเขต

คีย์แต่ละรายการจะมีขอบเขต API โมเดลจะตรวจสอบขอบเขตเหล่านี้:

| การดำเนินการ | ขอบเขตที่ต้องใช้ |
|---|---|
| รันโมเดล ยกเลิกคำขอ ลบไฟล์ของคำขอ เปลี่ยนการตั้งค่าพื้นที่จัดเก็บ | `models:run` (คีย์ที่มี `images:create` หรือ `videos:create` รุ่นเก่าก็ใช้ได้เช่นกัน) |
| สร้าง URL สำหรับอัปโหลด | `models:run` หรือ `media:upload` |
| อ่านคำขอและบัญชี | `models:read` (คีย์ที่รันโมเดลได้ก็อ่านได้เช่นกัน) |

คีย์ใหม่จะได้รับ `models:read` และ `models:run` เป็นค่าเริ่มต้น การเรียกใช้ที่ไม่มีขอบเขตที่ถูกต้องจะได้รับ `403` พร้อมโค้ด
`insufficient_scope`

## งบประมาณเครดิต

คีย์สามารถมีงบประมาณของตัวเองเป็นเครดิต API (1,000 เครดิต API = $1) ซึ่งเจ้าของบัญชีกำหนดได้ ได้แก่ งบประมาณรวม งบประมาณรายวัน (ย้อนหลัง 24 ชั่วโมง) หรือทั้งสองอย่าง ก่อนเรียกเก็บค่าใช้จ่ายของการรัน ระบบจะตรวจสอบค่าใช้จ่ายเทียบกับจำนวนที่คีย์ใช้ไปแล้วผ่าน API นี้ (หักยอดคืนเงินแล้ว) การรันที่ทำให้เกินงบประมาณจะถูกปฏิเสธด้วย `402 budget_exceeded` และจะไม่มีการเรียกเก็บเงิน

> [!IMPORTANT]
> การปฏิเสธเนื่องจากงบประมาณถือเป็นที่สิ้นสุด: การลองใหม่จะไม่ช่วยจนกว่าเจ้าของจะเพิ่มงบประมาณ

 คีย์ที่ไม่มีงบประมาณสามารถใช้จ่ายได้สูงสุดเท่ายอดคงเหลือ API แยกกันนั้น การรันที่ยอดคงเหลือ API ไม่เพียงพอจะได้รับ `402 insufficient_credits`
พร้อม `top_up_url`

`GET https://api.doitong.com/v1/account` แสดงยอดคงเหลือ API และงบประมาณที่เหลือของคีย์ (ทั้งสองค่าเป็นเครดิต API):

```json 200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}
```

`budget_remaining` จะเป็น `null` เมื่อคีย์ไม่มีงบประมาณของตัวเอง

## ขีดจำกัดอัตราการใช้งาน

คีย์แต่ละรายการส่งคำขอได้ 3600 คำขอต่อชั่วโมง เว้นแต่จะกำหนดขีดจำกัดไว้แตกต่างกัน การตอบกลับที่ผ่านการยืนยันตัวตนทุกครั้งจะมี
สถานะปัจจุบัน:

| ส่วนหัว | ความหมาย |
|---|---|
| `X-RateLimit-Limit` | จำนวนคำขอที่อนุญาตในช่วงเวลาปัจจุบัน |
| `X-RateLimit-Remaining` | จำนวนคำขอที่เหลือในช่วงเวลาปัจจุบัน |
| `X-RateLimit-Reset` | เวลา Unix ที่ช่วงเวลาจะรีเซ็ต |

เมื่อเกินขีดจำกัด คุณจะได้รับ `429` พร้อมส่วนหัว `Retry-After` (วินาที) การโพลระยะยาวด้วย `?wait=` จะนับเป็นหนึ่งคำขอ
ต่อการเรียกใช้ ดังนั้นการรอจึงประหยัดกว่าการโพลถี่ ๆ

นอกจากนี้ แต่ละบัญชียังมีขีดจำกัดคำขอที่กำลังดำเนินการอยู่ (`queued` หรือ `running`) 10 คำขอ การเริ่มเพิ่มอีกหนึ่งคำขอจะส่งคืน
`429 too_many_inflight`; ให้เริ่มใหม่หลังจากมีคำขอหนึ่งรายการเสร็จสิ้น