Skip to main content
POST
Create chat completion
The single inference endpoint. It is OpenAI-compatible: the official OpenAI clients work as-is with base_url pointed at https://api.hcompany.ai/v1/. Holo-specific behavior (structured outputs, the reasoning toggle) is controlled by extra body fields documented below. Returns a chat completion object, or a stream of chunk objects when stream is true.

Body parameters

string
required
Model ID to run. One of the IDs listed on the Models page, e.g. holo4-27b.
array
required
The conversation so far. Standard OpenAI message objects (role, content); content can be a string or an array of text and image_url parts. Images accept HTTPS URLs or base64 data URIs (JPEG, PNG, WebP), up to 5 per request.
object
Holo-specific. Constrain the response, at the decoding level, to a JSON object matching a schema: pass {"json": <JSON Schema>}. The object is returned in message.content. Use this for the structured-output agent loop and element localization.
object
Holo-specific. {"enable_thinking": bool} toggles the reasoning channel. Use true for agent loops (Holo plans before acting), false for single-shot calls like grounding and OCR.
string
How much the model plans before acting: "low", "medium", or "high". "medium" is a sensible default for agent loops.
array
OpenAI-style function declarations for native function calling. Supported by every model except holo3-122b-a10b. A model supports it when tools is in its supported_features in GET /v1/models. Set tool_choice: "required" so the model acts on every step, and do not mix with structured_outputs.
string
Standard OpenAI semantics. Use "required" in function-calling agent loops.
boolean
default:"false"
Stream the response as server-sent chunk events. Reasoning tokens arrive in delta.reasoning, content in delta.content.
integer
Output cap for this request. The hard ceiling is the model’s max_output_length in GET /v1/models, 8,192 tokens on the Holo3 models.
number
Sampling temperature. Use 0.0 for deterministic single-shot calls (localization, OCR); 0.8 works well in agent loops. Also supported: top_p, top_k, stop, frequency_penalty, presence_penalty, seed.

Response

string
The action or answer: the constrained JSON object (structured-output mode) or the assistant text. null when the model responded with tool_calls only.
string
The thinking trace, present when thinking is enabled. Read it for visibility; never feed it back. Not carried between turns, see Reasoning.
array
Present in native function-calling mode only. Each call carries an id and a function object with name and a JSON-encoded arguments string.
string
stop, length (hit max_tokens or the model ceiling), or tool_calls.
object
prompt_tokens, completion_tokens, total_tokens for the request. prompt_tokens_details.cached_tokens is the part of the prompt served from the cache, see Prompt caching. prompt_tokens_details is null when nothing was.

Prompt caching

When a prompt starts with the same tokens as a recent request to the same model, such as a fixed system prompt or the growing history of an agent loop, the server reuses its work on that part. There is nothing to enable. The reused part is reported as usage.prompt_tokens_details.cached_tokens and billed at the cached input price. The rest of the prompt and all output are billed at the listed rates. Each model’s cached input price is on the Models page and in GET /v1/models as pricing.input_cache_read. Caching is best effort. Keep the stable part of the prompt at the start, and expect the count to vary between requests.

Examples

Streaming