# Ceisiadau

Mae cais yn un alwad i un model. Mae ganddo id (`req_…`), statws, ei gost mewn credydau API (1000 = 1 USD), a’r ffeiliau a gynhyrchwyd pan fydd yn llwyddo. Daw’r un gwrthrych yn ôl o bob diweddbwynt isod, ar gyfer pob model.

## Dod o hyd i fodel

Mae catalog pob un o’r 1,496 modelau yn JSON cyhoeddus (nid oes angen allwedd):

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

| Paramedr ymholiad | Ystyr |
|---|---|
| `q` | Geiriau y mae’n rhaid iddynt i gyd ymddangos yn yr enw, id, gwneuthurwr neu dagiau, er enghraifft `kling 3`. |
| `category` | Un id categori, er enghraifft `text-to-video` neu `upscale`. Mae `GET https://api.doitong.com/v1/categories` yn rhestru pob un o’r 21 gyda’u cyfrifiadau. |
| `lab` | Gwneuthurwr y model, yn ôl enw neu id, er enghraifft `Google` neu `black-forest-labs`. |
| `family` | Id `family` o res flaenorol: pob amrywiad o un model (pro, fast, image-to-video, …). |
| `mode` | `exact` (cyfrifir y pris o’r mewnbwn), `measured` (o hyd neu faint y ffeiliau mewnbwn), `estimate` (pris amcangyfrifedig fesul rhediad) neu `metered` (codir yn ôl y defnydd gwirioneddol, hyd at uchafswm fesul rhediad). |
| `limit`, `cursor` | Maint y dudalen (1 i 100, rhagosodedig 50) a `next_cursor` y dudalen flaenorol. |

