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 send | Declare | What the engine gets |
|---|---|---|
| Text | a text state, or a string field | the text |
| Structured JSON | an object state with typed fields, or a list | the JSON |
| Image | an image field — PNG, JPEG, GIF or WebP | OpenAI Decisions: the image itself. Jev and Laya: a description of the image with its visible text, written by OpenAI |
| Text + image | an object state with a string field and an image field | both, side by side |
| Voice / audio | an audio field — MP3, WAV, OGG/Opus (WhatsApp voice notes), M4A, WebM, FLAC, AAC, AMR | the transcript (OpenAI speech-to-text) |
| Document or any file | a file field | its 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:
| Form | Example |
|---|---|
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.pdfFrom 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.pdfIn 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
| File | Read by | Cost |
|---|---|---|
| Documents Dcision can parse (PDF with text, Office, OpenDocument, spreadsheets, CSV, RTF, HTML, text) | Dcision | none |
| Images on OpenAI Decisions | the engine | part of the engine call |
| Audio; images on Jev or Laya; scanned PDFs and other formats | OpenAI | your 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:
| Field | What it is |
|---|---|
metrics.input_files | How many files were read. |
metrics.input_processing_ms | Time spent downloading and reading them, included in latency_ms. |
metrics.input_cost_usd | The 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
| Limit | Value |
|---|---|
| One file | 20 MB |
| All the files of a state | 24 MB, up to 10 files |
| Request body of a run | 32 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 state | about 96,000 characters together, cut evenly |
| Reading the files of one run | 60 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.