# SmartLLM API-Referenz

OpenAI-kompatible Inference-API auf eigener Hardware in Österreich.
Diese Datei wird von `scripts/generate_api_md.py` aus dem live laufenden
OpenAPI-Schema generiert — bitte nicht von Hand editieren.

- **Basis-URL:** `https://smartllm.at/v1`
- **Authentifizierung:** Bearer-API-Key im `Authorization`-Header
  (`Authorization: Bearer sk-smartllm-…`). Keys werden im Portal unter
  [smartllm.at/portal/keys](https://smartllm.at/portal/keys) verwaltet.
- **Konzept Production-Aliase:** Statt einer konkreten Modell-ID kann
  das Feld `model` einen Rollen-Namen wie `frontier`, `coder`, `vision`
  oder `fast` enthalten. Der Gateway löst den Alias auf das aktuell
  dahinterliegende Modell auf. Liste aller Aliase: `GET /v1/aliases`.
  Liste aller Modelle (inklusive Aliase als `owned_by: smartllm-alias`):
  `GET /v1/models`. `/v1/aliases` ist eine SmartLLM-Erweiterung und
  nicht Teil der OpenAI-Spec.

---

## Endpunkte

| Methode | Pfad | Zweck |
| --- | --- | --- |
| `GET` | `/v1/aliases` | List Aliases |
| `POST` | `/v1/chat/completions` | Chat Completions |
| `POST` | `/v1/completions` | Completions |
| `POST` | `/v1/embeddings` | Embeddings |
| `GET` | `/v1/models` | List Models |
| `GET` | `/v1/models/{model_id}` | Get Model |

---

## Referenz

### `GET /v1/aliases`

**List Aliases**

List curated aliases the caller may see.

Lane gating and per-key model whitelist are enforced by the shared
filter — see ``visible_aliases_for_lane`` for the rules.

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/aliases \
  -H "Authorization: Bearer IHR-API-KEY"
```

---

### `POST /v1/chat/completions`

**Chat Completions**

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/chat/completions \
  -H "Authorization: Bearer IHR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "frontier", "messages": [{"role": "user", "content": "Hallo!"}]}'
```

**Beispiel — OpenAI-Client (Python)**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://smartllm.at/v1",
    api_key="IHR-API-KEY",
)

resp = client.chat.completions.create(
    model="frontier",
    messages=[{"role": "user", "content": "Hallo!"}],
)
print(resp.choices[0].message.content)
```

---

### `POST /v1/completions`

**Completions**

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/completions \
  -H "Authorization: Bearer IHR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "frontier", "prompt": "Hallo!"}'
```

**Beispiel — OpenAI-Client (Python)**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://smartllm.at/v1",
    api_key="IHR-API-KEY",
)

resp = client.completions.create(
    model="frontier",
    prompt="Hallo!",
)
print(resp.choices[0].text)
```

---

### `POST /v1/embeddings`

**Embeddings**

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/embeddings \
  -H "Authorization: Bearer IHR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic-embed-text:latest", "input": "Hallo Welt"}'
```

**Beispiel — OpenAI-Client (Python)**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://smartllm.at/v1",
    api_key="IHR-API-KEY",
)

resp = client.embeddings.create(
    model="nomic-embed-text:latest",
    input="Hallo Welt",
)
print(len(resp.data[0].embedding))
```

---

### `GET /v1/models`

**List Models**

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/models \
  -H "Authorization: Bearer IHR-API-KEY"
```

**Beispiel — OpenAI-Client (Python)**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://smartllm.at/v1",
    api_key="IHR-API-KEY",
)

for m in client.models.list().data:
    print(m.id)
```

---

### `GET /v1/models/{model_id}`

**Get Model**

Per-model lookup. Works for both real model IDs and aliases.

OpenAI-shaped object. Real IDs return the same shape as in /v1/models;
aliases return the alias projection (with ``resolves_to`` gated by the
same visibility rule applied to /v1/models).

Unknown id, or an alias that the caller's lane may not see, → 404.
The 404 envelope is identical for unknown-real and hidden-alias to
avoid leaking the existence of internal-only aliases.

**Pfad-Parameter**

- `model_id` (string) **(required)**

**Response 200**

**Beispiel — curl**

```bash
curl https://smartllm.at/v1/models/{model_id} \
  -H "Authorization: Bearer IHR-API-KEY"
```

---