# Jearaldagat

Jearaldat lea ovtta modealla ovtta gohččun. Das lea id (`req_…`), stáhtus, máksu API-kredihttain (1000 = 1 USD), ja go dat lihkostuvvá, ráhkaduvvon fiillat. Seamma objeakta boahtá buot dás vuollelis loahppačuokkalas, buot modeallaid várás.

## Oza modealla

Buot 1 496 modealla katalog lea almmolaš JSON (čoavdda ii dárbbaš):

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

| Jearaldatparamehter | Mearka |
|---|---|
| `q` | Sániid mat galget buot gávdnot namas, id:s, dahkki namas dahje tagain, omd. `kling 3`. |
| `category` | Okta kategoriija id, omd. `text-to-video` dahje `upscale`. `GET https://api.doitong.com/v1/categories` čájeha buot 21 kategoriijaid lohkosiiguin. |
| `lab` | Modealla dahkki, nama dahje id bokte, omd. `Google` dahje `black-forest-labs`. |
| `family` | `family` id ovddit ráiddus: ovtta modealla buot variašuvnnat (pro, fast, image-to-video, …). |
| `mode` | `exact` (muktohaddi rehkenasto sisa-addi vuođul), `measured` (sisa-addi fiillaid guhkkodaga dahje sturrodaga vuođul), `estimate` (árvvoštallojuvvon haddi juohke geavahandárbbu várás) dahje `metered` (mákso duohta geavaheami vuođul, gitta juohke geavahandárbbu alimus haddái). |
| `limit`, `cursor` | Siidosturrodat (1 gitta 100 rádjái, standárda 50) ja ovddit siiddu `next_cursor`. |

