Skip to content
DecisionNodeDecisionNdedocs
  • Guides
  • API reference
  • Examples
  • Playground

start here

  • QuickstartGet startedGet an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state, optional images and video frames. One request, one buffered JSON response, one answer per question.
  • QuestionsConceptsQuestions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a…
  • ConfidenceConceptsProbabilities are calibrated per question type, so a threshold means what it says on the data we measure.
  • ImagesConceptsSend up to 16 images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and…
  • Batch jobsPatternsSend up to 10,000 requests in one file and collect the answers later, at a lower price than live calls.
  • Pricing and billingEvery workspace runs on a plan: Starter, Pro, Business or Dedicated.
↑↓ moveopen7 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  1. docs
  2. /
  3. Concepts

Images

Send up to 16 images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and answers through the same question types: choice, score, truth, and number for counts and values.

on this page6 sections
  1. Sending an image
  2. Encoding a file
  3. What the model reads
  4. What happens to an image
  5. Referring to images and videos
  6. Comparing images
  7. Tips
  8. What the model sees
  9. Video
images[0] "receipt"

Lumen Bakery

14 Harbour Row

28.09.202612:41
  • 2 x Flat white7.80
  • 1 x Club sandwich12.40
  • 2 x Lunch special28.00

TOTAL EUR48.20

Card **** 4417

thank you

state

claim EUR 48.20, 2026-09-28

  1. matches Truthtotal, currency, date

    0.00true

    approves at 0.900.00 false0.501.00 true

    your code approves the claim

  2. currency Choiceconfidence 0.94

    • EUR0.96
    • USD0.03
    • GBP0.01

input 1,184 tokensoutput 0, free

Does the receipt show the same total, currency and date as the claim? 0.97 true. Which currency is the receipt in? EUR, probability 0.96.

One photo of a receipt and the expense claim it should back up, in one request. matches is a Truth question that compares three fields at once; currency is a Choice read straight off the print. Both are answered from a single read of the image.

Sending an image#

Add an images array next to the state, up to 16 images within the request's token limit. Each image has an id you choose and either its bytes as base64 in data, with a media_type and no data: prefix, or an https url the server fetches. With more than one, say in each question which image it is about, best by its id: see Referring to images and videos.

curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode",
    "state": {
      "claim": { "amount": 48.2, "currency": "EUR", "date": "2026-09-28" }
    },
    "images": [
      { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "matches": {
        "type": "truth",
        "instructions": "Does the receipt show the same total, currency and date as the claim?",
        "criteria": {
          "true": "Total, currency and date on the receipt all match the claim",
          "false": "Any of them differs, or the receipt does not show it"
        }
      },
      "currency": {
        "type": "choice",
        "instructions": "Which currency is the receipt in?",
        "criteria": {
          "EUR": "euro",
          "GBP": "pound sterling",
          "USD": "US dollar"
        }
      }
    }
  }'

Image object

idstringrequired
Your name for the image, for example receipt or photo_1: unique within the request, at most 64 characters.
datastring
The image bytes, base64 encoded, with no data: prefix. Send data or url, not both.
urlstring
An https address the server fetches the image from, at most 2,048 characters. Nothing is uploaded with the request, so it stays small. Send data or url, not both.
media_typestring
image/jpeg, image/png or image/webp. Required with data. Optional with url: the type is read from the bytes, and must match when you give it.
An image by URL
{
  "images": [
    {
      "id": "receipt",
      "url": "https://files.example.com/claims/4411/receipt.jpg"
    }
  ]
}

Encoding a file#

Read the file's bytes, base64 encode them and put the text in data, with the media_type that matches the file. Each image may be up to 10 MB before encoding; the other limits are on Limits.

import base64, pathlib

raw = pathlib.Path("receipt.jpg").read_bytes()
data = base64.b64encode(raw).decode()
image = {"id": "receipt", "media_type": "image/jpeg", "data": data}

What the model reads#

  • Printed and handwritten text, including totals, dates and reference numbers.
  • Objects and their condition, as in a listing photo.
  • Layout: which number is the total, which line is the date, whether a stamp or signature is present.
  • Several images against each other, such as a photo and the document it should match.
  • How many: cars in a drone frame, items on a shelf, with a Number question.
  • Where: a spot on the thing or a box around it, with point and box questions.

What happens to an image#

  • Size

    What happens
    Up to 10 MB of image bytes each, up to 16 images per request within the token limit
  • Decoding

    What happens
    JPEG, PNG and WebP. An image above 40 megapixels is refused with a 400 before it is decoded
  • Orientation and metadata

    What happens
    EXIF orientation is applied, then all metadata (EXIF, GPS, camera data) is stripped before the model reads the image
  • Resolution

    What happens
    Resized so its longest side fits 2,048 px, enough to read small print on a photographed page. A smaller image is not enlarged
  • Order

    What happens
    Shown to the model as Picture 1, Picture 2 and so on, in the order of the images array, each with its id beside it
  • Questions

    What happens
    Every question in the request sees every image, together with the state
  • Tokens

    What happens
    About one token per 32 x 32 pixels as read, so a 1,024 x 1,024 image is about 1,026 tokens. Counted in usage.input_tokens and the context limit; the x-decisionnode-image-tokens response header says how many came from images
