Bouwcodes uit een foto, die kloppen

Hoe zeker is het antwoord

De code moet kloppen, u neemt hem over in uw bestek. Nagemeten op negenennegentig foto’s door een bestekschrijver: in 95% van de gevallen zit de juiste code in wat ClearCodes teruggeeft, en klopt het STABU-hoofdstuk.

Daarom staat het hoofdstuk altijd los in het antwoord (stabuHoofdstuk), en zegt zeker of de paragraaf uit de fóto volgt of alleen uit de catalogus. Verwerkt u liever alleen zekerheden, dan heeft u aan die twee velden genoeg. Bij twijfel krijgt u er een advies bij: één zin over wat wél vaststaat en wat een tweede foto zou oplossen.

En de ondergrens: het model mag alleen een id uit uw catalogus kiezen, en alles wat er niet in staat gooien we weg en geven we apart terug in afgewezen. Die controle staat buiten de AI-koppeling, dus er komt nooit een verzonnen code uit, welk model er ook onder draait.

Aan de slag

Van niets naar uw eerste antwoord. Er valt niets te installeren, het is één HTTP-aanroep, dus uw bestaande client is genoeg.

curl -X POST https://api.clearcodes.nl/v1/analyse \
  -H "Authorization: Bearer $CLEARCODES_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d "{\"fotoBase64\": \"$(base64 -w0 deur.jpg)\", \"mimeType\": \"image/jpeg\"}"

import { readFile } from "node:fs/promises";

const foto = await readFile("deur.jpg");

const res = await fetch("https://api.clearcodes.nl/v1/analyse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLEARCODES_SLEUTEL}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fotoBase64: foto.toString("base64"),
    mimeType: "image/jpeg",
  }),
});

const uitslag = await res.json();

import base64, os, requests

with open("deur.jpg", "rb") as f:
    foto = base64.b64encode(f.read()).decode()

res = requests.post(
    "https://api.clearcodes.nl/v1/analyse",
    headers={"Authorization": f"Bearer {os.environ['CLEARCODES_SLEUTEL']}"},
    json={"fotoBase64": foto, "mimeType": "image/jpeg"},
)

uitslag = res.json()

const onderwerp = uitslag.kandidaten.find((k) => k.hoofdonderwerp);

console.log(onderwerp.item.naam);          // "Binnendeur"
console.log(onderwerp.codes.stabu);        // "30.33"
console.log(onderwerp.codes.stabuOmschrijving); // "DEUREN"

Het antwoord

Eén object per herkend item, met de codes al samengesteld. kader is de uitsnede op de foto in fracties van 0 tot 1, en is null als het model niet kon aanwijzen waar het object staat.

{
  "verzoekId": "req_gj5nztuc81",
  "duurMs": 1449,
  "domein": "woningbouw",
  "hint": null,
  "regelsInLijst": 187,
  "kandidaten": [
    {
      "catalogId": "binnendeur",
      "label": "houten binnendeur",
      "materiaal": "eiken",
      "zekerheid": 0.9,
      "kader": { "x0": 0.13, "y0": 0.29, "x1": 0.35, "y1": 0.88 },
      "item": { "id": "binnendeur", "naam": "Binnendeur" },
      "codes": {
        "nlSfb": "32.31",
        "stabu": "30.33",
        "stabuHoofdstuk": "30",
        "stabuOmschrijving": "DEUREN",
        "zeker": true,
        "twijfelTussen": [],
        "raw": null,
        "rawOmschrijving": null,
        "naakt": "hout_eiken_element"
      },
      "advies": null
    }
  ],
  "afgewezen": []
}

Nul kandidaten is geen fout. Een foto van een lege muur levert terecht een lege lijst op; dan krijgt u 200 met kandidaten: []. Reserveer uw foutafhandeling voor de statuscodes hieronder.

domein is het domein waarop is gefilterd (null als er niet is gefilterd) en regelsInLijst is hoeveel regels van uw catalogus in de prompt zijn meegestuurd, zo ziet u meteen wat een aanroep gekost heeft.

stabuOmschrijving en rawOmschrijving zijn de tekst bij de code, zodat u 30.33. DEUREN kunt tonen zonder zelf een codelijst te hoeven bijhouden. Ze zijn null bij een code die wij niet kennen, bijvoorbeeld een code uit uw eigen lijst. raw hoort binnen een gebouw leeg te zijn: RAW is een infrabestek en vullen we alleen waar het klopt.

