# Pieprasījumi

Pieprasījums ir viens viena modeļa izsaukums. Tam ir id (`req_…`), statuss, izmaksas API kredītos (1000 = 1 USD) un, ja tas
izdodas, ģenerētie faili. Tas pats objekts tiek atgriezts no katra tālāk minētā galapunkta katram modelim.

## Atrast modeli

Visu 1496 modeļu katalogs ir publisks JSON (atslēga nav nepieciešama):

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

| Vaicājuma parametrs | Nozīme |
|---|---|
| `q` | Vārdiem visiem jāparādās nosaukumā, id, izstrādātājā vai tagos, piemēram, `kling 3`. |
| `category` | Vienas kategorijas id, piemēram, `text-to-video` vai `upscale`. `GET https://api.doitong.com/v1/categories` uzskaita visas 21 kategorijas ar to skaitu. |
| `lab` | Modeļa izstrādātājs pēc nosaukuma vai id, piemēram, `Google` vai `black-forest-labs`. |
| `family` | `family` id no iepriekšējās rindas: visi viena modeļa varianti (pro, fast, image-to-video, …). |
| `mode` | `exact` (cena tiek aprēķināta pēc ievades), `measured` (pēc ievades failu garuma vai izmēra), `estimate` (aptuvenā cena par palaišanu) vai `metered` (maksa pēc faktiskā lietojuma, nepārsniedzot maksimālo maksu par palaišanu). |
| `limit`, `cursor` | Lapas izmērs (no 1 līdz 100, noklusējums 50) un iepriekšējās lapas `next_cursor`. |

