Užklausos

Užklausa yra vienas vieno modelio iškvietimas. Ji turi ID (req_…), būseną, kainą API kreditais (1000 = 1 USD) ir, kai sėkminga, sugeneruotus failus. Tas pats objektas grąžinamas iš kiekvieno toliau pateikto galinio taško, kiekvienam modeliui.

Rasti modelį#

Visų 1 496 modelių katalogas yra viešas JSON (rakto nereikia):

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

Kiekvienoje eilutėje yra id, name, lab, category, family, summary, tags, output_kind, docs_url ir price objektas (žr. Kainodara). GET https://api.doitong.com/v1/models/{model_id} papildomai pateikia visą įvesties ir išvesties JSON Schema, kanoninius parametrų pavadinimus, kainos taisykles ir įvesties pavyzdį. Nežinoma category arba mode reikšmė grąžina 400 invalid_parameter.

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

• Užklausos turinys yra modelio įvestis — JSON objektas. Kiekvieno modelio puslapyje pateikiami jo parametrai.
• Įvestis patikrinama prieš nuskaičiuojant mokestį. Netinkama įvestis grąžina 422 invalid_input su klaidingu param ir nieko nekainuoja.
• ?wait=N (iki 20 sekundžių) laiko iškvietimą, kol užklausa baigiama arba baigiasi laikas.
• ?webhook_url=https://… užklausai baigus vykdyti siunčia pasirašytą POST į tą URL (žr. Webhook).
• ?storage=permanent arba ?storage=temporary nurodo, kiek laiko saugoti išvesties failus; jei nenurodyta, taikoma paskyros nuostata (žr. Kur saugomi failai).

Kol užklausa dar vykdoma, atsakymas yra 202 Accepted, o kai ji baigiama per laukimo laiką — 200 OK (arba kai tai pakartotinis atsakymas, žr. toliau). Antraštėse Location ir Doitong-Request-Id pateikiamas užklausos URL ir ID.

Būsenos#

Užklausa, vykdoma ilgiau nei leidžiama, baigiama kodu timeout, o lėšos grąžinamos: 15 minučių vaizdams, 60 minučių vaizdo įrašams, 30 minučių garsui ir viskam kitam.

Užklausos objektas#

{
  "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 visiems modeliams yra vienodas: po vieną įrašą kiekvienam sugeneruotam failui su type (image, video, audio, file arba 3d), url mūsų saugykloje, content_type ir, jei žinomi, file_size, width, height, duration.
• output yra paties modelio rezultatų objektas (jo laukai pateikiami kiekvieno modelio puslapyje) su tais pačiais URL.
• storage nurodo, kaip saugomi failai: mode (permanent arba temporary), saugomi bytes, expires_at (kada laikinas failas ištrinamas, nuolatiniams failams — null) ir expired (true, kai failų nebelieka).
• cost.credits yra iškvietimo kaina API kreditais (cost.usd — USD), cost.charged — iš API likučio nuskaičiuota suma, cost.refunded — grąžinta suma. metered modeliui cost.credits yra pradžioje sulaikyta didžiausia suma (cost.held); kai vykdymas sėkmingas, cost.settled nurodo faktinę naudojimo kainą, o likusi didžiausios sumos dalis yra cost.refunded (žr. Mokestis pagal naudojimą).
• Kai užklausa nepavyksta, error yra { "type": …, "code": …, "message": … }.

Skaityti užklausą#

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

• ?wait=N (iki 20 sekundžių) vykdo ilgą apklausą: iškvietimas grįžta, kai užklausa tampa galutinė, arba po N sekundžių su dabartine būsena. Kartoti šį iškvietimą yra paprasčiausias būdas laukti rezultato.
• ?logs=1 prideda modelio eigos žurnalo eilutes (paskutines 50) kaip logs.

Galite skaityti tik savo paskyros užklausas; bet kuris kitas ID grąžina 404 request_not_found.

Išvardyti užklausas#

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

Nuo naujausių. limit yra nuo 1 iki 100 (numatytasis 20), o status ir model filtruoja. Atsakymas yra { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; kitam puslapiui perduokite cursor=<next_cursor>.

Atšaukti užklausą#

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

• Atšaukta prieš pradedant modeliui: būsena tampa canceled, API kreditai grąžinami ir gaunate 200.
• Jau generuojama: atšaukimas perduodamas modeliui ir gaunate 202 su "cancel_requested": true. Jei modelis vis tiek baigia vykdyti, užklausa sėkmingai užbaigiama ir apmokestinama.
• Jau galutinė: 409 not_cancelable (jau canceled užklausa tiesiog grąžina 200).

Ištrinti užklausos failus#

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

Dabar ištrina mūsų užklausos išvesties failų kopijas ir sustabdo jų saugojimo mokestį. Atsakymas yra užklausos objektas su storage.expired: true; jo URL lieka įraše, bet nebeveikia. Pakartotinis iškvietimas nieko nekeičia (200). Užklausa, kuri vis dar yra queued arba running, failų dar neturi: 409 request_active. Reikalinga models:run.

Idempotentiškumas: kartoti nemokant du kartus#

Tinklai sutrinka. Norėdami saugiai pakartoti vykdymą, siųskite Idempotency-Key antraštę (bet kokią iki 255 simbolių ilgio eilutę, unikalią kiekvienai operacijai, pavyzdžiui, savo užsakymo ID):

• Tas pats raktas ir tas pats turinys kaip anksčiau: gaunate pradinę užklausą (200, antraštė Idempotent-Replayed: true), o mokestis dar kartą nenuskaičiuojamas.
• Tas pats raktas ir turinys po vykdymo, kuris nepavyko prieš pasiekiant modelį (upstream_error arba internal_error siunčiant, insufficient_credits, budget_exceeded, too_many_inflight): niekas nesugeneruota ir mokestis nenuskaičiuotas, todėl kartotinė užklausa vėl vykdo modelį, užuot grąžinusi klaidą.
• Tas pats raktas su kitu turiniu: 409 idempotency_mismatch.
• Raktai taikomi API raktui, kuris juos išsiuntė.

Kur saugomi failai#

Kiekvienas išvesties failas nukopijuojamas į mūsų saugyklą prieš pažymint užklausą kaip succeeded, todėl outputs URL yra mūsų serveriuose ir galite tiesiogiai į juos pateikti nuorodas. Kiek laiko jie saugomi, pasirenkate jūs:

• Paskyros nuostata taikoma naujoms užklausoms: jungiklis „Saugoti failus neribotą laiką“ valdymo skydelyje arba PATCH https://api.doitong.com/v1/account/storage su {"mode": "temporary"}. GET https://api.doitong.com/v1/account ją pateikia skiltyje storage kartu su saugomų baitų skaičiumi ir mėnesio sąmata.
• ?storage=permanent|temporary vykdant užklausą (MCP run įrankio storage argumentas) nepaiso šios nuostatos tame vykdyme.
• Pakeitus nuostatą, jau turimi failai nekeičiami; ištrinkite juos naudodami DELETE /requests/{id}/files.
• Kai API likučio nepakanka saugyklai apmokėti, mokestis nenuskaičiuojamas ir gaunate el. laišką: papildykite likutį per 30 dienas arba saugomi failai taps laikini ir bus ištrinti po 7 dienų.

Retu atveju, kai mūsų kopijavimas nepavyksta, įraše yra "stored": false, o URL yra pradinis, trumpai galiojantis: atsisiųskite failą kuo greičiau.