# Beiðnir Beiðni er eitt kall á eitt líkan. Hún hefur auðkenni (`req_…`), stöðu, kostnað í API-inneign (1000 = 1 USD) og, þegar hún heppnast, mynduðu skrárnar. Sami hlutur kemur til baka frá öllum endapunktunum hér fyrir neðan, fyrir hvert líkan. ## Finna líkan Vörulisti allra 1.496 líkananna er opinbert JSON (ekki þarf lykil): ```bash curl "https://api.doitong.ru/v1/models?category=text-to-video&lab=Google&limit=20" ``` | Færibreyta fyrir fyrirspurn | Merking | |---|---| | `q` | Orð sem öll verða að koma fyrir í heiti, auðkenni, framleiðanda eða tögum, til dæmis `kling 3`. | | `category` | Eitt flokksauðkenni, til dæmis `text-to-video` eða `upscale`. `GET https://api.doitong.ru/v1/categories` sýnir öll 21 með fjölda þeirra. | | `lab` | Framleiðandi líkansins, eftir heiti eða auðkenni, til dæmis `Google` eða `black-forest-labs`. | | `family` | `family`-auðkenni úr fyrri röð: hvert afbrigði eins líkans (pro, fast, image-to-video, …). | | `mode` | `exact` (verðið er reiknað út frá inntakinu), `measured` (út frá lengd eða stærð inntaksskránna), `estimate` (áætlað verð fyrir hverja keyrslu) eða `metered` (rukkað eftir raunnotkun, allt að hámarki fyrir hverja keyrslu). | | `limit`, `cursor` | Síðustærð (1 til 100, sjálfgefið 50) og `next_cursor` úr fyrri síðu. | Hver röð hefur `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` og `price`- hlut (sjá [Verðlagning](https://doitong.com/developers/docs/pricing#price-objects)). `GET https://api.doitong.ru/v1/models/{model_id}` bætir við fullu JSON Schema fyrir inntak og úttak, stöðluðum færibreytuheitum, verðreglunum og dæmi um inntak. Óþekkt `category` eða `mode` skilar `400 invalid_parameter`. ## Keyra líkan ```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": "..."}' ``` - Meginmálið er inntak líkansins, JSON-hlutur. Hver líkanasíða sýnir færibreytur þess. - Inntakið er yfirfarið áður en nokkuð er rukkað. Ógilt inntak skilar `422 invalid_input` með vandræðalegu `param` og kostar ekkert. - `?wait=N` (allt að 20 sekúndur) heldur kallinu opnu þar til beiðninni lýkur eða tíminn rennur út. - `?webhook_url=https://…` sendir undirritað `POST` á URL-ið þegar beiðninni lýkur (sjá [Vefkrókar](https://doitong.com/developers/docs/webhooks)). - `?storage=permanent` eða `?storage=temporary` velur hversu lengi úttaksskrárnar eru geymdar; án þess gildir stilling reikningsins (sjá [Hvar skrár eru geymdar](#storage)). Svarið er `202 Accepted` meðan beiðnin er enn í vinnslu og `200 OK` þegar henni lauk innan biðtímans (eða þegar um endurspilun er að ræða, sjá hér fyrir neðan). Hausarnir `Location` og `Doitong-Request-Id` innihalda URL og auðkenni beiðninnar. ## Stöður Lífsferill beiðni: `queued` → `running` → `succeeded` | `failed` | `canceled` (lokið; gjald fyrir misheppnuð og aflýst verk er endurgreitt). | Staða | Merking | Lokastöðutilvik | |---|---|---| | `queued` | Samþykkt og rukkað, bíður eftir vinnsluaðila. `queue_position` getur sýnt sætið í röðinni. | nei | | `running` | Líkanið er að mynda úttakið. | nei | | `succeeded` | Lokið. `outputs` sýnir skrárnar. | já | | `failed` | Líkanið eða takmörk stöðvuðu hana. `error` segir hvers vegna. API-inneignin er endurgreidd. | já | | `canceled` | Hætt við áður en niðurstaða varð til. API-inneignin er endurgreidd. | já | Beiðni sem keyrir lengur en tímamörk hennar nær ekki fram að ganga með kóðanum `timeout` og er endurgreidd: 15 mínútur fyrir myndir, 60 mínútur fyrir myndband, 30 mínútur fyrir hljóð og allt annað. ## Beiðnahluturinn ```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" } } ``` - `outputs` er eins fyrir hvert líkan: ein færsla fyrir hverja myndaða skrá með `type` (`image`, `video`, `audio`, `file` eða `3d`), `url` í geymslu okkar, `content_type` og, þegar það er þekkt, `file_size`, `width`, `height`, `duration`. - `output` er eigin niðurstöðuhlutur líkansins (reitir hans eru taldir upp á hverri líkanasíðu) með sömu URL-slóðum. - `storage` segir hvernig skrárnar eru geymdar: `mode` (`permanent` eða `temporary`), geymd `bytes`, `expires_at` (þegar tímabundinni skrá er eytt, `null` fyrir varanlegar) og `expired` (`true` þegar skrárnar eru horfnar). - `cost.credits` er verð kallsins í API-inneign (`cost.usd` í USD), `cost.charged` það sem var dregið af API-stöðunni, `cost.refunded` það sem kom til baka. Fyrir `metered`-líkan er `cost.credits` hámarkið sem haldið er eftir í upphafi (`cost.held`); þegar keyrslan heppnast sýnir `cost.settled` hver raunnotkunin varð og afgangur hámarksins er í `cost.refunded` (sjá [Rukkað eftir notkun](https://doitong.com/developers/docs/pricing#metered)). - Þegar beiðni mistekst er `error` `{ "type": …, "code": …, "message": … }`. ## Lesa beiðni ```bash curl "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \ -H "Authorization: Bearer $DOITONG_API_KEY" ``` - `?wait=N` (allt að 20 sekúndur) bíður með langri könnun: kallið skilar sér um leið og beiðnin er komin í lokastöðu eða eftir N sekúndur með núverandi stöðu. Að endurtaka þetta er einfaldasta leiðin til að bíða eftir niðurstöðu. - `?logs=1` bætir framvindulínum líkansins (síðustu 50) við sem `logs`. Þú getur aðeins lesið beiðnir á þínum eigin reikningi; annað auðkenni er `404 request_not_found`. ## Birta beiðnir ```bash curl "https://api.doitong.ru/v1/requests?limit=20&status=succeeded&model=flux/schnell" \ -H "Authorization: Bearer $DOITONG_API_KEY" ``` Nýjustu fyrst. `limit` er 1 til 100 (sjálfgefið 20), `status` og `model` sía niðurstöðurnar. Svarið er `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; sendu `cursor=` fyrir næstu síðu. ## Hætta við beiðni ```bash curl -X POST "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \ -H "Authorization: Bearer $DOITONG_API_KEY" ``` - Hætt við áður en líkanið hóf vinnslu: staðan verður `canceled`, API-inneignin er endurgreidd og þú færð `200`. - Þegar líkanið er þegar að mynda úttak: hætt við er komið áfram og þú færð `202` með `"cancel_requested": true`. Ef líkanið klárar samt heppnast beiðnin eðlilega og er rukkuð. - Þegar beiðnin er þegar í lokastöðu: `409 not_cancelable` (beiðni sem þegar er `canceled` skilar einfaldlega `200`). ## Eyða skrám beiðni ```bash curl -X DELETE "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \ -H "Authorization: Bearer $DOITONG_API_KEY" ``` Eyðir afritum okkar af úttaksskrám beiðninnar samstundis og stöðvar geymslugjaldið. Svarið er beiðni með `storage.expired: true`; URL-slóðirnar eru áfram í færslunni en virka ekki lengur. Að kalla á þetta aftur breytir engu (`200`). Beiðni sem er enn `queued` eða `running` hefur engar skrár enn: `409 request_active`. Krefst `models:run`. ## Endurtekningaröryggi: reyna aftur án tvöfaldrar greiðslu Net geta bilað. Til að reyna keyrslu aftur á öruggan hátt skaltu senda hausinn `Idempotency-Key` (hvaða streng sem er, allt að 255 stafir, einstakur fyrir hverja aðgerð, til dæmis eigið pöntunarnúmer): - Sami lykill og sami megintexti og áður: þú færð upphaflegu beiðnina til baka (`200`, hausinn `Idempotent-Replayed: true`) og ekkert er rukkað aftur. - Sami lykill og megintexti eftir keyrslu sem mistókst áður en hún náði til líkansins (`upstream_error` eða `internal_error` við sendingu, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): ekkert varð til og ekkert er rukkað, svo endurtekningin keyrir líkanið aftur í stað þess að skila biluninni. - Sami lykill með öðrum megintexta: `409 idempotency_mismatch`. - Lyklar eru bundnir við API-lykilinn sem sendi þá. ## Hvar skrár eru geymdar Hver úttaksskrá er afrituð í geymslu okkar áður en beiðnin er merkt `succeeded`, svo URL-slóðirnar í `outputs` eru á okkunar eigin hýsingum og þú getur tengt beint í þær. Þú velur hversu lengi þær eru geymdar: | Stilling | Hversu lengi | Verð | |---|---|---| | `permanent` (sjálfgefið) | Þar til þú eyðir þeim | 100 API-inneign (0,10 $) á hvert GB á mánuði, dregið daglega af API-stöðunni | | `temporary` | 7 dagar, síðan eytt | Ókeypis | - Stilling reikningsins ræður fyrir nýjar beiðnir: rofinn „Geyma skrár að eilífu“ í [stjórnborðinu](https://doitong.com/developers/dashboard#balance), eða `PATCH https://api.doitong.ru/v1/account/storage` með `{"mode": "temporary"}`. `GET https://api.doitong.ru/v1/account` sýnir hana undir `storage`, ásamt geymdum bætum og mánaðarlegu mati. - `?storage=permanent|temporary` í keyrslu (færibreytan `storage` í MCP-verkfærinu `run`) yfirskrifar hana fyrir þá keyrslu. - Að breyta stillingunni snertir aldrei skrár sem þú átt nú þegar; eyddu þeim með [`DELETE /requests/{id}/files`](#delete-files). - Þegar API-staðan getur ekki greitt fyrir geymslu er ekkert rukkað og þú færð tölvupóst: fylltu á innan 30 daga, annars verða geymdu skrárnar tímabundnar og þeim eytt 7 dögum síðar. Í sjaldgæfum tilvikum þar sem afritun okkar mistekst hefur færslan `"stored": false` og URL-slóðin er upprunalega, skammlífa slóðin: sæktu hana fljótlega.