# Dumondas

Ina dumonda è ina clamada d'in model. Ella ha in ID (`req_…`), in status, ses custs en credits API (1000 = 1 USD) e, sch'ella reussescha, las datotecas generadas. Il medem object vegn renvià da mintga endpoint sutvart, per mintga model.

## Chattar in model

Il catalog public da tut 1 496 models è JSON (senza clav necessaria):

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

| Parameter da query | Significaziun |
|---|---|
| `q` | Pleds che ston cumparair tuts en il num, l'ID, il producent u ils tags, per exempel `kling 3`. |
| `category` | In ID da categoria, per exempel `text-to-video` u `upscale`. `GET https://api.doitong.com/v1/categories` enumerescha tut 21 cun lur dumbers. |
| `lab` | Il producent dal model, tenor num u ID, per exempel `Google` u `black-forest-labs`. |
| `family` | In ID da `family` d'ina lingia precedenta: mintga varianta d'in model (pro, fast, image-to-video, …). |
| `mode` | `exact` (il pretsch vegn calculà a partir da l'input), `measured` (a partir da la lunghezza u grondezza da las datotecas d'input), `estimate` (in pretsch stimà per execuziun) u `metered` (facturà tenor l'utilisaziun reala, fin ad in maximum per execuziun). |
| `limit`, `cursor` | Grondezza da la pagina (1 fin 100, standard 50) e `next_cursor` da la pagina precedenta. |

Mintga lingia ha `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` ed in object `price` (vesair [Pretschs](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` agiunta il JSON Schema cumplain da l'input e da l'output, ils nums canonics dals parameters, las reglas da pretsch ed in input d'exempel. Ina `category` u in `mode` nunenconuschent è `400 invalid_parameter`.

## Exequir in model

```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 corp è l'input dal model, in object JSON. Mintga pagina da model enumerescha ses parameters.
- L'input vegn controllà avant che ins incassescha insatge. In input nunvalid returnescha `422 invalid_input` cun il `param` problemà e custa nagut.
- `?wait=N` (fin a 20 secundas) tegna la clamada fin che la dumonda è terminada u il temp è scadì.
- `?webhook_url=https://…` trametta in `POST` signà a quest URL, cur che la dumonda è terminada (vesair [Webhooks](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` u `?storage=temporary` tscherna quant ditg che las datotecas d'output vegnan tegnidas; senza quest parameter vala la configuraziun dal conto (vesair [Nua che las datotecas sa chattan](#storage)).

La resposta è `202 Accepted` durant che la dumonda vegn anc elavurada e `200 OK` cur ch'ella è terminada entaifer il temp d'attesa (u sch'ella è ina repetiziun, vesair sutvart). Ils headers `Location` e `Doitong-Request-Id` cuntegnan l'URL e l'ID da la dumonda.

## Status

Ciclus da vita da la dumonda: `queued` → `running` → `succeeded` | `failed` | `canceled` (final; las dumondas falladas e annulladas vegnan restituìdas).

| Status | Significaziun | Final |
|---|---|---|
| `queued` | Acceptada e chargiada, spetga in worker. `queue_position` po mussar il plaz en la fila. | no |
| `running` | Il model genera. | no |
| `succeeded` | Terminada. `outputs` enumerescha las datotecas. | yes |
| `failed` | Il model u ina limitaziun l'ha interrutta. `error` declera il motiv. Ils credits API vegnan restituids. | yes |
| `canceled` | Annullada avant ch'ella ha producì in resultat. Ils credits API vegnan restituids. | yes |

Ina dumonda che cuzza pli ditg che sia limita da temp fa naufragi cun il code `timeout` e vegn restituida: 15 minutas per maletgs, 60 minutas per video, 30 minutas per audio e tut il rest.

## L'object da la dumonda

```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` è il medem per mintga model: ina entrada per mintga datoteca generada cun `type` (`image`, `video`, `audio`, `file` u `3d`), in `url` en nossa memorisaziun, `content_type` e, sch'enconuschent, `file_size`, `width`, `height`, `duration`.
- `output` è l'object da resultat dal model (ses champs èn enumerads sin mintga pagina da model) cun ils medems URLs.
- `storage` inditgescha co che las datotecas vegnan tegnidas: `mode` (`permanent` u `temporary`), ils `bytes` memorisads, `expires_at` (cur che ina datoteca temporara vegn stizzada, `null` per datotecas permanentas) e `expired` (`true` cur che las datotecas èn svanidas).
- `cost.credits` è il pretsch da la clamada en credits API (`cost.usd` en USD), `cost.charged` quai ch'è vegnì dedrut dal saldo API, `cost.refunded` quai ch'è vegnì restituì. Per in model `metered` è `cost.credits` il maximum tegnì al cumenzament (`cost.held`); cur che l'execuziun reussescha, inditgescha `cost.settled` a quant che l'utilisaziun è muntada e il rest dal maximum è en `cost.refunded` (vesair [Facturà tenor l'utilisaziun](https://doitong.com/developers/docs/pricing#metered)).
- Cur che ina dumonda fa naufragi, è `error` `{ "type": …, "code": …, "message": … }`.

## Leger ina dumonda

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

- `?wait=N` (fin a 20 secundas) fa polling lung: la clamada returnescha immediat che la dumonda è finala, u suenter N secundas cun il stadi actual. Repetir questa clamada è la moda la pli simpla d'attender in resultat.
- `?logs=1` agiunta las lingias dal log da progress dal model (las ultimas 50) sco `logs`.

Ti pos leger mo dumondas da tes agen conto; mintga auter ID è `404 request_not_found`.

## Enumerar dumondas

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

Las pli novas emprimas. `limit` è 1 fin 100 (standard 20), `status` e `model` filters. La resposta è `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; trametta `cursor=<next_cursor>` per la pagina suandanta.

## Annullar ina dumonda

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

- Annullada avant che il model ha cumenzà: il status daventa `canceled`, ils credits API vegnan restituids e ti survegns `200`.
- Gia en generaziun: l'annullaziun vegn transmess e ti survegns `202` cun `"cancel_requested": true`. Sch'il model terminescha tuttina, la dumonda reussescha normalmain ed è chargiada.
- Gia finala: `409 not_cancelable` (ina dumonda gia `canceled` returnescha simplamain `200`).

## Stizzar las datotecas d'ina dumonda

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

Stizza ussa nossas copias da las datotecas d'output da la dumonda e ferma lur cust da memorisaziun. La resposta è l'object da la dumonda cun `storage.expired: true`; ses URLs restan en il protocol, ma na funcziunan betg pli. Ina segunda clamada na mida nagut (`200`). Ina dumonda che vegn anc `queued` u `running` n'ha anc naginas datotecas: `409 request_active`. Basegna `models:run`.

## Idempotenza: repeter senza pajar duas giadas

Las raits fan naufragi. Per repeter in'execuziun senza ristgar, trametta in header `Idempotency-Key` (mintga stringa fin a 255 caracters, unica per operaziun, per exempel tes agen ID d'incumbensa):

- Medema clav e medem corp sco avant: ti survegns la dumonda originala (`200`, header `Idempotent-Replayed: true`) e nagut na vegn chargià danovamain.
- Medema clav e corp suenter in'execuziun ch'ha fatg naufragi avant dad arrivar al model (`upstream_error` u `internal_error` al submit, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): nagut n'è vegnì producì e nagut na vegn chargià, uschia che la repetiziun exequescha puspè il model empè da returnar il naufragi.
- Medema clav cun in auter corp: `409 idempotency_mismatch`.
- Las clavs èn limitadas a la clav API che las ha tramessas.

## Nua che las datotecas sa chattan

Mintga datoteca d'output vegn copiada en nossa memorisaziun avant che la dumonda vegn marcada `succeeded`, perquai che ils URLs en `outputs` èn sin noss hosts e pon vegnir colliads directamain. Quant ditg ch'ellas restan è tia decisiun:

| Mode | Durada | Pretsch |
|---|---|---|
| `permanent` (standard) | Fin che ti las stizzas | 100 credits API ($0,10) per GB e mais, chargiads mintga di dal saldo API |
| `temporary` | 7 dis, lura stizzadas | Gratuit |

- La configuraziun dal conto decida per novas dumondas: l'interruptur "Conservar las datotecas per adina" en il [dashboard](https://doitong.com/developers/dashboard#balance), u `PATCH https://api.doitong.com/v1/account/storage` cun `{"mode": "temporary"}`. `GET https://api.doitong.com/v1/account` l'inditgescha sut `storage`, cun ils bytes che ti tegns e la stimaziun mensila.
- `?storage=permanent|temporary` durant in'execuziun (l'argument `storage` da l'utensil MCP `run`) surpiglia la configuraziun per quella execuziun.
- Midar la configuraziun na pertutga mai datotecas che ti possedas gia; stizza quellas cun [`DELETE /requests/{id}/files`](#delete-files).
- Sch'il saldo API na po betg pajar la memorisaziun, nagut na vegn chargià e ti survegns in e-mail: chargia danovamain entaifer 30 dis, autramain las datotecas tegnidas daventan temporaras e vegnan stizzadas 7 dis pli tard.

En il cas rar che nossa copia fa naufragi, l'entrada ha `"stored": false` e l'URL è quel original, da curta durada: telechargia la datoteca prest.