Talbiet

Talba hija sejħa waħda ta' mudell wieħed. Għandha id (req_…), status, l-ispiża tagħha fi krediti tal-API (1000 = 1 USD), u, meta tirnexxi, il-fajls iġġenerati. L-istess oġġett jiġi lura minn kull endpoint hawn taħt, għal kull mudell.

Sib mudell#

Il-katalgu tal-mudelli kollha ta' 1,496 huwa JSON pubbliku (mhi meħtieġa l-ebda ċavetta):

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

Kull ringiela għandha id, name, lab, category, family, summary, tags, output_kind, docs_url u oġġett price (ara Ipprezzar). GET https://api.doitong.com/v1/models/{model_id} iżid l-input u l-output JSON Schema sħaħ, l-ismijiet kanoniċi tal-parametri, ir-regoli tal-prezz u eżempju ta' input. category jew mode mhux magħruf jagħti 400 invalid_parameter.

Ħaddem mudell#

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

• Il-korp huwa l-input tal-mudell, oġġett JSON. Kull paġna tal-mudell telenka l-parametri tiegħu.
• L-input jiġi vverifikat qabel ma jitħallas xejn. Input mhux validu jagħti 422 invalid_input bil-param li kkawża l-problema, u ma jiswa xejn.
• ?wait=N (sa 20 sekonda) iżomm is-sejħa sakemm tispiċċa t-talba jew jgħaddi l-ħin.
• ?webhook_url=https://… jibgħat POST iffirmat lil dak l-URL meta tispiċċa t-talba (ara Webhooks).
• ?storage=permanent jew ?storage=temporary jagħżel kemm jinżammu l-fajls tal-output; mingħajru japplika l-issettjar tal-kont (ara Fejn jinżammu l-fajls).

It-tweġiba hija 202 Accepted waqt li t-talba tkun għadha qed taħdem, u 200 OK meta tkun spiċċat matul il-ħin ta' stennija (jew meta tkun replay, ara hawn taħt). Il-headers Location u Doitong-Request-Id iġorru l-URL u l-id tat-talba.

Statusijiet#

Talba li ddum aktar mil-limitu ta' ħin tagħha tfalli bil-kodiċi timeout u tiġi rifuża: 15-il minuta għall-immaġnijiet, 60 minuta għall-vidjo, 30 minuta għall-awdjo u kull ħaġa oħra.

L-oġġett tat-talba#