How the API handles each image
StepWhat happens
SizeUp to 10 MB of image bytes each, up to 16 images per request within the token limit
DecodingJPEG, PNG and WebP. An image above 40 megapixels is refused with a 400 before it is decoded
Orientation and metadataEXIF orientation is applied, then all metadata (EXIF, GPS, camera data) is stripped before the model reads the image
ResolutionResized so its longest side fits 2,048 px, enough to read small print on a photographed page. A smaller image is not enlarged
OrderShown to the model as Picture 1, Picture 2 and so on, in the order of the images array, each with its id beside it
QuestionsEvery question in the request sees every image, together with the state
TokensAbout one token per 32 x 32 pixels as read, so a 1,024 x 1,024 image is about 1,026 tokens. Counted in usage.input_tokens and the context limit; the x-decisionnode-image-tokens response header says how many came from images

What an image costs

Images are encoded once with the state and count toward usage.input_tokens and the 64k context. Image tokens are billed at the image price per million, $0.09 on DecisionNode and $0.08 on DecisionNode Flash, with no fee per image. At full size an image is about 4,096 tokens, so sixteen of them do not fit one request, and a large photo costs more than a small one: downscaling saves money when the decision is about the whole scene. When the question is about small things, such as counting many small objects or reading fine print, send the image at full resolution: the server keeps up to 2,048 px on the longest side, and downscaling below that loses the detail the answer depends on.

Referring to images and videos#

When a request has more than one image, say which image each question is about. There are two ways:

  1. 1.By id (recommended). Give each image a short, meaningful id and use it in the instructions, in backticks. With images receipt and claim_photo: "Does the total on receipt match the amount in the claim?", "Does claim_photo show visible damage?"
  2. 2.By number. Images are numbered from 1 in the order of the images array: "image 2", "the second image", "Picture 2" and "the last image" all work.
Two images, each named by its id
{
  "state": {
    "claim": { "amount": 48.2, "currency": "EUR", "date": "2026-09-28" }
  },
  "images": [
    {
      "id": "receipt",
      "url": "https://files.example.com/claims/4411/receipt.jpg"
    },
    {
      "id": "claim_photo",
      "url": "https://files.example.com/claims/4411/photo.jpg"
    }
  ],
  "questions": {
    "total_matches": {
      "type": "truth",
      "instructions": "Does the total on `receipt` match the amount in the claim?"
    },
    "damage": {
      "type": "truth",
      "instructions": "Does `claim_photo` show visible damage?"
    }
  }
}

Comparing images#

A question can compare images. A choice can name an image in each option:

Which camera shows more pallets
{
  "images": [
    {
      "id": "cam_north",
      "url": "https://cams.example.com/warehouse-3/north/latest.jpg"
    },
    {
      "id": "cam_south",
      "url": "https://cams.example.com/warehouse-3/south/latest.jpg"
    }
  ],
  "questions": {
    "more_pallets": {
      "type": "choice",
      "instructions": "Which camera shows more pallets?",
      "criteria": { "north": "`cam_north`", "south": "`cam_south`" }
    }
  }
}

A truth can name two images: with images dock_1, dock_2 and dock_3, "Is the package in picture 1 the same package as the one in picture 3?" The same by id: "Is the package in dock_1 the same package as the one in dock_3?"

Tips#

  • Prefer ids to numbers. An id stays right when images are added or reordered; a number moves with the order.
  • Use names, not digits, as ids: front, not 2, so an id never reads like a position.
  • Videos work the same way: by id, or by number ("video 1", "the first video"), counted from 1 in the order of the videos array and separately from the images.
  • In point and box questions the image field takes the id: a box "Draw a box around the package from picture 1" with "image": "dock_3" looks in dock_3 for the package shown in picture 1. See Points and boxes.

What the model sees#

Each image is introduced as Picture 1 (receipt):, Picture 2 (claim_photo): and so on, so a reference by number and a reference by id point to the same image. Videos are introduced the same way, as Video 1 (dock):. Ids are your own strings and must be unique within the request, across images and videos.

Video#

Frames from a camera, sent with their timestamps, are read as one video with order and timing, at about half the tokens of the same pictures sent as images: how many cars passed, which way a vehicle turned, whether smoke appeared. The request shape is on Video.

previousPoints and boxesnextVideo

DecisionNode is built and run by Bynn Intelligence, Inc.

  • Home
  • Playground
  • Examples
  • Console
  • Responsible use
  • Terms
  • Acceptable use
  • Privacy
  • Data processing
  • Defence addendum
  • Cookies
  • Affiliate program

on this page

  1. Sending an image
  2. Encoding a file
  3. What the model reads
  4. What happens to an image
  5. Referring to images and videos
  6. Comparing images
  7. Tips
  8. What the model sees
  9. Video