Claude API koppelen aan je eigen software: architectuur, kosten en de EU-vraag

De Claude API koppelen aan je eigen bedrijfssoftware is technisch één HTTP-call: een POST naar /v1/messages met je sleutel, een model-id en een berichtenlijst. Alles wat daarna moeilijk wordt — kosten, limieten, betrouwbaarheid en de AVG — zit in de parameters eromheen en in je eigen keten, niet in de koppeling zelf.

Dat is precies omgekeerd aan een ERP-koppeling. Bij Exact Online gaat je tijd op aan het model van de leverancier: divisions, tokenrotatie, endpoints per resource.

Bij Claude is dat model in een middag door, en gaat je tijd op aan begroten en begrenzen van wat je erdoorheen stuurt.

Deze pagina gaat over die tweede helft. Welke vorm AI in je software überhaupt moet krijgen, staat in de beslisgids software met AI.

Wij draaien deze keten zelf in productie: onze AI-assistent op een eigen tekstcorpus gebruikt de Claude API als redeneerlaag boven een pgvector-index.

De cijfers hieronder zijn lijstprijzen van Anthropic, doorgerekend op één scenario. Het is een rekenvoorbeeld, geen klantcijfer.

Eén endpoint, en waarom dat de vraag verschuift#

Er is geen aparte endpoint voor chat, voor classificatie of voor samenvatten. Alles loopt over dezelfde POST, en het verschil zit in wat je meestuurt.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Classificeer dit orderbericht." }]
  }'

Drie velden zijn verplicht: model, max_tokens en messages. De versieheader anthropic-version: 2023-06-01 staat los van het model en verandert niet mee.

De modelkeuze is een string die je per call kunt wisselen, en dat is de belangrijkste architectuurbeslissing die je later nog goedkoop kunt terugdraaien. Vier actuele opties, met de lijstprijs per miljoen tokens volgens Anthropic en het contextvenster uit het modeloverzicht:

Let op de verhouding: uitvoer is bij elk model vijf keer zo duur als invoer. Een functie die veel leest en weinig schrijft — classificeren, routeren, valideren — is daarom structureel goedkoper dan een functie die lange teksten produceert.

Drie architecturen, en waar je tokens heen gaan#

Welke van de drie je kiest, bepaalt je rekening meer dan je modelkeuze. Ze sluiten elkaar niet uit, maar ze belasten heel verschillende delen van de call.

Tool use is de enige vorm waarin de AI iets in jouw systeem verandert. Je definieert een functie met een JSON-schema, Claude kiest hem en levert de argumenten; jij voert hem uit en stuurt het resultaat terug.

Wil je die werkwijze niet zelf bouwen maar via een standaardprotocol aansluiten, dan is MCP de route: je zet je bestaande tools achter één MCP-server en verbindt die met de API.

RAG verplaatst het probleem naar je ophaallaag. In onze eigen assistent zit het meeste werk dan ook niet in de call maar in de index: chunkgrootte, verse embeddings en de vraag of de júiste passage bovenkomt.

Batch is de goedkoopste knop die er is en wordt het vaakst overgeslagen. De Message Batches API halveert de prijs en de meeste batches zijn binnen een uur klaar.

Wat na 24 uur niet af is verloopt zonder kosten, en resultaten blijven 29 dagen beschikbaar.

De praktische scheidslijn is of iemand op het antwoord wacht. Live orderroutering niet in batch; de nachtelijke herclassificatie van gisteren wél.

Het rekenvoorbeeld: 4.000 orderberichten per maand#

Neem een groothandel die orders per mail met PDF binnenkrijgt en ze wil laten classificeren naar route, debiteur en betrouwbaarheid. Drie aannames, elk met een eigen tokenpost:

• Vaste instructie met routedefinities en voorbeelden: 3.000 tokens.
• Variabel per bericht, mailtekst plus PDF-tekst: 3.000 tokens.
• Antwoord in JSON: 300 tokens.

Dat is 6.000 invoertokens en 300 uitvoertokens per bericht, oftewel 24 miljoen invoer- en 1,2 miljoen uitvoertokens per maand.

Dat zijn de hele modelkosten. Het bouwen en beheren van de keten eromheen — koppeling, escalatie, monitoring, evaluatieset — is bij ons de post die telt, en die begint bij €8.500 voor één ingebouwde AI-functie, zoals de gids software met AI per patroon uitsplitst.

Wie op dit volume kiest tussen Haiku en Opus kiest tussen dertig en honderdvijftig dollar. Dat is zelden het gesprek waard; de keuze hoort te gaan over hoe vaak het model ernaast zit en wat die fout kost.

De cachegrens die stil faalt#