{
  "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 huwa l-istess għal kull mudell: entrata waħda għal kull fajl iġġenerat b'type (image, video, audio, file jew 3d), url fil-ħażna tagħna, content_type u, meta magħrufin, file_size, width, height, duration.
• output huwa l-oġġett tar-riżultat tal-mudell innifsu (l-oqsma tiegħu huma elenkati fuq kull paġna tal-mudell) bl-istess URLs.
• storage jgħid kif jinżammu l-fajls: mode (permanent jew temporary), bytes maħżuna, expires_at (meta jitħassar fajl temporanju, null għal dawk permanenti) u expired (true ladarba l-fajls ikunu spiċċaw).
• cost.credits huwa l-prezz tas-sejħa fi krediti tal-API (cost.usd f'USD), cost.charged dak li ġie ddebitat mill-bilanċ tal-API, cost.refunded dak li ġie rritornat. Għal mudell metered, cost.credits huwa l-massimu miżmum fil-bidu (cost.held); ladarba l-eżekuzzjoni tirnexxi, cost.settled jgħid kemm kien l-użu u l-bqija tal-massimu jkun f'cost.refunded (ara Imħallas skont l-użu).
• Meta talba tfalli, error huwa { "type": …, "code": …, "message": … }.

Aqra talba#

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

• ?wait=N (sa 20 sekonda) jagħmel long-polling: is-sejħa tirritorna hekk kif it-talba tkun finali, jew wara N sekondi bl-istat attwali. Li tirrepeti dan huwa l-aktar mod sempliċi biex tistenna riżultat.
• ?logs=1 iżid il-linji tal-log tal-progress tal-mudell (l-aħħar 50) bħala logs.

Tista' taqra biss it-talbiet tal-kont tiegħek; kwalunkwe id ieħor huwa 404 request_not_found.

Elenka t-talbiet#

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

L-aktar ġodda l-ewwel. limit huwa 1 sa 100 (prestabbilit 20), u status u model jiffiltraw. It-tweġiba hija { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; għaddi cursor=<next_cursor> għall-paġna li jmiss.

Ikkanċella talba#

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

• Ikkanċellata qabel ma beda l-mudell: l-istatus isir canceled, il-krediti tal-API jiġu rifużi, u tirċievi 200.
• Diġà qed tiġi ġġenerata: il-kanċellazzjoni tintbagħat lill-mudell u tirċievi 202 b'"cancel_requested": true. Jekk il-mudell xorta jispiċċa, it-talba tirnexxi normalment u titħallas.
• Diġà finali: 409 not_cancelable (talba li diġà hija canceled sempliċement tirritorna 200).

Ħassar il-fajls ta' talba#

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

Tħassar minnufih il-kopji tagħna tal-fajls tal-output tat-talba u twaqqaf il-ħlas tal-ħażna tagħhom. It-tweġiba hija l-oġġett tat-talba b'storage.expired: true; l-URLs tagħha jibqgħu fir-rekord iżda ma jibqgħux jaħdmu. Li ssejħilha mill-ġdid ma jbiddel xejn (200). Talba li għadha queued jew running għad m'għandhiex fajls: 409 request_active. Teħtieġ models:run.

Idempotenza: erġa' pprova mingħajr ma tħallas darbtejn#

In-netwerks ifallu. Biex terġa' tipprova eżekuzzjoni b'mod sigur, ibgħat header Idempotency-Key (kwalunkwe string sa 255 karattru, uniku għal kull operazzjoni, pereżempju l-id tal-ordni tiegħek):

• L-istess ċavetta u l-istess korp bħal qabel: tirċievi t-talba oriġinali lura (200, header Idempotent-Replayed: true), u ma jitħallas xejn mill-ġdid.
• L-istess ċavetta u korp wara eżekuzzjoni li falliet qabel ma waslet għand il-mudell (upstream_error jew internal_error waqt is-submit, insufficient_credits, budget_exceeded, too_many_inflight): ma ġie prodott xejn u ma tħallas xejn, għalhekk il-prova mill-ġdid tħaddem il-mudell mill-ġdid minflok tirritorna l-falliment.
• L-istess ċavetta b'korp differenti: 409 idempotency_mismatch.
• Iċ-ċwievet huma marbuta maċ-ċavetta API li bagħthom.

Fejn jinżammu l-fajls#

Kull fajl tal-output jiġi kkupjat fil-ħażna tagħna qabel ma t-talba tiġi mmarkata succeeded, għalhekk l-URLs f'outputs ikunu fuq il-hosts tagħna stess u tista' torbothom direttament. Int tagħżel kemm jibqgħu:

• L-issettjar tal-kont jiddeċiedi għal talbiet ġodda: is-swiċċ "Żomm il-fajls għal dejjem" fid-dashboard, jew PATCH https://api.doitong.com/v1/account/storage b'{"mode": "temporary"}. GET https://api.doitong.com/v1/account jurih taħt storage, flimkien mal-bytes li żżomm u l-istima ta' kull xahar.
• ?storage=permanent|temporary fuq eżekuzzjoni (l-argument storage tal-għodda MCP run) jegħlebha għal dik l-eżekuzzjoni.
• It-tibdil tal-issettjar qatt ma jmiss fajls li diġà għandek; ħassarhom b'DELETE /requests/{id}/files.
• Meta l-bilanċ tal-API ma jkunx jista' jħallas għall-ħażna, ma jitħallas xejn u tirċievi email: agħmel top-up fi żmien 30 jum, inkella l-fajls miżmuma jsiru temporanji u jitħassru 7 jum wara.

Fil-każ rari li l-kopja tagħna tfalli, l-entrata jkollha "stored": false u l-URL tkun dik oriġinali, li ddum għal żmien qasir: niżżilha dalwaqt.