# கோரிக்கைகள்

ஒரு கோரிக்கை என்பது ஒரு மாதிரிக்கான ஒரு அழைப்பு. இதில் ஒரு id (`req_…`), ஒரு நிலை, API கிரெடிட்களில் அதன் செலவு (1000 = 1 USD), மேலும் அது
வெற்றியடைந்தால் உருவாக்கப்பட்ட கோப்புகள் இருக்கும். கீழே உள்ள ஒவ்வொரு முனையத்திலிருந்தும், ஒவ்வொரு மாதிரிக்கும் இதே பொருள் திரும்ப வரும்.

## ஒரு மாதிரியைக் கண்டறிதல்

அனைத்து 1,496 மாதிரிகளின் பட்டியல் பொது JSON ஆகும் (விசை தேவையில்லை):

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

| வினவல் அளவுரு | பொருள் |
|---|---|
| `q` | பெயர், id, உருவாக்குநர் அல்லது குறிச்சொற்களில் அனைத்தும் இடம்பெற வேண்டிய சொற்கள்; எடுத்துக்காட்டாக `kling 3`. |
| `category` | ஒரு வகை id; எடுத்துக்காட்டாக `text-to-video` அல்லது `upscale`. `GET https://api.doitong.ru/v1/categories` அனைத்து 21 வகைகளையும் அவற்றின் எண்ணிக்கைகளுடன் பட்டியலிடுகிறது. |
| `lab` | மாதிரியின் உருவாக்குநர்; பெயர் அல்லது id மூலம், எடுத்துக்காட்டாக `Google` அல்லது `black-forest-labs`. |
| `family` | முந்தைய வரியிலிருந்து ஒரு `family` id: ஒரே மாதிரியின் ஒவ்வொரு மாறுபாடும் (pro, fast, image-to-video, …). |
| `mode` | `exact` (விலை உள்ளீட்டிலிருந்து கணக்கிடப்படுகிறது), `measured` (உள்ளீட்டு கோப்புகளின் நீளம் அல்லது அளவிலிருந்து), `estimate` (ஒவ்வொரு இயக்கத்திற்குமான மதிப்பிடப்பட்ட விலை) அல்லது `metered` (உண்மையான பயன்பாட்டின் அடிப்படையில், ஒவ்வொரு இயக்கத்திற்குமான அதிகபட்ச வரம்பு வரை கட்டணம்). |
| `limit`, `cursor` | பக்க அளவு (1 முதல் 100 வரை, இயல்புநிலை 50) மற்றும் முந்தைய பக்கத்தின் `next_cursor`. |

