# တောင်းဆိုချက်များ

တောင်းဆိုချက်တစ်ခုသည် မော်ဒယ်တစ်ခုကို တစ်ကြိမ်ခေါ်ဆိုခြင်း ဖြစ်သည်။ ၎င်းတွင် id (`req_…`), အခြေအနေ၊ API ခရက်ဒစ်ဖြင့် ကုန်ကျစရိတ် (1000 = 1 USD) နှင့် အောင်မြင်ပါက ဖန်တီးထားသော ဖိုင်များ ပါဝင်သည်။ အောက်ပါ Endpoint တိုင်းမှ မော်ဒယ်တိုင်းအတွက် တူညီသော object ကို ပြန်လည်ရရှိသည်။

## မော်ဒယ်ရှာရန်

မော်ဒယ် ၁,၄၉၆ ခုလုံး၏ ကတ်တလောက်သည် အများမြင် JSON ဖြစ်သည် (ကီးမလိုအပ်ပါ)။

```bash
curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"
```

| Query ပါရာမီတာ | အဓိပ္ပာယ် |
|---|---|
| `q` | အမည်၊ id၊ ထုတ်လုပ်သူ သို့မဟုတ် tags တွင် မဖြစ်မနေ ပါဝင်ရမည့် စကားလုံးများ၊ ဥပမာ `kling 3`။ |
| `category` | category id တစ်ခု၊ ဥပမာ `text-to-video` သို့မဟုတ် `upscale`။ `GET https://api.doitong.com/v1/categories` သည် အမျိုးအစား ၂၁ ခုလုံးနှင့် ၎င်းတို့၏ အရေအတွက်များကို စာရင်းပြုစုသည်။ |
| `lab` | မော်ဒယ်၏ ထုတ်လုပ်သူကို အမည် သို့မဟုတ် id ဖြင့် သတ်မှတ်ခြင်း၊ ဥပမာ `Google` သို့မဟုတ် `black-forest-labs`။ |
| `family` | ယခင်အတန်းမှ `family` id တစ်ခု - မော်ဒယ်တစ်ခု၏ မူကွဲအားလုံး (pro, fast, image-to-video, …)။ |
| `mode` | `exact` (ထည့်သွင်းချက်မှ စျေးနှုန်းတွက်ချက်သည်)၊ `measured` (ထည့်သွင်းဖိုင်များ၏ အလျား သို့မဟုတ် အရွယ်အစားမှ)၊ `estimate` (run တစ်ကြိမ်အတွက် ခန့်မှန်းစျေးနှုန်း) သို့မဟုတ် `metered` (အများဆုံး run ကုန်ကျစရိတ်အထိ အမှန်တကယ် အသုံးပြုမှုအလိုက် ကောက်ခံသည်)။ |
| `limit`, `cursor` | စာမျက်နှာအရွယ်အစား (1 မှ 100၊ မူလတန်ဖိုး 50) နှင့် ယခင်စာမျက်နှာ၏ `next_cursor`။ |

