AI-API-referentie

Alle endpoints van api.nodion.ai/v1, inclusief limieten en fouten.

Basis-URL: https://api.nodion.ai/v1. De API volgt het formaat van OpenAI, dus OpenAI-SDK's werken als je deze basis-URL instelt. Sleutels, het tegoed en de tabbladen in het dashboard vind je bij AI Inference. Modellen, aanbieders en prijzen staan in de modelcatalogus.

pythonimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.nodion.ai/v1",
    api_key=os.environ["NODION_AI_KEY"],
)
reply = client.chat.completions.create(
    model="<model>",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

Authenticatie

Stuur bij elk request een inference-sleutel (nodion_ai_…) mee als bearer-token. Platformsleutels (nodion_…) werken hier niet. GET /v1/models is de enige call waarvoor je geen sleutel nodig hebt.

httpAuthorization: Bearer nodion_ai_…

Bij een geweigerde sleutel krijg je een 401 met een van deze meldingen:

• missing bearer token
• invalid api key
• api key expired
• account disabled
• account under review

Elk antwoord bevat een X-Request-ID-header. Vermeld die als je contact opneemt met support.

JSON-requestbody's mogen tot 25 MiB groot zijn (tools 1 MiB, System One 512 KiB). Base64 maakt een bestand een derde groter, dus een afbeelding, PDF of OCR-document dat je inline in JSON meestuurt, mag ongeveer 18 MiB groot zijn. Multipart-uploads naar /v1/audio/transcriptions en /v1/audio/voices mogen tot 25 MiB groot zijn, met transcriptiebestanden tot 20 MiB en bestanden met stemvoorbeelden tot 10 MiB (11 MiB voor het hele formulier).

Endpoints

Audio, afbeeldingen en tools worden met voorbeelden beschreven bij AI Inference. De rest staat hieronder.

Vóór een call wordt een maximumbedrag van je tegoed gereserveerd. Daarna betaal je voor het gemelde gebruik, nooit meer dan het gereserveerde bedrag. De rest komt weer vrij. Meldt een geslaagd antwoord geen gebruik, dan wordt de volledige reservering in rekening gebracht. Een realtime transcriptiesessie reserveert de max_audio_seconds van het model (1.800 seconden als het model niets instelt), dus het tegoed moet vooraf een volledige sessie dekken.

Modellen

GET /v1/models geeft {"object": "list", "data": [...]} terug en toont chat-, embeddings- en rerankmodellen. OCR-, spraak-, beeld- en toolmodellen staan er niet in; de publieke catalogus op https://api.nodion.com/v2/public/ai/models bevat alle soorten. Handige velden per model:

• id: de waarde voor model in requests.
• kind: chat, embeddings of rerank.
• context_length en max_output_length in tokens.
• pricing: USD per token als decimale strings. pricing_eur bevat de prijzen in EUR.
• supported_sampling_parameters en supported_features (bijvoorbeeld tools, json_mode, structured_outputs, reasoning).
• reasoning_efforts: de waarden voor reasoning_effort die dit model accepteert (bijvoorbeeld none, low, high). Leeg als de niveaus niet instelbaar zijn.
• is_ready: false betekent dat er op dit moment geen gezonde route is. Het model blijft in de lijst staan.
• lifecycle: ga of preview. serving: hosted (de modelgewichten draaien op Nodion) of routed (doorgestuurd naar een aanbieder).
• supports_decisions: het model beantwoordt System One.
• coding_plan: Codion mag dit chatmodel aanbieden. Altijd true of false. Dit heeft niets te maken met het coding plan in de facturering.
• free_until: gezet zolang er een gratis periode loopt op een model dat alleen door Nodion wordt aangeboden. De tokenprijzen staan dan op 0.

Chat completions

POST /v1/chat/completions accepteert de body van OpenAI Chat Completions: model, messages en de optionele velden die het model noemt in supported_sampling_parameters en supported_features, zoals tools of response_format. Stuur reasoning_effort alleen mee als reasoning_efforts niet leeg is, en alleen met een waarde uit die lijst.

bashcurl https://api.nodion.ai/v1/chat/completions \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "stream": true,
    "max_tokens": 512,
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What is an embedding?"}
    ]
  }'

Wat de gateway met het request en het antwoord doet:

