Co je API a jak se volá model

Doteď jsi s AI pracoval hlavně přes chatovací aplikace: otevřeš okno, napíšeš otázku, přečteš odpověď. Jenže když firma chce, aby AI třídila e-maily, odpovídala zákazníkům na webu nebo shrnovala smlouvy v interním systému, nikdo tam nesedí a nepíše do chatu. Program musí s modelem mluvit sám. K tomu slouží API. Tahle lekce ukazuje, jak takový rozhovor dvou programů vypadá, co v něm můžeš nastavit a co tě bude stát. Programovat k tomu nemusíš: ukázky kódu jsou schované v rozbalovacích blocích pro ty, koho zajímají.

Co je API

Pojem API už znáš z lekce Kam putují tvoje data: je to rozhraní, přes které spolu mluví programy. Teď se podíváme, jak to rozhraní vypadá zevnitř.

API(application programming interface)

Dohodnutý způsob, jak jeden program požádá jiný program o službu. Určuje, na jakou adresu se požadavek posílá, jaké údaje musí obsahovat, v jakém formátu, a co přesně přijde zpátky. Dohoda je popsaná v dokumentaci, takže obě strany vědí, co od sebe čekat.

Technicky to funguje tak, že program pošle přes internet zprávu na adresu výrobce (třeba api.anthropic.com nebo api.openai.com) a dostane zpátky odpověď. Obě zprávy jsou text ve formátu JSON, který znáš z lekce Strukturovaný výstup. Je to stejný princip, jakým tvoje banka komunikuje s platebním terminálem nebo e-shop s dopravcem.

Chat aplikace a volání modelu z vlastního systému

V lekci ChatGPT, Claude, Gemini a Copilot jsme si řekli, že model je motor a chatovací aplikace je auto kolem něj. API je ten samotný motor. Je dobré si uvědomit, co všechno auto dělalo za tebe a co teď musí udělat tvůj systém:

Z toho plyne praktický závěr: přes API dostaneš víc kontroly a víc odpovědnosti zároveň. Model je stejný, ale všechno kolem něj, od paměti po bezpečnost, je teď věc tvého systému. Jestli se vyplatí stavět vlastní řešení, nebo koupit hotové, rozebírá lekce Koupit, nebo postavit.

Anatomie požadavku

Každé volání modelu má stejnou kostru. Liší se jen názvy polí u jednotlivých výrobců.

Požadavek a odpověď(request, response)

Požadavek je zpráva, kterou tvůj program pošle API: co chce, s jakými údaji a nastavením. Odpověď je zpráva, kterou API vrátí: výsledek, nebo chybu s vysvětlením.

Model

Prvním údajem je název konkrétního modelu, například claude-opus-5-5. Výrobci mají vždy několik modelů různé velikosti a ceny a starší postupně vyřazují. Proto se do systému vyplatí psát název modelu na jedno místo v nastavení, ne roztroušeně po kódu. Až bude potřeba model vyměnit, uděláš to na jednom řádku.

Systémový prompt

Pokyny, které platí pro celou konverzaci: kdo model je, pro koho pracuje, co smí a nesmí, jak má odpovídat. Co systémový prompt je, víš z lekce Jak se model trénuje. V chatovací aplikaci ho píše výrobce, přes API ho píšeš ty, a je to typicky ta nejdůležitější a nejvíc laděná část celé aplikace. U Anthropicu je to samostatné pole system, u OpenAI pole instructions.

Zprávy a role

Samotná konverzace je seznam zpráv. Každá zpráva má roli, tedy údaj, kdo ji „řekl“:

• user (uživatel): co napsal člověk, nebo co za něj poslal tvůj systém,
• assistant (asistent): co předtím odpověděl model.

Seznam vždy začíná zprávou uživatele a role se střídají. Model na konec seznamu dopíše další zprávu asistenta. Všechno, co píšeš, se tak skládá do textu, jehož pokračování model předpovídá token po tokenu.

Parametry

Pak přichází nastavení, jak má model generovat:

• Maximální počet tokenů (max_tokens). Pojistka, kolik nejvýš smí model napsat. Jak víš z lekce o strukturovaném výstupu, model o limitu „neví“ a nepíše kvůli němu stručněji. Když limit dojde, odpověď se prostě utne. U Anthropicu je tenhle parametr povinný.
• Teplota (temperature). Jak moc náhodně model vybírá další token, vyzkoušel sis v lekci Předpověď dalšího slova a teplota. Pozor, tady se situace rychle mění. U řady novějších modelů, hlavně těch, které před odpovědí „přemýšlejí“, teplotu nastavit nejde. Anthropic ji v nejnovější verzi svého API (v době psaní verze z října 2026) odstranil úplně, spolu s příbuznými parametry top_p a top_k. Místo toho se u nových modelů nastavuje spíš to, kolik úsilí má model do odpovědi vložit (u Anthropicu parametr effort), což mění důkladnost i spotřebu tokenů.

Dalších parametrů je mnohem víc (zastavovací sekvence, nástroje, formát výstupu…). Nástrojům a formátu se věnuje příští lekce.

