# Iarrtasan

Is e iarrtas aon ghairm de aon mhodail. Tha id (`req_…`), inbhe, cosgais ann an creideasan API (1000 = 1 USD), agus, nuair a shoirbicheas e, na faidhlichean a chaidh a chruthachadh aige. Tillidh an aon nì bho gach puing-crìche gu h-ìosal, airson gach modail.

## Lorg modail

Tha catalog nan 1,496 modail uile na JSON phoblach (chan eil iuchair a dhìth):

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

| Paramadair ceiste | Ciall |
|---|---|
| `q` | Faclan a dh’fheumas nochdadh uile san ainm, id, neach-dèanaimh no tagaichean, mar eisimpleir `kling 3`. |
| `category` | Aon id roinne, mar eisimpleir `text-to-video` no `upscale`. Tha `GET https://api.doitong.com/v1/categories` a’ liostadh nan 21 uile leis na cunntasan aca. |
| `lab` | Neach-dèanaimh a’ mhodail, a rèir ainm no id, mar eisimpleir `Google` no `black-forest-labs`. |
| `family` | Id `family` à sreath roimhe: gach caochladh de aon mhodail (pro, fast, image-to-video, …). |
| `mode` | `exact` (tha a’ phrìs air a h-àireamhachadh bhon in-chur), `measured` (bho fhad no mheud nam faidhlichean in-chuir), `estimate` (prìs thuairmseach gach ruith) no `metered` (cosgais a rèir cleachdaidh fhèin, suas gu àirde gach ruith). |
| `limit`, `cursor` | Meud na duilleige (1 gu 100, bun-roghainn 50) agus `next_cursor` na duilleige roimhe. |