• Zonder max_tokens (of max_completion_tokens) zet de gateway max_tokens op de max_output_length van het model. Hogere waarden worden daartoe verlaagd.
• Met "stream": true komt het antwoord als server-sent events (regels data: {...}, daarna data: [DONE]). De gateway zet stream_options.include_usage, zodat de laatste chunk normaal gesproken het gebruik bevat. Breekt de upstreamverbinding halverwege de stream af, dan bevat een laatste chunk een error-object en finish_reason: "error", gevolgd door data: [DONE].
• Het veld model in het antwoord is het id dat je hebt gestuurd. Reasoning-tekst staat, als een model die teruggeeft, in reasoning_content.

PDF's kun je inline meesturen als file-contentblok met een base64-data-URI. De gateway zet de eerste 20 pagina's vóór de call om naar afbeeldingen, dus dit helpt alleen bij modellen met beeldinput. Verwijzingen via file_id worden geweigerd.

json{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize this contract."},
    {"type": "file", "file": {"file_data": "data:application/pdf;base64,JVBERi0..."}}
  ]
}

Facturering: input- en outputtokens tegen de prijs van het model, input uit de cache tegen de cacheprijs als de route die meldt. De reservering telt elke byte van het request als inputtoken, plus max_tokens. Bij requests met afbeeldingen of PDF's wordt het inputdeel verhoogd tot de contextlengte van het model, of tot minstens 128.000 tokens als het request groter is dan de context. Binnen de gratis periode van een model (free_until) zijn chat completions op gehoste routes gratis.

Responses API

POST /v1/responses accepteert de body van de OpenAI Responses API: model, input (tekst of een lijst items) en de optionele velden instructions, tools, tool_choice, parallel_tool_calls, text.format, reasoning.effort, max_output_tokens, max_tool_calls, temperature, top_p, top_logprobs, include en stream. De gateway vertaalt het request naar een chat completion, dus alles uit de sectie over chat completions geldt hier ook: de outputlimiet, de toegestane waarden voor reasoning_efforts, PDF's en facturering.

bashcurl https://api.nodion.ai/v1/responses \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "instructions": "Answer in one sentence.",
    "input": "What is an embedding?"
  }'

Met "stream": true is het antwoord de eventstream van de Responses API, zoals response.created, response.output_text.delta en response.function_call_arguments.delta, eindigend met response.completed en de bijbehorende usage. Breekt de stream af, dan is het laatste event response.failed. Reasoning-tekst komt in een reasoning-item als reasoning_text. Stuur dat item mee terug in vervolgrequests: reasoning sinds het laatste gebruikersbericht gaat terug naar het model, oudere reasoning alleen met reasoning.context: "all_turns".

De gateway voert web_search zelf uit, via de webzoekfunctie van Nodion. Als het model zoekt, haalt de gateway de resultaten op, geeft ze aan het model en roept het opnieuw aan. Het antwoord bevat een web_search_call-item met de zoekopdracht en de bron-URL's, gestreamd met de events response.web_search_call.in_progress, searching en completed. Facturering: elke zoekopdracht als een call naar /v1/tools/web_search, elke modelronde als een chat completion, en usage is de som van alle rondes. Een Response telt eenmaal mee voor de requestlimiet van de sleutel. Maximaal max_tool_calls zoekopdrachten per Response (standaard 10, maximaal 20); max_output_tokens geldt voor alle rondes samen. filters.allowed_domains, user_location (stad, regio, land) en search_context_size (5, 10 of 20 resultaten) worden toegepast. De zoekopdracht geeft alleen resultaten uit de zoekindex terug (titel, URL, snippet) en opent geen pagina's, ook niet met external_web_access: true.

Logprobs: met top_logprobs (tot 20) of include: ["message.output_text.logprobs"] staan ze op output_text als het model ze teruggeeft.

Hiermee werkt Codex CLI met Nodion, inclusief zoeken op het web:

toml# ~/.codex/config.toml
model = "<model>"
model_provider = "nodion"

[model_providers.nodion]
name = "Nodion"
base_url = "https://api.nodion.ai/v1"
env_key = "NODION_AI_KEY"
wire_api = "responses"

Verschillen met OpenAI:

