# প্রমাণীকরণ

যে কল কোনো মডেল চালায় বা আপনার রিকোয়েস্ট পড়ে, তার জন্য একটি API কী প্রয়োজন। ক্যাটালগ (`GET /models`,
`GET /categories`), `POST /quote` এবং OpenAPI ডকুমেন্ট সর্বসাধারণের জন্য উন্মুক্ত।

## API কী

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys)-এ কী তৈরি ও বাতিল করুন। একটি কী দেখতে
`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 ক্রেডিটে নিজস্ব বাজেট থাকতে পারে (১,০০০ API ক্রেডিট = ১$): মোট বাজেট, দৈনিক বাজেট (গত 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 সময় |

লিমিট অতিক্রম করলে `Retry-After` হেডারসহ `429` পাবেন (সেকেন্ড)। `?wait=`-সহ দীর্ঘ পোলিং প্রতি কলে একটি রিকোয়েস্ট
হিসেবে গণনা হয়, তাই দ্রুত পোলিংয়ের চেয়ে অপেক্ষা করা সাশ্রয়ী।

প্রতি অ্যাকাউন্টে একই সময়ে সর্বাধিক 10টি রিকোয়েস্ট (`queued` বা `running`) থাকতে পারে। আরও একটি শুরু করলে
`429 too_many_inflight` ফেরত আসে; একটি শেষ হওয়ার পর আবার শুরু করুন।