Create a chat completion

OpenAI-compatible. Point any OpenAI client at https://api.hcompany.ai/v1/.

POST /v1/chat/completions

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hcompany.ai/v1/",
    api_key=os.environ["HAI_API_KEY"],
)

resp = client.chat.completions.create(
    model="holo4-27b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://your-host/screenshot.png"}},
            {"type": "text", "text": "Which open ticket has the highest priority? Answer in one sentence."},
        ],
    }],
    reasoning_effort="medium",
)

print(resp.choices[0].message.content)

200

{
  "id": "chatcmpl-01a189d0-85ba-7dd2-b716-209047f04ee6",
  "object": "chat.completion",
  "created": 1793313506,
  "model": "holo4-27b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Ticket #2042, \"Export to CSV fails,\" is the open ticket with the highest priority.",
        "reasoning": "I need to identify which open ticket has the highest priority. Tickets 2042, 2040, and 2036 are Open..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 575,
    "completion_tokens": 201,
    "total_tokens": 776,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 176}
  }
}

Request body

model · string · required

Model ID to run. One of the IDs from List models, for example holo4-27b.

messages · object[] · required

The conversation so far, as standard OpenAI message objects. Images accept HTTPS URLs or base64 data URIs (JPEG, PNG, WebP), up to 5 per request.

role · string

content · string | object[]

A string or an array of text and image_url parts.

structured_outputs · 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.

With the OpenAI SDKs, pass Holo-specific fields through extra_body (Python) or an untyped spread (TypeScript). On the wire they are top-level fields, and the API silently ignores a literal "extra_body" key.

response_format · object

The standard OpenAI field for the same constraint: {"type": "json_schema", "json_schema": {"name": "...", "schema": <JSON Schema>}}. Typed in the OpenAI SDKs, so no extra_body is needed.

chat_template_kwargs · object

Holo-specific. {"enable_thinking": false} turns thinking off on every model, like reasoning_effort: "none". Keep thinking on for agent loops, and turn it off for single-shot calls like grounding and OCR.

reasoning_effort · string

How much the model plans before acting. "none" turns thinking off on every model. "disabled" is the Agents API spelling and returns 400 here.

Model	Accepted levels	Default	Turn thinking off
holo4-27b	low, medium, xhigh. Others, such as high, return 400	xhigh	"none", or chat_template_kwargs: {"enable_thinking": false}
holo4-35b-a3b, holo3-1-35b-a3b, holo3-122b-a10b	Accepted and ignored	Thinking on	"none", or chat_template_kwargs: {"enable_thinking": false}

tools · object[]

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.

tool_choice · string

Standard OpenAI semantics. Use "required" in function-calling agent loops.

stream · boolean · default: "false"

Stream the response as server-sent chunk events. Reasoning tokens arrive in delta.reasoning, content in delta.content. Set stream_options: {"include_usage": true} to get usage in the last chunk.

max_tokens · integer

Output cap for this request. max_completion_tokens is accepted as an alias. The hard ceiling is the model’s max_output_length in GET /v1/models, 8,192 tokens on Holo3 and Holo3.1.

temperature · number

Sampling temperature. Use 0.0 for deterministic single-shot calls (localization, OCR) and 0.8 in agent loops.

top_p · number

Nucleus sampling: sample only from the smallest token set whose probability mass reaches top_p.

top_k · integer

Sample only from the top_k most likely tokens. Not an OpenAI SDK argument, so pass it through extra_body like the Holo-specific fields.

stop · string | string[]

Sequences that end generation when produced.

frequency_penalty · number

Penalizes tokens in proportion to how often they already appeared.

presence_penalty · number

Penalizes tokens that already appeared at least once.

seed · integer

Seed for best-effort reproducible sampling.

Each model lists the sampling fields it accepts in supported_sampling_parameters from GET /v1/models. n must be 1.

Response

200 with a chat completion object, or a stream of chunk objects when stream is true.

choices[].message.content · 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.

choices[].message.reasoning · string

The thinking trace, present when thinking is on. Read it for visibility, but never feed it back: reasoning is not carried between turns.

choices[].message.tool_calls · object[]

Present in native function-calling mode only.

id · string

function.name · string

function.arguments · string

The call’s arguments, JSON-encoded.

choices[].finish_reason · string

stop, length (hit max_tokens or the model ceiling), or tool_calls.

usage · object

Token counts for the request.

prompt_tokens · integer

completion_tokens · integer

total_tokens · integer

prompt_tokens_details.cached_tokens · integer

The part of the prompt served from the cache.

completion_tokens_details.reasoning_tokens · integer

The part of the completion spent thinking.

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hcompany.ai/v1/",
    api_key=os.environ["HAI_API_KEY"],
)

resp = client.chat.completions.create(
    model="holo4-27b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://your-host/screenshot.png"}},
            {"type": "text", "text": "Which open ticket has the highest priority? Answer in one sentence."},
        ],
    }],
    reasoning_effort="medium",
)

print(resp.choices[0].message.content)

200

{
  "id": "chatcmpl-01a189d0-85ba-7dd2-b716-209047f04ee6",
  "object": "chat.completion",
  "created": 1793313506,
  "model": "holo4-27b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Ticket #2042, \"Export to CSV fails,\" is the open ticket with the highest priority.",
        "reasoning": "I need to identify which open ticket has the highest priority. Tickets 2042, 2040, and 2036 are Open..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 575,
    "completion_tokens": 201,
    "total_tokens": 776,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 176}
  }
}

Streaming

Python

stream = client.chat.completions.create(
    model="holo4-27b",
    messages=[{"role": "user", "content": "In one sentence, what is a computer-use agent?"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Stream

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"holo4-27b","choices":[{"index":0,"delta":{"reasoning":"..."},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"holo4-27b","choices":[{"index":0,"delta":{"content":"..."},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"holo4-27b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Errors

Status	Cause
400	A parameter value the model rejects, for example reasoning_effort: "high" on holo4-27b (error.code invalid_reasoning_effort), or "disabled".
404	Unknown model ID (error.code model_not_found), for example one removed after its deprecation_date. Switch to a served ID from GET /v1/models.