Požadavky

Požadavek je jedno volání jednoho modelu. Má id (req_…), stav, cenu v API kreditech (1000 = 1 USD) a po úspěšném dokončení vygenerované soubory. Stejný objekt se vrací z každého níže uvedeného endpointu pro každý model.

Najít model#

Katalog všech 1 496 modelů je veřejný JSON (klíč není potřeba):

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

Každý řádek obsahuje id, name, lab, category, family, summary, tags, output_kind, docs_url a objekt price (viz Ceník). GET https://api.doitong.com/v1/models/{model_id} přidává úplné vstupní a výstupní JSON Schema, kanonické názvy parametrů, pravidla účtování a příklad vstupu. Neznámá hodnota category nebo mode vrací 400 invalid_parameter.

Spustit model#

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

• Tělo požadavku je vstup modelu, objekt JSON. Každá stránka modelu uvádí jeho parametry.
• Vstup se kontroluje před účtováním. Neplatný vstup vrací 422 invalid_input s problematickým param a nic nestojí.
• ?wait=N (až 20 sekund) podrží volání, dokud požadavek neskončí nebo nevyprší čas.
• ?webhook_url=https://… pošle na danou URL podepsaný POST, jakmile požadavek skončí (viz Webhooky).
• ?storage=permanent nebo ?storage=temporary určuje, jak dlouho se uchovávají výstupní soubory; bez tohoto parametru se použije nastavení účtu (viz Kde jsou soubory uložené).

Odpověď je 202 Accepted, dokud požadavek stále probíhá, a 200 OK, když skončil během čekání (nebo jde o opakované doručení, viz níže). Hlavičky Location a Doitong-Request-Id obsahují URL a id požadavku.

Stavy#

Požadavek, který běží déle než povolený čas, selže s kódem timeout a částka se refunduje: 15 minut pro obrázky, 60 minut pro video, 30 minut pro zvuk a vše ostatní.

Objekt požadavku#

{
  "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 má stejnou podobu pro každý model: jednu položku pro každý vygenerovaný soubor s type (image, video, audio, file nebo 3d), url v našem úložišti, content_type a, pokud jsou známy, file_size, width, height, duration.
• output je vlastní objekt výsledku modelu (jeho pole jsou uvedena na stránce každého modelu) se stejnými URL.
• storage uvádí, jak se soubory uchovávají: mode (permanent nebo temporary), uložené bytes, expires_at (kdy se dočasný soubor smaže, u trvalých souborů null) a expired (true, jakmile soubory zmizí).
• cost.credits je cena volání v API kreditech (cost.usd v USD), cost.charged částka stržená ze zůstatku API, cost.refunded vrácená částka. U modelu metered je cost.credits maximální částka zablokovaná na začátku (cost.held); po úspěšném dokončení cost.settled uvádí skutečné využití a zbytek maximální částky je v cost.refunded (viz Účtování podle využití).
• Když požadavek selže, error je { "type": …, "code": …, "message": … }.

Načíst požadavek#

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

• ?wait=N (až 20 sekund) používá dlouhé dotazování: volání se vrátí, jakmile je požadavek dokončen, nebo po N sekundách s aktuálním stavem. Opakované volání je nejjednodušší způsob, jak čekat na výsledek.
• ?logs=1 přidá řádky protokolu průběhu modelu (posledních 50) jako logs.

Můžete načítat pouze požadavky vlastního účtu; jakékoli jiné id je 404 request_not_found.

Vypsat požadavky#

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

Od nejnovějších. limit je 1 až 100 (výchozí 20), status a model filtrují výsledky. Odpověď je { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; pro další stránku předejte cursor=<next_cursor>.

Zrušit požadavek#

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

• Zrušeno před spuštěním modelu: stav se změní na canceled, API kredity se refundují a obdržíte 200.
• Probíhá generování: zrušení se předá dál a obdržíte 202 s "cancel_requested": true. Pokud model přesto dokončí práci, požadavek normálně uspěje a bude zpoplatněn.
• Již dokončené: 409 not_cancelable (požadavek, který je již canceled, jednoduše vrátí 200).

Smazat soubory požadavku#

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

Okamžitě smaže naše kopie výstupních souborů požadavku a zastaví účtování úložiště. Odpověď je objekt požadavku s storage.expired: true; jeho URL zůstanou v záznamu, ale přestanou fungovat. Opakované volání nic nezmění (200). Požadavek ve stavu queued nebo running zatím žádné soubory nemá: 409 request_active. Vyžaduje models:run.

Idempotence: opakování bez dvojího účtování#

Sítě selhávají. Chcete-li spuštění bezpečně zopakovat, odešlete hlavičku Idempotency-Key (libovolný řetězec o délce až 255 znaků, jedinečný pro každou operaci, například vlastní id objednávky):

• Stejný klíč a stejné tělo jako předtím: obdržíte původní požadavek (200, hlavička Idempotent-Replayed: true) a nic se znovu neúčtuje.
• Stejný klíč a tělo po spuštění, které selhalo před předáním modelu (upstream_error nebo internal_error při odeslání, insufficient_credits, budget_exceeded, too_many_inflight): nic nebylo vytvořeno a nic se neúčtuje, takže opakovaný požadavek znovu spustí model místo vrácení chyby.
• Stejný klíč s jiným tělem: 409 idempotency_mismatch.
• Klíče platí pro API klíč, který je odeslal.

Kde jsou soubory uložené#

Každý výstupní soubor se před označením požadavku jako succeeded zkopíruje do našeho úložiště, takže URL v outputs vedou na naše vlastní hostitele a můžete na ně přímo odkazovat. Jak dlouho zůstanou uložené, je na vás:

• Nastavení účtu určuje chování nových požadavků: přepínač „Uchovávat soubory navždy“ v dashboardu, nebo PATCH https://api.doitong.com/v1/account/storage s {"mode": "temporary"}. GET https://api.doitong.com/v1/account ho zobrazuje pod storage spolu s počtem uchovávaných bajtů a měsíčním odhadem.
• ?storage=permanent|temporary při spuštění (argument storage nástroje MCP run) toto nastavení pro dané spuštění přepíše.
• Změna nastavení se nikdy nedotkne souborů, které již máte; smažte je pomocí DELETE /requests/{id}/files.
• Když zůstatek API nemůže úložiště zaplatit, nic se neúčtuje a obdržíte e-mail: dobijte účet do 30 dnů, jinak se uchovávané soubory změní na dočasné a o 7 dnů později se smažou.

Ve vzácném případě, že naše kopie selže, má položka "stored": false a URL je původní s krátkou platností: stáhněte ji co nejdříve.