အတန်းတိုင်းတွင် `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` နှင့် `price` object ပါဝင်သည်။ [စျေးနှုန်းသတ်မှတ်ခြင်း](https://doitong.com/developers/docs/pricing#price-objects) ကို ကြည့်ပါ။ `GET https://api.doitong.com/v1/models/{model_id}` တွင် ထည့်သွင်းချက်နှင့် ထွက်ရလဒ် JSON Schema အပြည့်အစုံ၊ စံပါရာမီတာအမည်များ၊ စျေးနှုန်းစည်းမျဉ်းများနှင့် နမူနာထည့်သွင်းချက်ကို ထပ်မံပေးသည်။ မသိသော `category` သို့မဟုတ် `mode` သည် `400 invalid_parameter` ဖြစ်သည်။

## မော်ဒယ် run ရန်

```bash
curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'
```

- Body သည် JSON object ဖြစ်သော မော်ဒယ်ထည့်သွင်းချက် ဖြစ်သည်။ မော်ဒယ်စာမျက်နှာတိုင်းတွင် ၎င်း၏ ပါရာမီတာများကို ဖော်ပြထားသည်။
- မည်သည့်အရာမျှ မကောက်ခံမီ ထည့်သွင်းချက်ကို စစ်ဆေးသည်။ မမှန်ကန်သော ထည့်သွင်းချက်သည် ပြဿနာဖြစ်စေသော `param` နှင့်အတူ `422 invalid_input` ကို ပြန်ပေးပြီး ကုန်ကျစရိတ်မရှိပါ။
- `?wait=N` (အများဆုံး 20 စက္ကန့်) သည် တောင်းဆိုချက်ပြီးဆုံးသည်အထိ သို့မဟုတ် အချိန်ကုန်သည်အထိ ခေါ်ဆိုမှုကို ဆိုင်းငံ့ထားသည်။
- `?webhook_url=https://…` သည် တောင်းဆိုချက်ပြီးဆုံးသောအခါ ထို URL သို့ လက်မှတ်ထိုးထားသော POST ပို့သည် ([Webhook များ](https://doitong.com/developers/docs/webhooks) ကို ကြည့်ပါ)။
- `?storage=permanent` သို့မဟုတ် `?storage=temporary` သည် ထွက်ရလဒ်ဖိုင်များကို မည်မျှကြာ သိမ်းဆည်းမည်ကို ရွေးချယ်သည်။ မသတ်မှတ်ပါက အကောင့်ဆက်တင်ကို အသုံးပြုသည် ([ဖိုင်များရှိသည့်နေရာ](#storage) ကို ကြည့်ပါ)။

တောင်းဆိုချက် လုပ်ဆောင်နေဆဲဖြစ်ပါက တုံ့ပြန်ချက်သည် `202 Accepted` ဖြစ်ပြီး၊ wait အတွင်း ပြီးဆုံးပါက (သို့မဟုတ် အောက်တွင် ဖော်ပြထားသည့် replay ဖြစ်ပါက) `200 OK` ဖြစ်သည်။ `Location` နှင့် `Doitong-Request-Id` headers များတွင် တောင်းဆိုချက် URL နှင့် id ပါဝင်သည်။

## အခြေအနေများ

တောင်းဆိုချက် လုပ်ဆောင်မှုအဆင့်များ: `queued` → `running` → `succeeded` | `failed` | `canceled` (final; failed နှင့် canceled များကို ငွေပြန်အမ်းသည်).

| Status | အဓိပ္ပာယ် | Final |
|---|---|---|
| `queued` | လက်ခံပြီး ကောက်ခံထားကာ worker ကို စောင့်နေသည်။ `queue_position` တွင် တန်းစီနေရာကို ပြနိုင်သည်။ | no |
| `running` | မော်ဒယ်က ဖန်တီးနေသည်။ | no |
| `succeeded` | ပြီးဆုံးပြီ။ `outputs` တွင် ဖိုင်များကို စာရင်းပြုစုထားသည်။ | yes |
| `failed` | မော်ဒယ် သို့မဟုတ် ကန့်သတ်ချက်တစ်ခုက ရပ်တန့်စေသည်။ `error` တွင် အကြောင်းရင်းကို ဖော်ပြသည်။ API ခရက်ဒစ်များကို ငွေပြန်အမ်းသည်။ | yes |
| `canceled` | ရလဒ်မထုတ်မီ ပယ်ဖျက်ထားသည်။ API ခရက်ဒစ်များကို ငွေပြန်အမ်းသည်။ | yes |

အချိန်ကန့်သတ်ချက်ထက် ပိုကြာသော တောင်းဆိုချက်သည် `timeout` ကုဒ်ဖြင့် မအောင်မြင်ဘဲ ငွေပြန်အမ်းသည် - ပုံများအတွက် 15 မိနစ်၊ ဗီဒီယိုအတွက် 60 မိနစ်၊ အသံနှင့် အခြားအရာအားလုံးအတွက် 30 မိနစ်။

## တောင်းဆိုချက် object

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

- `outputs` သည် မော်ဒယ်တိုင်းအတွက် တူညီသည် - ဖန်တီးထားသော ဖိုင်တစ်ခုစီအတွက် entry တစ်ခုစီဖြင့် `type` (`image`, `video`, `audio`, `file` သို့မဟုတ် `3d`), ကျွန်ုပ်တို့၏ သိုလှောင်မှုရှိ `url`, `content_type` နှင့် သိရှိပါက `file_size`, `width`, `height`, `duration` တို့ ပါဝင်သည်။
- `output` သည် မော်ဒယ်၏ ကိုယ်ပိုင်ရလဒ် object ဖြစ်ပြီး (၎င်း၏ fields များကို မော်ဒယ်စာမျက်နှာတိုင်းတွင် ဖော်ပြထားသည်) တူညီသော URL များ ပါဝင်သည်။
- `storage` သည် ဖိုင်များကို မည်သို့သိမ်းဆည်းထားသည်ကို ဖော်ပြသည် - `mode` (`permanent` သို့မဟုတ် `temporary`), သိမ်းဆည်းထားသော `bytes`, `expires_at` (temporary ဖိုင်ကို ဖျက်မည့်အချိန်၊ permanent ဖိုင်များအတွက် `null`) နှင့် `expired` (ဖိုင်များ ပျောက်ဆုံးသွားသည်နှင့် `true`)။
- `cost.credits` သည် ခေါ်ဆိုမှု၏ API ခရက်ဒစ်ဖြင့် စျေးနှုန်း (`cost.usd` သည် USD ဖြင့်)၊ `cost.charged` သည် API လက်ကျန်မှ နုတ်ယူထားသည့် ပမာဏ၊ `cost.refunded` သည် ပြန်အမ်းသည့် ပမာဏ ဖြစ်သည်။ `metered` မော်ဒယ်အတွက် `cost.credits` သည် အစတွင် ထိန်းသိမ်းထားသည့် အများဆုံးပမာဏ (`cost.held`) ဖြစ်သည်။ run အောင်မြင်သောအခါ `cost.settled` သည် အသုံးပြုမှုကုန်ကျသည့် ပမာဏကို ဖော်ပြပြီး အများဆုံးပမာဏ၏ ကျန်ငွေသည် `cost.refunded` တွင် ပါဝင်သည် ([အသုံးပြုမှုအလိုက် ကောက်ခံခြင်း](https://doitong.com/developers/docs/pricing#metered) ကို ကြည့်ပါ)။
- တောင်းဆိုချက် မအောင်မြင်ပါက `error` သည် `{ "type": …, "code": …, "message": … }` ဖြစ်သည်။

## တောင်းဆိုချက်ဖတ်ရန်

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- `?wait=N` (အများဆုံး 20 စက္ကန့်) သည် long-poll ပြုလုပ်သည် - တောင်းဆိုချက် အပြီးသတ်သည်နှင့် ခေါ်ဆိုမှုကို ပြန်ပေးမည် သို့မဟုတ် N စက္ကန့်အကြာတွင် လက်ရှိအခြေအနေကို ပြန်ပေးမည်။ ရလဒ်ကို စောင့်ရန် ဤနည်းလမ်းကို ထပ်ခါတလဲလဲ ခေါ်ဆိုခြင်းသည် အလွယ်ကူဆုံးဖြစ်သည်။
- `?logs=1` သည် မော်ဒယ်၏ တိုးတက်မှုမှတ်တမ်းလိုင်းများ (နောက်ဆုံး 50 ခု) ကို `logs` အဖြစ် ထည့်ပေးသည်။

မိမိအကောင့်၏ တောင်းဆိုချက်များကိုသာ ဖတ်နိုင်သည်။ အခြား id များသည် `404 request_not_found` ဖြစ်သည်။

## တောင်းဆိုချက်များ စာရင်းပြုစုရန်

```bash
curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

အသစ်ဆုံးမှ စတင်သည်။ `limit` သည် 1 မှ 100 (မူလတန်ဖိုး 20) ဖြစ်ပြီး `status` နှင့် `model` တို့ဖြင့် စစ်ထုတ်သည်။ တုံ့ပြန်ချက်သည် `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }` ဖြစ်သည်။ နောက်စာမျက်နှာအတွက် `cursor=<next_cursor>` ကို ပေးပို့ပါ။

## တောင်းဆိုချက်ပယ်ဖျက်ရန်

```bash
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- မော်ဒယ်မစတင်မီ ပယ်ဖျက်ပါက အခြေအနေသည် `canceled` ဖြစ်လာပြီး API ခရက်ဒစ်များကို ငွေပြန်အမ်းကာ `200` ရရှိမည်။
- ဖန်တီးနေပြီးသားဖြစ်ပါက ပယ်ဖျက်မှုကို ဆက်လက်ပေးပို့ပြီး `"cancel_requested": true` နှင့်အတူ `202` ရရှိမည်။ မော်ဒယ်က ဆက်လက်ပြီးဆုံးသွားပါက တောင်းဆိုချက်သည် ပုံမှန်အတိုင်း အောင်မြင်ပြီး ကောက်ခံမည်။
- အပြီးသတ်ပြီးသားဖြစ်ပါက `409 not_cancelable` ဖြစ်သည် (ပယ်ဖျက်ပြီးသား တောင်းဆိုချက်သည် `200` ကိုသာ ပြန်ပေးသည်)။

## တောင်းဆိုချက်၏ ဖိုင်များကို ဖျက်ရန်

```bash
curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

တောင်းဆိုချက်၏ ထွက်ရလဒ်ဖိုင်များကို ကျွန်ုပ်တို့၏ မိတ္တူများမှ ယခုပင် ဖျက်ပြီး သိုလှောင်မှုကောက်ခံမှုကို ရပ်တန့်သည်။ တုံ့ပြန်ချက်သည် `storage.expired: true` ပါသော တောင်းဆိုချက် object ဖြစ်သည်။ ၎င်း၏ URL များသည် မှတ်တမ်းတွင် ဆက်ရှိသော်လည်း အလုပ်မလုပ်တော့ပါ။ ထပ်မံခေါ်ဆိုပါက မည်သည့်အရာမျှ မပြောင်းလဲပါ (`200`)။ `queued` သို့မဟုတ် `running` ဖြစ်နေဆဲ တောင်းဆိုချက်တွင် ဖိုင်များမရှိသေးပါ - `409 request_active`။ `models:run` လိုအပ်သည်။

## Idempotency: နှစ်ကြိမ်မပေးဘဲ ပြန်စမ်းရန်

ကွန်ရက်များ ပျက်နိုင်သည်။ run တစ်ခုကို ဘေးကင်းစွာ ပြန်စမ်းရန် `Idempotency-Key` header ကို ပေးပို့ပါ (အများဆုံး စာလုံး 255 လုံးရှိ မည်သည့် string မဆို၊ operation တစ်ခုစီအတွက် မတူညီရမည်၊ ဥပမာ မိမိ၏ order id)။

- ယခင် body နှင့် key တူပါက မူလတောင်းဆိုချက်ကို ပြန်ရရှိမည် (`200`, `Idempotent-Replayed: true` header ပါဝင်မည်)၊ ထပ်မံကောက်ခံမည်မဟုတ်ပါ။
- မော်ဒယ်သို့ မရောက်မီ run မအောင်မြင်ခဲ့ပြီးနောက် body နှင့် key တူပါက (`upstream_error` သို့မဟုတ် `internal_error` on submit, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`) မည်သည့်အရာမျှ မထုတ်လုပ်ခဲ့သလို မည်သည့်အရာမျှ မကောက်ခံသောကြောင့် မအောင်မြင်မှုကို ပြန်ပေးမည့်အစား retry သည် မော်ဒယ်ကို ထပ်မံ run မည်။
- body မတူဘဲ key တူပါက `409 idempotency_mismatch` ဖြစ်သည်။
- Keys များသည် ၎င်းတို့ကို ပေးပို့သည့် API ကီးအလိုက် သီးခြားသတ်မှတ်ထားသည်။

## ဖိုင်များရှိသည့်နေရာ

တောင်းဆိုချက်ကို `succeeded` ဟု မသတ်မှတ်မီ ထွက်ရလဒ်ဖိုင်တိုင်းကို ကျွန်ုပ်တို့၏ သိုလှောင်မှုသို့ ကူးယူသည်။ ထို့ကြောင့် `outputs` ရှိ URL များသည် ကျွန်ုပ်တို့၏ host များပေါ်တွင်ရှိပြီး တိုက်ရိုက်လင့်ခ်ချိတ်နိုင်သည်။ ၎င်းတို့ မည်မျှကြာ ရှိနေမည်ကို မိမိရွေးချယ်နိုင်သည်။

| Mode | ကြာချိန် | စျေးနှုန်း |
|---|---|---|
| `permanent` (မူလတန်ဖိုး) | မိမိဖျက်သည်အထိ | တစ်လလျှင် GB တစ်ခုအတွက် ၁၀၀ API ခရက်ဒစ် (၀.၁၀ $)၊ API လက်ကျန်မှ နေ့စဉ်ကောက်ခံသည် |
| `temporary` | ၇ ရက်၊ ထို့နောက် ဖျက်မည် | အခမဲ့ |

- အကောင့်ဆက်တင်သည် တောင်းဆိုချက်အသစ်များအတွက် ဆုံးဖြတ်ပေးသည် - [dashboard](https://doitong.com/developers/dashboard#balance) ရှိ "ဖိုင်များကို အမြဲတမ်း သိမ်းဆည်းထားပါ" switch သို့မဟုတ် `PATCH https://api.doitong.com/v1/account/storage` နှင့် `{"mode": "temporary"}`။ `GET https://api.doitong.com/v1/account` သည် `storage` အောက်တွင် ၎င်းကို ပြသပြီး မိမိသိမ်းဆည်းထားသည့် bytes နှင့် လစဉ်ခန့်မှန်းကုန်ကျစရိတ်ကိုလည်း ပြသည်။
- run တစ်ခုတွင် `?storage=permanent|temporary` (MCP `run` tool ၏ `storage` argument) ဖြင့် ထိုဆက်တင်ကို အဆိုပါ run အတွက် အစားထိုးနိုင်သည်။
- ဆက်တင်ပြောင်းလဲခြင်းသည် ရှိပြီးသားဖိုင်များကို မထိခိုက်စေပါ။ ၎င်းတို့ကို [`DELETE /requests/{id}/files`](#delete-files) ဖြင့် ဖျက်ပါ။
- API လက်ကျန်ဖြင့် သိုလှောင်မှုအတွက် မပေးချေနိုင်ပါက မည်သည့်အရာမျှ မကောက်ခံဘဲ အီးမေးလ်ရရှိမည်။ ၃၀ ရက်အတွင်း ငွေဖြည့်ခြင်း ပြုလုပ်ပါ၊ မဟုတ်ပါက သိမ်းဆည်းထားသော ဖိုင်များသည် temporary ဖြစ်လာပြီး ၇ ရက်အကြာတွင် ဖျက်ပစ်မည်။

ရှားရှားပါးပါး ကျွန်ုပ်တို့၏ မိတ္တူကူးယူမှု မအောင်မြင်ပါက entry တွင် `"stored": false` ပါဝင်ပြီး URL သည် သက်တမ်းတိုသော မူရင်း URL ဖြစ်သည်။ အမြန်ဒေါင်းလုဒ်လုပ်ပါ။