# Iarratais

Is glao amháin ar shamhail amháin é iarratas. Tá aitheantas aige (`req_…`), stádas, a chostas i gcreidmheasanna API (1000 = 1 USD), agus, nuair a éiríonn leis, na comhaid ghinte. Tagann an réad céanna ar ais ó gach críochphointe thíos, do gach samhail.

## Aimsigh samhail

Tá catalóg phoiblí JSON de na 1,496 samhail go léir (níl eochair ag teastáil):

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

| Paraiméadar fiosraithe | Ciall |
|---|---|
| `q` | Focail nach mór dóibh go léir a bheith sa ainm, san aitheantas, sa déantóir nó sna clibeanna, mar shampla `kling 3`. |
| `category` | Aitheantas catagóire amháin, mar shampla `text-to-video` nó `upscale`. Liostaíonn `GET https://api.doitong.com/v1/categories` na 21 go léir lena gcomhaireamh. |
| `lab` | Déantóir na samhla, de réir ainm nó aitheantais, mar shampla `Google` nó `black-forest-labs`. |
| `family` | Aitheantas `family` ó ró roimhe seo: gach leagan de shamhail amháin (pro, fast, image-to-video, …). |
| `mode` | `exact` (ríomhtar an praghas ón ionchur), `measured` (ó fhad nó méid na gcomhad ionchuir), `estimate` (praghas measta in aghaidh na rith) nó `metered` (naprítear de réir na húsáide iarbhír, suas go dtí uasmhéid in aghaidh na rith). |
| `limit`, `cursor` | Méid an leathanaigh (1 go 100, réamhshocrú 50) agus `next_cursor` an leathanaigh roimhe seo. |