Co přijde zpátky

Odpověď API obsahuje víc než jen text. Tři údaje jsou důležité i pro neprogramátora, protože na nich stojí kontrola kvality a nákladů:

1. Obsah. Text odpovědi, případně další bloky (třeba žádost o použití nástroje).
2. Důvod zastavení (stop reason). Proč model přestal psát. Nejčastěji proto, že odpověď dokončil (u Anthropicu end_turn). Ale může to být i max_tokens, tedy že došel limit a odpověď je useknutá, nebo refusal, že model odpovědět odmítl. Dobře postavený systém tenhle údaj vždy kontroluje. Useknutá odpověď, kterou nikdo nezkontroluje, je typická tichá chyba.
3. Spotřeba tokenů (usage). Kolik tokenů šlo dovnitř a kolik ven. Podle toho se platí, a proto se tenhle údaj vyplatí ukládat ke každému volání. Bez něj nebudeš vědět, kolik která funkce aplikace stojí.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "Jsi asistent podpory e-shopu. Odpovídej stručně a česky. Doručení: ČR 1–2 dny, Slovensko 2–3 pracovní dny.",
    "messages": [
      { "role": "user", "content": "Jak dlouho trvá doručení na Slovensko?" }
    ]
  }'

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Na Slovensko doručujeme do 2–3 pracovních dnů." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 41, "output_tokens": 58 }
}

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // klíč si vezme z proměnné ANTHROPIC_API_KEY

const response = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  system: "Jsi asistent podpory e-shopu. Odpovídej stručně a česky. Doručení: ČR 1–2 dny, Slovensko 2–3 pracovní dny.",
  messages: [{ role: "user", content: "Jak dlouho trvá doručení na Slovensko?" }],
});

if (response.stop_reason === "max_tokens") {
  console.warn("Odpověď je useknutá, nepoužívat bez kontroly.");
}
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}
console.log(response.usage); // kolik tokenů šlo dovnitř a ven

from openai import OpenAI

client = OpenAI()  # klíč z proměnné OPENAI_API_KEY

response = client.responses.create(
    model="NAZEV_MODELU",  # doplň aktuální model z dokumentace
    instructions="Jsi asistent podpory e-shopu. Odpovídej stručně a česky. Doručení: ČR 1–2 dny, Slovensko 2–3 pracovní dny.",
    input="Jak dlouho trvá doručení na Slovensko?",
)
print(response.output_text)

Model si nic nepamatuje: konverzaci posíláš znovu

Z lekce Kontextové okno víš, že model je bezstavový: mezi dvěma dotazy si nic nepamatuje a chatovací aplikace mu při každé zprávě posílá celou dosavadní konverzaci. Přes API tohle dělá tvůj systém. Když zákazník na webu napíše třetí zprávu, tvůj program musí poslat systémový prompt, první otázku, první odpověď, druhou otázku, druhou odpověď a teprve pak tu třetí.

Pro toho, kdo aplikaci zadává nebo platí, z toho plynou tři věci:

• Někdo musí rozhodnout, co se ukládá. Historie konverzací leží ve tvém systému (nebo u dodavatele). To je otázka ochrany osobních údajů: jak dlouho se drží, kdo k ní má přístup.
• Dlouhé konverzace jsou čím dál dražší. Desátá zpráva znamená zaplatit znovu vstupní tokeny všech devíti předchozích výměn. Proto aplikace historii často zkracují nebo shrnují.
• Paměť je věc návrhu, ne modelu. Když má asistent „pamatovat si“ zákazníka mezi návštěvami, musí tvůj systém ty informace uložit a příště je vložit do požadavku.

Někteří výrobci nabízejí pohodlnější varianty, kdy si historii drží jejich server a ty pošleš jen novou zprávu (u OpenAI třeba odkaz na předchozí odpověď). Model se tím ale nezmění, jen práci s historií převezme někdo jiný. OpenAI v dokumentaci výslovně uvádí, že i v tom případě se všechny předchozí vstupní tokeny v řetězci účtují jako vstup.

API klíč: heslo, které platí účty

Aby výrobce věděl, kdo volá a komu poslat fakturu, každý požadavek nese API klíč.

API klíč(API key)

Dlouhý tajný řetězec znaků, který identifikuje tvůj účet u výrobce. Kdo ho zná, může volat model jménem tvé firmy a na její účet. Funguje jako heslo a platební karta v jednom.

Uniklý klíč je jeden z nejčastějších a nejdražších průšvihů začínajících AI projektů. Kdo ho najde, může na tvůj účet generovat text, dokud si toho nevšimneš. Základní pravidla, na kterých se shodují výrobci i bezpečnostní praxe:

