# အထောက်အထားအတည်ပြုခြင်း

မော်ဒယ်တစ်ခုကို လုပ်ဆောင်ခြင်း သို့မဟုတ် သင့်တောင်းဆိုချက်များကို ဖတ်ရှုခြင်း ပြုလုပ်သည့် ခေါ်ဆိုမှုတိုင်းတွင် API ကီး လိုအပ်သည်။ ကတ်တလောက် (`GET /models`,
`GET /categories`), `POST /quote` နှင့် OpenAPI စာရွက်စာတမ်းတို့သည် အများပြည်သူသုံး ဖြစ်သည်။

## API ကီးများ

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) တွင် ကီးများကို ဖန်တီးပြီး ရုပ်သိမ်းနိုင်သည်။ ကီးတစ်ခုသည် `doitong_` နောက်တွင် ဆက်ပါလာသော
hex အက္ခရာ 64 လုံးဖြစ်ပြီး ဖန်တီးချိန်တွင် တစ်ကြိမ်သာ ပြသသည်။ ၎င်းကို `Authorization` ခေါင်းစီးတွင် ပို့ပါ:

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

`X-API-Key: <key>` ကိုလည်း အသုံးပြုနိုင်သည်။

> [!WARNING]
> ကီးများကို သင့်ဆာဗာပေါ်တွင်သာ ထားပါ: ကီးရှိသူတိုင်းသည် ခွင့်ပြုထားသည့် API ခရက်ဒစ်များကို သုံးစွဲနိုင်သည်။ ကီးပေါက်ကြားပါက
> ၎င်းကို ရုပ်သိမ်းပြီး အသစ်တစ်ခု ဖန်တီးပါ။

ကီးမပါသော တောင်းဆိုချက်သည် `missing_api_key` ကုဒ်ဖြင့် `401` ရရှိသည်။ မသိရှိသော၊ ရုပ်သိမ်းထားသော သို့မဟုတ် သက်တမ်းကုန်ဆုံးသော ကီးသည်လည်း `401` ရရှိသည်။

## အကျုံးဝင်ခွင့်များ

ကီးတစ်ခုစီတွင် အကျုံးဝင်ခွင့်များ ပါဝင်သည်။ မော်ဒယ် API သည် အောက်ပါတို့ကို စစ်ဆေးသည်:

| လုပ်ဆောင်ချက် | လိုအပ်သော အကျုံးဝင်ခွင့် |
|---|---|
| မော်ဒယ်ကို လုပ်ဆောင်ခြင်း၊ တောင်းဆိုချက်ကို ပယ်ဖျက်ခြင်း၊ တောင်းဆိုချက်၏ ဖိုင်များကို ဖျက်ခြင်း၊ သိုလှောင်မှု ဆက်တင်ကို ပြောင်းလဲခြင်း | `models:run` (အဟောင်း `images:create` သို့မဟုတ် `videos:create` ပါသော ကီးများလည်း အလုပ်လုပ်သည်) |
| အပ်လုဒ် URL ဖန်တီးခြင်း | `models:run` သို့မဟုတ် `media:upload` |
| တောင်းဆိုချက်များနှင့် အကောင့်ကို ဖတ်ရှုခြင်း | `models:read` (မော်ဒယ်များကို လုပ်ဆောင်နိုင်သော ကီးသည်လည်း ဖတ်ရှုနိုင်သည်) |

ကီးအသစ်များတွင် မူလတန်ဖိုးအဖြစ် `models:read` နှင့် `models:run` ပါရှိသည်။ မှန်ကန်သော အကျုံးဝင်ခွင့်မပါသော ခေါ်ဆိုမှုသည် `insufficient_scope` ကုဒ်ဖြင့်
`403` ရရှိသည်။

## ခရက်ဒစ် ဘတ်ဂျက်များ

အကောင့်ပိုင်ရှင်က သတ်မှတ်ထားသည့် API ခရက်ဒစ် (၁,၀၀၀ API ခရက်ဒစ် = ၁ $) အတွင်း ကီးတစ်ခုစီတွင် ကိုယ်ပိုင် ဘတ်ဂျက် ရှိနိုင်သည်: စုစုပေါင်း ဘတ်ဂျက်၊
နေ့စဉ်ဘတ်ဂျက် (နောက်ဆုံး 24 နာရီ) သို့မဟုတ် နှစ်မျိုးစလုံး ဖြစ်နိုင်သည်။ လုပ်ဆောင်မှုတစ်ခုအတွက် ကုန်ကျစရိတ် ကောက်ခံခြင်းမပြုမီ၊ ဤ API မှတစ်ဆင့် ကီးက သုံးစွဲပြီးသားပမာဏနှင့်
ငွေပြန်အမ်းမှုများကို နှုတ်ပြီးနောက် ကျန်ရှိသည့် ပမာဏနှင့် ကုန်ကျစရိတ်ကို စစ်ဆေးသည်။ သတ်မှတ်ထားသည့် ပမာဏကို ကျော်လွန်မည့် လုပ်ဆောင်မှုကို `402 budget_exceeded` ဖြင့် ငြင်းပယ်ပြီး
မည်သည့်ပမာဏမျှ ကောက်ခံမည်မဟုတ်ပါ။

> [!IMPORTANT]
> ဘတ်ဂျက်ကြောင့် ငြင်းပယ်ခံရမှုသည် အပြီးသတ်ဖြစ်သည်: ပိုင်ရှင်က ဘတ်ဂျက်ကို မြှင့်မပေးမချင်း ထပ်မံကြိုးစားခြင်းဖြင့် အဆင်ပြေမည်မဟုတ်ပါ။

 ဘတ်ဂျက်မရှိသော ကီးတစ်ခုသည်
API လက်ကျန်အထိ သုံးစွဲနိုင်သည်။ သီးခြားအနေဖြင့် API လက်ကျန်က မကာမိနိုင်သော လုပ်ဆောင်မှုတစ်ခုသည် `top_up_url` ပါရှိသည့်
`402 insufficient_credits` ရရှိသည်။

`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 အချိန် |

ကန့်သတ်ချက်ကျော်လွန်ပါက `Retry-After` ခေါင်းစီး (စက္ကန့်) ပါရှိသည့် `429` ရရှိသည်။ `?wait=` ဖြင့် ကြာရှည်စောင့်ကြည့်ခြင်းကို ခေါ်ဆိုမှုတစ်ခုလျှင် တောင်းဆိုချက်တစ်ခုအဖြစ်
တွက်ချက်သောကြောင့် မြန်မြန်ဆန်ဆန် စောင့်ကြည့်ခြင်းထက် စောင့်ဆိုင်းခြင်းက ပိုသက်သာသည်။

အကောင့်တစ်ခုလျှင် လုပ်ဆောင်နေဆဲ (`queued` သို့မဟုတ် `running`) တောင်းဆိုချက် 10 ခုအထိသာ ခွင့်ပြုသည့် ကန့်သတ်ချက်လည်း ရှိသည်။ နောက်ထပ်တစ်ခု စတင်ပါက
`429 too_many_inflight` ပြန်လည်ရရှိမည်ဖြစ်ပြီး တစ်ခု ပြီးဆုံးပြီးနောက် ထပ်မံစတင်ပါ။