# Talbiet

Talba hija sejħa waħda ta' mudell wieħed. Għandha id (`req_…`), status, l-ispiża tagħha fi krediti tal-API (1000 = 1 USD), u, meta tirnexxi, il-fajls iġġenerati. L-istess oġġett jiġi lura minn kull endpoint hawn taħt, għal kull mudell.

## Sib mudell

Il-katalgu tal-mudelli kollha ta' 1,496 huwa JSON pubbliku (mhi meħtieġa l-ebda ċavetta):

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

| Parametru tal-mistoqsija | Tifsira |
|---|---|
| `q` | Kliem li kollha jridu jidhru fl-isem, l-id, il-produttur jew it-tags, pereżempju `kling 3`. |
| `category` | Id ta' kategorija waħda, pereżempju `text-to-video` jew `upscale`. `GET https://api.doitong.com/v1/categories` jelenka l-21 kollha flimkien mal-għadd tagħhom. |
| `lab` | Il-produttur tal-mudell, bl-isem jew bl-id, pereżempju `Google` jew `black-forest-labs`. |
| `family` | Id ta' `family` minn ringiela preċedenti: kull varjant ta' mudell wieħed (pro, fast, image-to-video, …). |
| `mode` | `exact` (il-prezz jiġi kkalkulat mill-input), `measured` (mit-tul jew mid-daqs tal-fajls tal-input), `estimate` (prezz stmat għal kull eżekuzzjoni) jew `metered` (jitħallas skont l-użu attwali, sa massimu għal kull eżekuzzjoni). |
| `limit`, `cursor` | Daqs tal-paġna (1 sa 100, prestabbilit 50) u l-`next_cursor` tal-paġna preċedenti. |

