AI API

Autentizace

Každý chráněný request posílá klíč v HTTP hlavičce. Klíč nikdy nedávej do URL, logu ani veřejného JavaScriptu.

Authorization: Bearer lux-TVUJ_KLIC

Jednoduchý request

curl https://api.lux-ai.cz/v1/generate \
  -H 'Authorization: Bearer lux-TVUJ_KLIC' \
  -H 'Content-Type: application/json' \
  -d '{"m":"flash","p":"Ahoj"}'

{"v":1,"r":"Dobrý den, jak Vám mohu pomoci?"}

Reasoning a streaming

r nastavuje množství reasoning, i určuje, zda se reasoning pošle zařízení, a x zapíná stream. Model může přemýšlet i s i:false; tím se šetří přenesená data, nikoli výstupní tokeny.

curl -N https://api.lux-ai.cz/v1/generate \
  -H 'Authorization: Bearer lux-TVUJ_KLIC' \
  -H 'Content-Type: application/json' \
  -d '{"m":"pro","p":"Vyřeš úlohu","r":"high","i":true,"x":true}'

data:{"q":"Průběžné reasoning…"}

data:{"r":"Průběžná odpověď…"}

data:{"d":1}

Nativní function calling

Pro agenty používej OpenAI kompatibilní endpoint POST /v1/chat/completions. Definice nástrojů se předává v poli tools; model vrací strukturované message.tool_calls. Po vykonání funkce přidej celou assistant zprávu a výsledek s rolí tool a stejným tool_call_id.

curl https://api.lux-ai.cz/v1/chat/completions \
  -H 'Authorization: Bearer lux-TVUJ_KLIC' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"flash",
    "messages":[{"role":"user","content":"Jaké je počasí v Praze?"}],
    "tools":[{"type":"function","function":{
      "name":"get_weather",
      "description":"Vrátí aktuální počasí",
      "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}
    }}],
    "tool_choice":"auto"
  }'

{
  "choices":[{"finish_reason":"tool_calls","message":{
    "role":"assistant","content":null,
    "tool_calls":[{"id":"call_…","type":"function","function":{
      "name":"get_weather","arguments":"{\"city\":\"Praha\"}"
    }}]
  }}]
}

Při stream:true používají požadavky s nástroji ve výchozím stavu transakční stream. Gateway nejprve získá, případně zopakuje a ověří celé volání a až potom pošle standardní SSE chunk s kompletními argumenty a data: [DONE]. Klient má argumenty přesto skládat podle index, aby zůstal kompatibilní s OpenAI protokolem. Nástroj spusť až po finish_reason: "tool_calls".

Kompaktní endpoint přijímá stejné tools, tool_choice a parallel_tool_calls. Místo p/c může dostat standardní messages, což umožní pokračovat po výsledku nástroje. V JSON odpovědi vrací tool_calls; v kompaktním streamu je posílá jako strukturované delty. Flash přijme parallel_tool_calls kvůli kompatibilitě klientů, ale gateway tento jediný přepínač neposílá OpenRouteru, protože jej momentálně neinzeruje žádný Flash provider. Function calling přesto zůstává nativní a není převáděný do textového protokolu.

Vision přes Flash a Ultra

Pole a obsahuje až 8 obrázků nebo videí pro modely Flash a Ultra. Krátký typ i znamená obrázek a v video. Veřejné soubory posílej přes HTTPS URL — request je výrazně menší než s base64. Pro soukromý lokální soubor lze použít podporovanou base64 data URL.

curl https://api.lux-ai.cz/v1/generate \
  -H 'Authorization: Bearer lux-TVUJ_KLIC' \
  -H 'Content-Type: application/json' \
  -d '{"m":"flash","p":"Co je na obrázku?","a":[["i","https://example.com/photo.webp"]]}'

Pole requestu

Odpovědi a chyby

Kompaktní JSON vrací finální text v r, volitelné reasoning v q a nativní volání funkcí v tool_calls. SSE používá stejné názvy po částech; {"d":1} znamená konec. Chat Completions vrací standardní OpenAI JSON/SSE. Chyby kompaktního endpointu jsou krátké, například {"e":"auth"}, {"e":"rate"} nebo {"e":"upstream"}.

Prázdnou či poškozenou odpověď, neplatné volání nástroje, timeout, 408, 409, 425, 429 a dočasné 5xx gateway zpracuje až v pěti celkových pokusech a respektuje Retry-After. U nástrojů ověřuje i návaznost assistant/tool zpráv a při opakování se snaží vynechat providera, který selhal. Flash přepne nečinného providera po 120 sekundách; Lite po 180 a Pro/Ultra po 300 sekundách. Navazování spojení a opakované pokusy mají společný limit 10 minut. Úspěšná odpověď obsahuje diagnostickou hlavičku X-Lux-Upstream-Attempts.

Transakční stream je odolnější, ale první modelová data odešle až po dokončení a validaci odpovědi. Režim live má nejnižší latenci; pokud se upstream přeruší až po odeslání části odpovědi, stream skončí strukturovanou chybou a klient nesmí částečný výsledek považovat za dokončený.

Limity se uplatňují současně globálně na API klíč a na zdrojovou IP. Odpověď 429 obsahuje Retry-After: 60.

OpenAPI 3.1 specifikace · Health check