Op den Inhalt sprangen
Lëtzebuergesch
API-Schlëssel kréien
API-Guide

Ufroen

Als Markdown weisen Aktualiséiert

Eng Ufro ass een Opruff vun engem Modell. Si huet eng ID (req_…), e Status, hir Käschten an API-Kreditter (1000 = 1 USD) an, wann si erfollegräich ass, déi generéiert Dateien. Deeselwechten Objet kënnt vun all Endpunkt hei drënner zeréck, fir all Modell.

E Modell fannen

De Katalog vun allen 1.496 Modeller ass ëffentlechen JSON (kee Schlëssel néideg):

Terminal
curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"
Ufroparameter Bedeitung
q Wierder, déi all am Numm, an der ID, beim Hiersteller oder an den Tags virkomme mussen, zum Beispill kling 3.
category Eng Kategorie-ID, zum Beispill text-to-video oder upscale. GET https://api.doitong.com/v1/categories list all 21 mat hiren Zuelen op.
lab Den Hiersteller vum Modell, nom Numm oder no der ID, zum Beispill Google oder black-forest-labs.
family Eng family-ID aus enger viregter Zeil: all Variant vun engem Modell (pro, fast, image-to-video, …).
mode exact (de Präis gëtt aus dem Input berechent), measured (aus der Längt oder Gréisst vun den Input-Dateien), estimate (en geschätzte Präis pro Laf) oder metered (no der tatsächlecher Notzung verrechent, bis zu engem Maximum pro Laf).
limit, cursor Säitegréisst (1 bis 100, Standard 50) an den next_cursor vun der viregter Säit.

All Zeil huet id, name, lab, category, family, summary, tags, output_kind, docs_url an en price-Objet (kuckt Präisser). GET https://api.doitong.com/v1/models/{model_id} füügt de komplette JSON Schema fir Input an Output, déi kanonesch Parameternimm, d'Präisreegelen an en Input-Beispill dobäi. Eng onbekannt category oder mode ass 400 invalid_parameter.

E Modell lafen loossen

Terminal
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": "..."}'
  • De Kierper ass de Modell-Input, en JSON-Objet. All Modell-Säit list seng Parameteren op.
  • Den Input gëtt gepréift, ier eppes verrechent gëtt. En ongültegen Input gëtt mat 422 invalid_input an dem problematesche param zeréckginn a kascht näischt.
  • ?wait=N (bis zu 20 Sekonnen) hält den Opruff, bis d'Ufro fäerdeg ass oder d'Zäit ofgelaf ass.
  • ?webhook_url=https://… schéckt e signéierten POST un dës URL, wann d'Ufro fäerdeg ass (kuckt Webhooks).
  • ?storage=permanent oder ?storage=temporary wielt, wéi laang d'Output-Dateie gespäichert ginn; ouni dëst gëllt d'Kontastellung (kuckt Wou Dateie leien).

D'Äntwert ass 202 Accepted, soulaang d'Ufro nach leeft, an 200 OK, wann si bannent der Waardezäit fäerdeg gouf (oder wann et e Replay ass, kuckt hei drënner). D'Header Location an Doitong-Request-Id enthalen d'Ufro-URL an d'ID.

Statusen

Liewenszyklus vun enger Ufro
  1. queued Ugeholl a verrechent, waart op en Aarbechter
  2. running De Modell generéiert
  3. Final Statusen:
    • succeededDe Präis gouf verrechent; outputs[] enthalen URLen an eiser Späicherung
    • failedAutomatesch rembourséiert; de Feeler erkläert firwat
    • canceledVirum Resultat gestoppt; rembourséiert
Status Bedeitung Final
queued Akzeptéiert a verrechent, waart op en Aarbechter. queue_position kann d'Positioun an der Rei weisen. nee
running De Modell generéiert. nee
succeeded Fäerdeg. outputs list d'Dateien op. jo
failed De Modell oder eng Limit huet en ofgebrach. error erkläert firwat. D'API-Kreditter ginn rembourséiert. jo
canceled Ofgebrach, ier e Resultat produzéiert gouf. D'API-Kreditter ginn rembourséiert. jo

Eng Ufro, déi méi laang leeft wéi hir Zäitlimit, schléit mam Code timeout feel a gëtt rembourséiert: 15 Minutte fir Biller, 60 Minutte fir Video, 30 Minutte fir Audio an alles anescht.

Den Ufro-Objet

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 ass fir all Modell d'selwecht: een Element pro generéierter Datei mat type (image, video, audio, file oder 3d), enger url an eiser Späicherung, content_type an, wann bekannt, file_size, width, height, duration.
  • output ass den eegene Resultat-Objet vum Modell (seng Felder sinn op all Modell-Säit opgelëscht) mat deeselwechten URLen.
  • storage weist, wéi d'Dateie gespäichert ginn: mode (permanent oder temporary), gespäichert bytes, expires_at (wann eng temporär Datei geläscht gëtt, null fir permanent Dateien) an expired (true, soubal d'Dateie fort sinn).
  • cost.credits ass de Präis vum Opruff an API-Kreditter (cost.usd an USD), cost.charged ass de Betrag, dee vum API-Saldo ofgebucht gouf, cost.refunded dee Betrag, dee zeréckkoum. Bei engem metered-Modell ass cost.credits de Maximum, deen um Ufank reservéiert gëtt (cost.held); wann de Laf erfollegräich ass, weist cost.settled, wéi héich d'Notzung war, an de Rescht vum Maximum steet an cost.refunded (kuckt No Notzung verrechent).
  • Wann eng Ufro feelerschléit, ass error { "type": …, "code": …, "message": … }.

