# Ngā tono

Ko te tono he karanga kotahi ki tētahi tauira kotahi. He id tōna (`req_…`), he tūnga, tōna utu ki ngā whiwhinga API (1000 = 1 USD), ā, ina
angitu, ko ngā kōnae kua hangaia. Ka hoki mai taua ahanoa anō i ia pito API kei raro nei, mō ia tauira.

## Kimihia he tauira

He JSON tūmatanui te rārangi o ngā tauira 1,496 katoa (kāore he kī e hiahiatia ana):

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

| Tawhā uiui | Tikanga |
|---|---|
| `q` | Ngā kupu me puta katoa i te ingoa, id, kaihanga, tohu rānei, hei tauira `kling 3`. |
| `category` | Kotahi te id kāwai, hei tauira `text-to-video` rānei `upscale`. Mā `GET https://api.doitong.com/v1/categories` e whakarārangi ngā 21 katoa me ō rātou tatau. |
| `lab` | Te kaihanga o te tauira, mā te ingoa, mā te id rānei, hei tauira `Google` rānei `black-forest-labs`. |
| `family` | He id `family` nō tētahi rārangi o mua: ngā momo katoa o tētahi tauira kotahi (pro, fast, image-to-video, …). |
| `mode` | `exact` (ka tātaihia te utu mai i te tāuru), `measured` (mai i te roa, te rahi rānei o ngā kōnae tāuru), `estimate` (he utu whakatauria mō ia whakahaere), `metered` rānei (ka utua e ai ki te whakamahinga tūturu, tae atu ki te mōrahi mō ia whakahaere). |
| `limit`, `cursor` | Te rahi whārangi (1 ki te 100, taunoa 50) me te `next_cursor` o te whārangi o mua. |