Juohke rásis leat `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` ja `price` objeakta (geahča [Pricing](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.com/v1/models/{model_id}` lasiha olles sisa-addi ja boađusa JSON Schema, kanonalaš paramehternamaid, haddereglaid ja ovdamearkka sisa-addi. Dovdameahttun `category` dahje `mode` lea `400 invalid_parameter`.

## Geavat modealla

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

- Rumaš lea modealla sisa-addi, JSON objeakta. Juohke modeallasiidu listá dan paramehteraid.
- Sisa-addi dárkkistuvvo ovdal go mihkkege máksojuvvo. Invalid sisa-addi máhcaha `422 invalid_input` nugo vahágahtti `param`, ja ii mákso mihkkege.
- `?wait=N` (gitta 20 sekundii) doallá gohččuma dassážii jearaldat geargá dahje áigi nohká.
- `?webhook_url=https://…` sáddá vuolláičállojuvvon POST dan URL:ii go jearaldat geargá (geahča [Webhooks](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` dahje `?storage=temporary` vállje man guhkes boađusfiillat vurkejuvvojit; haga dan kontuvra sajádat gusto (geahča [Gos fiillat leat](#storage)).

Vástádus lea `202 Accepted` dalle go jearaldat bargá ain, ja `200 OK` go dat geargá wait-áiggi siste (dahje go dat lea ođđasit geavahuvvon, geahča vuollelis). `Location` ja `Doitong-Request-Id` vuolábeal-čállagat doibmet jearaldaga URL:n ja id:n.

## Stáhtusat

Ohcamuša eallinvuohki: `queued` → `running` → `succeeded` | `failed` | `canceled` (loahppalaš; boasttuvuođat ja gomihuvvon bivdagat máksojuvvojit ruovttoluotta).

| Stáhtus | Mearka | Loahpalaš |
|---|---|---|
| `queued` | Dohkkehuvvon ja máksojuvvon, bargi vuordimin. `queue_position` sáhttá čájehit báikki vuorrolinnjás. | ii |
| `running` | Modealla ráhkada. | ii |
| `succeeded` | Geargan. `outputs` listá fiillaid. | juo |
| `failed` | Modealla dahje ráddjehus bissehii dan. `error` muitala manne. API-kredihtta máhcaheamit dahkkojuvvojit. | juo |
| `canceled` | Gáhttejuvvon ovdal go boađus ráhkaduvvui. API-kredihtta máhcaheamit dahkkojuvvojit. | juo |

Jearaldat mii bistá guhkit go dan áigeráddjehus, gahččá koden `timeout` ja máhcaheapmi dahkkojuvvo: 15 minuhtta govvii, 60 minuhtta videobargguide, 30 minuhtta jietnii ja buot earáide.

## Jearaldaga objeakta

```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` lea seamma buot modeallaide: okta merket juohke ráhkaduvvon fiilii, `type`-in (`image`, `video`, `audio`, `file` dahje `3d`), `url` min vurkemii, `content_type` ja, go dovdojuvvo, `file_size`, `width`, `height`, `duration`.
- `output` lea modealla iežas boađusobjeakta (dan giettit leat listtus juohke modeallasiiddus) seamma URL:iguin.
- `storage` muitala mo fiillat vurkejuvvojit: `mode` (`permanent` dahje `temporary`), vurkejuvvon `bytes`, `expires_at` (go gaskaboddosaš fiila sihkkojuvvo, `null` bissovaš fiillaid várás) ja `expired` (`true` go fiillat leat váldon eret).
- `cost.credits` lea gohččuma haddi API-kredihttain (`cost.usd` USD:s), `cost.charged` dat mii váldon eret API saldos, `cost.refunded` dat mii máhcahuvvui. `metered` modealla várás lea `cost.credits` álggus doallun alimus haddi (`cost.held`); go bargu lihkostuvvá, `cost.settled` muitala man olu geavaheapmi lei ja alimus haddi báza lea `cost.refunded` (geahča [Mákso geavaheami vuođul](https://doitong.com/developers/docs/pricing#metered)).
- Go jearaldat gahččá, `error` lea `{ "type": …, "code": …, "message": … }`.

## Lohkat jearaldaga

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

- `?wait=N` (gitta 20 sekundii) lea guhkes-vuordán-jearaldat: gohččun máhcaha vástádusa dárbbašlaččat go jearaldat lea loahpalaš, dahje N sekundda maŋŋá dálá diliin. Dán geardduhit lea álkkimus vuohki vuordit boađusa.
- `?logs=1` lasiha modealla ovdáneami logaráidduid (maŋemus 50) `logs` namas.

Sáhtát lohkat du iežat kontuvrra jearaldagaid dušše; eará id lea `404 request_not_found`.

## Listet jearaldagaid

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

Ođđaseamos vuosttažin. `limit` lea 1 gitta 100 rádjái (standárda 20), `status` ja `model` filterejit. Vástádus lea `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; sáddet `cursor=<next_cursor>` boahtte siidui.

## Gáhtte jearaldaga

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

- Gáhttejuvvon ovdal go modealla álggii: stáhtus šaddá `canceled`, API-kredihtta máhcaheapmi dahkkojuvvo, ja oaččut `200`.
- Juó vuolggahuvvame: gáhtten sáddejuvvo ovddos ja oaččut `202` ja `"cancel_requested": true`. Jus modealla liikká geargá, jearaldat lihkostuvvá dábálaččat ja máksojuvvo.
- Juó loahpalaš: `409 not_cancelable` (jearaldat mii lea juo `canceled` máhcaha dušše `200`).

## Sihko jearaldaga fiillaid

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

Sihkkon min máŋgosiid jearaldaga boađusfiillain dál ja bisseha sin vurkenmávssu. Vástádus lea jearaldaga objeakta mas lea `storage.expired: true`; dan URL:at báhcejuvvojit girjegáibádussii muhto eai doaibma šat. Ođđasit gohččun ii rievdat mihkkege (`200`). Jearaldagas mii lea ain `queued` dahje `running` eai leat fiillat vel: `409 request_active`. Dárbbaša `models:run`.

## Idempotency: gearddut haga máksit guokte geardde

Fierpmádat sáhttá gahččat. Vai sáhtát ođđasit geavahit barggu dorvvolaččat, sáddet `Idempotency-Key` vuolábealčállaga (juoga čála gitta 255 mearkka rádjái, iešguđetge doaimma várás, omd. iežat diŋgonummir):

- Seamma čoavdda ja seamma rumaš go ovdal: oaččut ovddit jearaldaga ruovttoluotta (`200`, vuolábealčállagiin `Idempotent-Replayed: true`), iige mihkkege máksojuvvo ođđasit.
- Seamma čoavdda ja rumaš maŋŋá barggu mii gahččai ovdal modealla ollema (`upstream_error` dahje `internal_error` submit:s, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): mihkkege ii ráhkaduvvon iige mihkkege máksojuvvo, nu ahte geardduhus geavaha modealla fas dan sadjái go máhcaha gahččama.
- Seamma čoavdda iešguđetge rumašiin: `409 idempotency_mismatch`.
- Čoavddagat leat ráddjejuvvon dan API-čoavdaga várás mii daid sáddii.

## Gos fiillat leat

Juohke boađusfiila kopierejuvvo min vurkemii ovdal go jearaldat merkojuvvo `succeeded`, nu ahte `outputs` URL:at leat min iežamet hostain ja sáhtát čuovvulit daid njuolgga. Man guhkes dat bázahit lea du válljen:

| Vuohki | Man guhkes | Haddi |
|---|---|---|
| `permanent` (standárda) | Gitta go don daid sihkut | 100 API-kredihtta (0,10 $) juohke GB juohke mánus, máksojuvvon juohke beaivvi API saldos |
| `temporary` | 7 beaivvi, de sihkojuvvon | Nu ahte nu |

- Kontuvra sajádat mearrida ođđa jearaldagaid várás: "Vurke fiillaid álo" heivehus [dashboard](https://doitong.com/developers/dashboard#balance)-siiddus, dahje `PATCH https://api.doitong.com/v1/account/storage` ja `{"mode": "temporary"}`. `GET https://api.doitong.com/v1/account` čájeha dan `storage` vuolde, daiguin bytes:iguin maid vurket ja mánnosaš árvvoštallamiin.
- `?storage=permanent|temporary` geavahandárbbu alde (MCP `run`-reaŋga `storage` argumeanta) badjá dan dán geavahandárbbu várás.
- Sajádaga rievdadeapmi ii goassige guoskka fiillaide maid don juo anát; sihko daid dain `DELETE /requests/{id}/files` bokte (geahča [Sihko fiillaid](#delete-files)).
- Go API saldo ii sáhte máksit vurkemis, ii mákso mihkkege ja oaččut e-poasta: lasáhus 30 beaivvi siste, dahje vurkejuvvon fiillat šaddet gaskaboddosažžan ja sihkojuvvojit 7 beaivvi maŋŋá.

Dávjá hárvenaš dilis, go min máŋgos gahččá, lea merket `"stored": false` ja URL lea álgo, oanehisáigásaš URL: don galgget viežžat dan fargga.