Mae gan bob rhes `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` a gwrthrych `price` (gweler [Prisio](https://doitong.com/developers/docs/pricing#price-objects)). Mae `GET https://api.doitong.com/v1/models/{model_id}` yn ychwanegu’r JSON Schema mewnbwn ac allbwn llawn, yr enwau paramedrau canonaidd, y rheolau prisio ac enghraifft o fewnbwn. Mae `category` neu `mode` anhysbys yn `400 invalid_parameter`.

## Rhedeg model

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

- Mewnbwn y model yw’r corff, sef gwrthrych JSON. Mae pob tudalen model yn rhestru ei baramedrau.
- Caiff y mewnbwn ei wirio cyn codi unrhyw dâl. Mae mewnbwn annilys yn dychwelyd `422 invalid_input` gyda’r `param` tramgwyddus, ac nid yw’n costio dim.
- Mae `?wait=N` (hyd at 20 eiliad) yn dal yr alwad nes bod y cais wedi gorffen neu’r amser wedi dod i ben.
- Mae `?webhook_url=https://…` yn anfon POST wedi’i lofnodi i’r URL hwnnw pan fydd y cais wedi gorffen (gweler [Webhooks](https://doitong.com/developers/docs/webhooks)).
- Mae `?storage=permanent` neu `?storage=temporary` yn dewis pa mor hir y cedwir y ffeiliau allbwn; hebddo, defnyddir gosodiad y cyfrif (gweler [Ble mae ffeiliau’n byw](#storage)).

Yr ymateb yw `202 Accepted` tra bod y cais yn dal i weithio, a `200 OK` pan fydd wedi gorffen o fewn yr amser aros (neu pan fydd yn ailchwarae, gweler isod). Mae penynnau `Location` a `Doitong-Request-Id` yn cario URL ac id y cais.

## Statwsau

Cylch oes y cais: `queued` → `running` → `succeeded` | `failed` | `canceled` (terfynol; ad-delir am rai a fethodd neu a gafodd eu canslo).

| Statws | Ystyr | Terfynol |
|---|---|---|
| `queued` | Wedi’i dderbyn a chodwyd tâl, yn aros am weithiwr. Gall `queue_position` ddangos ei le yn y rhes. | na |
| `running` | Mae’r model yn cynhyrchu. | na |
| `succeeded` | Wedi gorffen. Mae `outputs` yn rhestru’r ffeiliau. | ie |
| `failed` | Ataliwyd ef gan y model neu derfyn. Mae `error` yn egluro pam. Ad-delir y credydau API. | ie |
| `canceled` | Wedi’i ganslo cyn cynhyrchu canlyniad. Ad-delir y credydau API. | ie |

Mae cais sy’n rhedeg yn hwy na’i derfyn amser yn methu gyda chod `timeout` ac yn cael ad-daliad: 15 munud ar gyfer delweddau, 60 munud ar gyfer fideo, 30 munud ar gyfer sain a phopeth arall.

## Gwrthrych y cais

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

- Mae `outputs` yr un fath ar gyfer pob model: un cofnod fesul ffeil a gynhyrchwyd gyda `type` (`image`, `video`, `audio`, `file` neu `3d`), `url` ar ein storio, `content_type` a, phan fo’n hysbys, `file_size`, `width`, `height`, `duration`.
- Canlyniad y model ei hun yw `output` (rhestrir ei feysydd ar bob tudalen model) gyda’r un URLau.
- Mae `storage` yn dweud sut y cedwir y ffeiliau: `mode` (`permanent` neu `temporary`), `bytes` a storiwyd, `expires_at` (pan gaiff ffeil dros dro ei dileu, `null` ar gyfer rhai parhaol) ac `expired` (`true` unwaith y bydd y ffeiliau wedi diflannu).
- Pris yr alwad mewn credydau API yw `cost.credits` (`cost.usd` yn USD), `cost.charged` yw’r hyn a ddebydwyd o falans yr API, a `cost.refunded` yw’r hyn a ddychwelwyd. Ar gyfer model `metered`, `cost.credits` yw’r uchafswm a gedwir ar y dechrau (`cost.held`); pan fydd y rhediad yn llwyddo, mae `cost.settled` yn dweud faint oedd y defnydd a’r gweddill o’r uchafswm yn `cost.refunded` (gweler [Codir yn ôl defnydd](https://doitong.com/developers/docs/pricing#metered)).
- Pan fydd cais yn methu, mae `error` yn `{ "type": …, "code": …, "message": … }`.

## Darllen cais

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

- Mae `?wait=N` (hyd at 20 eiliad) yn cynnal pleidleisio hir: mae’r alwad yn dychwelyd cyn gynted ag y bydd y cais yn derfynol, neu ar ôl N eiliad gyda’r cyflwr cyfredol. Dyma’r ffordd symlaf o aros am ganlyniad.
- Mae `?logs=1` yn ychwanegu llinellau log cynnydd y model (y 50 olaf) fel `logs`.

Dim ond ceisiadau eich cyfrif eich hun y gallwch eu darllen; mae unrhyw id arall yn `404 request_not_found`.

## Rhestru ceisiadau

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

Y rhai mwyaf newydd yn gyntaf. Mae `limit` rhwng 1 a 100 (rhagosodedig 20), ac mae `status` a `model` yn hidlo. Yr ymateb yw `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`; pasiwch `cursor=<next_cursor>` ar gyfer y dudalen nesaf.

## Canslo cais

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

- Wedi’i ganslo cyn i’r model ddechrau: daw’r statws yn `canceled`, ad-delir y credydau API, a chewch `200`.
- Eisoes yn cynhyrchu: trosglwyddir y canslo a chewch `202` gyda `"cancel_requested": true`. Os bydd y model yn gorffen beth bynnag, bydd y cais yn llwyddo fel arfer a chodir tâl.
- Eisoes yn derfynol: `409 not_cancelable` (mae cais sydd eisoes yn `canceled` yn dychwelyd `200` yn unig).

## Dileu ffeiliau cais

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

Mae hyn yn dileu ein copïau o ffeiliau allbwn y cais ar unwaith ac yn atal eu tâl storio. Yr ymateb yw gwrthrych y cais gyda `storage.expired: true`; mae ei URLau’n aros yn y cofnod ond nid ydynt yn gweithio mwyach. Nid yw ei alw eto’n newid dim (`200`). Nid oes gan gais sy’n dal yn `queued` neu `running` ffeiliau eto: `409 request_active`. Mae angen `models:run`.

## Idempotency: ailgeisio heb dalu ddwywaith

Mae rhwydweithiau’n methu. I ailgeisio rhediad yn ddiogel, anfonwch bennyn `Idempotency-Key` (unrhyw linyn hyd at 255 nod, unigryw fesul gweithrediad, er enghraifft eich id archeb eich hun):

- Yr un allwedd a’r un corff â chynt: cewch y cais gwreiddiol yn ôl (`200`, pennyn `Idempotent-Replayed: true`), ac ni chodir tâl eto.
- Yr un allwedd a chorff ar ôl rhediad a fethodd cyn cyrraedd y model (`upstream_error` neu `internal_error` wrth gyflwyno, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): ni chynhyrchwyd dim ac ni chodwyd tâl, felly mae’r ailgais yn rhedeg y model eto yn lle dychwelyd y methiant.
- Yr un allwedd â chorff gwahanol: `409 idempotency_mismatch`.
- Mae allweddi wedi’u cwmpasu i’r allwedd API a’u hanfonodd.

## Ble mae ffeiliau’n byw

Mae pob ffeil allbwn yn cael ei chopïo i’n storio cyn i’r cais gael ei farcio’n `succeeded`, felly mae’r URLau yn `outputs` ar ein gwesteiwyr ein hunain a gallwch gysylltu â nhw’n uniongyrchol. Eich dewis chi yw pa mor hir y maent yn aros:

| Modd | Pa mor hir | Pris |
|---|---|---|
| `permanent` (rhagosodedig) | Tan i chi eu dileu | 100 credydau API ($0.10) fesul GB y mis, wedi’u codi’n ddyddiol o falans yr API |
| `temporary` | 7 diwrnod, yna eu dileu | Am ddim |

- Mae gosodiad y cyfrif yn penderfynu ar gyfer ceisiadau newydd: y switsh "Cadw ffeiliau am byth" yn y [dangosfwrdd](https://doitong.com/developers/dashboard#balance), neu `PATCH https://api.doitong.com/v1/account/storage` gyda `{"mode": "temporary"}`. Mae `GET https://api.doitong.com/v1/account` yn ei ddangos o dan `storage`, gyda’r bytes a gedwir gennych a’r amcangyfrif misol.
- Mae `?storage=permanent|temporary` ar rediad (y ddadl `storage` yn offeryn MCP `run`) yn ei ddiystyru ar gyfer y rhediad hwnnw.
- Nid yw newid y gosodiad byth yn cyffwrdd â ffeiliau sydd gennych eisoes; dilëwch y rheini gyda [`DELETE /requests/{id}/files`](#delete-files).
- Pan na all balans yr API dalu am storio, ni chodir tâl ac anfonir e-bost atoch: gwnewch ychwanegiad o fewn 30 diwrnod, neu daw’r ffeiliau a gedwir yn rhai dros dro a chânt eu dileu 7 diwrnod yn ddiweddarach.

Yn yr achos prin y bydd ein copi’n methu, mae’r cofnod yn cynnwys `"stored": false` a’r URL yw’r un gwreiddiol, byrhoedlog: lawrlwythwch ef yn fuan.