# Сұраулар

Сұрау — бір модельді бір рет шақыру. Оның id (`req_…`), күйі, API кредиттеріндегі құны (1000 = 1 USD) және сәтті орындалған кезде жасалған файлдары болады. Төмендегі әр соңғы нүктеден әр модель үшін бірдей нысан қайтарылады.

## Модельді табу

Барлық 1 496 модельдің каталогы жалпыға қолжетімді JSON болып табылады (кілт қажет емес):

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

| Сұрау параметрі | Мағынасы |
|---|---|
| `q` | Атауда, id-де, жасаушыда немесе тегтерде түгел кездесуі тиіс сөздер, мысалы `kling 3`. |
| `category` | Бір санат id-і, мысалы `text-to-video` немесе `upscale`. `GET https://api.doitong.com/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.com/v1/models/{model_id}` толық кіріс және шығыс JSON Schema-сын, канондық параметр атауларын, баға ережелерін және кіріс үлгісін қосады. Белгісіз `category` немесе `mode` мәні `400 invalid_parameter` қайтарады.

## Модельді іске қосу

```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": "..."}'
```

- Дене — модель кірісі, 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`, ал күту уақытында аяқталса (немесе қайта ойнату болса, төменде қараңыз) `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.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/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` (`temporary` файл жойылатын уақыт, тұрақты файлдар үшін `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.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- `?wait=N` (20 секундқа дейін) ұзақ сұрау режимінде жұмыс істейді: шақыру сұрау соңғы күйге жеткенде немесе 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` (әлдеқашан `canceled` болған сұрау жай ғана `200` қайтарады).

## Сұрау файлдарын жою

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

Сұраудың шығыс файлдарының біздің көшірмелерін қазір жояды және оларды сақтау ақысын тоқтатады. Жауапта `storage.expired: true` бар сұрау нысаны қайтарылады; оның URL-дері жазбада қалады, бірақ енді жұмыс істемейді. Қайта шақыру ештеңені өзгертпейді (`200`). `queued` немесе `running` күйіндегі сұрауда әлі файл жоқ: `409 request_active`. `models:run` қажет.

## Идемпотенттілік: екі рет төлемей қайталап көру

Желі істен шығуы мүмкін. Іске қосуды қауіпсіз қайталау үшін `Idempotency-Key` тақырыбын жіберіңіз (255 таңбаға дейінгі кез келген жол, әр операция үшін бірегей, мысалы өз тапсырысыңыздың id-і):

- Бұрынғыдай кілт және сол дене: бастапқы сұрау қайтарылады (`200`, `Idempotent-Replayed: true` тақырыбымен), ақы қайта алынбайды.
- Модельге жетпей сәтсіз аяқталған іске қосудан кейінгі сол кілт пен сол дене (`submit` кезіндегі `upstream_error` немесе `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 күн, кейін жойылады | Тегін |

- Аккаунт параметрі жаңа сұраулар үшін қолданылады: [бақылау тақтасындағы](https://doitong.com/developers/dashboard#balance) "Файлдарды мәңгілікке сақтау" ауыстырып-қосқышы немесе `{"mode": "temporary"}` мәнімен `PATCH https://api.doitong.com/v1/account/storage`. `GET https://api.doitong.com/v1/account` оны `storage` ішінде, сақтап отырған байттармен және айлық болжаммен көрсетеді.
- Іске қосу кезіндегі `?storage=permanent|temporary` (MCP `run` құралының `storage` аргументі) сол іске қосу үшін бұл параметрді қайта анықтайды.
- Параметрді өзгерту бұрыннан бар файлдарға әсер етпейді; оларды [`DELETE /requests/{id}/files`](#delete-files) арқылы жойыңыз.
- API теңгерімі сақтау ақысын төлеуге жетпесе, ақы алынбайды және электрондық хат аласыз: 30 күн ішінде теңгерімді толықтырыңыз, әйтпесе сақталған файлдар уақытша режимге ауысып, 7 күннен кейін жойылады.

Сирек жағдайда біздің көшірме жасау сәтсіз болса, жазбада `"stored": false` болады және URL бастапқы, қысқа мерзімді URL болып қалады: оны жақын арада жүктеп алыңыз.