Maombi

Ombi ni simu moja ya modeli moja. Lina id (req_…), hali, gharama yake kwa krediti za API (1000 = 1 USD), na, linapofaulu, mafaili yaliyotengenezwa. Kitu hicho hicho hurudi kutoka kila endpoint hapa chini, kwa kila modeli.

Tafuta modeli#

Katalogi ya modeli zote 1,496 ni JSON ya umma (hakuna ufunguo unaohitajika):

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

Kila safu ina id, name, lab, category, family, summary, tags, output_kind, docs_url na kitu cha price (angalia Bei). GET https://api.doitong.com/v1/models/{model_id} huongeza Schema kamili ya JSON ya ingizo na tokeo, majina sanifu ya vigezo, kanuni za bei na mfano wa ingizo. category au mode isiyojulikana ni 400 invalid_parameter.

Endesha modeli#

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

• Mwili ni ingizo la modeli, kitu cha JSON. Kila ukurasa wa modeli huorodhesha vigezo vyake.
• Ingizo hukaguliwa kabla ya chochote kutozwa. Ingizo lisilo sahihi hurudisha 422 invalid_input pamoja na param iliyosababisha tatizo, na hakuna kinachotozwa.
• ?wait=N (hadi sekunde 20) hushikilia simu hadi ombi likamilike au muda uishe.
• ?webhook_url=https://… hutuma POST iliyotiwa sahihi kwenye URL hiyo ombi linapokamilika (angalia Webhooks).
• ?storage=permanent au ?storage=temporary huchagua muda ambao mafaili ya tokeo yanahifadhiwa; bila hiyo, mpangilio wa akaunti hutumika (angalia Mafaili yanapatikana wapi).

Jibu ni 202 Accepted wakati ombi bado linafanya kazi, na 200 OK linapokamilika ndani ya muda wa kusubiri (au linapokuwa replay, tazama hapa chini). Vichwa vya Location na Doitong-Request-Id hubeba URL na id ya ombi.

Hali#

Ombi linalozidi kikomo chake cha muda hushindwa kwa msimbo timeout na kurejeshewa fedha: dakika 15 kwa picha, dakika 60 kwa video, dakika 30 kwa sauti na kila kitu kingine.

Kitu cha ombi#