ஒவ்வொரு வரியிலும் `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` மற்றும் ஒரு `price`
பொருள் இருக்கும் ([விலை நிர்ணயம்](https://doitong.com/developers/docs/pricing#price-objects) பார்க்கவும்). `GET https://api.doitong.ru/v1/models/{model_id}` முழு
உள்ளீடு மற்றும் வெளியீட்டு JSON Schema, தரநிலையான அளவுருப் பெயர்கள், விலை விதிகள் மற்றும் ஓர் எடுத்துக்காட்டு உள்ளீட்டைச் சேர்க்கிறது. தெரியாத
`category` அல்லது `mode` என்பது `400 invalid_parameter` ஆகும்.

## ஒரு மாதிரியை இயக்குதல்

```bash
curl -X POST "https://api.doitong.ru/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": "..."}'
```

- உடல் என்பது மாதிரி உள்ளீடான ஒரு JSON பொருள். ஒவ்வொரு மாதிரிப் பக்கமும் அதன் அளவுருக்களைப் பட்டியலிடுகிறது.
- எதற்கும் கட்டணம் வசூலிக்கப்படுவதற்கு முன் உள்ளீடு சரிபார்க்கப்படுகிறது. தவறான உள்ளீடு, பாதிப்பை ஏற்படுத்திய
  `param` உடன் `422 invalid_input` ஐத் திருப்பும்; எந்தக் கட்டணமும் இல்லை.
- `?wait=N` (அதிகபட்சம் 20 வினாடிகள்) கோரிக்கை முடியும் வரை அல்லது நேரம் முடியும் வரை அழைப்பை நிறுத்தி வைக்கும்.
- `?webhook_url=https://…` கோரிக்கை முடிந்ததும் அந்த URL-க்கு கையொப்பமிடப்பட்ட POST ஐ அனுப்பும் ([வெப்ஹுக்குகள்](https://doitong.com/developers/docs/webhooks) பார்க்கவும்).
- `?storage=permanent` அல்லது `?storage=temporary` வெளியீட்டு கோப்புகள் எவ்வளவு காலம் வைக்கப்பட வேண்டும் என்பதைத் தேர்ந்தெடுக்கிறது; இதை வழங்காவிட்டால் கணக்கு
  அமைப்பு பயன்படுத்தப்படும் ([கோப்புகள் எங்கு வைக்கப்படுகின்றன](#storage) பார்க்கவும்).

கோரிக்கை இன்னும் செயல்பாட்டில் இருக்கும்போது பதில் `202 Accepted` ஆகும்; wait நேரத்திற்குள் அது முடிந்தால் (அல்லது
கீழே பார்க்கும் மீள்இயக்கமாக இருந்தால்) `200 OK` ஆகும். `Location` மற்றும் `Doitong-Request-Id` தலைப்புகள் கோரிக்கை URL மற்றும் id-ஐக் கொண்டிருக்கும்.

## நிலைகள்

கோரிக்கை வாழ்க்கைச் சுழற்சி: `queued` → `running` → `succeeded` | `failed` | `canceled` (இறுதி; தோல்வியுற்றதும் ரத்துசெய்யப்பட்டதும் API கிரெடிட்கள் திருப்பியளிக்கப்படும்).

| நிலை | பொருள் | இறுதியா? |
|---|---|---|
| `queued` | ஏற்றுக்கொள்ளப்பட்டு கட்டணம் வசூலிக்கப்பட்டது; பணியாளர் காத்திருக்கிறது. வரிசையில் உள்ள இடத்தை `queue_position` காட்டக்கூடும். | இல்லை |
| `running` | மாதிரி உருவாக்கிக் கொண்டிருக்கிறது. | இல்லை |
| `succeeded` | முடிந்தது. `outputs` கோப்புகளைப் பட்டியலிடுகிறது. | ஆம் |
| `failed` | மாதிரி அல்லது ஓர் வரம்பு அதை நிறுத்தியது. `error` காரணத்தைக் கூறுகிறது. API கிரெடிட்கள் பணத்தைத் திருப்பியளிக்கப்படுகின்றன. | ஆம் |
| `canceled` | முடிவை உருவாக்குவதற்கு முன் ரத்து செய்யப்பட்டது. API கிரெடிட்கள் பணத்தைத் திருப்பியளிக்கப்படுகின்றன. | ஆம் |

நேர வரம்பை விட நீண்ட நேரம் இயங்கும் கோரிக்கை `timeout` குறியீட்டுடன் தோல்வியடையும்; அதற்கான கட்டணம் திருப்பியளிக்கப்படும்: படங்களுக்கு 15 நிமிடங்கள்,
வீடியோவுக்கு 60 நிமிடங்கள், ஆடியோவுக்கும் மற்ற அனைத்திற்கும் 30 நிமிடங்கள்.

## கோரிக்கைப் பொருள்

```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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

- `outputs` எல்லா மாதிரிகளுக்கும் ஒன்றே: உருவாக்கப்பட்ட ஒவ்வொரு கோப்புக்கும் ஒரு பதிவு; அதில் `type` (`image`, `video`, `audio`,
  `file` அல்லது `3d`), எங்கள் சேமிப்பகத்தில் உள்ள ஒரு `url`, `content_type`, மேலும் தெரிந்திருந்தால் `file_size`, `width`, `height`,
  `duration` ஆகியவை இருக்கும்.
- `output` என்பது மாதிரியின் சொந்த முடிவுப் பொருள் (அதன் புலங்கள் ஒவ்வொரு மாதிரிப் பக்கத்திலும் பட்டியலிடப்பட்டுள்ளன); அதே URL-களுடன் இருக்கும்.
- `storage` கோப்புகள் எவ்வாறு வைக்கப்படுகின்றன என்பதைக் கூறுகிறது: `mode` (`permanent` அல்லது `temporary`), சேமிக்கப்பட்ட `bytes`, `expires_at` (ஒரு
  தற்காலிக கோப்பு நீக்கப்படும் நேரம்; நிரந்தர கோப்புகளுக்கு `null`) மற்றும் `expired` (கோப்புகள் நீக்கப்பட்டதும் `true`).
- `cost.credits` என்பது அழைப்பின் API கிரெடிட் விலை (`cost.usd` USD-யில்), `cost.charged` என்பது API இருப்பிலிருந்து
  கழிக்கப்பட்ட தொகை, `cost.refunded` என்பது திரும்பிய தொகை. `metered` மாதிரிக்கு `cost.credits` என்பது தொடக்கத்தில் வைத்திருக்கும் அதிகபட்சத் தொகை
  (`cost.held`); இயக்கம் வெற்றியடைந்ததும் பயன்பாட்டிற்கான தொகையை `cost.settled` காட்டும், அதிகபட்சத் தொகையின் மீதம்
  `cost.refunded` இல் இருக்கும் ([பயன்பாட்டின் அடிப்படையில் கட்டணம்](https://doitong.com/developers/docs/pricing#metered) பார்க்கவும்).
- ஒரு கோரிக்கை தோல்வியடைந்தால், `error` என்பது `{ "type": …, "code": …, "message": … }` ஆகும்.

## ஒரு கோரிக்கையைப் படித்தல்

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

- `?wait=N` (அதிகபட்சம் 20 வினாடிகள்) நீண்ட polling செய்கிறது: கோரிக்கை இறுதி நிலைக்கு வந்தவுடன் அல்லது N வினாடிகளுக்குப் பிறகு தற்போதைய
  நிலையுடன் அழைப்பு திரும்பும். முடிவுக்காகக் காத்திருக்க இதைச் சுழற்றுவது எளிய வழியாகும்.
- `?logs=1` மாதிரியின் முன்னேற்றப் பதிவுக் கோடுகளை (கடைசி 50) `logs` ஆகச் சேர்க்கிறது.

உங்கள் சொந்தக் கணக்கின் கோரிக்கைகளை மட்டுமே படிக்க முடியும்; வேறு எந்த id-யும் `404 request_not_found` ஆகும்.

## கோரிக்கைகளைப் பட்டியலிடுதல்

```bash
curl "https://api.doitong.ru/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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- மாதிரி தொடங்குவதற்கு முன் ரத்து செய்தால்: நிலை `canceled` ஆகும், API கிரெடிட்கள் பணத்தைத் திருப்பியளிக்கப்படும், மேலும் `200` கிடைக்கும்.
- ஏற்கனவே உருவாக்கிக் கொண்டிருந்தால்: ரத்து கோரிக்கை அனுப்பப்பட்டு `"cancel_requested": true` உடன் `202` கிடைக்கும். மாதிரி
  எப்படியும் முடிந்தால், கோரிக்கை வழக்கம்போல் வெற்றியடைந்து கட்டணம் வசூலிக்கப்படும்.
- ஏற்கனவே இறுதி நிலையில் இருந்தால்: `409 not_cancelable` (ஏற்கனவே `canceled` ஆகியுள்ள கோரிக்கை `200` ஐ மட்டும் திருப்பும்).

## ஒரு கோரிக்கையின் கோப்புகளை நீக்குதல்

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

கோரிக்கையின் வெளியீட்டு கோப்புகளின் எங்கள் நகல்களை உடனே நீக்கி, அவற்றுக்கான சேமிப்பகக் கட்டணத்தை நிறுத்துகிறது. பதில் `storage.expired: true` கொண்ட
கோரிக்கைப் பொருளாக இருக்கும்; அதன் பதிவில் URL-கள் இருக்கும், ஆனால் இனி செயல்படாது. இதை மீண்டும் அழைத்தாலும் மாற்றம் இல்லை
(`200`). `queued` அல்லது `running` நிலையில் இருக்கும் கோரிக்கைக்கு இன்னும் கோப்புகள் இருக்காது: `409 request_active`. `models:run` தேவை.

## Idempotency: இருமுறை கட்டணம் செலுத்தாமல் மீண்டும் முயற்சித்தல்

நெட்வொர்க்குகள் தோல்வியடையலாம். ஓர் இயக்கத்தைப் பாதுகாப்பாக மீண்டும் முயற்சிக்க, `Idempotency-Key` தலைப்பை அனுப்பவும் (255 எழுத்துகள் வரை உள்ள எந்தச் சரமும், ஒவ்வொரு
செயல்பாட்டிற்கும் தனித்துவமானது; எடுத்துக்காட்டாக உங்கள் சொந்த order id):

- முன்பு இருந்த அதே விசையும் அதே உடலும்: அசல் கோரிக்கை திரும்பும் (`200`, `Idempotent-Replayed: true` தலைப்புடன்), மேலும் மீண்டும் கட்டணம் வசூலிக்கப்படாது.
- மாதிரியை அடைவதற்கு முன் தோல்வியடைந்த இயக்கத்திற்குப் பிறகு அதே விசையும் உடலும் (`upstream_error` அல்லது submit இல் `internal_error`,
  `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): எதுவும் உருவாக்கப்படவில்லை, எதற்கும் கட்டணம் வசூலிக்கப்படவில்லை; எனவே தோல்வியைத்
  திருப்புவதற்குப் பதிலாக மீண்டும் முயற்சி மாதிரியை மறுபடியும் இயக்கும்.
- வேறுபட்ட உடலுடன் அதே விசை: `409 idempotency_mismatch`.
- விசைகள் அவற்றை அனுப்பிய API விசைக்கான வரம்பில் இருக்கும்.

## கோப்புகள் எங்கு வைக்கப்படுகின்றன

கோரிக்கை `succeeded` எனக் குறிக்கப்படுவதற்கு முன் ஒவ்வொரு வெளியீட்டு கோப்பும் எங்கள் சேமிப்பகத்தில் நகலெடுக்கப்படும்; எனவே `outputs` இல் உள்ள URL-கள்
எங்கள் சொந்த ஹோஸ்ட்களில் இருக்கும், அவற்றுடன் நேரடியாக இணைக்கலாம். அவை எவ்வளவு காலம் இருக்கும் என்பது உங்கள் தேர்வு:

| பயன்முறை | காலம் | விலை |
|---|---|---|
| `permanent` (இயல்புநிலை) | நீங்கள் நீக்கும் வரை | ஒரு GB-க்கு மாதத்திற்கு 100 API கிரெடிட்கள் ($0.10); API இருப்பிலிருந்து தினசரி வசூலிக்கப்படும் |
| `temporary` | 7 நாட்கள், பின்னர் நீக்கப்படும் | இலவசம் |

- புதிய கோரிக்கைகளுக்கான கணக்கு அமைப்பை [dashboard](https://doitong.com/developers/dashboard#balance) இல் உள்ள
  "கோப்பை நிரந்தரமாக வைத்திருக்கவும்" சுவிட்ச் அல்லது `{"mode": "temporary"}` உடன் `PATCH https://api.doitong.ru/v1/account/storage` தீர்மானிக்கிறது. `GET https://api.doitong.ru/v1/account` இதை
  `storage` இன் கீழ், நீங்கள் வைத்திருக்கும் பைட்டுகள் மற்றும் மாதாந்திர மதிப்பீட்டுடன் காட்டுகிறது.
- இயக்கத்தில் உள்ள `?storage=permanent|temporary` (MCP `run` கருவியின் `storage` வாதம்) அந்த இயக்கத்திற்காக இதை மீறுகிறது.
- அமைப்பை மாற்றுவது ஏற்கனவே உங்களிடம் உள்ள கோப்புகளை ஒருபோதும் பாதிக்காது; அவற்றை
  [`DELETE /requests/{id}/files`](#delete-files) மூலம் நீக்கவும்.
- சேமிப்பகத்திற்குக் கட்டணம் செலுத்த API இருப்பு போதாதபோது, எந்தக் கட்டணமும் வசூலிக்கப்படாது, உங்களுக்கு மின்னஞ்சல் வரும்: 30 நாட்களுக்குள்
  மீள்நிரப்பவும்; இல்லையெனில் வைத்திருக்கும் கோப்புகள் தற்காலிகமாகி 7 நாட்களுக்குப் பிறகு நீக்கப்படும்.

எங்கள் நகல் அரிதாகத் தோல்வியடைந்தால், பதிவில் `"stored": false` இருக்கும், URL அசல் குறுகிய கால URL ஆக இருக்கும்:
அதை விரைவில் பதிவிறக்கவும்.