ColdHost AI API pro vývojáře – první požadavek v curl, Pythonu a Node.js

ColdHost AI nabízí API kompatibilní s formátem OpenAI Chat Completions. To znamená, že můžete použít libovolnou knihovnu, která tento formát podporuje, a jen změnit adresu a klíč. V tomto návodu pošlete první požadavek ze tří prostředí a ukážeme si streamování a ošetření chyb.

Základní údaje

Položka	Hodnota
Base URL	https://coldhost-ai.cz/v1
Endpoint	POST /chat/completions
Autentizace	hlavička Authorization: Bearer <klíč>
Modely	coldhost-frost, coldhost-glacier, coldhost-polaris
Účtování	API kredit v Kč

API klíč vytvoříte v Nastavení → API. Uložte ho do proměnné prostředí, ne do kódu:

export COLDHOST_API_KEY="vas_klic"

curl

curl https://coldhost-ai.cz/v1/chat/completions \
  -H "Authorization: Bearer $COLDHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "coldhost-glacier",
    "messages": [
      {"role": "system", "content": "Odpovídej stručně česky."},
      {"role": "user", "content": "Co dělá příkaz chmod 640?"}
    ]
  }'

Text odpovědi najdete v choices[0].message.content. S nástrojem jq ho vytáhnete rovnou:

curl -s ... | jq -r '.choices[0].message.content'

Python

Nejjednodušší je oficiální klient openai, kterému změníte base_url:

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"],
)

resp = client.chat.completions.create(
    model="coldhost-glacier",
    messages=[
        {"role": "system", "content": "Odpovídej stručně česky."},
        {"role": "user", "content": "Napiš regex pro české PSČ."},
    ],
)

print(resp.choices[0].message.content)
print("Tokeny:", resp.usage.total_tokens if resp.usage else "n/a")

Streamování v Pythonu

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

stream = client.chat.completions.create(
    model="coldhost-glacier",
    messages=[{"role": "user", "content": "Vysvětli, jak funguje HTTPS."}],
    stream=True,
)

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

Node.js

npm install openai

// index.mjs
import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "coldhost-frost",
  messages: [{ role: "user", content: "Tři nápady na název kavárny." }],
});

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

Spuštění: node index.mjs (Node.js 18 a novější).

Bez knihovny, jen fetch

const res = await fetch("https://coldhost-ai.cz/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.COLDHOST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "coldhost-glacier",
    messages: [{ role: "user", content: "Ahoj!" }],
  }),
});

if (!res.ok) {
  throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}
const data = await res.json();
console.log(data.choices[0].message.content);

Konverzace s historií

API je bezstavové – historii musíte posílat sami. Každou odpověď asistenta přidejte do pole messages:

messages = [{"role": "system", "content": "Jsi pomocník pro Linux."}]

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

Pamatujte, že s délkou historie roste spotřeba – starší zprávy je vhodné ořezávat.

Ošetření chyb

from openai import APIStatusError, APIConnectionError

try:
    resp = client.chat.completions.create(model="coldhost-glacier", messages=messages)
except APIStatusError as e:
    print("Chyba API:", e.status_code, e.response.text)
except APIConnectionError:
    print("Nepodařilo se připojit")

Kód	Obvyklý význam
400	chybný formát požadavku
401	neplatný nebo chybějící klíč
404	špatná URL nebo model
429	příliš mnoho požadavků nebo vyčerpaný kredit
5xx	dočasná chyba serveru – zkuste znovu s prodlevou

Volba modelu v aplikaci

• coldhost-frost – klasifikace, krátké odpovědi, vysoký objem volání.
• coldhost-glacier – výchozí volba pro chatboty a generování textu.
• coldhost-polaris – složitá analýza; počítejte s vyšší cenou a delší odezvou.

Bezpečnost

Klíč nikdy nedávejte do frontendového JavaScriptu – kdokoli by ho vyčetl z prohlížeče. Volání API vždy směrujte přes vlastní backend a klíč držte v proměnné prostředí nebo správci tajemství.