Tha `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` agus nì `price` aig gach sreath (faic [Prìsean](https://doitong.com/developers/docs/pricing#price-objects)). Bidh `GET https://api.doitong.com/v1/models/{model_id}` a’ cur ris an sgeama JSON iomlan airson in-chur is às-chur, na h-ainmean canonical de na paramadairean, riaghailtean na prìse agus eisimpleir de in-chur. Tha `category` no `mode` neo-aithnichte na `400 invalid_parameter`.

## Ruith modail

```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 e corp an iarrtais in-chur a’ mhodail, nì JSON. Tha gach duilleag mhodail a’ liostadh nam paramadairean aige.
- Thèid an in-chur a dhearbhadh mus tèid dad a chur fo chìs. Tillidh in-chur neo-dhligheach `422 invalid_input` leis a’ `param` a rinn a’ mhearachd, agus chan eil cosgais ann.
- Bidh `?wait=N` (suas ri 20 diog) a’ cumail na gairm gus an crìochnaich an t-iarrtas no gus an ruig an ùine a cheann-uidhe.
- Bidh `?webhook_url=https://…` a’ cur POST soidhnichte chun URL sin nuair a chrìochnaicheas an t-iarrtas (faic [Webhooks](https://doitong.com/developers/docs/webhooks)).
- Taghaidh `?storage=permanent` no `?storage=temporary` dè cho fada ’s a thèid na faidhlichean às-chuir a chumail; às aonais sin, bidh roghainn a’ chunntais an sàs (faic [Far a bheil faidhlichean a’ fuireach](#storage)).

Is e `202 Accepted` an fhreagairt fhad ’s a tha an t-iarrtas fhathast ag obair, agus `200 OK` nuair a chrìochnaich e taobh a-staigh na h-ùine feitheimh (no nuair is e ath-chluich a th’ ann, faic gu h-ìosal). Bidh na bannan-cinn `Location` agus `Doitong-Request-Id` a’ giùlan URL agus id an iarrtais.

## Inbhean

Cuairt-beatha an iarrtais: `queued` → `running` → `succeeded` | `failed` | `canceled` (deireannach; thèid fàilligidhean agus cuirmean dheth ath-dhìoladh).

| Inbhe | Ciall | Deireannach |
|---|---|---|
| `queued` | Air gabhail ris agus fo chìs, a’ feitheamh ri neach-obrach. Faodaidh `queue_position` an t-àite san loidhne a shealltainn. | chan eil |
| `running` | Tha am modail a’ gineadh. | chan eil |
| `succeeded` | Deiseil. Tha `outputs` a’ liostadh nam faidhlichean. | tha |
| `failed` | Chuir am modail no crìoch stad air. Tha `error` ag innse carson. Thèid na creideasan API a phàigheadh air ais. | tha |
| `canceled` | Air a chur dheth mus do rinn e toradh. Thèid na creideasan API a phàigheadh air ais. | tha |

Ma ruitheas iarrtas nas fhaide na a chrìoch-ama, fàilligidh e leis a’ chòd `timeout` agus thèid a phàigheadh air ais: 15 mionaid airson ìomhaighean, 60 mionaid airson bhidio, 30 mionaid airson claisneachd agus a h-uile càil eile.

## Nì an iarrtais

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

- Tha `outputs` co-ionann airson gach modail: aon inntrigeadh airson gach faidhle a chaidh a chruthachadh le `type` (`image`, `video`, `audio`, `file` no `3d`), `url` air an stòradh againn, `content_type` agus, nuair a tha fios air, `file_size`, `width`, `height`, `duration`.
- Is e `output` nì toraidh a’ mhodail fhèin (tha na raointean aige air an liostadh air gach duilleag mhodail) leis na h-aon URLan.
- Tha `storage` ag innse mar a thèid na faidhlichean a chumail: `mode` (`permanent` no `temporary`), `bytes` air an stòradh, `expires_at` (nuair a thèid faidhle sealach a sguabadh às, `null` airson feadhainn mhaireannach) agus `expired` (`true` aon uair ’s gu bheil na faidhlichean air falbh).
- Is e `cost.credits` prìs na gairme ann an creideasan API (`cost.usd` ann an USD), `cost.charged` na chaidh a thoirt à iarmad API, agus `cost.refunded` na thill. Airson modail `metered`, is e `cost.credits` an t-suim as motha a chaidh a chumail aig an toiseach (`cost.held`); nuair a shoirbicheas an ruith, tha `cost.settled` ag innse dè an ìre a ràinig an cleachdadh agus tha an còrr den t-suim as motha ann an `cost.refunded` (faic [Cosgais a rèir cleachdaidh](https://doitong.com/developers/docs/pricing#metered)).
- Nuair a dh’fhàillicheas iarrtas, is e `error` `{ "type": …, "code": …, "message": … }`.

## Leugh iarrtas

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

- Bidh `?wait=N` (suas ri 20 diog) a’ dèanamh long-poll: tillidh a’ ghairm cho luath ’s a tha an t-iarrtas deireannach, no às dèidh N diog leis an staid làithrich. ’S e lùbadh air seo an dòigh as sìmplidhe airson feitheamh ri toradh.
- Cuiridh `?logs=1` loidhnichean log adhartais a’ mhodail (na 50 mu dheireadh) ris mar `logs`.

Chan urrainn dhut ach iarrtasan a’ chunntais agad fhèin a leughadh; is e `404 request_not_found` a th’ ann an id sam bith eile.

## Liostaich iarrtasan

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

An fheadhainn as ùire an toiseach. Tha `limit` eadar 1 agus 100 (bun-roghainn 20), agus bidh `status` agus `model` gan sìoladh. Is e an fhreagairt `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; cuir `cursor=<next_cursor>` airson na h-ath dhuilleige.

## Cuir dheth iarrtas

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

- Air a chur dheth mus do thòisich am modail: bidh an inbhe `canceled`, thèid na creideasan API a phàigheadh air ais, agus gheibh thu `200`.
- A’ gineadh mar-thà: thèid an cur dheth a chur air adhart agus gheibh thu `202` le `"cancel_requested": true`. Ma chrìochnaicheas am modail co-dhiù, soirbhichidh an t-iarrtas mar as àbhaist agus thèid cosgais a chur air.
- Deireannach mar-thà: `409 not_cancelable` (tillidh iarrtas a tha `canceled` mar-thà `200` gu sìmplidh).

## Sguab às faidhlichean iarrtais

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

Sguabaidh seo às na lethbhric againn de na faidhlichean às-chuir aig an iarrtas sa bhad agus cuiridh e stad air a’ chosgais stòraidh aca. Is e nì an iarrtais an fhreagairt le `storage.expired: true`; fuirichidh na URLan aige sa chlàr ach chan obraich iad tuilleadh. Cha dèan gairm eile dad (`200`). Chan eil faidhlichean aig iarrtas a tha fhathast `queued` no `running`: `409 request_active`. Feumach air `models:run`.

## Idempotency: ath-oidhirp gun phàigheadh dà thuras

Fàilligidh lìonraidhean. Gus ruith ath-oidhirp gu sàbhailte, cuir bann-cinn `Idempotency-Key` (sreang sam bith suas ri 255 caractar, sònraichte do gach obrachadh, mar eisimpleir id òrduigh agad fhèin):

- An aon iuchair agus an aon chorp ’s a bha roimhe: gheibh thu an t-iarrtas tùsail air ais (`200`, bann-cinn `Idempotent-Replayed: true`), agus cha tèid cosgais a chur air a-rithist.
- An aon iuchair agus corp às dèidh ruith a dh’fhàillig mus do ràinig e am modail (`upstream_error` no `internal_error` nuair a chaidh a chur a-steach, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): cha deach dad a chruthachadh agus chan eil cosgais ann, mar sin ruithidh an ath-oidhirp am modail a-rithist an àite an fhàilligeadh a thilleadh.
- An aon iuchair le corp eadar-dhealaichte: `409 idempotency_mismatch`.
- Tha iuchraichean taobh a-staigh na h-iuchrach API a chuir iad.

## Far a bheil faidhlichean a’ fuireach

Thèid gach faidhle às-chuir a chopaigeadh dhan stòradh againn mus tèid an t-iarrtas a chomharrachadh mar `succeeded`, agus mar sin tha na URLan ann an `outputs` air na h-aoighean againn fhèin agus faodaidh tu ceangal riutha gu dìreach. ’S ann leatsa a tha an roghainn dè cho fada ’s a dh’fhuiricheas iad:

| Modh | Dè cho fada | Prìs |
|---|---|---|
| `permanent` (bun-roghainn) | Gus an sguab thu às iad | 100 creideasan API ($0.10) gach GB gach mìos, air an cur fo chìs gach latha à iarmad API |
| `temporary` | 7 latha, agus an uair sin air an sguabadh às | An-asgaidh |

- Bidh suidheachadh a’ chunntais a’ co-dhùnadh airson iarrtasan ùra: an tionndadh "Cùm faidhlichean gu bràth" anns an [deas-bhòrd](https://doitong.com/developers/dashboard#balance), no `PATCH https://api.doitong.com/v1/account/storage` le `{"mode": "temporary"}`. Tha `GET https://api.doitong.com/v1/account` ga shealltainn fo `storage`, leis na bytes a chumas tu agus an tuairmse mhìosail.
- Bidh `?storage=permanent|temporary` air ruith (an argamaid `storage` den inneal MCP `run`) a’ sgrìobhadh thairis air airson na ruith sin.
- Cha toir atharrachadh an t-suidheachaidh buaidh air faidhlichean a th’ agad mar-thà; sguab às iad le [`DELETE /requests/{id}/files`](#delete-files).
- Nuair nach urrainn do iarmad API pàigheadh airson stòraidh, cha tèid cosgais a chur air agus gheibh thu post-d: dèan cur-ris taobh a-staigh 30 latha, no bidh na faidhlichean glèidhte sealach agus thèid an sguabadh às 7 latha às dèidh sin.

Ma dh’fhàilligeas an lethbhreac againn sa chùis ainneamh, bidh `"stored": false` aig an inntrigeadh agus is e an URL an tè thùsail, gheàrr-ùine: luchdaich a-nuas e a dh’aithghearr.