Eng Ufro liesen

Terminal
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
  • ?wait=N (bis zu 20 Sekonnen) mécht Long-Polling: den Opruff gëtt zeréck, soubal d'Ufro final ass, oder no N Sekonne mam aktuelle Status. Dëst an enger Schleef ze widderhuelen ass deen einfachste Wee, op e Resultat ze waarden.
  • ?logs=1 füügt d'Fortschrëtts-Logzeile vum Modell (déi lescht 50) als logs dobäi.

Dir kënnt nëmmen Ufroe vun Ärem eegene Kont liesen; all aner ID ass 404 request_not_found.

Ufroen oplëschten

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

Déi neist fir d'éischt. limit ass 1 bis 100 (Standard 20), status a model filteren. D'Äntwert ass { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; gitt cursor=<next_cursor> fir déi nächst Säit un.

Eng Ufro ofbriechen

Terminal
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
  • Ofgebrach, ier de Modell gestart ass: De Status gëtt canceled, d'API-Kreditter ginn rembourséiert, an Dir kritt 200.
  • Scho beim Generéieren: Den Ofbriech-Opruff gëtt weidergeleet an Dir kritt 202 mat "cancel_requested": true. Wann de Modell trotzdeem fäerdeg gëtt, ass d'Ufro normal erfollegräich a gëtt verrechent.
  • Scho final: 409 not_cancelable (eng Ufro, déi scho canceled ass, gëtt einfach mat 200 zeréckginn).

D'Dateie vun enger Ufro läschen

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

Läscht elo eis Kopië vun den Output-Dateie vun der Ufro a stoppt hir Späicherkäschten. D'Äntwert ass den Ufro-Objet mat storage.expired: true; seng URLen bleiwen am Record, funktionéieren awer net méi. En zweeten Opruff ännert näischt (200). Eng Ufro, déi nach queued oder running ass, huet nach keng Dateien: 409 request_active. Erfordert models:run.

Idempotenz: widderhuelen ouni zweemol ze bezuelen

Netzwierker falen aus. Fir e Laf sécher ze widderhuelen, schéckt en Idempotency-Key-Header (e String mat bis zu 255 Zeechen, eenzegaarteg pro Operatioun, zum Beispill Är eegen Bestell-ID):

  • Dee selwechte Schlëssel an dee selwechte Kierper wéi virdrun: Dir kritt déi ursprénglech Ufro zeréck (200, Header Idempotent-Replayed: true), an et gëtt näischt nach eng Kéier verrechent.
  • Dee selwechte Schlëssel a Kierper no engem Laf, dee feelgeschloen ass, ier en de Modell erreecht huet (upstream_error oder internal_error beim Ofschécken, insufficient_credits, budget_exceeded, too_many_inflight): Et gouf näischt produzéiert an näischt verrechent, dofir leeft d'Widderhuelung de Modell nach eng Kéier amplaz de Feeler zeréckzeginn.
  • Dee selwechte Schlëssel mat engem anere Kierper: 409 idempotency_mismatch.
  • Schlëssele si limitéiert op den API-Schlëssel, dee si geschéckt huet.

Wou Dateie leien

All Output-Datei gëtt virum Status succeeded an eis Späicherung kopéiert, dofir leien d'URLen an outputs op eisen eegenen Hosten an Dir kënnt direkt op si verlinken. Wéi laang si bleiwen, decidéiert Dir:

Modus Dauer Präis
permanent (Standard) Bis Dir se läscht 100 API-Kreditter (0,10 $) pro GB pro Mount, all Dag vum API-Saldo verrechent
temporary 7 Deeg, duerno geläscht Gratis
  • D'Kontastellung gëllt fir nei Ufroen: de Schalter "Fichiere fir ëmmer behalen" am Dashboard, oder PATCH https://api.doitong.com/v1/account/storage mat {"mode": "temporary"}. GET https://api.doitong.com/v1/account weist se ënner storage, zesumme mat de Bytes, déi Dir behält, an der monatlecher Schätzung.
  • ?storage=permanent|temporary bei engem Laf (d'Argument storage vum MCP-Tool run) iwwerschreift se fir dee Laf.
  • D'Ännere vun der Astellung beréiert ni Dateien, déi Dir scho hutt; läscht déi mat DELETE /requests/{id}/files.
  • Wann den API-Saldo d'Späicherung net bezuele kann, gëtt näischt verrechent an Dir kritt eng E-Mail: lued bannent 30 Deeg op, soss ginn déi behalen Dateien temporär a 7 Deeg méi spéit geläscht.

Am rare Fall, datt eis Kopie feelerschléit, huet den Element "stored": false an d'URL ass déi ursprénglech, kuerzlieweg URL: lued d'Datei séier erof.