zeker zegt of u de paragraaf mag geloven. Staat er false, dan is de paragraaf niet uit deze foto af te leiden, een losse deur is niet te zien als binnen- of buitendeur. U krijgt dantwijfelTussen met de codes waar het tussen ging, en advies in gewone taal: laten nakijken, of een tweede foto van iets specifieks. Het hoofdstuk staat altijd los in stabuHoofdstuk en klopt aantoonbaar veel vaker dan de paragraaf, dus verwerkt u alleen zekerheden, gebruik dan dat veld.

Wat het kost

€ 0,65 per gescande foto. Niet per aanroep en niet per herkend object: een foto waarop we drie dingen herkennen kost hetzelfde als een foto met één. U weet hoeveel foto's u maakt; hoeveel dingen erop staan weet u vooraf niet.

De eerste 30 foto's per maand zijn gratis, zonder dat u een kaart hoeft achter te laten. Daarna een 402 met een link naar de checkout. Er is geen opzegtermijn en geen minimumafname: scan u een maand niets, dan betaalt u niets.

Een eigen codelijst

U hebt er geen nodig: zonder eigen lijst draai u op onze meegeleverde lijst. Upload u die van uzelf, dan antwoordt de API met uw codes en gaat uw lijst vóór de onze. Uw lijst is van u en komt nooit bij een andere klant terecht.

curl -X PUT https://api.clearcodes.nl/v1/catalogus \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: text/csv" \
  --data-binary @mijn-lijst.csv

Koppen: id, naam, synoniemen, nl_sfb, stabu, raw, naakt_toepassing. Alleen naam is verplicht; volgorde, hoofdletters en extra kolommen maken niet uit. Een upload vervangt de hele lijst.

Eén verschil tussen de twee lijsten: GET /v1/catalogus geeft stabu en raw leeg terug zolang u op de meegeleverde lijst draait, dat zijn codes van derden en die geven we niet als lijst weg. U krijgt ze bij de objecten die /v1/analyse op uw foto herkent. Bij een eigen lijst is er niets om weg te laten: dat zijn uw codes.

Endpoints

/v1/analyse en /v1/catalogus accepteren allebei twee optionele velden: domein (bijvoorbeeld "woningbouw") en codesysteem (nlSfb, stabu, raw of naakt). Meegeven zonder domein te zetten op uw account blijft werken zoals nu. /v1/analyse heeft er één die de andere twee niet hebben: hint.

Eén ding om te weten voordat u bouwt. Op GET /v1/catalogus geven codesysteem=stabu en raw een 400 zolang u op de meegeleverde lijst zit: dat endpoint geeft die codes niet terug, dus het filter zou alleen verklappen wélke regels er een hebben. Op /v1/analyse werken ze wel, en met uw eigen geüploade lijst ook hier.

De catalogus gaat bij elke aanroep mee in de prompt aan het model: meer regels betekent meer tokens en een grotere kans dat het model de verkeerde regel kiest. Stuurt u een domein mee, dan ziet het model alleen de regels die daarbij horen, kleinere prompt, lagere kosten, betere keuze. Wilt u dat niet elke aanroep apart doen, zet dan een standaarddomein op de tenant (npm run tenant -- domein <tenantId> <domein>); een veld in het verzoek zelf gaat daar altijd voor.

hint vertelt het model waar de foto voor gemaakt is. Weet de gebruiker dat hij een doucheput fotografeert, stuur dan "hint": "douche" mee. Het model zoekt dat als eerste op en zet het vooraan in het antwoord. Maximaal 100 tekens, meerdere woorden mogen. Het kort de catalogus niet in, u krijgt nog steeds elk ander object dat op de foto staat, en staat het genoemde er niet op, dan wordt het weggelaten in plaats van bevestigd. Een hint kan dus geen verkeerd antwoord afdwingen. Opnieuw scannen met een hint is wel een tweede foto op uw rekening , er gaat een tweede modelaanroep overheen.

Foutafhandeling

De statuscode zegt of het gelukt is; u hoeft het lichaam niet te lezen om dat te weten. De code is machineleesbaar en verandert nooit, het bericht is voor mensen en mag wel wijzigen.

{ "fout": { "code": "niet_betaald", "bericht": "Er staat een factuur open." } }

Limieten en privacy

• Elk antwoord draagt X-RateLimit-Remaining. Bij een 429 staat er ook Retry-After bij, in seconden.
• Foto's tot 10 MB. Verklein ze eerst tot zo'n 1600 pixels, dat scheelt wachttijd en kosten, en een kozijn blijft prima herkenbaar.
• Wij bewaren uw foto's niet. Analyseren en vergeten. Er is geen archief om te lekken.
• Aanroepen die mislukken door een storing bij ons tellen niet mee voor uw factuur.