Streaming

Set "stream": true in your request body to receive the response as server-sent events. Each event contains a partial delta that you append until the stream ends. Streaming gives you lower time-to-first-token and a smoother user experience.

Request

Response format

Each event is a data: line followed by a JSON object. The stream ends with data: [DONE].

The first chunk contains the role delta. Subsequent chunks carry content deltas. The final chunk has an empty delta with a finish_reason.

Usage in code

When using the OpenAI SDK, set stream: true and iterate over the returned chunks:

Python

JavaScript

Streaming with tool calls

When streaming with tools, the model may emit tool_calls deltas across multiple chunks instead of (or after) content. Each tool call has an index to correlate deltas for the same tool invocation.

The stream produces tool_calls deltas across multiple chunks:

Accumulate tool calls by index. When finish_reason is "tool_calls", the tool call arguments are complete. Execute each tool and send the results back in a follow-up request.

Assembling tool calls from streamed chunks (Python)

After collecting the tool calls, execute each one and send a follow-up request with the tool role result messages appended. The model will then produce its final answer — either as a text stream or additional tool calls.

Image input

Deca models are multimodal — you can include images alongside text in user messages. Images must be base64-encoded and passed as a data URL. Hosted URLs are not supported.

Supported formats

Format	MIME type	Notes
PNG	image/png	Preferred for screenshots and diagrams.
JPEG	image/jpeg	Good for photographs.
WEBP	image/webp	Smaller file size, wide support.
GIF	image/gif	Only the first frame is processed.

Maximum image size is 20 MB per image (before base64 encoding adds ~33% overhead). Images are automatically resized and compressed by the API to fit the model's input constraints.

Multiple images

Include several images in one message by adding more image_url blocks:

SDK usage

Python

JavaScript

Tool use

Tools let the model call functions defined in your application. The model returns a tool_calls payload with function names and arguments; your code executes each function and sends the results back in a follow-up request.

Defining tools

Pass a tools array in your request. Each tool is a JSON Schema description of a function the model may call.

The model decides whether to call a tool based on the conversation. If it does, the response contains tool_calls instead of (or alongside) content.

The tool call loop

1. Request — send messages + tool definitions.
2. Response — model returns tool_calls with finish_reason: "tool_calls".
3. Execute — run each function in your application.
4. Continue — append the assistant message (with tool_calls) and each tool result as a tool-role message, then re-send.

The model may call multiple tools in one turn or go back and forth several times before producing a final text answer.

Response shape

Each tool call has a unique id used to match the result when sending it back.

Returning tool results

Append the assistant response (with tool_calls) and a tool-role message per result. The tool result references the call id and tool_call_id.

The model will read the tool result and either produce a final answer or call another tool.

SDK usage

Python

JavaScript

Best practices

• Write clear description fields — the model uses them to decide which tool to call.
• Mark all required parameters with "required".
• Keep tool result content compact to save context tokens.
• Validate arguments server-side before executing — the model may generate valid JSON that violates your schema.
• Return errors as normal tool content so the model can retry or apologize.
• Streaming works with tools — see the Streaming guide for how to assemble streamed tool_calls deltas.

Thinking

All Deca models use adaptive thinking internally. The model automatically decides when and how much to reason through a problem before generating a response — no configuration is needed.

• Thinking is always on and cannot be disabled.
• There are no knobs: you cannot set a thinking budget, adjust effort, or choose a display mode.
• Reasoning traces are internal and are not returned in the response. You only see the final text output.

This happens transparently on every request. The output you receive already reflects whatever reasoning the model applied.

Prompt caching

Prompt caching is on by default. Deca automatically caches prompt prefixes across requests, reducing latency and cost for repetitive or multi-turn workloads. Cache writes have no extra surcharge: tokens written to cache are billed at the normal input rate, and later cache hits are billed at a reduced token rate.

To opt out of caching for a specific request, set "cache_control": "none" at the top level:

The minimum cacheable prefix is 1,024 tokens. Shorter prefixes are processed normally without caching. Cached entries expire after 5 minutes of inactivity; each cache hit refreshes the TTL at no extra cost.

Check cache performance in the response usage fields:

Field	Description
cache_read_input_tokens	Tokens served from cache (billed at reduced rate).
cache_creation_input_tokens	Tokens written to cache for the first time.
input_tokens	Tokens after the last cache breakpoint (not cached).

Prompt caching works well for long system instructions, large context documents, tool definitions, and multi-turn conversations where earlier turns stay stable.

Rate limits

Rate limits are applied per API key and depend on the requested model and account tier. Paid accounts can send up to 1,000 requests per hour for deca-2.5-mini and deca-2.5-pro, and up to 500 requests per hour for deca-2.5-ultra. Free-tier accounts receive half of those limits.

If you receive a 429 response, retry with exponential backoff and jitter. For batch jobs, queue work rather than retrying every request at once.

Errors

Status	Meaning	What to do
400	Invalid request body.	Check JSON shape, required fields, and model name.
401	Missing or invalid API key.	Send Authorization: Bearer YOUR_API_KEY.
402	Insufficient credits.	Add credits or reduce request volume before retrying.
429	Too many requests.	Back off and retry later.
500+	Temporary service error.	Retry with backoff, then surface a graceful fallback.