Prompt caching is de tweede goedkope knop: je markeert het vaste deel van je call, en herhaalde calls lezen dat deel uit de cache. Een cache write kost 1,25 keer de invoerprijs, een cache read 0,1 keer — dus vanaf de tweede identieke prefix ben je goedkoper uit dan zonder cache.

Alleen: onder een modelafhankelijke ondergrens gebeurt er niets, en je krijgt géén foutmelding. Volgens de documentatie van Anthropic worden kortere prompts "processed without caching, and no error is returned".

Die reeks loopt niet netjes met de generaties mee, en dat is de valkuil. Het goedkoopste model heeft de strengste ondergrens: onze instructie van 3.000 tokens cachet wél op Sonnet 5 en Opus 5, en op Haiku 4.5 helemaal niet.

Controleer het daarom in de response en niet in je hoofd. Staan cache_creation_input_tokens en cache_read_input_tokens allebei op nul, dan is er niets gecacht.

Terug naar het voorbeeld. Op Sonnet 5 komt de vaste instructie uit de cache: 12 miljoen tokens à $0,20 in plaats van $2, plus enkele honderden cache writes, wat de maandrekening van $60 naar ongeveer $41 brengt.

Op Haiku 4.5 blijft diezelfde instructie op $30 staan, ongecacht. Het verschil tussen een sterker model mét cache en het goedkoopste model zónder is op dit volume ruim een derde — niet een factor.

De limiet die je raakt is niet de limiet die je verwacht#

De Claude API begrenst drie dingen tegelijk per model: requests per minuut, invoertokens per minuut en uitvoertokens per minuut. Op de Start-tier is dat volgens Anthropic 1.000 RPM, 2.000.000 ITPM en 400.000 OTPM voor Sonnet 5, Opus 5 en Haiku 4.5.

Reken het om naar calls per minuut en de rangorde draait om:

• Op invoer: 2.000.000 ÷ 6.000 = 333 calls per minuut.
• Op uitvoer: 400.000 ÷ 300 = 1.333 calls per minuut.
• Op requests: 1.000 calls per minuut.

Je plafond is dus de invoerlimiet, op een derde van je RPM. Bij een classificatiekoppeling zit de rem bijna altijd daar; bij een functie die lange teksten genereert kantelt het naar OTPM.

Caching verhoogt dat plafond bovendien gratis: cache reads tellen op vrijwel alle modellen niet mee voor ITPM. Met 3.000 van de 6.000 tokens uit de cache verdubbelt je doorvoer naar ongeveer 666 calls per minuut, zonder tierverhoging.

Op 4.000 berichten per maand raak je dit nooit. Je raakt het bij de eenmalige actie die niemand begroot: de volledige hersynchronisatie na een migratie — precies dezelfde les als bij de limieten van Exact Online.

Twee foutvormen lijken op elkaar en zijn het niet. Een echte rate limit geeft HTTP 429 met een retry-after-header; het bereiken van de maandelijkse spend cap geeft óók 429, maar zónder retry-after en met error_code: enforced_spend_limit_reached.

Een limiet die je zélf hebt ingesteld geeft zelfs HTTP 400.

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic() // leest ANTHROPIC_API_KEY uit de omgeving

try {
  const response = await client.messages.create({ model: 'claude-sonnet-5', max_tokens: 1024, messages })
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // 429: respecteer retry-after. Ontbreekt die header, dan is het de spend cap
    // en heeft opnieuw proberen geen zin tot de volgende maand.
  } else if (error instanceof Anthropic.BadRequestError) {
    // 400: nooit opnieuw proberen. Jouw request, of je eigen spend limit.
  } else if (error instanceof Anthropic.APIError) {
    // 500 en 529 (overloaded): exponentiele backoff.
  }
}

Blindelings herhalen op elke fout is de duurste bug in dit soort koppelingen: een 400 wordt er nooit beter van, en een spend-cap-429 evenmin.

AVG, de DPA en de EU-vraag die je niet mag wegpoetsen#

Het contractuele deel is ongebruikelijk simpel. Anthropic treedt op als verwerker en "only processes the data as instructed by the customer", en de DPA met Standard Contractual Clauses is automatisch onderdeel van de Commercial Terms — je hoeft hem niet apart te tekenen.

Training op je data is contractueel uitgesloten: de commerciële voorwaarden stellen dat Anthropic "may not train models on Customer Content from Services", en de uitvoer is van jou.

Bewaartermijnen zijn kort, met één uitzondering die je in je DPIA hoort te noemen. Invoer en uitvoer worden binnen 30 dagen verwijderd, maar bij een signalering door de trust-and-safety-systemen tot 2 jaar bewaard, en de bijbehorende scores tot 7 jaar.

En dan de vraag die in Nederlandse offertes stelselmatig wordt weggepoetst: EU-dataresidentie kan op de eigen Claude API vandaag niet. De parameter inference_geo kent volgens de documentatie precies twee waarden, "global" en "us", en voor opslag geldt dat "us" momenteel de enige beschikbare workspace-geo is.

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "inference_geo": "us",
  "messages": [{ "role": "user", "content": "..." }]
}

