ColdHost AI API: napojení přes OpenAI kompatibilní rozhraní

ColdHost AI nabízí pro vývojáře API kompatibilní s rozhraním OpenAI Chat Completions. Prakticky to znamená, že můžete použít oficiální SDK openai pro Python nebo JavaScript, jen změníte adresu serveru a klíč. Stejné rozhraní využívají i rozšíření pro VS Code jako Continue, Cline nebo Roo Code.

Co budete potřebovat

• API klíč – vygenerujete ho v aplikaci v sekci Nastavení → API.
• API kredit – volání se účtují z API kreditu v Kč.
• Base URL: https://coldhost-ai.cz/v1
• Model – jeden ze tří:

Model ID	Vhodné pro
coldhost-frost	rychlé a levné úlohy: klasifikace, krátké odpovědi, shrnutí
coldhost-glacier	vyvážený model pro běžnou práci
coldhost-polaris	hluboké přemýšlení, složité programátorské a analytické úlohy

Bezpečné uložení klíče

Klíč nikdy nedávejte přímo do kódu ani do frontendu v prohlížeči – kdokoli by ho z JavaScriptu přečetl. Uložte ho do proměnné prostředí na serveru:

export COLDHOST_API_KEY="vas-klic"

V projektu pak do souboru .env (přidaného do .gitignore), nebo do správce tajemství vaší platformy.

První volání přes curl

curl https://coldhost-ai.cz/v1/chat/completions \
  -H "Authorization: Bearer $COLDHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "coldhost-frost",
    "messages": [
      {"role": "system", "content": "Odpovídej stručně česky."},
      {"role": "user", "content": "Co je idempotentní HTTP metoda?"}
    ]
  }'

Odpověď má standardní tvar – text najdete v choices[0].message.content a spotřebu tokenů v poli usage.

Python

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://coldhost-ai.cz/v1",
    api_key=os.environ["COLDHOST_API_KEY"],
)

response = client.chat.completions.create(
    model="coldhost-glacier",
    messages=[
        {"role": "system", "content": "Jsi zkušený backend vývojář. Odpovídej česky."},
        {"role": "user", "content": "Navrhni index pro dotaz WHERE user_id = ? ORDER BY created_at DESC."},
    ],
)

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

Node.js

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://coldhost-ai.cz/v1",
  apiKey: process.env.COLDHOST_API_KEY,
});

const response = await client.chat.completions.create({
  model: "coldhost-frost",
  messages: [{ role: "user", content: "Shrň tento text do jedné věty: ..." }],
});

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

Streamování odpovědi

U delších odpovědí je lepší text zobrazovat průběžně, jak vzniká:

stream = client.chat.completions.create(
    model="coldhost-polaris",
    messages=[{"role": "user", "content": "Vysvětli rozdíl mezi optimistickým a pesimistickým zamykáním."}],
    stream=True,
)

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

Pokud odpověď streamujete dál do prohlížeče, přeposílejte ji ze svého backendu (například jako Server-Sent Events) – klíč tak zůstane na serveru.

Konverzace s historií

API si nepamatuje předchozí zprávy. Kontext konverzace posíláte pokaždé celý v poli messages:

history = [{"role": "system", "content": "Jsi asistent e-shopu."}]

def ask(question: str) -> str:
    history.append({"role": "user", "content": question})
    reply = client.chat.completions.create(model="coldhost-glacier", messages=history)
    answer = reply.choices[0].message.content
    history.append({"role": "assistant", "content": answer})
    return answer

Každá zpráva v historii se počítá do spotřeby tokenů. U dlouhých konverzací proto staré zprávy ořezávejte nebo je nahraďte shrnutím.

Ošetření chyb a opakování

SDK vyhazuje typované výjimky. Na přetížení a dočasné chyby reagujte opakováním, na chybný klíč ne:

from openai import APIConnectionError, APIStatusError, RateLimitError

try:
    response = client.chat.completions.create(model="coldhost-frost", messages=messages)
except RateLimitError:
    ...  # 429 – počkat a zkusit znovu
except APIConnectionError:
    ...  # síťová chyba
except APIStatusError as e:
    print(e.status_code, e.response.text)  # 401 = špatný klíč, 4xx = chybný požadavek

Oficiální SDK má vestavěné automatické opakování (výchozí 2 pokusy) a timeout – obojí nastavíte parametry max_retries a timeout při vytváření klienta.

Volba modelu a náklady

• Pro hromadné zpracování (štítkování, extrakce dat z tisíců záznamů) začněte s coldhost-frost a ověřte kvalitu na vzorku.
• coldhost-polaris nechte na úlohy, kde se rychlejší model prokazatelně plete – návrh architektury, ladění složitých chyb.
• Sledujte pole usage a logujte ho. Uvidíte, které funkce aplikace stojí nejvíc.
• Omezte délku odpovědi parametrem max_tokens, pokud víte, že stačí krátká.

Typické použití v backendu

• Automatické shrnutí tiketů nebo recenzí.
• Klasifikace příchozích e-mailů do kategorií.
• Generování popisků produktů z parametrů.
• Interní asistent nad dokumentací.

Dlouhé úlohy (zpracování tisíců záznamů) nevolejte v HTTP požadavku, ale ve frontě – viz fronty úloh. Na stejné API se napojíte i v editoru: v rozšíření Continue, Cline nebo Roo Code zvolte poskytovatele „OpenAI Compatible“, zadejte base URL https://coldhost-ai.cz/v1, svůj klíč a ID modelu.