# ਪ੍ਰਮਾਣੀਕਰਨ

ਹਰ ਉਹ ਕਾਲ ਜੋ ਕਿਸੇ ਮਾਡਲ ਨੂੰ ਚਲਾਉਂਦੀ ਹੈ ਜਾਂ ਤੁਹਾਡੀਆਂ ਬੇਨਤੀਆਂ ਪੜ੍ਹਦੀ ਹੈ, ਲਈ 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.ru/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.ru/v1/account` API ਬਕਾਇਆ ਅਤੇ ਕੁੰਜੀ ਦਾ ਬਾਕੀ ਬਜਟ (ਦੋਵੇਂ API ਕ੍ਰੈਡਿਟ ਵਿੱਚ) ਦਿਖਾਉਂਦਾ ਹੈ:

```json 200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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` ਮਿਲਦਾ ਹੈ; ਇੱਕ ਦੇ ਮੁਕੰਮਲ ਹੋਣ ਤੋਂ ਬਾਅਦ ਇਸਨੂੰ ਦੁਬਾਰਾ ਸ਼ੁਰੂ ਕਰੋ।