# Kérések

Egy kérés egy modell egyetlen meghívása. Van egy azonosítója (`req_…`), egy állapota, API-kreditben megadott költsége (1000 = 1 USD), valamint sikeres végrehajtás esetén a generált fájlok. Az alábbi végpontok mindegyike, minden modell esetén ugyanazt az objektumot adja vissza.

## Modell keresése

Az összesen 1496 modellt tartalmazó katalógus nyilvános JSON (nem szükséges kulcs):

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

| Lekérdezési paraméter | Jelentés |
|---|---|
| `q` | Azok a szavak, amelyeknek mind szerepelniük kell a névben, az azonosítóban, a készítőben vagy a címkék között, például `kling 3`. |
| `category` | Egy kategóriaazonosító, például `text-to-video` vagy `upscale`. A `GET https://api.doitong.ru/v1/categories` felsorolja mind a 21 kategóriát a darabszámukkal együtt. |
| `lab` | A modell készítője név vagy azonosító alapján, például `Google` vagy `black-forest-labs`. |
| `family` | Egy korábbi sorból származó `family` azonosító: egy modell minden változata (pro, fast, image-to-video, …). |
| `mode` | `exact` (az ár a bemenet alapján kerül kiszámításra), `measured` (a bemeneti fájlok hosszából vagy méretéből), `estimate` (futtatásonként becsült ár) vagy `metered` (a tényleges használat alapján számlázva, futtatásonkénti maximumig). |
| `limit`, `cursor` | Oldalméret (1–100, alapértelmezett érték: 50) és az előző oldal `next_cursor` értéke. |