{
  "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 ni sawa kwa kila modeli: ingizo moja kwa kila faili lililotengenezwa lenye type (image, video, audio, file au 3d), url kwenye hifadhi yetu, content_type na, inapojulikana, file_size, width, height, duration.
• output ni kitu cha matokeo cha modeli yenyewe (sehemu zake zimeorodheshwa kwenye kila ukurasa wa modeli) chenye URL zilezile.
• storage hueleza jinsi mafaili yanavyohifadhiwa: mode (permanent au temporary), bytes zilizohifadhiwa, expires_at (faili la muda linapofutwa, null kwa mafaili ya kudumu) na expired (true mafaili yakishaondoka).
• cost.credits ni bei ya simu kwa krediti za API (cost.usd katika USD), cost.charged ni kiasi kilichokatwa kutoka salio la API, cost.refunded ni kilichorejeshwa. Kwa modeli ya metered, cost.credits ni kiwango cha juu kilichoshikiliwa mwanzoni (cost.held); uendeshaji unapofaulu cost.settled huonyesha kiasi cha matumizi na salio la kiwango cha juu huwekwa kwenye cost.refunded (angalia Hutozwa kulingana na matumizi).
• Ombi linaposhindwa, error ni { "type": …, "code": …, "message": … }.

Soma ombi#

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

• ?wait=N (hadi sekunde 20) husubiri kwa muda mrefu: simu hurudi mara tu ombi linapokuwa la mwisho, au baada ya sekunde N ikiwa na hali ya sasa. Kurudia hii ndiyo njia rahisi zaidi ya kusubiri matokeo.
• ?logs=1 huongeza mistari ya kumbukumbu ya maendeleo ya modeli (50 ya mwisho) kama logs.

Unaweza kusoma tu maombi ya akaunti yako; id nyingine yoyote ni 404 request_not_found.

Orodhesha maombi#

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

Mapya kwanza. limit ni 1 hadi 100 (chaguomsingi 20), status na model huchuja. Jibu ni { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; pitisha cursor=<next_cursor> kwa ukurasa unaofuata.

Ghairi ombi#

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

• Limeghairiwa kabla modeli kuanza: hali inakuwa canceled, krediti za API hurejeshwa, na unapata 200.
• Tayari linazalisha: ombi la kughairi hupitishwa na unapata 202 pamoja na "cancel_requested": true. Modeli ikikamilisha hata hivyo, ombi hufaulu kawaida na hutozwa.
• Tayari ni la mwisho: 409 not_cancelable (ombi ambalo tayari ni canceled hurudisha 200 tu).

Futa mafaili ya ombi#

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

Hufuta sasa nakala zetu za mafaili ya tokeo ya ombi na kusimamisha gharama ya hifadhi. Jibu ni kitu cha ombi chenye storage.expired: true; URL zake hubaki kwenye rekodi lakini hazifanyi kazi tena. Kulita tena hakubadilishi chochote (200). Ombi ambalo bado ni queued au running halina mafaili bado: 409 request_active. Linahitaji models:run.

Idempotency: jaribu tena bila kulipa mara mbili#

Mitandao hushindwa. Ili kujaribu uendeshaji tena kwa usalama, tuma kichwa cha Idempotency-Key (mfuatano wowote wa hadi vibambo 255, wa kipekee kwa kila operesheni, kwa mfano id ya agizo lako):

• Ufunguo uleule na mwili uleule wa awali: unapata ombi la awali (200, kichwa Idempotent-Replayed: true), na hakuna kinachotozwa tena.
• Ufunguo uleule na mwili uleule baada ya uendeshaji ulioshindwa kabla haujafikia modeli (upstream_error au internal_error wakati wa kutuma, insufficient_credits, budget_exceeded, too_many_inflight): hakuna kilichotengenezwa na hakuna kilichotozwa, hivyo jaribio tena huendesha modeli badala ya kurudisha hitilafu.
• Ufunguo uleule wenye mwili tofauti: 409 idempotency_mismatch.
• Vifunguo vinahusishwa na ufunguo wa API ulio vituma.

Mafaili yanapatikana wapi#

Kila faili la tokeo hunakiliwa kwenye hifadhi yetu kabla ombi kuwekwa kuwa succeeded, kwa hiyo URL zilizo kwenye outputs ziko kwenye seva zetu na unaweza kuziunganisha moja kwa moja. Muda wa kuzihifadhi ni chaguo lako:

• Mpangilio wa akaunti huamua kwa maombi mapya: swichi ya "Hifadhi faili milele" kwenye dashibodi, au PATCH https://api.doitong.com/v1/account/storage yenye {"mode": "temporary"}. GET https://api.doitong.com/v1/account huionyesha chini ya storage, pamoja na baiti unazohifadhi na makadirio ya kila mwezi.
• ?storage=permanent|temporary kwenye uendeshaji (kigezo cha storage cha zana ya MCP run) huubatilisha kwa uendeshaji huo.
• Kubadilisha mpangilio hakugusi mafaili uliyo nayo tayari; yafute kwa DELETE /requests/{id}/files.
• Salio la API lisipoweza kulipia hifadhi, hakuna kinachotozwa na utapata barua pepe: ongeza salio ndani ya siku 30, au mafaili yaliyohifadhiwa yatakuwa ya muda na kufutwa siku 7 baadaye.

Katika hali adimu ambapo nakala yetu inashindwa, ingizo huwa na "stored": false na URL huwa ile ya awali ya muda mfupi: lipakue mapema.