Tá `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` agus réad `price` i ngach ró (féach [Praghsáil](https://doitong.com/developers/docs/pricing#price-objects)). Cuireann `GET https://api.doitong.com/v1/models/{model_id}` an JSON Schema iomlán don ionchur agus don aschur, na hainmneacha canónacha paraiméadar, rialacha an phraghais agus ionchur samplach leis. Is é `400 invalid_parameter` a bhíonn i gceist le `category` nó `mode` anaithnid.

## Rith samhail

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

- Is é corp an iarratais ionchur na samhla, réad JSON. Liostaíonn leathanach gach samhla a paraiméadair.
- Seiceáiltear an t-ionchur sula ngearrtar aon táille. Filleann ionchur neamhbhailí `422 invalid_input` leis an `param` ciontach, agus ní chosnaíonn sé tada.
- Coinníonn `?wait=N` (suas le 20 soicind) an glao ar feitheamh go dtí go gcríochnaíonn an t-iarratas nó go n-imíonn an t-am.
- Seolann `?webhook_url=https://…` POST sínithe chuig an URL sin nuair a chríochnaíonn an t-iarratas (féach [Crúcaí gréasáin](https://doitong.com/developers/docs/webhooks)).
- Roghnaíonn `?storage=permanent` nó `?storage=temporary` cá fhad a choimeádtar na comhaid aschuir; mura sonraítear é, cuirtear socrú an chuntais i bhfeidhm (féach [Cá gcónaíonn na comhaid](#storage)).

Is é `202 Accepted` an freagra agus an t-iarratas fós ar bun, agus `200 OK` nuair a chríochnaigh sé laistigh den tréimhse feithimh (nó nuair is athsheoladh é, féach thíos). Iompraíonn na ceanntásca `Location` agus `Doitong-Request-Id` URL agus aitheantas an iarratais.

## Stádais

Saolré an iarratais: `queued` → `running` → `succeeded` | `failed` | `canceled` (críochnaitheach; aisíoctar cinn a theip orthu agus a cuireadh ar ceal).

| Stádas | Ciall | Críochnaithe |
|---|---|---|
| `queued` | Glactha agus gearrtha táille, ag fanacht le hoibrí. Féadfaidh `queue_position` an áit sa líne a thaispeáint. | níl |
| `running` | Tá an tsamhail ag giniúint. | níl |
| `succeeded` | Críochnaithe. Liostaíonn `outputs` na comhaid. | tá |
| `failed` | Chuir an tsamhail nó teorainn stop leis. Deir `error` cén fáth. Aisíoctar na creidmheasanna API. | tá |
| `canceled` | Cealaíodh é sular tháirg sé toradh. Aisíoctar na creidmheasanna API. | tá |

Teipeann ar iarratas a ritheann níos faide ná a theorainn ama leis an gcód `timeout` agus aisíoctar é: 15 nóiméad d’íomhánna, 60 nóiméad d’fhíseán, 30 nóiméad d’fhuaim agus gach rud eile.

## Réad an iarratais

```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"
  }
}
```

- Is ionann `outputs` do gach samhail: iontráil amháin in aghaidh an chomhaid ghinte le `type` (`image`, `video`, `audio`, `file` nó `3d`), `url` ar ár stóráil, `content_type` agus, nuair is eol iad, `file_size`, `width`, `height`, `duration`.
- Is é `output` réad toraidh na samhla féin (liostaítear a réimsí ar leathanach gach samhla) leis na URLanna céanna.
- Deir `storage` conas a choimeádtar na comhaid: `mode` (`permanent` nó `temporary`), `bytes` stóráilte, `expires_at` (nuair a scriostar comhad sealadach, `null` do na cinn bhuana) agus `expired` (`true` nuair a bhíonn na comhaid imithe).
- Is é `cost.credits` praghas an ghlao i gcreidmheasanna API (`cost.usd` in USD), `cost.charged` an méid a baineadh d’iarmhéid an API, agus `cost.refunded` an méid a tháinig ar ais. Maidir le samhail `metered`, is é `cost.credits` an t-uasmhéid a coinníodh ag an tús (`cost.held`); nuair a éiríonn leis an rith, deir `cost.settled` méid na húsáide agus bíonn an chuid eile den uasmhéid in `cost.refunded` (féach [Gearrtar de réir úsáide](https://doitong.com/developers/docs/pricing#metered)).
- Nuair a theipeann ar iarratas, is é `error` `{ "type": …, "code": …, "message": … }`.

## Léigh iarratas

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

- Déanann `?wait=N` (suas le 20 soicind) vótaíocht fhada: filleann an glao a luaithe is atá an t-iarratas críochnaithe, nó tar éis N soicind leis an staid reatha. Is é lúbadh air seo an bealach is simplí chun fanacht le toradh.
- Cuireann `?logs=1` línte loga dul chun cinn na samhla (na 50 deireanacha) leis mar `logs`.

Ní féidir leat ach iarratais de do chuntas féin a léamh; is é `404 request_not_found` a bhíonn i gceist le haon aitheantas eile.

## Liostaigh iarratais

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

Is nuaí ar dtús. Is é 1 go 100 an raon do `limit` (réamhshocrú 20), agus déanann `status` agus `model` scagadh. Is é an freagra `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; seol `cursor=<next_cursor>` don chéad leathanach eile.

## Cealaigh iarratas

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

- Cealaithe sular thosaigh an tsamhail: athraíonn an stádas go `canceled`, aisíoctar na creidmheasanna API, agus faigheann tú `200`.
- Má tá sé á ghiniúint cheana: seoltar an cealú ar aghaidh agus faigheann tú `202` le `"cancel_requested": true`. Má chríochnaíonn an tsamhail ar aon nós, éiríonn leis an iarratas de ghnáth agus gearrtar táille.
- Má tá sé críochnaithe cheana: `409 not_cancelable` (filleann iarratas atá `canceled` cheana `200` amháin).

## Scrios comhaid iarratais

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

Scriosann sé cóipeanna na gcomhad aschuir ónár stóráil anois agus stopann sé an táille stórála. Is é réad an iarratais an freagra le `storage.expired: true`; fanann a URLanna sa taifead ach ní oibríonn siad níos mó. Ní athraíonn glao eile air tada (`200`). Níl aon chomhaid fós ag iarratas atá `queued` nó `running`: `409 request_active`. Teastaíonn `models:run` uaidh.

## Idempotacht: bain triail eile as gan íoc faoi dhó

Teipeann ar líonraí. Chun rith a athiarraidh go sábháilte, seol ceanntásc `Idempotency-Key` (teaghrán ar bith suas le 255 carachtar, uathúil in aghaidh na hoibríochta, mar shampla d’aitheantas ordaithe féin):

- An eochair chéanna agus an corp céanna agus roimhe seo: faigheann tú an t-iarratas bunaidh ar ais (`200`, ceanntásc `Idempotent-Replayed: true`), agus ní ghearrtar táille eile.
- An eochair agus an corp céanna tar éis rith a theip sular shroich sé an tsamhail (`upstream_error` nó `internal_error` ar chur isteach, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): níor táirgeadh tada agus ní ghearrtar táille, mar sin ritheann an iarracht eile an tsamhail arís seachas an teip a thabhairt ar ais.
- An eochair chéanna le corp eile: `409 idempotency_mismatch`.
- Tá raon feidhme na n-eochracha teoranta don eochair API a sheol iad.

## Cá gcónaíonn na comhaid

Cóipeáiltear gach comhad aschuir chuig ár stóráil sula marcáiltear an t-iarratas `succeeded`, mar sin tá na URLanna in `outputs` ar ár n-óstach féin agus is féidir nasc díreach a dhéanamh leo. Is fútsa atá cá fhad a fhanann siad:

| Mód | Cá fhad | Praghas |
|---|---|---|
| `permanent` (réamhshocrú) | Go dtí go scriosann tú iad | 100 creidmheasanna API ($0.10) in aghaidh GB in aghaidh na míosa, gearrtha go laethúil ón iarmhéid API |
| `temporary` | 7 lá, ansin scriosta | Saor in aisce |

- Cinneann socrú an chuntais do na hiarratais nua: an lasc "Coinnigh comhaid go deo" sa [deais](https://doitong.com/developers/dashboard#balance), nó `PATCH https://api.doitong.com/v1/account/storage` le `{"mode": "temporary"}`. Taispeánann `GET https://api.doitong.com/v1/account` é faoi `storage`, leis na bearta a choinníonn tú agus an meastachán míosúil.
- Sáraíonn `?storage=permanent|temporary` ar rith (an argóint `storage` den uirlis MCP `run`) é don rith sin.
- Ní dhéanann athrú an tsocraithe teagmháil riamh leis na comhaid atá agat cheana; scrios iad le [`DELETE /requests/{id}/files`](#delete-files).
- Nuair nach féidir leis an iarmhéid API íoc as stóráil, ní ghearrtar táille agus seoltar ríomhphost chugat: déan breisiú laistigh de 30 lá, nó éiríonn na comhaid choimeádta sealadach agus scriostar iad 7 lá ina dhiaidh sin.

Sa chás annamh go dteipeann ar ár gcóip, bíonn `"stored": false` san iontráil agus is é an URL an ceann bunaidh gearrshaolach: íoslódáil go luath é.