> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> H Platform has three products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). The `holo` CLI (`pip install "hai-agents[cli]"`) runs Agents API agents from a terminal, drives the user's own desktop with `-a h/holo-desktop`, and serves coding agents through `holo mcp`.
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `holo`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Models API

> Holo agent models behind an OpenAI-compatible API.

```python Python wrap theme={"system"}
response = 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": "Click the Login button."},
    ]}],
    tools=[click],
)
```

```typescript TypeScript wrap theme={"system"}
const response = await 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: "Click the Login button." },
  ] }],
  tools: [click],
});
```

```bash cURL wrap theme={"system"}
curl https://api.hcompany.ai/v1/chat/completions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "holo4-27b", "tools": [{"type": "function", "function": {"name": "click", "parameters": {"type": "object", "properties": {"x": {"type": "integer"}, "y": {"type": "integer"}}, "required": ["x", "y"]}}}],
    "messages": [{"role": "user", "content": [{"type": "image_url", "image_url": {"url": "https://your-host/screenshot.png"}}, {"type": "text", "text": "Click the Login button."}]}]}'
```

## Models

| Model | Tier | Best for | Context | Max output | [Agent loop](https://hub.hcompany.ai/models-api/build-an-agent/core-concepts.md#pick-an-output-format) | `reasoning_effort` | Price per 1M tokens (input / cached / output) |
| :- | :- | :- | -: | -: | :- | :- | :- |
| `holo4-27b` | Paid | **Start here.** Most capable: complex multi-step tasks and novel environments | 262,144 | 16,384 | Function calling | `low`, `medium`, `xhigh` (default), `none` | \$0.40 / \$0.04 / \$3.00 |
| `holo4-35b-a3b` | Paid | **Fastest.** Interactive agent loops: low cost and latency | 262,144 | 16,384 | Function calling | On, or `none` | \$0.30 / \$0.03 / \$2.00 |
| `holo3-1-35b-a3b` | Free | Trying Holo at no cost | 65,537 | 8,192 | Function calling, structured outputs | On, or `none` | \$0.25 / \$0.025 / \$1.80 |
| `holo3-122b-a10b` | Paid | Holo3 generation: long tasks with dense reasoning | 65,537 | 8,192 | Structured outputs | On, or `none` | \$0.40 / \$0.04 / \$3.00 |

Thinking is on by default. Only `holo4-27b` has effort levels; `reasoning_effort: "none"` turns thinking off on every model. Every model takes up to 5 images per request (JPEG, PNG, WebP). Cached input is the part of a prompt served from the [prompt cache](https://hub.hcompany.ai/models-api/build-an-agent/core-concepts.md#prompt-caching). Pin a model ID in production: before one is removed, `GET /v1/models` sets its [`deprecation_date`](https://hub.hcompany.ai/models-api/list-models).

Benchmarks and methodology: [Holo4](https://hcompany.ai/newsroom/holo4), [Holo3.1](https://hcompany.ai/holo3.1). Holo4 and Holo3.1 also ship as open weights for [local inference](https://hub.hcompany.ai/agents-api/local-inference.md), including sizes the API does not serve.

## Quickstart

### 1. Get an API key

Generate a key on [H Platform](https://platform.hcompany.ai/?product=modelsapi\&source=docs) and export it.

```bash theme={"system"}
export HAI_API_KEY="your-api-key-here"
```

### 2. Install the OpenAI client

Only `base_url` changes from the OpenAI defaults. Skip this step for cURL.

```bash Python theme={"system"}
pip install openai
```

```bash TypeScript theme={"system"}
npm install openai
```

### 3. Send a screenshot

```bash cURL theme={"system"}
curl https://api.hcompany.ai/v1/chat/completions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "holo3-1-35b-a3b",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://your-host/screenshot.png"}},
        {"type": "text", "text": "What is on this screen, and what would you click to sign in?"}
      ]
    }]
  }'
```

```python Python theme={"system"}
import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="holo3-1-35b-a3b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://your-host/screenshot.png"}},
            {"type": "text", "text": "What is on this screen, and what would you click to sign in?"},
        ],
    }],
)

print(response.choices[0].message.content)
```

```typescript TypeScript theme={"system"}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hcompany.ai/v1/",
  apiKey: process.env.HAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "holo3-1-35b-a3b",
  messages: [{
    role: "user",
    content: [
      { type: "image_url", image_url: { url: "https://your-host/screenshot.png" } },
      { type: "text", text: "What is on this screen, and what would you click to sign in?" },
    ],
  }],
});

console.log(response.choices[0].message.content);
```

Paid plans: swap in `holo4-27b`.

Images can be a URL or a base64 data URI. List the models your key can reach with [`GET /v1/models`](https://hub.hcompany.ai/models-api/list-models).

## Request options

Beyond `model` and `messages`, these are the fields that change Holo's behavior. The rest are standard OpenAI sampling fields. The full list is in [Chat completions](https://hub.hcompany.ai/models-api/chat-completions.md).

| Field | Effect | Models |
| :- | :- | :- |
| [`reasoning_effort`](https://hub.hcompany.ai/models-api/chat-completions#param-reasoning-effort) | How long the model thinks first: `low`, `medium`, or `xhigh` (default). `"none"` turns thinking off | Levels on `holo4-27b`. `"none"` on all |
| [`tools`](https://hub.hcompany.ai/models-api/chat-completions#param-tools), `tool_choice` | [Function calling](https://hub.hcompany.ai/models-api/build-an-agent/function-calling.md). Use `tool_choice: "required"` in agent loops | All except `holo3-122b-a10b` |
| [`structured_outputs`](https://hub.hcompany.ai/models-api/chat-completions#param-structured-outputs) or [`response_format`](https://hub.hcompany.ai/models-api/chat-completions#param-response-format) | Constrain the answer to a JSON Schema | All |
| [`chat_template_kwargs`](https://hub.hcompany.ai/models-api/chat-completions#param-chat-template-kwargs) | `{"enable_thinking": false}` turns thinking off, like `reasoning_effort: "none"` | All |
| `temperature`, `top_p`, `top_k`, `max_tokens`, `stop`, `seed`, `frequency_penalty`, `presence_penalty` | Sampling. `0.0` for single calls, `0.8` in agent loops | All |
| `stream` | Stream the response as server-sent chunks | All |

## Rate limits and credits

Free: 10 requests per minute on `holo3-1-35b-a3b`, no credit card. Paid: all models, higher limits, once you [add credits](https://platform.hcompany.ai/settings/billing?product=modelsapi\&source=docs).

Credits can take up to 15 minutes to appear. The **Inference credits** tab of the [credit dashboard](https://platform.hcompany.ai/settings/billing) shows your balance and usage. The balance is checked before a request runs, so a large request on a low balance can overshoot by a few cents. Contact [support@hcompany.ai](mailto:support@hcompany.ai) if the overshoot keeps growing. Unused credits may expire one year after purchase and are not refundable by default, subject to regional obligations and the [terms of use](https://hcompany.ai/terms-of-use).

## Data retention

The API logs request time, model, and token counts. It does not store prompts or responses: zero data retention by default. H runs its own models, so it never shares inputs or outputs with third parties. H is SOC 2 Type II and ISO 27001 certified. Details are in the [privacy policy](https://hcompany.ai/privacy-policy).

## Next


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.