• Nodion slaat geen responses op. store wordt genegeerd en het antwoord meldt store: false. Er is geen previous_response_id, conversation, item_reference of GET /v1/responses/{id}. Stuur het hele gesprek mee in input, zoals Codex doet.
• Tools: function, custom, namespace en web_search. Andere gehoste tools, zoals file_search of code_interpreter, worden geweigerd met 400.
• Zoekresultaten worden niet opgeslagen. Een web_search_call in het gesprek bereikt het model als de call met een opmerking, niet met de oude resultaten. annotations (bronvermeldingen) blijft leeg; de bronnen staan in de web_search_call.
• Afbeeldingen en bestanden in tooloutput bereiken het model niet; een notitie in de tekst vervangt ze.
• Niet ondersteund (400): background, prompt, truncation: "auto", file_id en file_url. Stuur afbeeldingen als image_url (een URL of data-URI) en PDF's als input_file met file_data.

Embeddings

POST /v1/embeddings accepteert de OpenAI-body (model, input als string of array) en geeft het embeddingsantwoord van OpenAI terug. Geen streaming. Gefactureerd op usage.prompt_tokens. Gebruik een model met kind: "embeddings".

bashcurl https://api.nodion.ai/v1/embeddings \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<embeddings-model>", "input": ["first text", "second text"]}'

Rerank

POST /v1/rerank geeft documents een score ten opzichte van een query. Het optionele top_n beperkt het aantal resultaten. Het antwoord bevat results met index (positie in documents) en relevance_score, plus usage.prompt_tokens, waarop je wordt gefactureerd. Gebruik een model met kind: "rerank".

bashcurl https://api.nodion.ai/v1/rerank \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<rerank-model>",
    "query": "How do I reset my password?",
    "documents": ["Billing FAQ", "Account recovery guide", "Release notes"],
    "top_n": 2
  }'

System One

POST /v1/systemone beantwoordt getypeerde vragen over een toestand. Het model geeft elk mogelijk antwoord een score in plaats van tekst te schrijven, dus je krijgt kansen terug, geen proza. Gebruik het voor routing, triage, moderatie of als controlepunt voordat een agent een tool uitvoert. Eén call beantwoordt tot 16 vragen over dezelfde toestand.

Modellen met supports_decisions: true op /v1/models ondersteunen System One. System One draait op door Nodion gehoste routes en bij aanbieders die System One zelf aanbieden. Faalt een route voordat die het request heeft uitgevoerd (rate limit, storing), dan gaat hetzelfde request naar de volgende route. Het tabblad Decisions in de Playground heeft kant-en-klare voorbeelden.

bashcurl https://api.nodion.ai/v1/systemone \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aleph-alpha/kolibri-1",
    "state": {
      "customer_tier": "enterprise",
      "ticket": "My checkout page shows a blank screen after I click Pay."
    },
    "questions": {
      "is_bug": {
        "type": "noul",
        "instructions": "Is the customer reporting a software defect?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should own this ticket?",
        "criteria": {
          "payments": "Checkout, billing, or payment processing issues.",
          "frontend": "Rendering, layout, or browser issues.",
          "account": "Login, permissions, or profile issues."
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": [
          "Can wait for the next release",
          "Should be fixed this week",
          "Blocking revenue right now"
        ]
      }
    }
  }'

Request

• model (verplicht): een model met supports_decisions.
• state (verplicht): waar de vragen over gaan. Een string, een object, een array of null.
• questions (verplicht): een object met 1 tot 16 entries. De sleutel is jouw naam voor de vraag (tot 128 tekens) en komt terug als sleutel in answers.

Elke vraag heeft een type, optionele instructions en criteria die van het type afhangen. Waarden van instructions en criteria kunnen een string, een object of een array zijn; null is overal toegestaan behalve bij scoreniveaus.

• noul: een ja/nee-vraag. criteria is optioneel en mag alleen de sleutels true en false hebben. Een noul vereist niet-lege instructions of minstens één niet-leeg criterium.
• choice: kies één label. criteria wijst 1 tot 26 labels elk een waarde toe; lege strings worden geweigerd. Labels moeten uniek zijn, ongeacht hoofdletters, en mogen maximaal 256 tekens lang zijn.
• score: beoordelen op een schaal. criteria is een array van 2 tot 10 niet-lege niveaus, laagste eerst. Niveau-indexen beginnen bij 0.