• Klíč nikdy nepatří do kódu, který běží u uživatele, tedy do webové stránky v prohlížeči nebo do mobilní aplikace. Tam si ho kdokoli přečte. Model se vždy volá ze serveru, který je pod tvou kontrolou.
• Klíč nepatří do kódu ani do repozitáře (místa, kde se kód ukládá a sdílí). Ukládá se do proměnných prostředí nebo do správce tajných údajů.
• Každá aplikace a každé prostředí má vlastní klíč. Když jeden unikne, zrušíš jen ten a ostatní běží dál. Výrobci k tomu nabízejí oddělené pracovní prostory (workspaces) a klíčům lze nastavit platnost.
• Nastav si limit útraty a sleduj spotřebu. Náhlý skok bývá první známka, že se něco děje.

Kolik to stojí

Z lekce Tokeny víš, že se přes API platí za tokeny, zvlášť za vstupní a zvlášť za výstupní, a výstupní bývají dražší. Ceníky se uvádějí za milion tokenů. Pojďme si to spočítat na příkladu.

Do skutečného rozpočtu patří ještě několik položek: delší konverzace (viz bezstavovost), opakované pokusy po chybě, testování a vývoj, a čeština, která na stejný obsah potřebuje víc tokenů než angličtina. Výrobci zároveň nabízejí cesty, jak cenu snížit. Opakující se začátek požadavku (třeba dlouhý systémový prompt) lze uložit do mezipaměti (prompt caching) a platit za něj při dalších voláních jen zlomek. A úlohy, které nespěchají, lze poslat dávkově (batch) se slevou, u Anthropicu v době psaní 50 %. Jak náklady řídit soustavně, probírá lekce Náklady a volba modelu.

Limity: kolik a jak rychle

Výrobce ti nedovolí poslat neomezené množství požadavků. Existují dva druhy omezení:

• Limity rychlosti (rate limits): kolik požadavků a tokenů smíš poslat za minutu. U Anthropicu se počítají zvlášť požadavky za minutu, vstupní tokeny za minutu a výstupní tokeny za minutu, pro každý model. Když limit překročíš, API vrátí chybu s kódem 429 a často i údaj, za kolik sekund to zkusit znovu.
• Limity útraty: kolik smí organizace utratit za měsíc. Výrobci je mají odstupňované podle úrovní (tiers) a nové účty začínají na nižších limitech, které rostou s historií používání.

Pro plánování to znamená: když chceš v pondělí ráno nechat AI zpracovat archiv deseti tisíc smluv, narazíš na limit dřív, než čekáš. Dobře postavená aplikace s limity počítá: při chybě 429 chvíli počká a zkusí to znovu, rozkládá zátěž v čase a velké nespěchající úlohy posílá dávkově. Na začátku projektu se vyplatí zjistit, na jaké úrovni limitů tvůj účet je a jak se dá zvýšit.

Streamování: odpověď po kouscích

Model píše odpověď token po tokenu. U dlouhé odpovědi to může trvat desítky sekund a uživatel by celou dobu koukal na prázdnou obrazovku. Proto API umí streamování (streaming): místo jedné odpovědi na konci posílá text průběžně, jak vzniká. Právě proto v chatovacích aplikacích vidíš, jak se odpověď „píše“.

Streamování nezrychluje model ani nesnižuje cenu. Zlepšuje jen to, jak rychle uživatel vidí první slova. Pro chatbota je skoro nutnost, pro noční zpracování faktur, kde odpověď nikdo nesleduje, je zbytečné. Jednu past má: když odpověď streamuješ rovnou uživateli, ukazuješ mu text dřív, než ho stihneš zkontrolovat celý. U výstupů, které je potřeba před zobrazením ověřit, se proto streamovat buď nedá, nebo se kontrola musí navrhnout jinak.

Velký, nebo malý model

Výrobci nabízejí rodiny modelů: velké, které zvládnou složité uvažování, ale jsou dražší a pomalejší, a malé, které jsou levné a rychlé, ale u náročných úloh chybují častěji. Výpočet výš ukázal, že rozdíl v ceně může být desítky násobků.

Rozumný postup je opačný, než by člověk čekal. Nezačínej otázkou „který model je nejlepší“, ale „jaký nejmenší model tuhle úlohu spolehlivě zvládne“:

• Jednoduché a opakované úlohy (třídění e-mailů do kategorií, vytažení údajů z formuláře, krátká odpověď z dodaného textu) často zvládne malý model.
• Složité úlohy (rozbor smlouvy, plánování v několika krocích, práce s nástroji, kde chyba něco stojí) obvykle potřebují větší model.
• Kombinace je běžná: levný model třídí a jednoduché případy vyřeší, složité předá většímu.

Rozhodnout se dá jen měřením na vlastních příkladech, ne podle žebříčků. Jak postavit sadu testovacích příkladů a jak volbu modelu vyhodnotit, probírají lekce Měření kvality a Náklady a volba modelu.

Zdroje a další čtení

• Anthropic: API overview – jak vypadá API Claude, hlavičky, klíče a pracovní prostory.
• Anthropic: Rate limits – limity rychlosti a útraty, úrovně a chyba 429.
• Anthropic: Pricing – aktuální ceny za vstupní a výstupní tokeny, mezipaměť a dávkové zpracování.
• OpenAI: Text generation – základní volání přes rozhraní Responses.
• OpenAI: Conversation state – jak se předává historie konverzace a jak se účtuje.