# 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):

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

| Kigezo cha utafutaji | Maana |
|---|---|
| `q` | Maneno yote yanayopaswa kuonekana kwenye jina, id, mtengenezaji au lebo, kwa mfano `kling 3`. |
| `category` | Id ya kategoria moja, kwa mfano `text-to-video` au `upscale`. `GET https://api.doitong.com/v1/categories` huorodhesha kategoria zote 21 pamoja na idadi zake. |
| `lab` | Mtengenezaji wa modeli, kwa jina au id, kwa mfano `Google` au `black-forest-labs`. |
| `family` | Id ya `family` kutoka safu iliyotangulia: kila toleo la modeli moja (pro, fast, image-to-video, …). |
| `mode` | `exact` (bei huhesabiwa kutoka kwenye ingizo), `measured` (kutoka urefu au ukubwa wa mafaili ya ingizo), `estimate` (bei inayokadiriwa kwa kila uendeshaji) au `metered` (hutozwa kulingana na matumizi halisi, hadi kiwango cha juu kwa kila uendeshaji). |
| `limit`, `cursor` | Ukubwa wa ukurasa (1 hadi 100, chaguomsingi 50) na `next_cursor` ya ukurasa uliotangulia. |

Kila safu ina `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` na kitu cha `price` (angalia [Bei](https://doitong.com/developers/docs/pricing#price-objects)). `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

```bash
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](https://doitong.com/developers/docs/webhooks)).
- `?storage=permanent` au `?storage=temporary` huchagua muda ambao mafaili ya tokeo yanahifadhiwa; bila hiyo, mpangilio wa akaunti hutumika (angalia [Mafaili yanapatikana wapi](#storage)).

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

Mzunguko wa ombi: `queued` → `running` → `succeeded` | `failed` | `canceled` (imekamilika; yaliyoshindikana na yaliyoghairiwa yanarejeshewa fedha).

| Hali | Maana | Ya mwisho |
|---|---|---|
| `queued` | Limekubaliwa na kutozwa, likisubiri mfanyakazi. `queue_position` inaweza kuonyesha nafasi kwenye foleni. | hapana |
| `running` | Modeli inazalisha. | hapana |
| `succeeded` | Limekamilika. `outputs` huorodhesha mafaili. | ndiyo |
| `failed` | Modeli au kikomo kimesimamisha. `error` hueleza sababu. Krediti za API hurejeshwa. | ndiyo |
| `canceled` | Limeghairiwa kabla ya kutoa matokeo. Krediti za API hurejeshwa. | ndiyo |

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

```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.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](https://doitong.com/developers/docs/pricing#metered)).
- Ombi linaposhindwa, `error` ni `{ "type": …, "code": …, "message": … }`.

## Soma ombi

```bash
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

```bash
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

```bash
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

```bash
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:

| Hali | Muda gani | Bei |
|---|---|---|
| `permanent` (chaguomsingi) | Hadi uzifute | 100 krediti za API ($ 0.10) kwa GB kwa mwezi, hutozwa kila siku kutoka salio la API |
| `temporary` | Siku 7, kisha hufutwa | Bila malipo |

- Mpangilio wa akaunti huamua kwa maombi mapya: swichi ya "Hifadhi faili milele" kwenye [dashibodi](https://doitong.com/developers/dashboard#balance), 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`](#delete-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.