Inputs — text, JSON, images, audio and documents

What a decision can read — text, structured JSON, images, voice notes and documents (PDF, Word, Excel, PowerPoint, CSV and more) — and how each one reaches Jev, Laya or OpenAI Decisions.

A decision reads its state. Besides text and JSON, an object state can carry files: declare a field as image, audio or file and send the file in it. Dcision turns every file into something the engine reads — text, or an image for engines that see images — before the engine is called, so the same decision runs on any engine.

You sendDeclareWhat the engine gets
Texta text state, or a string fieldthe text
Structured JSONan object state with typed fields, or a listthe JSON
Imagean image field — PNG, JPEG, GIF or WebPOpenAI Decisions: the image itself. Jev and Laya: a description of the image with its visible text, written by OpenAI
Text + imagean object state with a string field and an image fieldboth, side by side
Voice / audioan audio field — MP3, WAV, OGG/Opus (WhatsApp voice notes), M4A, WebM, FLAC, AAC, AMRthe transcript (OpenAI speech-to-text)
Document or any filea file fieldits text: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx, .xls), OpenDocument (.odt, .ods, .odp), CSV, RTF, HTML, XML, EPUB, Markdown and plain text are read by Dcision; scanned PDFs, legacy .doc/.ppt and other formats are read by OpenAI. Images and audio sent in a file field are handled as above

Declare file fields

{
  "kind": "object",
  "fields": [
    { "key": "message", "type": "string" },
    { "key": "photo", "type": "image" },
    { "key": "voice", "type": "audio" },
    { "key": "invoice", "type": "file", "required": true }
  ]
}

Send a file

A file field takes any of these:

FormExample
data: URL (base64)"data:image/png;base64,iVBORw0KGgo…"
Object with base64{ "data": "JVBERi0xLjQK…", "filename": "nf-1042.pdf", "mime_type": "application/pdf" } — filename and mime_type are optional
https:// URL"https://files.example.com/nf-1042.pdf" or { "url": "…", "filename": "nf-1042.pdf" } — Dcision downloads it
curl -X POST https://api.dcision.io/v1/decisions/invoice-triage \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"state\": {\"message\": \"Can we pay this?\", \"invoice\": {\"data\": \"$(base64 -w0 nf-1042.pdf)\", \"filename\": \"nf-1042.pdf\"}}}"

From the SDKs and the CLI:

import { readFile } from "node:fs/promises";
import { Dcision, fileFromBytes, fileFromUrl } from "@dcision/sdk";

const decision = await new Dcision().decide("invoice-triage", {
  message: "Can we pay this?",
  invoice: fileFromBytes(await readFile("nf-1042.pdf"), "nf-1042.pdf"),
  photo: fileFromUrl("https://files.example.com/receipt.jpg"),
});
from dcision import Dcision, file_from_path

decision = Dcision().decide("voice-routing", {"voice": file_from_path("note.ogg")})
dcision decide invoice-triage --state '{"message":"Can we pay this?"}' --file invoice=./nf-1042.pdf

From a form, n8n, Make or Zapier, the webhook trigger also takes files as multipart/form-data:

curl https://api.dcision.io/v1/hooks/whk_… \
  -F state='{"message":"Can we pay this?"}' \
  -F invoice=@nf-1042.pdf

In the Playground, file fields get a file picker — and audio fields a Record button for a voice note.

The format comes from the file's bytes, not from its name or mime_type: a .pdf that is really a PNG is read as an image. An image field refuses anything but an image and an audio field anything but audio (422 INVALID_STATE); a file field takes any format.

URLs must be public https:// addresses that answer 200 with the file — redirects are not followed, and private or reserved addresses are refused, like destinations.

What the engine reads

Each file field is replaced by what was read from it, and the engine — and your destinations and the execution log — see that instead of the bytes:

{
  "message": "Can we pay this?",
  "invoice": { "kind": "document", "file": "nf-1042.pdf", "content_type": "application/pdf", "bytes": 48213, "text": "NOTA FISCAL Nº 1042 … Total R$ 380,00" },
  "voice": { "kind": "audio", "file": "note.ogg", "content_type": "audio/ogg", "bytes": 21877, "text": "I want to cancel order 1042 and get a refund." },
  "photo": { "kind": "image", "file": "receipt.jpg", "content_type": "image/jpeg", "bytes": 90311, "text": "", "image": 1 }
}

On OpenAI Decisions, "image": 1 points to the first image sent with the call; write instructions that refer to it naturally ("Does the photo show damage?"). On Jev and Laya, text holds the image's description instead.

Point instructions at the text by field name: "Does the `invoice` total exceed R$ 1,000?", "Does `voice` ask for a refund?". In destinations, use {{state.voice.text}} to forward the transcript.

Long files are cut to fit the engine's token budget: the texts of all files share about 96,000 characters — short ones stay whole — and a cut text ends with … and has "truncated": true.

Who reads each file — and who pays

FileRead byCost
Documents Dcision can parse (PDF with text, Office, OpenDocument, spreadsheets, CSV, RTF, HTML, text)Dcisionnone
Images on OpenAI Decisionsthe enginepart of the engine call
Audio; images on Jev or Laya; scanned PDFs and other formatsOpenAIyour OpenAI account

Files that need OpenAI use the workspace's OpenAI key (Settings → Engine → OpenAI key), or Dcision's when this environment has one. Without either, those runs answer 424 ENGINE_NOT_CONFIGURED — documents Dcision parses never need a key. A failure while OpenAI reads a file is an engine error (ENGINE_*): with onEngineError: "fallback" the decision answers with its fallback action.

Reading files takes time — a minute of audio takes a few seconds to transcribe — on top of the engine call. Give clients a timeout of 60 s for decisions with audio.

Cost in the response

When the state had files, the response's metrics show what reading them took:

FieldWhat it is
metrics.input_filesHow many files were read.
metrics.input_processing_msTime spent downloading and reading them, included in latency_ms.
metrics.input_cost_usdThe estimated OpenAI cost of reading them — 0 when Dcision read them all itself.

metrics.estimated_cost_usd — and the estimated cost in the execution log and the Overview — includes input_cost_usd. The estimate uses OpenAI's list prices for the models that read files by default: gpt-4o-transcribe for audio (US$2.50 per 1M input tokens, US$10 per 1M output tokens) and gpt-5-mini for image descriptions and file reading (US$0.25 and US$2). It is an estimate; your OpenAI bill is the reference. Without files, these fields are absent. See Run a decision.

Limits

LimitValue
One file20 MB
All the files of a state24 MB, up to 10 files
Request body of a run32 MB on the API, the Playground and webhook triggers (413 PAYLOAD_TOO_LARGE past it); the state without its files stays limited to 128 KB
File text read into the stateabout 96,000 characters together, cut evenly
Reading the files of one run60 s

The execution log keeps each file's name, type, size and the first 4,000 characters of its text — never the file itself. With storeInput: false it keeps nothing.

MCP requests are limited to 1 MB: send files to the MCP server as https:// URLs.

On this page