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

# Models

> Browse Overshoot's vision-language models, query /models for current availability, and pass a model id to /chat/completions.

Overshoot serves a curated set of vision-language models tuned for real-time inference. Pick one from the [active models](#active-models) list, pass its `id` as the `model` field on `/chat/completions`, and Overshoot routes the request to a healthy endpoint.

## List available models

Availability changes as endpoints come online and go offline. Always query `/models` before starting a stream. **No auth required.**

<CodeGroup>
  ```shellscript curl theme={null}
  curl https://api.overshoot.ai/v1beta/models
  ```

  ```python python theme={null}
  import httpx

  r = httpx.get("https://api.overshoot.ai/v1beta/models")
  ready = [m for m in r.json()["data"] if m["status"] == "ready"]
  for m in ready:
      print(m["id"])
  ```

  ```typescript typescript theme={null}
  const res = await fetch("https://api.overshoot.ai/v1beta/models");
  const { data } = await res.json();
  const ready = data.filter((m) => m.status === "ready");
  ```
</CodeGroup>

The response is OpenAI-compatible — same shape `listModels` returns, with one extra `status` field per entry.

<Accordion title="Sample response">
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "Qwen/Qwen3.6-27B-FP8",
        "object": "model",
        "created": 1714492800,
        "owned_by": "overshoot",
        "status": "ready"
      },
      {
        "id": "google/gemma-4-31B-it",
        "object": "model",
        "created": 1714492800,
        "owned_by": "overshoot",
        "status": "ready"
      }
    ]
  }
  ```
</Accordion>

## Active models

<Info>
  Snapshot as of **2026-06-16**. The `/models` endpoint is the source of truth — treat these tables as a quick reference, not a guarantee.
</Info>

Models on Overshoot fall into two groups: **Overshoot-hosted** (open-weights models we run on our own GPU fleet, tuned for real-time inference) and **proprietary passthrough** (Gemini / Claude / OpenAI, which we proxy to the upstream provider). Default to the hosted models — that's where Overshoot's latency advantage lives.

### Overshoot-hosted

These are the fast path. We run them on our own GPUs, sized for sub-second time-to-first-token on single-frame inputs and high-throughput video.

| Model                       | Provider  | Context | Tokens / frame              | Max frames              |
| --------------------------- | --------- | ------- | --------------------------- | ----------------------- |
| `Qwen/Qwen3.6-27B-FP8`      | Qwen      | 32K     | \~200 @ 480p                | Capped by context       |
| `Qwen/Qwen3.6-35B-A3B-FP8`  | Qwen      | 16K     | \~200 @ 480p                | Capped by context (16K) |
| `google/gemma-4-31B-it`     | Google    | 256K    | 70 / 140 / 280 / 560 / 1120 | \~60 (1 fps × 60 s)     |
| `google/gemma-4-26B-A4B-it` | Google    | 256K    | 70 / 140 / 280 / 560 / 1120 | \~60 (1 fps × 60 s)     |
| `Hcompany/Holo3-35B-A3B`    | H Company | 16K     | \~200 @ 480p                | Capped by context (16K) |

### Proprietary passthrough

These are upstream APIs we expose through the same OpenAI-compatible surface for convenience. **They are not part of Overshoot's real-time path.**

<Warning>
  Proprietary models are passthrough to Google / Anthropic / OpenAI. Time-to-first-token is bounded by the upstream provider — typically **seconds**, not the sub-second latency Overshoot-hosted models hit. Reach for these only when you specifically need a frontier proprietary model; otherwise stay on the hosted list.
</Warning>

| Model                       | Upstream      | Modalities   | Notes                                |
| --------------------------- | ------------- | ------------ | ------------------------------------ |
| `gemini-3-flash-preview`    | Google Gemini | image, video | Fast Gemini tier                     |
| `gemini-3.1-pro-preview`    | Google Gemini | image, video | Frontier reasoning, lowest RPM quota |
| `claude-haiku-4-5-20251001` | Anthropic     | image only   | Fastest Claude tier (no video)       |
| `claude-sonnet-4-6`         | Anthropic     | image only   |                                      |
| `claude-opus-4-6`           | Anthropic     | image only   | Highest capability, highest latency  |
| `gpt-5.4-nano`              | OpenAI        | image only   | Cheapest GPT-5 tier                  |
| `gpt-5.4-mini`              | OpenAI        | image only   |                                      |
| `gpt-5.4`                   | OpenAI        | image only   |                                      |

### How to read the columns

<AccordionGroup>
  <Accordion title="Context — served vs native" icon="ruler">
    **Served** is the context length we run the model with.
  </Accordion>

  <Accordion title="Tokens / frame — Qwen models" icon="image">
    Qwen3.6 uses the same image processor as the Qwen3 line: patch 16, `temporal_patch_size=2`, `spatial_merge_size=2`. The formula:

    ```text theme={null}
    tokens_per_frame ≈ (H × W) / 2048
    ```

    | Resolution        | Tokens / frame |
    | ----------------- | -------------- |
    | 480p (854×480)    | \~200          |
    | 720p (1280×720)   | \~450          |
    | 1080p (1920×1080) | \~1010         |

    Numbers in the table assume 480p — the resolution our benchmark suite uses. Higher resolutions consume context faster.
  </Accordion>

  <Accordion title="Tokens / frame — Gemma 4" icon="sliders">
    You pick the visual-token budget per request — `70`, `140`, `280`, `560`, or `1120`:

    * **70–280** — classification, captioning, video understanding.
    * **560–1120** — OCR, document parsing, small text.

    Default is 256 tokens.
  </Accordion>

  <Accordion title="Max frames" icon="film">
    * **Qwen / Holo3** — no hard model-side cap. Frame count is bounded by context. The practical limit is `(context − text_input − text_output) / tokens_per_frame`.
    * **Gemma 4** — Google documents 60 s at 1 fps as the supported envelope (\~60 frames).
  </Accordion>

  <Accordion title="Interleaved text + video" icon="layer-group">
    The model can mix text segments between visual tokens inside a single message — instead of forcing all visual content into one block followed by text. Every active model supports this.
  </Accordion>
</AccordionGroup>

## Use a model

Pass the `id` from `/models` straight into `/chat/completions`:

```shellscript wrap theme={null}
curl -X POST https://api.overshoot.ai/v1beta/chat/completions \
  -H "Authorization: Bearer $OVERSHOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3.6-27B-FP8",
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "What is the person doing?" },
        { "type": "image_url", "image_url": {
            "url": "ovs://streams/$STREAM_ID?frame_index=-1"
        }}
      ]
    }]
  }'