Minden sor tartalmazza az `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` mezőket, valamint egy `price` objektumot (lásd: [Árazás](https://doitong.com/developers/docs/pricing#price-objects)). A `GET https://api.doitong.ru/v1/models/{model_id}` hozzáadja a teljes bemeneti és kimeneti JSON Schemat, a kanonikus paraméterneveket, az árszabályokat és egy példa bemenetet. Az ismeretlen `category` vagy `mode` értéke `400 invalid_parameter`.

## Modell futtatása

```bash
curl -X POST "https://api.doitong.ru/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": "..."}'
```

- A törzs a modell bemenete, egy JSON-objektum. Az egyes modelloldalak felsorolják a paramétereit.
- A rendszer a bemenetet minden terhelés előtt ellenőrzi. Érvénytelen bemenet esetén `422 invalid_input` érkezik a hibás `param` mezővel, és semmilyen költség nem merül fel.
- A `?wait=N` (legfeljebb 20 másodpercig) nyitva tartja a hívást, amíg a kérés be nem fejeződik, vagy le nem telik az idő.
- A `?webhook_url=https://…` aláírt POST-kérést küld az URL-re, amikor a kérés befejeződik (lásd: [Webhookok](https://doitong.com/developers/docs/webhooks)).
- A `?storage=permanent` vagy `?storage=temporary` beállítja, hogy meddig maradjanak meg a kimeneti fájlok; enélkül a fiókbeállítás érvényesül (lásd: [Hol találhatók a fájlok](#storage)).

A válasz `202 Accepted`, amíg a kérés feldolgozása folyamatban van, és `200 OK`, ha a várakozási időn belül befejeződött (vagy ha újrajátszásról van szó, lásd lent). A `Location` és a `Doitong-Request-Id` fejlécek tartalmazzák a kérés URL-jét és azonosítóját.

## Állapotok

A kérés életciklusa: `queued` → `running` → `succeeded` | `failed` | `canceled` (végleges; a sikertelen és a megszakított műveletek díját visszatérítjük).

| Állapot | Jelentés | Végleges |
|---|---|---|
| `queued` | Elfogadva és terhelve, feldolgozóra vár. A `queue_position` jelezheti a sorban elfoglalt helyet. | nem |
| `running` | A modell generál. | nem |
| `succeeded` | Elkészült. Az `outputs` felsorolja a fájlokat. | igen |
| `failed` | A modell vagy egy korlát leállította. Az `error` jelzi az okot. Az API-kreditek visszatérítésre kerülnek. | igen |
| `canceled` | Eredmény létrehozása előtt megszakítva. Az API-kreditek visszatérítésre kerülnek. | igen |

Az időkorlátnál tovább futó kérés `timeout` kóddal meghiúsul, és az összeg visszatérítésre kerül: képek esetén 15 perc, videó esetén 60 perc, hang és minden más esetén 30 perc.

## A kérés objektuma

```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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

- Az `outputs` minden modell esetén azonos: minden generált fájlhoz egy bejegyzés tartozik `type` (`image`, `video`, `audio`, `file` vagy `3d`), a tárhelyünkön lévő `url`, `content_type`, valamint ismert érték esetén `file_size`, `width`, `height`, `duration` mezőkkel.
- Az `output` a modell saját eredményobjektuma (mezőit az egyes modelloldalak sorolják fel), ugyanazokkal az URL-ekkel.
- A `storage` jelzi, hogyan vannak megőrizve a fájlok: `mode` (`permanent` vagy `temporary`), a tárolt `bytes`, az `expires_at` (az ideiglenes fájl törlésének időpontja, végleges fájloknál `null`) és az `expired` (`true`, miután a fájlok eltűntek).
- A `cost.credits` a hívás ára API-kreditben (`cost.usd` USD-ben), a `cost.charged` az API-egyenlegből levont összeg, a `cost.refunded` pedig a visszatérített összeg. `metered` modell esetén a `cost.credits` a kezdetkor zárolt maximum (`cost.held`); a sikeres futtatás után a `cost.settled` jelzi a használat költségét, a maximum fennmaradó része pedig a `cost.refunded` értékében szerepel (lásd: [Használatalapú számlázás](https://doitong.com/developers/docs/pricing#metered)).
- Ha egy kérés meghiúsul, az `error` értéke `{ "type": …, "code": …, "message": … }`.

## Kérés lekérése

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

- A `?wait=N` (legfeljebb 20 másodpercig) hosszú lekérdezést végez: a hívás azonnal visszatér, amint a kérés végleges állapotba kerül, vagy N másodperc elteltével az aktuális állapottal. Ennek ismétlése a legegyszerűbb módja az eredmény megvárásának.
- A `?logs=1` hozzáadja a modell előrehaladási naplósorait (az utolsó 50-et) `logs` néven.

Csak a saját fiókod kéréseit olvashatod; minden más azonosító esetén `404 request_not_found` érkezik.

## Kérések listázása

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

A legújabbakkal kezdve. A `limit` értéke 1–100 (alapértelmezett érték: 20), a `status` és a `model` szűr. A válasz: `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; a következő oldalhoz add át a `cursor=<next_cursor>` értéket.

## Kérés megszakítása

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

- Ha a modell elindulása előtt szakítod meg: az állapot `canceled` lesz, az API-kreditek visszatérítésre kerülnek, és `200` választ kapsz.
- Ha a generálás már folyamatban van: a megszakítási kérés továbbításra kerül, és `202` választ kapsz `"cancel_requested": true` értékkel. Ha a modell ennek ellenére befejezi a futást, a kérés normálisan sikeres lesz, és terhelésre kerül.
- Ha a kérés már végleges: `409 not_cancelable` (a már `canceled` állapotú kérés egyszerűen `200` választ ad).

## Kérés fájljainak törlése

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

Azonnal törli a kérés kimeneti fájljainak nálunk tárolt másolatait, és leállítja a tárhely díjának felszámítását. A válasz a kérés objektuma `storage.expired: true` értékkel; az URL-ek megmaradnak a rekordban, de többé nem működnek. A művelet újbóli meghívása nem változtat semmin (`200`). A még `queued` vagy `running` állapotú kérésnek még nincsenek fájljai: `409 request_active`. A `models:run` jogosultság szükséges.

## Idempotencia: újrapróbálás kettős fizetés nélkül

A hálózat meghibásodhat. A futtatás biztonságos újrapróbálásához küldj `Idempotency-Key` fejlécet (legfeljebb 255 karakteres, műveletenként egyedi karakterláncot, például a saját rendelésazonosítódat):

- Ugyanaz a kulcs és ugyanaz a törzs, mint korábban: visszakapod az eredeti kérést (`200`, `Idempotent-Replayed: true` fejléccel), és újabb terhelés nem történik.
- Ugyanaz a kulcs és törzs egy olyan futtatás után, amely még azelőtt meghiúsult, hogy elérte volna a modellt (`upstream_error` vagy `internal_error` beküldéskor, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): semmi nem jött létre, és nem történt terhelés, ezért az újrapróbálás a hiba visszaadása helyett ismét futtatja a modellt.
- Ugyanaz a kulcs eltérő törzzsel: `409 idempotency_mismatch`.
- A kulcsok az őket küldő API-kulcshoz vannak kötve.

## Hol találhatók a fájlok

Minden kimeneti fájl a tárhelyünkre kerül másolásra, mielőtt a kérés `succeeded` állapotba kerül, ezért az `outputs` URL-jei a saját hosztjainkra mutatnak, és közvetlenül hivatkozhatsz rájuk. Te döntöd el, meddig maradjanak meg:

| Mód | Időtartam | Ár |
|---|---|---|
| `permanent` (alapértelmezett) | Amíg nem törlöd őket | 100 API-kredit (0,10 $) GB-onként havonta, naponta az API-egyenlegből terhelve |
| `temporary` | 7 nap, majd törlés | Ingyenes |

- A fiókbeállítás határozza meg az új kérések értékét: a „Fájlok megőrzése örökre” kapcsoló a [vezérlőpulton](https://doitong.com/developers/dashboard#balance), vagy a `PATCH https://api.doitong.ru/v1/account/storage` a `{"mode": "temporary"}` értékkel. A `GET https://api.doitong.ru/v1/account` a `storage` alatt jeleníti meg, a megőrzött bájtokkal és a havi becsléssel együtt.
- A futtatáskor megadott `?storage=permanent|temporary` (az MCP `run` eszköz `storage` argumentuma) felülírja ezt az adott futtatásra.
- A beállítás módosítása soha nem érinti a már meglévő fájlokat; ezeket a [`DELETE /requests/{id}/files`](#delete-files) használatával törölheted.
- Ha az API-egyenleg nem fedezi a tárhely költségét, nem történik terhelés, és e-mailt kapsz: töltsd fel az egyenleget 30 napon belül, különben a megőrzött fájlok ideiglenessé válnak, majd 7 nappal később törlődnek.

Abban a ritka esetben, ha a másolatunk létrehozása sikertelen, a bejegyzésben `"stored": false` szerepel, az URL pedig az eredeti, rövid élettartamú URL lesz: töltsd le hamar.