# Mangipena

Jekh mangipen si jekh akharipen jekh modelosko. Les si les jekh id (`req_…`), jekh status, lesko kosto ande API krediti (1000 = 1 USD), thaj, kana ulavol, generirime fajlo. Sa jekh objektos avel palpale katar sa endpointa tele, sakone modelosa.

## Arakh jekh modelo

O katalogo savorre 1,496 modelonqo si publiku JSON (na trebal API klidin):

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

| Query parametro | So phenel |
|---|---|
| `q` | Laven so trubul te aven savorre ande anav, id, kerutno vaj tagur, sar `kling 3`. |
| `category` | Jekh kategorijako id, sar `text-to-video` vaj `upscale`. `GET https://api.doitong.com/v1/categories` sikavel savore 21 lença ginença. |
| `lab` | O kerutno modelosko, anavesa vaj idesa, sar `Google` vaj `black-forest-labs`. |
| `family` | Jekh `family` id katar jekh angluno rindo: sa variantura jekhe modeloske (pro, fast, image-to-video, …). |
| `mode` | `exact` (o kosto ginavel pes katar o inputo), `measured` (katar o lungipen vaj baripen e inputosqe fajlongo), `estimate` (andazime kosto per run) vaj `metered` (paisol pes katar o realno labaripen, dži jekh maksimumo per run). |
| `limit`, `cursor` | Rindosko baripen (1 dži 100, standardno 50) thaj o `next_cursor` katar o anglutno rindo. |

