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

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

Mae gan bob rhes id, name, lab, category, family, summary, tags, output_kind, docs_url a gwrthrych price (gweler Prisio). 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#

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).
• 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).

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#

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#

{
  "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).
• Pan fydd cais yn methu, mae error yn { "type": …, "code": …, "message": … }.

Darllen cais#

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#

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#

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#

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:

• Mae gosodiad y cyfrif yn penderfynu ar gyfer ceisiadau newydd: y switsh "Cadw ffeiliau am byth" yn y dangosfwrdd, 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.
• 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.