Pyynnöt

Pyyntö on yksi yhden mallin kutsu. Sillä on tunnus (req_…), tila, hinta API-krediitteinä (1000 = 1 USD) ja onnistuessaan luodut tiedostot. Sama objekti palautetaan jokaisesta alla olevasta päätepisteestä jokaiselle mallille.

Mallin etsiminen#

Kaikkien 1 496 mallin luettelo on julkista JSON-dataa (avainta ei tarvita):

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

Jokaisella rivillä on id, name, lab, category, family, summary, tags, output_kind, docs_url ja price-objekti (katso Hinnoittelu). GET https://api.doitong.ru/v1/models/{model_id} lisää täydellisen syötteen ja tulosteen JSON Scheman, kanoniset parametrien nimet, hintasäännöt ja esimerkkisyötteen. Tuntematon category tai mode palauttaa virheen 400 invalid_parameter.

Mallin suorittaminen#

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

• Runko on mallin syöte, JSON-objekti. Jokaisella mallisivulla luetellaan sen parametrit.
• Syöte tarkistetaan ennen veloitusta. Virheellinen syöte palauttaa 422 invalid_input -virheen ja ilmoittaa ongelmallisen param-parametrin, eikä siitä veloiteta.
• ?wait=N (enintään 20 sekuntia) pitää kutsun avoinna, kunnes pyyntö valmistuu tai aika loppuu.
• ?webhook_url=https://… lähettää allekirjoitetun POST-pyynnön kyseiseen URL-osoitteeseen, kun pyyntö valmistuu (katso Webhookit).
• ?storage=permanent tai ?storage=temporary määrittää, kuinka kauan tulostetiedostoja säilytetään; ilman tätä käytetään tilin asetusta (katso Tiedostojen sijainti).

Vastaus on 202 Accepted, kun pyyntö on vielä käynnissä, ja 200 OK, kun se valmistui odotusajan kuluessa (tai kyseessä on uudelleentoisto, katso alla). Location- ja Doitong-Request-Id-otsakkeet sisältävät pyynnön URL-osoitteen ja tunnuksen.

Tilat#

Aikarajan ylittävä pyyntö epäonnistuu koodilla timeout, ja se hyvitetään: kuville 15 minuuttia, videolle 60 minuuttia, äänelle ja kaikelle muulle 30 minuuttia.

Pyyntöobjekti#