Onbekende velden worden geweigerd. De body mag tot 512 KiB groot zijn, en de toestand en de grootste vraag moeten samen in de context van het model passen.

Antwoord

json{
  "model": "aleph-alpha/kolibri-1",
  "answers": {
    "is_bug": {"type": "noul", "noul": 0.91},
    "team": {
      "type": "choice",
      "choice": "payments",
      "confidence": 0.78,
      "probabilities": {"payments": 0.82, "frontend": 0.15, "account": 0.03}
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "confidence": 0.6,
      "legend": {
        "0": "Can wait for the next release",
        "1": "Should be fixed this week",
        "2": "Blocking revenue right now"
      },
      "probabilities": {"0": 0.1, "1": 0.3, "2": 0.6}
    }
  },
  "usage": {"input_tokens": 412, "output_tokens": 0}
}

• noul: de kans dat het antwoord true is, van 0 tot 1.
• choice: choice is het waarschijnlijkste label, probabilities bevat elk label en telt op tot 1, en confidence is een waarde van 0 tot 1.
• score: score is het gemiddelde van de niveau-indexen, gewogen naar hun kans (0 tot het aantal niveaus min 1). probabilities en legend hebben de niveau-index als sleutel; legend wijst elke index een niveaubeschrijving toe. confidence is een waarde van 0 tot 1.
• model is het model dat heeft geantwoord. usage.output_tokens is altijd 0.

De waarden in het voorbeeldantwoord dienen ter illustratie.

Facturering

Alleen inputtokens worden gefactureerd, tegen de inputprijs van het model. Het model leest de toestand één keer per vraag, dus usage.input_tokens groeit met het aantal vragen. Vóór de call reserveert het tegoed (bytes van de toestand + bytes van alle vragen + 4.096) × het aantal vragen als inputtokens, en het request wordt afgerekend op usage.input_tokens, nooit boven de reservering. Mislukte requests worden niet gefactureerd; verbreek je de verbinding nadat het model heeft geantwoord, dan worden de inputtokens gefactureerd. Gratis periodes gelden zoals bij chat.

Fouten

System One gebruikt een eigen foutbody: {"detail": "message"}, en bij 422 een lijst met loc / msg / type-items die naar het veld wijzen.

json{
  "detail": [
    {"loc": ["body", "questions", "team", "criteria"], "msg": "choice accepts 1 to 26 criteria", "type": "too_long"}
  ]
}

• 401: sleutel ontbreekt of is ongeldig.
• 402: de facturering heeft het request geweigerd: tegoed, uitgavenlimieten, of er kon geen prijs voor het request worden bepaald. De redenen zijn die van de 402-codes, hier alleen als tekst in detail.
• 404: model not found, ook voor modellen zonder supports_decisions.
• 422: ongeldige body, body groter dan 512 KiB, toestand en vragen groter dan de context, of het model heeft het request geweigerd.
• 429: een sleutellimiet is bereikt (Retry-After: 5), of elke geprobeerde route van een aanbieder liep tegen een rate limit aan (de Retry-After van de aanbieder, maximaal 60 seconden).
• 502: het model kon niet antwoorden.
• 503: geen gezonde route, geen route die past bij de privacy-instellingen van het project, of de instellingen konden niet worden geladen.
• 529: alle routes voor het model zitten aan hun capaciteit. Retry-After: 5.

OCR

POST /v1/ocr volgt het formaat van Mistral OCR. Stuur het bestand inline mee als base64-data-URI; externe URL's worden geweigerd. PDF, PNG, JPEG en WebP werken.

bashcurl https://api.nodion.ai/v1/ocr \
  -H "Authorization: Bearer $NODION_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral/mistral-ocr-4-1",
    "document": {
      "type": "document_url",
      "document_url": "data:application/pdf;base64,JVBERi0..."
    }
  }'

• model: een OCR-model uit de publieke catalogus (kind: "ocr").
• document: {"type": "document_url", "document_url": "data:..."} of {"type": "image_url", "image_url": "data:..."}.
• pages (optioneel): indexen van de pagina's die gelezen moeten worden, beginnend bij 0. Niet elk OCR-model ondersteunt dit; gehoste OCR-modellen en firecrawl/pdf-inspector antwoorden met 400.
• include_image_base64 (optioneel): geeft ingesloten afbeeldingen terug als base64. Niet elk OCR-model geeft afbeeldingen terug; sommige antwoorden altijd met een lege images-lijst.