US-only verwerking kost bovendien 1,1 keer de standaardprijs, op invoer, uitvoer én cache. Je koopt er voorspelbaarheid mee, geen Europese verwerking.

Wat betekent dat praktisch? Voor een classificatiekoppeling op orderberichten is de doorgifte naar de VS gedekt door de SCC's in de DPA en is dit een DPIA-regel, geen blokkade.

Voor bijzondere persoonsgegevens — zorgdossiers, medische data — is het wél een blokkade zolang je beleid Europese verwerking eist. Dan blijft er één route over die niet aan het model raakt: pseudonimiseer vóór de call, zodat wat de VS bereikt geen herleidbare persoon meer is.

Welke abonnementsvorm daarnaast bij je team past, en hoe Team en Enterprise zich op ditzelfde punt verhouden, staat in Claude zakelijk inzetten. De brede modelvergelijking staat in Claude vs ChatGPT zakelijk.

Orders uit Exact classificeren: hoe de keten eruitziet#

Het concrete voorbeeld, met de stukken die er in productie echt toe doen. Een binnenkomend orderbericht moet een route krijgen, aan een debiteur worden gekoppeld en in de juiste administratie belanden.

const response = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: ROUTE_INSTRUCTIE, // routedefinities + voorbeelden, minimaal 1.024 tokens
      cache_control: { type: 'ephemeral' },
    },
  ],
  tools: [
    {
      name: 'orderroute',
      description: 'Legt route, debiteur en betrouwbaarheid van een orderbericht vast.',
      input_schema: {
        type: 'object',
        properties: {
          route: { type: 'string', enum: ['spoed', 'standaard', 'retour', 'vraag'] },
          debiteurcode: { type: 'string' },
          betrouwbaarheid: { type: 'number' },
        },
        required: ['route', 'debiteurcode', 'betrouwbaarheid'],
        additionalProperties: false,
      },
      strict: true,
    },
  ],
  tool_choice: { type: 'tool', name: 'orderroute' },
  messages: [{ role: 'user', content: bericht }],
})

Vier dingen in dit fragment doen het werk. cache_control op de instructie zet de caching uit de vorige sectie aan; strict: true met additionalProperties: false garandeert dat de argumenten exact je schema volgen.

tool_choice dwingt af dát er geclassificeerd wordt in plaats van dat er over wordt gepraat. Eén waarschuwing: op Claude Fable 5.1 is een gedwongen tool_choice niet toegestaan en krijg je een 400 — gebruik daar auto plus strict.

En betrouwbaarheid is geen sier. Onder je eigen drempel schrijft de koppeling niets weg maar zet hij het bericht in een wachtrij voor een mens, precies zoals onze OCR-keten bij een onleesbare foto expliciet géén waarde levert in plaats van een gok.

Daarna begint het Exact-deel, en dat is het deel dat de meeste tijd kost. De boeking moet expliciet naar het juiste division-nummer, het access-token leeft tien minuten en het refresh-token roteert bij elke vernieuwing.

Lees de argumenten bovendien als object uit het tool_use-blok en doe nooit string-matching op de geserialiseerde invoer: de JSON-escaping verschilt per model.

De vraag of je zo'n laag bovenop je pakket bouwt of de software eronder verbouwt, is een aparte afweging — die staat uitgewerkt in AI integreren in bestaande software.

Wanneer je de Claude API níét zelf koppelt#

Drie situaties waarin wij afraden om zelf op de API te bouwen, ook al kan het technisch prima.

• Je pakket heeft al een AI-knop die doet wat je nodig hebt. Dan koop je met een eigen koppeling vooral beheerlast; de afweging staat in AI integreren in bestaande software.
• Je wilt een afgebakende taak zelfstandig laten uitvoeren. Dan is de agentvorm de kortere route, met een eigen kostenmodel: zie AI-agent laten maken.
• Je hebt nog geen evaluatieset. Zonder een verzameling echte gevallen waartegen je meet, weet je bij de eerste modelwissel niet of je vooruit of achteruit bent gegaan.

Die laatste is de belangrijkste en de goedkoopste om nu al te regelen. Verzamel honderd echte berichten met het juiste antwoord erbij, vóórdat er één regel koppelcode staat.

Hoe het ontwikkelen zelf verandert wanneer een bureau met AI bouwt, staat los van dit alles beschreven in software laten ontwikkelen met AI.

Wil je weten welk patroon in jouw software thuishoort en wat het op jouw volume kost? Bekijk hoe wij AI-software bouwen, of laat ons met AI op eigen data meekijken op je documenten.

Twijfel je nog over de vorm, plan dan een gesprek van 30 minuten.