Kei ia rārangi ngā `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` me tētahi ahanoa `price`
(see [Pricing](https://doitong.com/developers/docs/pricing#price-objects)). Mā `GET https://api.doitong.com/v1/models/{model_id}` e tāpiri te
JSON Schema katoa mō te tāuru me te putanga, ngā ingoa tawhā matua, ngā ture utu me tētahi tauira tāuru. Ko tētahi
`category` `mode` rānei kāore e mōhiotia ana ko `400 invalid_parameter`.

## Whakahaerehia he tauira

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

- Ko te tinana te tāuru tauira, he ahanoa JSON. Kei te whārangi o ia tauira ōna tawhā.
- Ka tirohia te tāuru i mua i te utu. Ka whakahoki tētahi tāuru muhu i `422 invalid_input` me te `param` kua hē, ā, kāore he utu.
- Mā `?wait=N` (tae atu ki te 20 hēkona) e pupuri te karanga kia mutu rā anō te tono, kia pau rānei te wā.
- Mā `?webhook_url=https://…` e tuku he POST kua waitohua ki taua URL ina mutu te tono (tirohia [Webhooks](https://doitong.com/developers/docs/webhooks)).
- Mā `?storage=permanent` rānei `?storage=temporary` e kōwhiri te roa e puritia ai ngā kōnae putanga; ki te kore, ka whakamahia
  te tautuhinga pūkete (tirohia [Kei hea ngā kōnae](#storage)).

Ko te whakautu he `202 Accepted` i te wā e mahi tonu ana te tono, ā, he `200 OK` ina mutu i roto i te wā tatari (ina rānei
he replay, tirohia i raro). Kei ngā pane `Location` me `Doitong-Request-Id` te URL me te id o te tono.

## Ngā tūnga

Te huringa ora o te tono: `queued` → `running` → `succeeded` | `failed` | `canceled` (whakamutunga; ka whakahokia ngā rahua me ngā whakakore).

| Tūnga | Tikanga | Whakamutunga |
|---|---|---|
| `queued` | Kua whakaaetia, kua utua, e tatari ana ki tētahi kaimahi. Ka whakaatu pea a `queue_position` i te wāhi ki te rārangi. | kāo |
| `running` | Kei te hanga te tauira. | kāo |
| `succeeded` | Kua oti. Mā `outputs` ngā kōnae e whakarārangi. | āe |
| `failed` | Nā te tauira, nā tētahi here rānei i aukati. Mā `error` e kī te take. Ka whakahokia ngā whiwhinga API. | āe |
| `canceled` | Kua whakakorea i mua i te whakaputanga hua. Ka whakahokia ngā whiwhinga API. | āe |

Ki te roa ake te whakahaere tono i tōna here wā, ka hē me te waehere `timeout`, ā, ka whakahokia te utu: 15 meneti mō ngā atahanga,
60 meneti mō te ataata, 30 meneti mō te ororongo me ērā atu katoa.

## Te ahanoa tono

```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"
  }
}
```

- He ōrite a `outputs` mō ia tauira: kotahi te tāurunga mō ia kōnae kua hangaia me te `type` (`image`, `video`, `audio`,
  `file` rānei `3d`), he `url` kei roto i tō mātou rokiroki, `content_type`, ā, ina mōhiotia, `file_size`, `width`, `height`,
  `duration`.
- Ko `output` te ahanoa hua ake a te tauira (kei ia whārangi tauira ōna āpure) me ngā URL ōrite.
- Mā `storage` e kī te āhua o te pupuri kōnae: `mode` (`permanent` rānei `temporary`), ngā `bytes` kua puritia, `expires_at` (ina
  mukua tētahi kōnae rangitahi, `null` mō ngā kōnae pūmau) me `expired` (`true` ina ngaro ngā kōnae).
- Ko `cost.credits` te utu o te karanga ki ngā whiwhinga API (`cost.usd` ki te USD), ko `cost.charged` te mea i tangohia mai i
  te toenga API, ko `cost.refunded` te mea i hoki mai. Mō tētahi tauira `metered`, ko `cost.credits` te mōrahi i puritia i te
  tīmatanga (`cost.held`); ina angitu te whakahaere, mā `cost.settled` e kī te tapeke o te whakamahinga, ā, kei
  `cost.refunded` te toenga o te mōrahi (tirohia [Charged by whakamahinga](https://doitong.com/developers/docs/pricing#metered)).
- Ina hē tētahi tono, ko `error` `{ "type": …, "code": …, "message": … }`.

## Pānuitia he tono

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

- He pātai-roa a `?wait=N` (tae atu ki te 20 hēkona): ka hoki mai te karanga ina mutu te tono, i muri rānei i te N hēkona me
  te tūnga o nāianei. Ko te whakahoki haere i tēnei te huarahi māmā hei tatari hua.
- Mā `?logs=1` e tāpiri ngā rārangi rangitaki ahunga whakamua a te tauira (ko ngā 50 whakamutunga) hei `logs`.

Ka taea noa e koe te pānui i ngā tono o tō ake pūkete; ko ētahi atu id he `404 request_not_found`.

## Whakarārangitia ngā tono

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

Ko ngā mea hōu ki mua. Ko `limit` mai i te 1 ki te 100 (taunoa 20), ā, mā `status` me `model` e tātari. Ko te whakautu
`{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; tukuna `cursor=<next_cursor>` mō
te whārangi e whai ake nei.

## Whakakorea he tono

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

- Mēnā ka whakakorea i mua i te tīmatanga o te tauira: ka noho te tūnga hei `canceled`, ka whakahokia ngā whiwhinga API, ā, ka whiwhi koe i te `200`.
- Mēnā kua tīmata kē te hanga: ka tukuna te whakakorenga, ā, ka whiwhi koe i te `202` me `"cancel_requested": true`. Mēnā
  ka oti tonu te tauira, ka angitu noa te tono, ā, ka utua.
- Mēnā kua mutu kē: `409 not_cancelable` (mēnā kua `canceled` kē, ka whakahoki noa i te `200`).

## Mukua ngā kōnae o tētahi tono

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

Ka mukua ināianei ā mātou kape o ngā kōnae putanga o te tono, ka mutu te utu rokiroki mō aua kōnae. Ko te whakautu te ahanoa
tono me `storage.expired: true`; ka noho tonu ngā URL ki te pūkete, engari kua kore e mahi. Ki te karanga anō, kāore he panonitanga
(`200`). Kāore he kōnae o tētahi tono e `queued` ana, e `running` ana rānei: `409 request_active`. Me whai `models:run`.

## Idempotency: ngana anō me te kore utu rua

Ka hē ngā whatunga. Hei ngana anō kia haumaru, tukuna he pane `Idempotency-Key` (he aho ahakoa he aha, tae atu ki te 255 pūāhua,
he ahurei mō ia mahi, hei tauira tō ake id ota):

- He kī ōrite me te tinana ōrite ki mua: ka whiwhi koe i te tono taketake (`200`, pane
  `Idempotent-Replayed: true`), ā, kāore e utua anō.
- He kī ōrite me te tinana ōrite i muri i tētahi whakahaere i hē i mua i te taenga ki te tauira (`upstream_error` rānei `internal_error` i te
  tuku, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): kāore he mea i hangaia, kāore he utu, nō reira ka whakahaere anō te
  ngana i te tauira, kaua e whakahoki i te hapa.
- He kī ōrite me tētahi tinana rerekē: `409 idempotency_mismatch`.
- Ka herea ngā kī ki te kī API nāna i tuku.

## Kei hea ngā kōnae

Ka tāruahia ia kōnae putanga ki tō mātou rokiroki i mua i te tohu `succeeded` o te tono, nō reira kei ō mātou ake tūmau ngā URL kei `outputs`,
ā, ka taea e koe te hono tika atu ki aua URL. Māu e kōwhiri te roa e noho ai:

| Aratau | Te roa | Utu |
|---|---|---|
| `permanent` (taunoa) | Kia mukua rā anō e koe | 100 whiwhinga API ($ 0.10) mō ia GB ia marama, ka utua ia rā mai i te toenga API |
| `temporary` | 7 rā, kātahi ka mukua | Kore utu |

- Mā te tautuhinga pūkete e whakatau mō ngā tono hōu: te pana "Pupurihia ngā kōnae mō ake tonu atu" i te
  [papatohu](https://doitong.com/developers/dashboard#balance), mā `PATCH https://api.doitong.com/v1/account/storage` rānei me
  `{"mode": "temporary"}`. Mā `GET https://api.doitong.com/v1/account` e whakaatu i raro i `storage`, me ngā paita e puritia ana e koe me te
  whakatau tata ā-marama.
- Mā `?storage=permanent|temporary` i te whakahaere (te tohenga `storage` o te taputapu MCP `run`) e whakakore taua tautuhinga mō taua whakahaere.
- Kāore te whakarerekē tautuhinga e pā ki ngā kōnae kei a koe kē; mukua aua kōnae mā
  [`DELETE /requests/{id}/files`](#delete-files).
- Ina kore e taea e te toenga API te utu rokiroki, kāore he utu ka tangohia, ā, ka tukuna he īmēra: tāpiri pūtea i roto i ngā
  30 rā, ki te kore ka noho rangitahi ngā kōnae e puritia ana, ā, ka mukua 7 rā i muri mai.

Mēnā ka hē te tārua a mātou i te wā onge, ka whai te tāurunga i `"stored": false`, ā, ko te URL te URL taketake, he poto noa te wā e ora ai:
tikiake wawe.