{
  "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 on sama jokaiselle mallille: yksi merkintä kutakin luotua tiedostoa kohti, ja siinä ovat type (image, video, audio, file tai 3d), tallennustilamme url, content_type sekä tunnettaessa file_size, width, height ja duration.
• output on mallin oma tulosobjekti (sen kentät luetellaan kullakin mallisivulla), jossa ovat samat URL-osoitteet.
• storage kertoo, miten tiedostot säilytetään: mode (permanent tai temporary), tallennettujen tavujen määrä bytes, expires_at (milloin väliaikainen tiedosto poistetaan, pysyville tiedostoille null) ja expired (true, kun tiedostot ovat poistuneet).
• cost.credits on kutsun hinta API-krediitteinä (cost.usd USD-valuuttana), cost.charged API-saldosta veloitettu määrä ja cost.refunded takaisin hyvitetty määrä. metered-mallilla cost.credits on alussa varattu enimmäismäärä (cost.held); kun ajo onnistuu, cost.settled kertoo käytetyn määrän ja enimmäismäärän loppuosa on cost.refunded-kentässä (katso Käytön mukaan veloitettavat).
• Kun pyyntö epäonnistuu, error on { "type": …, "code": …, "message": … }.

Pyynnön lukeminen#

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

• ?wait=N (enintään 20 sekuntia) tekee pitkän kyselyn: kutsu palautuu heti, kun pyyntö on lopullisessa tilassa, tai N sekunnin kuluttua nykyisen tilan kanssa. Kutsun toistaminen tällä tavalla on yksinkertaisin tapa odottaa tulosta.
• ?logs=1 lisää mallin etenemislokin rivit (viimeiset 50) logs-kenttään.

Voit lukea vain oman tilisi pyyntöjä; mikä tahansa muu tunnus palauttaa 404 request_not_found.

Pyyntöjen luettelo#

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

Uusimmat ensin. limit on 1–100 (oletus 20), ja status sekä model suodattavat tuloksia. Vastaus on { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; välitä cursor=<next_cursor> seuraavaa sivua varten.

Pyynnön peruuttaminen#

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

• Ennen mallin käynnistymistä peruutettu: tilaksi tulee canceled, API-krediitit hyvitetään ja saat vastauksen 200.
• Jos generointi on jo käynnissä: peruutus välitetään eteenpäin ja saat vastauksen 202 sekä "cancel_requested": true. Jos malli valmistuu silti, pyyntö onnistuu normaalisti ja siitä veloitetaan.
• Jos pyyntö on jo lopullisessa tilassa: 409 not_cancelable (jo canceled-tilassa oleva pyyntö palauttaa yksinkertaisesti 200).

Pyynnön tiedostojen poistaminen#

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

Poistaa pyyntöön liittyvät tulostetiedostojen kopiot nyt ja lopettaa niiden tallennusveloituksen. Vastaus on pyyntöobjekti, jossa on storage.expired: true; sen URL-osoitteet säilyvät tietueessa, mutta eivät enää toimi. Kutsun toistaminen ei muuta mitään (200). Vielä queued- tai running-tilassa olevalla pyynnöllä ei ole tiedostoja: 409 request_active. Edellyttää käyttöoikeutta models:run.

Idempotenssi: yritä uudelleen ilman kaksinkertaista veloitusta#

Verkot voivat kaatua. Lähetä ajo turvallisesti uudelleen välittämällä Idempotency-Key-otsake (mikä tahansa enintään 255 merkin merkkijono, yksilöllinen operaatiota kohti, esimerkiksi oma tilausnumerosi):

• Sama avain ja sama runko kuin aiemmin: saat alkuperäisen pyynnön takaisin (200, otsake Idempotent-Replayed: true), eikä uudelleen veloiteta.
• Sama avain ja runko ajon jälkeen, joka epäonnistui ennen mallin saavuttamista (upstream_error tai internal_error lähetyksen yhteydessä, insufficient_credits, budget_exceeded, too_many_inflight): mitään ei tuotettu eikä veloitettu, joten uudelleenyritys suorittaa mallin uudelleen epäonnistuneen vastauksen palauttamisen sijaan.
• Sama avain eri rungon kanssa: 409 idempotency_mismatch.
• Avaimet koskevat niitä lähettänyttä API-avainta.

Tiedostojen sijainti#

Jokainen tulostetiedosto kopioidaan tallennustilaamme ennen kuin pyyntö merkitään succeeded-tilaan, joten outputs-kentän URL-osoitteet ovat omilla palvelimillamme ja voit linkittää niihin suoraan. Säilytyksen kesto on sinun valintasi:

• Tilin asetus määrittää uusien pyyntöjen säilytyksen: "Säilytä tiedostot ikuisesti"-kytkin hallintapaneelissa tai PATCH https://api.doitong.ru/v1/account/storage määrityksellä {"mode": "temporary"}. GET https://api.doitong.ru/v1/account näyttää asetuksen storage-kentässä säilyttämiesi tavujen määrän ja kuukausiarvion kanssa.
• Ajon ?storage=permanent|temporary (MCP:n run-työkalun storage-argumentti) ohittaa asetuksen kyseisen ajon osalta.
• Asetuksen muuttaminen ei koskaan vaikuta jo olemassa oleviin tiedostoihin; poista ne komennolla DELETE /requests/{id}/files.
• Jos API-saldo ei riitä tallennustilaan, mitään ei veloiteta ja saat sähköpostin: lisää saldoa 30 päivän kuluessa, tai säilytettävät tiedostot muutetaan väliaikaisiksi ja poistetaan 7 päivää myöhemmin.

Harvinaisessa tapauksessa, jossa kopiointi epäonnistuu, merkinnässä on "stored": false ja URL-osoite on alkuperäinen, lyhytkestoinen osoite: lataa tiedosto pian.