# Ufroen

Eng Ufro ass een Opruff vun engem Modell. Si huet eng ID (`req_…`), e Status, hir Käschten an API-Kreditter (1000 = 1 USD) an, wann si erfollegräich ass, déi generéiert Dateien. Deeselwechten Objet kënnt vun all Endpunkt hei drënner zeréck, fir all Modell.

## E Modell fannen

De Katalog vun allen 1.496 Modeller ass ëffentlechen JSON (kee Schlëssel néideg):

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

| Ufroparameter | Bedeitung |
|---|---|
| `q` | Wierder, déi all am Numm, an der ID, beim Hiersteller oder an den Tags virkomme mussen, zum Beispill `kling 3`. |
| `category` | Eng Kategorie-ID, zum Beispill `text-to-video` oder `upscale`. `GET https://api.doitong.com/v1/categories` list all 21 mat hiren Zuelen op. |
| `lab` | Den Hiersteller vum Modell, nom Numm oder no der ID, zum Beispill `Google` oder `black-forest-labs`. |
| `family` | Eng `family`-ID aus enger viregter Zeil: all Variant vun engem Modell (pro, fast, image-to-video, …). |
| `mode` | `exact` (de Präis gëtt aus dem Input berechent), `measured` (aus der Längt oder Gréisst vun den Input-Dateien), `estimate` (en geschätzte Präis pro Laf) oder `metered` (no der tatsächlecher Notzung verrechent, bis zu engem Maximum pro Laf). |
| `limit`, `cursor` | Säitegréisst (1 bis 100, Standard 50) an den `next_cursor` vun der viregter Säit. |

