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):

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

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). A GET https://api.doitong.com/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#

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

• 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).
• 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).

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#

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#

{
  "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"
  }
}

• 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).
• Ha egy kérés meghiúsul, az error értéke { "type": …, "code": …, "message": … }.

Kérés lekérése#

curl "https://api.doitong.com/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#

curl "https://api.doitong.com/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#

curl -X POST "https://api.doitong.com/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#

curl -X DELETE "https://api.doitong.com/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:

• 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, vagy a PATCH https://api.doitong.com/v1/account/storage a {"mode": "temporary"} értékkel. A GET https://api.doitong.com/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 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.