Kull ringiela għandha `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` u oġġett `price` (ara [Ipprezzar](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` iżid l-input u l-output JSON Schema sħaħ, l-ismijiet kanoniċi tal-parametri, ir-regoli tal-prezz u eżempju ta' input. `category` jew `mode` mhux magħruf jagħti `400 invalid_parameter`.

## Ħaddem mudell

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

- Il-korp huwa l-input tal-mudell, oġġett JSON. Kull paġna tal-mudell telenka l-parametri tiegħu.
- L-input jiġi vverifikat qabel ma jitħallas xejn. Input mhux validu jagħti `422 invalid_input` bil-`param` li kkawża l-problema, u ma jiswa xejn.
- `?wait=N` (sa 20 sekonda) iżomm is-sejħa sakemm tispiċċa t-talba jew jgħaddi l-ħin.
- `?webhook_url=https://…` jibgħat POST iffirmat lil dak l-URL meta tispiċċa t-talba (ara [Webhooks](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` jew `?storage=temporary` jagħżel kemm jinżammu l-fajls tal-output; mingħajru japplika l-issettjar tal-kont (ara [Fejn jinżammu l-fajls](#storage)).

It-tweġiba hija `202 Accepted` waqt li t-talba tkun għadha qed taħdem, u `200 OK` meta tkun spiċċat matul il-ħin ta' stennija (jew meta tkun replay, ara hawn taħt). Il-headers `Location` u `Doitong-Request-Id` iġorru l-URL u l-id tat-talba.

## Statusijiet

Ċiklu tal-ħajja tat-talba: `queued` → `running` → `succeeded` | `failed` | `canceled` (finali; it-talbiet falluti u kkanċellati jiġu rimborżati).

| Status | Tifsira | Finali |
|---|---|---|
| `queued` | Aċċettata u mħallsa, qed tistenna ħaddiem. `queue_position` jista' juri l-pożizzjoni fil-kju. | le |
| `running` | Il-mudell qed jiġġenera. | le |
| `succeeded` | Lesta. `outputs` jelenka l-fajls. | iva |
| `failed` | Il-mudell jew limitu waqqafha. `error` jgħid għaliex. Il-krediti tal-API jiġu rifużi. | iva |
| `canceled` | Ikkanċellata qabel ma pproduċiet riżultat. Il-krediti tal-API jiġu rifużi. | iva |

Talba li ddum aktar mil-limitu ta' ħin tagħha tfalli bil-kodiċi `timeout` u tiġi rifuża: 15-il minuta għall-immaġnijiet, 60 minuta għall-vidjo, 30 minuta għall-awdjo u kull ħaġa oħra.

## L-oġġett tat-talba

```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` huwa l-istess għal kull mudell: entrata waħda għal kull fajl iġġenerat b'`type` (`image`, `video`, `audio`, `file` jew `3d`), `url` fil-ħażna tagħna, `content_type` u, meta magħrufin, `file_size`, `width`, `height`, `duration`.
- `output` huwa l-oġġett tar-riżultat tal-mudell innifsu (l-oqsma tiegħu huma elenkati fuq kull paġna tal-mudell) bl-istess URLs.
- `storage` jgħid kif jinżammu l-fajls: `mode` (`permanent` jew `temporary`), `bytes` maħżuna, `expires_at` (meta jitħassar fajl temporanju, `null` għal dawk permanenti) u `expired` (`true` ladarba l-fajls ikunu spiċċaw).
- `cost.credits` huwa l-prezz tas-sejħa fi krediti tal-API (`cost.usd` f'USD), `cost.charged` dak li ġie ddebitat mill-bilanċ tal-API, `cost.refunded` dak li ġie rritornat. Għal mudell `metered`, `cost.credits` huwa l-massimu miżmum fil-bidu (`cost.held`); ladarba l-eżekuzzjoni tirnexxi, `cost.settled` jgħid kemm kien l-użu u l-bqija tal-massimu jkun f'`cost.refunded` (ara [Imħallas skont l-użu](https://doitong.com/developers/docs/pricing#metered)).
- Meta talba tfalli, `error` huwa `{ "type": …, "code": …, "message": … }`.

## Aqra talba

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

- `?wait=N` (sa 20 sekonda) jagħmel long-polling: is-sejħa tirritorna hekk kif it-talba tkun finali, jew wara N sekondi bl-istat attwali. Li tirrepeti dan huwa l-aktar mod sempliċi biex tistenna riżultat.
- `?logs=1` iżid il-linji tal-log tal-progress tal-mudell (l-aħħar 50) bħala `logs`.

Tista' taqra biss it-talbiet tal-kont tiegħek; kwalunkwe id ieħor huwa `404 request_not_found`.

## Elenka t-talbiet

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

L-aktar ġodda l-ewwel. `limit` huwa 1 sa 100 (prestabbilit 20), u `status` u `model` jiffiltraw. It-tweġiba hija `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; għaddi `cursor=<next_cursor>` għall-paġna li jmiss.

## Ikkanċella talba

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

- Ikkanċellata qabel ma beda l-mudell: l-istatus isir `canceled`, il-krediti tal-API jiġu rifużi, u tirċievi `200`.
- Diġà qed tiġi ġġenerata: il-kanċellazzjoni tintbagħat lill-mudell u tirċievi `202` b'`"cancel_requested": true`. Jekk il-mudell xorta jispiċċa, it-talba tirnexxi normalment u titħallas.
- Diġà finali: `409 not_cancelable` (talba li diġà hija `canceled` sempliċement tirritorna `200`).

## Ħassar il-fajls ta' talba

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

Tħassar minnufih il-kopji tagħna tal-fajls tal-output tat-talba u twaqqaf il-ħlas tal-ħażna tagħhom. It-tweġiba hija l-oġġett tat-talba b'`storage.expired: true`; l-URLs tagħha jibqgħu fir-rekord iżda ma jibqgħux jaħdmu. Li ssejħilha mill-ġdid ma jbiddel xejn (`200`). Talba li għadha `queued` jew `running` għad m'għandhiex fajls: `409 request_active`. Teħtieġ `models:run`.

## Idempotenza: erġa' pprova mingħajr ma tħallas darbtejn

In-netwerks ifallu. Biex terġa' tipprova eżekuzzjoni b'mod sigur, ibgħat header `Idempotency-Key` (kwalunkwe string sa 255 karattru, uniku għal kull operazzjoni, pereżempju l-id tal-ordni tiegħek):

- L-istess ċavetta u l-istess korp bħal qabel: tirċievi t-talba oriġinali lura (`200`, header `Idempotent-Replayed: true`), u ma jitħallas xejn mill-ġdid.
- L-istess ċavetta u korp wara eżekuzzjoni li falliet qabel ma waslet għand il-mudell (`upstream_error` jew `internal_error` waqt is-submit, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): ma ġie prodott xejn u ma tħallas xejn, għalhekk il-prova mill-ġdid tħaddem il-mudell mill-ġdid minflok tirritorna l-falliment.
- L-istess ċavetta b'korp differenti: `409 idempotency_mismatch`.
- Iċ-ċwievet huma marbuta maċ-ċavetta API li bagħthom.

## Fejn jinżammu l-fajls

Kull fajl tal-output jiġi kkupjat fil-ħażna tagħna qabel ma t-talba tiġi mmarkata `succeeded`, għalhekk l-URLs f'`outputs` ikunu fuq il-hosts tagħna stess u tista' torbothom direttament. Int tagħżel kemm jibqgħu:

| Modalità | Kemm idumu | Prezz |
|---|---|---|
| `permanent` (prestabbilit) | Sakemm tħassarhom | 100 krediti tal-API ($0.10) għal kull GB fix-xahar, iċċarġjati kuljum mill-bilanċ tal-API |
| `temporary` | 7 jum, imbagħad jitħassru | B'xejn |

- L-issettjar tal-kont jiddeċiedi għal talbiet ġodda: is-swiċċ "Żomm il-fajls għal dejjem" fid-[dashboard](https://doitong.com/developers/dashboard#balance), jew `PATCH https://api.doitong.com/v1/account/storage` b'`{"mode": "temporary"}`. `GET https://api.doitong.com/v1/account` jurih taħt `storage`, flimkien mal-bytes li żżomm u l-istima ta' kull xahar.
- `?storage=permanent|temporary` fuq eżekuzzjoni (l-argument `storage` tal-għodda MCP `run`) jegħlebha għal dik l-eżekuzzjoni.
- It-tibdil tal-issettjar qatt ma jmiss fajls li diġà għandek; ħassarhom b'[`DELETE /requests/{id}/files`](#delete-files).
- Meta l-bilanċ tal-API ma jkunx jista' jħallas għall-ħażna, ma jitħallas xejn u tirċievi email: agħmel top-up fi żmien 30 jum, inkella l-fajls miżmuma jsiru temporanji u jitħassru 7 jum wara.

Fil-każ rari li l-kopja tagħna tfalli, l-entrata jkollha `"stored": false` u l-URL tkun dik oriġinali, li ddum għal żmien qasir: niżżilha dalwaqt.