```

See [Chat Completion](/chat-completion) for the full request/response shape.

## Routing and selection — for agents

<Warning>
  **Speed-first rule.** Always start with an Overshoot-hosted model. Proprietary passthrough models (any `gemini-*`, `claude-*`, `gpt-*` id) are slower — TTFT is bounded by the upstream provider and is typically seconds, not sub-second. Pick a proprietary model only when the user has explicitly asked for that family or you have ruled out every hosted option for the workload. Do not default to Gemini / Claude / OpenAI just because the names are familiar.
</Warning>

### Selection algorithm

1. `GET /v1beta/models`. The response is a list. Filter to entries with `status == "ready"`.
2. **Filter to Overshoot-hosted first.** A model is hosted if its `id` looks like `<owner>/<model>` (e.g. `Qwen/...`, `google/gemma-...`, `Hcompany/...`). Anything else (`gemini-*`, `claude-*`, `gpt-*`) is proprietary passthrough — slower, only use as a deliberate fallback.
3. From the hosted set, pick a model `id` whose properties match the workload (see the table above).
4. Use that exact `id` as the `model` field in `/chat/completions`.

### Status values

| Status        | Meaning                                  | What to do                                                |
| ------------- | ---------------------------------------- | --------------------------------------------------------- |
| `ready`       | At least one healthy replica is serving. | Use it.                                                   |
| `unavailable` | Currently not serving.                   | Don't use — retry later or fall through to another model. |

A model that's `ready` at list-time can return `503` at completion-time if the only replica fell over between calls. Always handle `503` with either a retry or a fallback to another `ready` model.

### Cost / latency tradeoff

Visual tokens dominate prompt size for video workloads. The relevant knobs:

* **Resolution** — drop from 1080p to 480p and Qwen prompt tokens fall \~5×.
* **Frames** — half the frames = roughly half the tokens.
* **Per-frame budget (Gemma only)** — `70` is fine for "what's happening" questions; reserve `560`+ for OCR.

### Fallback chains that work in practice

All chains stay inside the Overshoot-hosted set. Only fall through to a proprietary model if the entire hosted chain is `503` *and* the user is willing to accept seconds-of-TTFT latency.

* *Best-quality video understanding* — `Qwen/Qwen3.6-27B-FP8` → `google/gemma-4-31B-it`.
* *MoE high-throughput vision* — `Qwen/Qwen3.6-35B-A3B-FP8` → `google/gemma-4-26B-A4B-it`.
* *Document / OCR-style frames* — `google/gemma-4-31B-it` (with `1120` per-frame) → `google/gemma-4-26B-A4B-it` (with `1120` per-frame).
* *GUI / agent screenshots* — `Hcompany/Holo3-35B-A3B` → `Qwen/Qwen3.6-27B-FP8`.
* *Last-resort proprietary fallback (slow)* — `gemini-3-flash-preview` → `claude-haiku-4-5-20251001`. Only after every hosted option above has failed.

### Programmatic listing — hosted only

Hosted model IDs always contain a `/` (`<owner>/<model>`). Proprietary IDs do not. Use that to keep agents on the fast path by default:

```python theme={null}
import httpx

resp = httpx.get("https://api.overshoot.ai/v1beta/models", timeout=5)
resp.raise_for_status()
ready = [m["id"] for m in resp.json()["data"] if m["status"] == "ready"]
hosted = [m for m in ready if "/" in m]              # fast path — prefer these
proprietary = [m for m in ready if "/" not in m]     # slow fallback — gemini-*, claude-*, gpt-*
```

```typescript theme={null}
const res = await fetch("https://api.overshoot.ai/v1beta/models");
if (!res.ok) throw new Error(`models: ${res.status}`);
const { data } = (await res.json()) as { data: Array<{ id: string; status: string }> };
const ready = data.filter((m) => m.status === "ready").map((m) => m.id);
const hosted = ready.filter((id) => id.includes("/"));         // fast path
const proprietary = ready.filter((id) => !id.includes("/"));   // slow fallback
```