Het antwoord bevat pages (elk met index, markdown en images) en usage_info.pages_processed. Gefactureerd per verwerkte pagina. De reservering dekt het hele document, en documenten boven de max_pages van het model worden geweigerd. firecrawl/pdf-inspector leest alleen digitaal gegenereerde PDF's. Een afbeelding krijgt 422; een PDF met gescande pagina's krijgt 422 met code: "pages_need_ocr" en de betreffende pagina's in pages_needing_ocr.

Fouten en limieten

Elk endpoint behalve System One geeft fouten terug in de OpenAI-envelop:

json{
  "error": {
    "message": "insufficient AI balance. Top up in the AI Billing tab.",
    "type": "error",
    "code": "empty_balance"
  }
}

message is er altijd. type en de aanwezigheid van code verschillen per endpoint, dus kijk eerst naar de HTTP-status. Chat, embeddings, rerank en de webtools zetten de 402-codes in code. Als de route van het model op chat, embeddings of rerank antwoordt met een HTTP-fout, bevat de body ook request_id. De header X-Request-ID is er altijd.

• 400: ongeldige JSON, ontbrekend model, of een model van de verkeerde soort voor het endpoint (bijvoorbeeld een OCR-model op chat). Een body groter dan 25 MiB die het API-proces bereikt, krijgt request body exceeds 25 MiB.
• 401: zie Authenticatie.
• 402: het request is wegens het tegoed geweigerd; zie de codes hieronder.
• 404: model not found, of een endpoint dat niet bestaat.
• 413: de publieke host heeft een body groter dan 25 MiB geweigerd voordat de API draaide.
• 429: een sleutellimiet is bereikt, of het model is overbelast. Houd je aan Retry-After als die wordt meegestuurd.
• 502: de route van het model is mislukt. Probeer het later opnieuw.
• 503: geen gezonde route voor het model, geen route die past bij de privacy-instellingen van het project (tabblad Settings), of de instellingen konden niet worden geladen.

402-codes. Chat, embeddings, rerank en de webtools sturen ze in code. OCR, audio en afbeeldingen sturen alleen de melding, en System One stuurt die als detail.

• empty_balance: het beschikbare AI-tegoed dekt de reservering voor dit request niet. Waardeer op in het tabblad Billing, of zet automatisch opwaarderen aan.
• daily_quota: de uitgaven van vandaag op deze sleutel plus de openstaande reserveringen plus dit request zouden de daglimiet voor uitgaven van de sleutel overschrijden.
• month_quota: de uitgaven van deze maand plus openstaande reserveringen plus dit request zouden de maandelijkse uitgavenlimiet overschrijden die je in het tabblad Billing instelt.
• usage_limit: de uitgaven van deze maand plus openstaande reserveringen plus dit request zouden het maandplafond van je gebruiksniveau (usage tier) overschrijden. Het tabblad Billing toont je niveau en wanneer het volgende van kracht wordt.
• pricing_unavailable en reserve_failed: er kon geen prijs voor het request worden bepaald of geen reservering worden gemaakt. Probeer het opnieuw en neem daarna contact op met support, met het request-id erbij.

Standaardlimieten per sleutel:

• 600 requests per minuut
• 4.000.000 tokens per minuut (chat, embeddings, rerank en System One)
• 20 gelijktijdige requests
• 25 MiB requestbody bij chat, embeddings, rerank, OCR, audio en afbeeldingen. Tools: 1 MiB. System One: 512 KiB.

Bij chat, embeddings en rerank stuurt een 429 Retry-After: 5 voor de requestfrequentie en bij overbelasting, 10 voor de tokenrate en 2 voor gelijktijdigheid. System One stuurt altijd Retry-After: 5. Het aanmaken van een stem stuurt Retry-After als de eigen limieten worden bereikt (te veel gelijktijdige uploads, of meer dan tien aanmaakpogingen per uur). Andere 429's bij OCR, audio, afbeeldingen, de webtools en stemmen sturen er geen; wacht een paar seconden voordat je het opnieuw probeert. Neem contact op met support als je hogere limieten nodig hebt.