Katrā rindā ir `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` un `price`
objekts (skatiet [Cenas](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` pievieno
pilno ievades un izvades JSON Schema, kanoniskos parametru nosaukumus, cenu noteikumus un ievades piemēru. Nezināma
`category` vai `mode` vērtība ir `400 invalid_parameter`.

## Palaist modeli

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

- Ķermenis ir modeļa ievade — JSON objekts. Katras modeļa lapas uzskaita tā parametrus.
- Ievade tiek pārbaudīta, pirms tiek iekasēta maksa. Nederīga ievade atgriež `422 invalid_input` ar kļūdaino
  `param`, un nekas netiek iekasēts.
- `?wait=N` (līdz 20 sekundēm) aiztur izsaukumu, līdz pieprasījums tiek pabeigts vai laiks beidzas.
- `?webhook_url=https://…` nosūta parakstītu POST uz šo URL, kad pieprasījums tiek pabeigts (skatiet [Tīmekļa āķi](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` vai `?storage=temporary` nosaka, cik ilgi tiek glabāti izvades faili; ja parametrs nav norādīts, tiek izmantots konta
  iestatījums (skatiet [Kur atrodas faili](#storage)).

Atbilde ir `202 Accepted`, kamēr pieprasījums vēl tiek apstrādāts, un `200 OK`, ja tas tika pabeigts gaidīšanas laikā (vai
ja tā ir atkārtota atbilde, skatiet tālāk). Galvenes `Location` un `Doitong-Request-Id` satur pieprasījuma URL un id.

## Statusi

Pieprasījuma dzīves cikls: `queued` → `running` → `succeeded` | `failed` | `canceled` (pabeigts; par neveiksmīgiem un atceltiem pieprasījumiem tiek atmaksāti API kredīti).

| Statuss | Nozīme | Gala |
|---|---|---|
| `queued` | Pieņemts un apmaksāts, gaida apstrādi. `queue_position` var parādīt vietu rindā. | nē |
| `running` | Modelis ģenerē. | nē |
| `succeeded` | Pabeigts. `outputs` uzskaita failus. | jā |
| `failed` | Modelis vai ierobežojums to apturēja. `error` paskaidro iemeslu. API kredīti tiek atmaksāti. | jā |
| `canceled` | Atcelts, pirms tika izveidots rezultāts. API kredīti tiek atmaksāti. | jā |

Pieprasījums, kas pārsniedz tam atvēlēto laiku, neizdodas ar kodu `timeout`, un maksa tiek atmaksāta: 15 minūtes attēliem,
60 minūtes video, 30 minūtes audio un visam pārējam.

## Pieprasījuma objekts

```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` ir vienāds visiem modeļiem: pa vienam ierakstam par katru ģenerēto failu ar `type` (`image`, `video`, `audio`,
  `file` vai `3d`), `url` mūsu krātuvē, `content_type` un, ja zināms, `file_size`, `width`, `height`,
  `duration`.
- `output` ir modeļa paša rezultāta objekts (tā lauki ir uzskaitīti katras modeļa lapā) ar tiem pašiem URL.
- `storage` norāda, kā faili tiek glabāti: `mode` (`permanent` vai `temporary`), saglabātie `bytes`, `expires_at` (kad
  pagaidu fails tiek dzēsts, pastāvīgajiem failiem `null`) un `expired` (`true`, tiklīdz faili ir pazuduši).
- `cost.credits` ir izsaukuma cena API kredītos (`cost.usd` USD), `cost.charged` ir no API atlikuma debetētā summa,
  bet `cost.refunded` — atmaksātā summa. `metered` modelim `cost.credits` ir sākumā aizturētais maksimums
  (`cost.held`); kad palaišana izdodas, `cost.settled` norāda faktisko lietojumu, bet pārējais maksimums ir
  `cost.refunded` (skatiet [Maksa pēc lietojuma](https://doitong.com/developers/docs/pricing#metered)).
- Ja pieprasījums neizdodas, `error` ir `{ "type": …, "code": …, "message": … }`.

## Lasīt pieprasījumu

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

- `?wait=N` (līdz 20 sekundēm) veic ilgo aptauju: izsaukums atgriežas, tiklīdz pieprasījums ir galīgs, vai pēc N sekundēm
  ar pašreizējo stāvokli. Atkārtota izsaukšana ir vienkāršākais veids, kā gaidīt rezultātu.
- `?logs=1` pievieno modeļa progresa žurnāla rindas (pēdējās 50) kā `logs`.

Varat lasīt tikai sava konta pieprasījumus; jebkurš cits id ir `404 request_not_found`.

## Uzskaitīt pieprasījumus

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

Vispirms jaunākie. `limit` ir no 1 līdz 100 (noklusējums 20), `status` un `model` filtrē rezultātus. Atbilde ir
`{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; nākamajai lapai nododiet
`cursor=<next_cursor>`.

## Atcelt pieprasījumu

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

- Atcelts, pirms modelis sāka darbu: statuss kļūst par `canceled`, API kredīti tiek atmaksāti, un saņemat `200`.
- Jau tiek ģenerēts: atcelšana tiek pārsūtīta, un saņemat `202` ar `"cancel_requested": true`. Ja modelis tomēr
  pabeidz darbu, pieprasījums parasti izdodas un maksa tiek iekasēta.
- Jau galīgs: `409 not_cancelable` (pieprasījums, kas jau ir `canceled`, vienkārši atgriež `200`).

## Dzēst pieprasījuma failus

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

Nekavējoties dzēš mūsu pieprasījuma izvades failu kopijas un aptur to glabāšanas maksu. Atbilde ir pieprasījuma
objekts ar `storage.expired: true`; tā URL paliek ierakstā, bet vairs nedarbojas. Atkārtots izsaukums neko nemaina
(`200`). Pieprasījumam, kas joprojām ir `queued` vai `running`, failu vēl nav: `409 request_active`. Nepieciešama
`models:run` atļauja.

## Idempotence: atkārtot, nemaksājot divreiz

Tīkli mēdz nedarboties. Lai droši atkārtotu palaišanu, nosūtiet `Idempotency-Key` galveni (jebkura virkne līdz 255
rakstzīmēm, unikāla katrai darbībai, piemēram, jūsu pasūtījuma id):

- Tā pati atslēga un tas pats ķermenis kā iepriekš: saņemat sākotnējo pieprasījumu (`200`, galvene
  `Idempotent-Replayed: true`), un nekas netiek iekasēts atkārtoti.
- Tā pati atslēga un ķermenis pēc palaišanas, kas neizdevās, pirms sasniedza modeli (`upstream_error` vai `internal_error` iesniegšanas laikā,
  `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): nekas netika izveidots un nekas netiek iekasēts,
  tāpēc atkārtotais mēģinājums palaiž modeli no jauna, nevis atgriež kļūmi.
- Tā pati atslēga ar citu ķermeni: `409 idempotency_mismatch`.
- Atslēgas ir piesaistītas API atslēgai, kas tās nosūtīja.

## Kur atrodas faili

Katrs izvades fails tiek kopēts mūsu krātuvē, pirms pieprasījums tiek atzīmēts kā `succeeded`, tāpēc `outputs` URL ir
mūsu resursdatoros un varat uz tiem izveidot tiešas saites. Jūs izvēlaties, cik ilgi tie tiek glabāti:

| Režīms | Ilgums | Cena |
|---|---|---|
| `permanent` (noklusējums) | Līdz to dzēšanai | 100 API kredīti (0,10 $) par GB mēnesī, iekasēti katru dienu no API atlikuma |
| `temporary` | 7 dienas, pēc tam dzēsti | Bezmaksas |

- Konta iestatījums nosaka jaunu pieprasījumu noklusējumu: slēdzis "Glabāt failus mūžīgi"
  [informācijas panelī](https://doitong.com/developers/dashboard#balance) vai `PATCH https://api.doitong.com/v1/account/storage` ar
  `{"mode": "temporary"}`. `GET https://api.doitong.com/v1/account` to parāda sadaļā `storage` kopā ar saglabātajiem baitiem un
  mēneša aprēķinu.
- `?storage=permanent|temporary` palaišanas laikā (MCP `run` rīka `storage` arguments) ignorē iestatījumu šai palaišanai.
- Iestatījuma maiņa nekad neietekmē jau esošos failus; dzēsiet tos ar
  [`DELETE /requests/{id}/files`](#delete-files).
- Ja API atlikums nevar samaksāt par krātuvi, maksa netiek iekasēta un jūs saņemat e-pastu: papildiniet atlikumu 30
  dienu laikā, citādi saglabātie faili kļūs pagaidu faili un tiks dzēsti pēc 7 dienām.

Retos gadījumos, kad mūsu kopēšana neizdodas, ierakstā ir `"stored": false`, un URL ir sākotnējais, īslaicīgais URL:
lejupielādējiet failu drīz.