All Zeil huet `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` an en `price`-Objet (kuckt [Präisser](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` füügt de komplette JSON Schema fir Input an Output, déi kanonesch Parameternimm, d'Präisreegelen an en Input-Beispill dobäi. Eng onbekannt `category` oder `mode` ass `400 invalid_parameter`.

## E Modell lafen loossen

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

- De Kierper ass de Modell-Input, en JSON-Objet. All Modell-Säit list seng Parameteren op.
- Den Input gëtt gepréift, ier eppes verrechent gëtt. En ongültegen Input gëtt mat `422 invalid_input` an dem problematesche `param` zeréckginn a kascht näischt.
- `?wait=N` (bis zu 20 Sekonnen) hält den Opruff, bis d'Ufro fäerdeg ass oder d'Zäit ofgelaf ass.
- `?webhook_url=https://…` schéckt e signéierten POST un dës URL, wann d'Ufro fäerdeg ass (kuckt [Webhooks](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` oder `?storage=temporary` wielt, wéi laang d'Output-Dateie gespäichert ginn; ouni dëst gëllt d'Kontastellung (kuckt [Wou Dateie leien](#storage)).

D'Äntwert ass `202 Accepted`, soulaang d'Ufro nach leeft, an `200 OK`, wann si bannent der Waardezäit fäerdeg gouf (oder wann et e Replay ass, kuckt hei drënner). D'Header `Location` an `Doitong-Request-Id` enthalen d'Ufro-URL an d'ID.

## Statusen

Liewenszyklus vun enger Ufro: `queued` → `running` → `succeeded` | `failed` | `canceled` (final; feelgeschloen a ofgebrach Ufroe ginn rembourséiert).

| Status | Bedeitung | Final |
|---|---|---|
| `queued` | Akzeptéiert a verrechent, waart op en Aarbechter. `queue_position` kann d'Positioun an der Rei weisen. | nee |
| `running` | De Modell generéiert. | nee |
| `succeeded` | Fäerdeg. `outputs` list d'Dateien op. | jo |
| `failed` | De Modell oder eng Limit huet en ofgebrach. `error` erkläert firwat. D'API-Kreditter ginn rembourséiert. | jo |
| `canceled` | Ofgebrach, ier e Resultat produzéiert gouf. D'API-Kreditter ginn rembourséiert. | jo |

Eng Ufro, déi méi laang leeft wéi hir Zäitlimit, schléit mam Code `timeout` feel a gëtt rembourséiert: 15 Minutte fir Biller, 60 Minutte fir Video, 30 Minutte fir Audio an alles anescht.

## Den Ufro-Objet

```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` ass fir all Modell d'selwecht: een Element pro generéierter Datei mat `type` (`image`, `video`, `audio`, `file` oder `3d`), enger `url` an eiser Späicherung, `content_type` an, wann bekannt, `file_size`, `width`, `height`, `duration`.
- `output` ass den eegene Resultat-Objet vum Modell (seng Felder sinn op all Modell-Säit opgelëscht) mat deeselwechten URLen.
- `storage` weist, wéi d'Dateie gespäichert ginn: `mode` (`permanent` oder `temporary`), gespäichert `bytes`, `expires_at` (wann eng temporär Datei geläscht gëtt, `null` fir permanent Dateien) an `expired` (`true`, soubal d'Dateie fort sinn).
- `cost.credits` ass de Präis vum Opruff an API-Kreditter (`cost.usd` an USD), `cost.charged` ass de Betrag, dee vum API-Saldo ofgebucht gouf, `cost.refunded` dee Betrag, dee zeréckkoum. Bei engem `metered`-Modell ass `cost.credits` de Maximum, deen um Ufank reservéiert gëtt (`cost.held`); wann de Laf erfollegräich ass, weist `cost.settled`, wéi héich d'Notzung war, an de Rescht vum Maximum steet an `cost.refunded` (kuckt [No Notzung verrechent](https://doitong.com/developers/docs/pricing#metered)).
- Wann eng Ufro feelerschléit, ass `error` `{ "type": …, "code": …, "message": … }`.

## Eng Ufro liesen

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

- `?wait=N` (bis zu 20 Sekonnen) mécht Long-Polling: den Opruff gëtt zeréck, soubal d'Ufro final ass, oder no N Sekonne mam aktuelle Status. Dëst an enger Schleef ze widderhuelen ass deen einfachste Wee, op e Resultat ze waarden.
- `?logs=1` füügt d'Fortschrëtts-Logzeile vum Modell (déi lescht 50) als `logs` dobäi.

Dir kënnt nëmmen Ufroe vun Ärem eegene Kont liesen; all aner ID ass `404 request_not_found`.

## Ufroen oplëschten

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

Déi neist fir d'éischt. `limit` ass 1 bis 100 (Standard 20), `status` a `model` filteren. D'Äntwert ass `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; gitt `cursor=<next_cursor>` fir déi nächst Säit un.

## Eng Ufro ofbriechen

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

- Ofgebrach, ier de Modell gestart ass: De Status gëtt `canceled`, d'API-Kreditter ginn rembourséiert, an Dir kritt `200`.
- Scho beim Generéieren: Den Ofbriech-Opruff gëtt weidergeleet an Dir kritt `202` mat `"cancel_requested": true`. Wann de Modell trotzdeem fäerdeg gëtt, ass d'Ufro normal erfollegräich a gëtt verrechent.
- Scho final: `409 not_cancelable` (eng Ufro, déi scho `canceled` ass, gëtt einfach mat `200` zeréckginn).

## D'Dateie vun enger Ufro läschen

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

Läscht elo eis Kopië vun den Output-Dateie vun der Ufro a stoppt hir Späicherkäschten. D'Äntwert ass den Ufro-Objet mat `storage.expired: true`; seng URLen bleiwen am Record, funktionéieren awer net méi. En zweeten Opruff ännert näischt (`200`). Eng Ufro, déi nach `queued` oder `running` ass, huet nach keng Dateien: `409 request_active`. Erfordert `models:run`.

## Idempotenz: widderhuelen ouni zweemol ze bezuelen

Netzwierker falen aus. Fir e Laf sécher ze widderhuelen, schéckt en `Idempotency-Key`-Header (e String mat bis zu 255 Zeechen, eenzegaarteg pro Operatioun, zum Beispill Är eegen Bestell-ID):

- Dee selwechte Schlëssel an dee selwechte Kierper wéi virdrun: Dir kritt déi ursprénglech Ufro zeréck (`200`, Header `Idempotent-Replayed: true`), an et gëtt näischt nach eng Kéier verrechent.
- Dee selwechte Schlëssel a Kierper no engem Laf, dee feelgeschloen ass, ier en de Modell erreecht huet (`upstream_error` oder `internal_error` beim Ofschécken, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): Et gouf näischt produzéiert an näischt verrechent, dofir leeft d'Widderhuelung de Modell nach eng Kéier amplaz de Feeler zeréckzeginn.
- Dee selwechte Schlëssel mat engem anere Kierper: `409 idempotency_mismatch`.
- Schlëssele si limitéiert op den API-Schlëssel, dee si geschéckt huet.

## Wou Dateie leien

All Output-Datei gëtt virum Status `succeeded` an eis Späicherung kopéiert, dofir leien d'URLen an `outputs` op eisen eegenen Hosten an Dir kënnt direkt op si verlinken. Wéi laang si bleiwen, decidéiert Dir:

| Modus | Dauer | Präis |
|---|---|---|
| `permanent` (Standard) | Bis Dir se läscht | 100 API-Kreditter (0,10 $) pro GB pro Mount, all Dag vum API-Saldo verrechent |
| `temporary` | 7 Deeg, duerno geläscht | Gratis |

- D'Kontastellung gëllt fir nei Ufroen: de Schalter "Fichiere fir ëmmer behalen" am [Dashboard](https://doitong.com/developers/dashboard#balance), oder `PATCH https://api.doitong.com/v1/account/storage` mat `{"mode": "temporary"}`. `GET https://api.doitong.com/v1/account` weist se ënner `storage`, zesumme mat de Bytes, déi Dir behält, an der monatlecher Schätzung.
- `?storage=permanent|temporary` bei engem Laf (d'Argument `storage` vum MCP-Tool `run`) iwwerschreift se fir dee Laf.
- D'Ännere vun der Astellung beréiert ni Dateien, déi Dir scho hutt; läscht déi mat [`DELETE /requests/{id}/files`](#delete-files).
- Wann den API-Saldo d'Späicherung net bezuele kann, gëtt näischt verrechent an Dir kritt eng E-Mail: lued bannent 30 Deeg op, soss ginn déi behalen Dateien temporär a 7 Deeg méi spéit geläscht.

Am rare Fall, datt eis Kopie feelerschléit, huet den Element `"stored": false` an d'URL ass déi ursprénglech, kuerzlieweg URL: lued d'Datei séier erof.