Sakone rindos si `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` thaj jekh `price` objektos (dikh [Pricing](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` dodavel sa inputosko thaj rezultatosko JSON Schema, kanonicka parametronqe anava, olesqe kostonqe regule thaj jekh inputosko egzamplo. Na-zhalido `category` vaj `mode` si `400 invalid_parameter`.

## Phirav jekh modelo

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

- O body si inputo modelosko, jekh JSON objekto. Sakone modelosko lil sikavel lesqe parametra.
- O inputo proverisarel pes anglal so vareso te ovel charge. Na-validno inputo del `422 invalid_input` le doshalutne `param`-esa, thaj na kostol khanchi.
- `?wait=N` (dži 20 sekunda) astarel o akharipen dži o mangipen agoril vaj o vaxt nakhel.
- `?webhook_url=https://…` bičhalel jekh sinjalizime POST ko URL kana o mangipen agoril (dikh [Webhooks](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` vaj `?storage=temporary` kidel sar dugo te ačhen o rezultatosqe fajlo; bi lesko, balanosko setipen applies (dikh [Kaj si o fajlo](#storage)).

O response si `202 Accepted` kana o mangipen mek kerel pes, thaj `200 OK` kana agorisardilo ande o wait (vaj kana si replay, dikh tele). O `Location` thaj `Doitong-Request-Id` headers anen o mangipenosko URL thaj id.

## Statusura

Dživipen e mangipnasqo: `queued` → `running` → `succeeded` | `failed` | `canceled` (finalno; o na-baxtale thaj cancelarime si refundime).

| Status | So phenel | Agoruno |
|---|---|---|
| `queued` | Lijardo thaj charge-ime, astarel jekh worker. `queue_position` shaj sikavel than ande rindo. | na |
| `running` | O modelo generiril. | na |
| `succeeded` | Agorisardo. `outputs` sikavel o fajlo. | va |
| `failed` | O modelo vaj jekh limit astardas les. `error` phenel sosqe. O API krediti iren. | va |
| `canceled` | Cancelime anglal te kerel jekh rezultato. O API krediti iren. | va |

Jekh mangipen so phirel maj dugo katar lesko vaxtosko limit, failol koda `timeout`-esa thaj iren: 15 minuta pентru kipo, 60 minuta pентru video, 30 minuta pентru audio thaj sa aver.

## O mangipenosko objekto

```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` si sajekh savorre modelonqe: jekh entry pентru sakono generirime fajlo, `type`-esa (`image`, `video`, `audio`, `file` vaj `3d`), jekh `url` amaro arakhipneste, `content_type` thaj, kana džanlape, `file_size`, `width`, `height`, `duration`.
- `output` si o modelosko korkori rezultatosko objekto (lesqe fields si sikavde sakone modelosqe lileste) le sajekhe URL-enca.
- `storage` phenel sar o fajlo ačhen: `mode` (`permanent` vaj `temporary`), `bytes` arakhime, `expires_at` (kana jekh temporary fajlo borrarol, `null` pентru permanent) thaj `expired` (`true` kana o fajlo na maj si).
- `cost.credits` si o akharipenosko kosto ande API krediti (`cost.usd` ande USD), `cost.charged` so debitisardilo katar o API balanso, `cost.refunded` so irime. Pентru jekh `metered` modelo `cost.credits` si o maksimumo astardo ko angluno (`cost.held`); kana o run ulavol, `cost.settled` phenel so sas o labaripen thaj o ostatko maksimumosko si ande `cost.refunded` (dikh [Charged by labaripen](https://doitong.com/developers/docs/pricing#metered)).
- Kana jekh mangipen failol, `error` si `{ "type": …, "code": …, "message": … }`.

## Ginav jekh mangipen

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

- `?wait=N` (dži 20 sekunda) si long-poll: o akharipen avel palpale kana o mangipen si agoruno, vaj palal N sekundura le akanutne statussa. Te kerdol lesko loop si o maj lokho drom te ačhes rezultatoske.
- `?logs=1` dodavel o modelosqe progressosqe rinde (o palutne 50) sar `logs`.

Shaj te ginaves numa mangipena tire balanosqe; savorre aver idura si `404 request_not_found`.

## Rindoj o mangipena

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

Neve anglal. `limit` si 1 dži 100 (standardno 20), `status` thaj `model` filtraren. O response si `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; bičhal `cursor=<next_cursor>` pентru o avutno rindo.

## Cancel jekh mangipen

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

- Cancelime anglal te startisarel o modelo: o status ačhel `canceled`, o API krediti iren, thaj reses `200`.
- Kana generiril: o cancel bičhalol pes angleder thaj reses `202` le `"cancel_requested": true`-sa. Kana o modelo pherel leske buća, o mangipen ulavol normalno thaj charge-ol.
- Kana si agoruno: `409 not_cancelable` (jekh mangipen so si već `canceled`, numa del `200`).

## Borrar o fajlo jekhe mangipenosqe

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

Borrarol akanak amare kopije e rezultatosqe fajlongo thaj ačhavel lenqo arakhipnako charge. O response si o mangipenosko objekto le `storage.expired: true`-sa; lesqe URL-a ačhen ande rekord, numa na maj keren. Kana akhares les palem, na kerel khanchi (`200`). Jekh mangipen so mek si `queued` vaj `running` na si les fajlo: `409 request_active`. Kamlel `models:run`.

## Idempotency: palem bi te paisos duvar

Nets failon. Te palem kerel jekh run sigur, bičhal jekh `Idempotency-Key` header (savo string dži 255 karaktera, jekhvar per operacia, sar tiro order id):

- Sako key thaj sajekh body sar anglal: reses o originalno mangipen palem (`200`, header `Idempotent-Replayed: true`), thaj na charge-ol palem.
- Sako key thaj body palal jekh run so failisardilo anglal te resel ko modelo (`upstream_error` vaj `internal_error` ko submit, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): khanchi na sas kerdo thaj khanchi na charge-ol, kadaleste o retry kerel palem o modelo, na te del palpale o failipen.
- Sako key le aver body-esa: `409 idempotency_mismatch`.
- Keys si scoped ko API klidin so bičhaldas len.

## Kaj si o fajlo

Sakono rezultatosko fajlo si kopirime amare arakhipneste anglal o mangipen te avel `succeeded`, kadaleste o URL-a ande `outputs` si amare hostonqe thaj shaj linkis len direktno. Tu kidel sar dugo te ačhen:

| Mode | Kasa dugo | Kosto |
|---|---|---|
| `permanent` (standardno) | Dži tu borrares len | 100 API krediti ($0.10) per GB per minuta, charge-ime diveses katar o API balanso |
| `temporary` | 7 divesa, palal borrarime | Bi pais |

- O balanosko setipen kidel pентru neve mangipena: o "Astar fajlura sa dživdipe" switch ande [dashboard](https://doitong.com/developers/dashboard#balance), vaj `PATCH https://api.doitong.com/v1/account/storage` le `{"mode": "temporary"}`-sa. `GET https://api.doitong.com/v1/account` sikavel les telal `storage`, le bytes-enca so arakhes thaj le mensalno andazesa.
- `?storage=permanent|temporary` ko run (o `storage` argumento e MCP `run` tool-esko) overrides les pентru kodo run.
- Te paruves o setipen, na chudel fajlo so već si tire; borrar len le [`DELETE /requests/{id}/files`](#delete-files)-sa.
- Kana o API balanso na del te paisol pентru arakhipen, khanchi na charge-ol thaj reses email: pher tiro balanso ande 30 divesa, vaj o fajlo ačhade aven temporary thaj borrarena palal 7 divesa.

Kana, redko, amare kopija failol, o entry si le `"stored": false`-sa thaj o URL si originalno, curto-vaktesko: download les sigo.