# Protokoly a SDK

Používejte protokoly OpenAI-compatible, Responses a Anthropic Messages včetně streamování, volání nástrojů a migrace.

Model API mluví třemi síťovými protokoly. Zachovejte své stávající SDK a změňte základní URL, API klíč a ID modelu.

## Matice koncových bodů

| Protokol | Konečný bod | Typický klient |
|----------|----------|----------------|
| OpenAI Chat Completions | `POST https://openapi.felo.ai/api/v1/chat/completions` | OpenAI SDK, většina nástrojů kompatibilních s OpenAI |
| OpenAI Responses | `POST https://openapi.felo.ai/api/v1/responses` | OpenAI SDK s funkcemi Responses API |
| Anthropic Messages | `POST https://openapi.felo.ai/api/v1/messages` | Anthropic SDK, Claude Code, nativní nástroje Claude |

## Základní URL

| Klient | Základní URL | Proč |
|--------|----------|-----|
| OpenAI SDK | `https://openapi.felo.ai/api/v1` | SDK přidá `/chat/completions` nebo `/responses` |
| Anthropic SDK | `https://openapi.felo.ai/api` | SDK přidá `/v1/messages`; nepřidávejte `/v1` sami |

Oba klienti používají váš Felo API klíč jako API klíč SDK.

```javascript
import OpenAI from "openai";
import Anthropic from "@anthropic-ai/sdk";

const openai = new OpenAI({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api/v1",
});

const anthropic = new Anthropic({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api",
});
```

## Zvolte protokol

- Použijte **Chat Completions**, když váš nástroj nebo SDK očekává známé pole `messages` a `choices[0].message.content`.
- Použijte **Responses**, když potřebujete objekt Responses od OpenAI, `input`, `instructions` nebo `output_text`.
- Použijte **Messages**, když používáte Anthropic SDK nebo nativní nástroj Claude.

Zkontrolujte model, než budete předpokládat, že každý protokol funguje. Katalog vystavuje `supported_protocols`, `supported_parameters` a `recommended_protocol`. `recommended_protocol` je doporučení klienta, nikoli omezení; model může stále přijímat jiný protokol.

## Streamování

Nastavte `stream: true` pro příjem Server-Sent Events.

- Chat Completions vysílá chat chunk stylu OpenAI.
- Responses vysílá události Responses SSE a končí dokončeným objektem odpovědi.
- Messages vysílá stream události zpráv Anthropic.

Čtěte datový tok událostí průběžně a před uzavřením spojení zpracujte koncovou událost. Ztracené spojení není totéž co dokončená odpověď.

## Volání nástrojů a strukturovaný výstup

Předávejte `tools` v nativní podobě daného protokolu. Podpora se liší podle modelu, proto před spoléháním na volání nástrojů, režim JSON nebo strukturovaný výstup zkontrolujte v katalogu `supported_parameters`. Model může pole přijmout a přitom ignorovat nepodporovanou možnost.

## Nahrání souborů modelu

Nahrajte soubor jednou pomocí `POST https://openapi.felo.ai/api/v1/files` a pak na vrácené ID `felo_file_` odkazujte v požadavcích Messages nebo Responses. Chat Completions ID souborů nepřijímá.

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Tělo požadavku je `multipart/form-data` s právě jednou částí `file`. Multipart boundary nechte vygenerovat klienta a nepřidávejte další části, například `purpose`. Bloky obsahu, limity, podporu modelů a chybové kódy najdete v části [Nahrávání souborů](https://openapi.felo.ai/cs/docs/guides/file-uploads.md).

Chcete-li uložit materiál jako znalostní zdroj LiveDoc, použijte [API pro nahrávání LiveDoc](https://openapi.felo.ai/cs/docs/api-reference/livedocs.md). Nahrávání souborů modelu a nahrávání prostředků LiveDoc mají vlastní identifikátory a navazující workflow.

## Směrování kanálů

Všechny tři koncové body přijímají `X-Felo-Channel`, pokud potřebujete připnout poskytovatele. Viz [Proč má stejný model různé ceny?](https://openapi.felo.ai/cs/docs/guides/provider-routing.md) pro pravidla hlaviček a příklady.

## Migrace z oficiálního API

1. Změňte základní URL na odpovídající Felo URL.
2. Nahraďte API klíč za `FELO_API_KEY`.
3. Nahraďte název modelu veřejným ID modelu Felo.
4. Zachovejte zbytek tvaru požadavku.

| Příznak | Pravděpodobná příčina |
|---------|--------------|
| 404 u každého požadavku | Základní URL už obsahuje `/v1`, nebo byla základní URL Anthropic ručně doplněna o `/v1` |
| 401 | Felo klíč chybí nebo klient stále posílá starý klíč |
| 400 chyba `model` | ID modelu není veřejné nebo nepodporuje zvolený koncový bod |
| Požadavek Messages odmítnut | Protokol Messages vyžaduje `max_tokens` |
| Volání nástroje ignorováno | Model neoznamuje tuto schopnost |

## Přepis řeči / Syntéza řeči

Vyberte publikovaný model `model_kind=audio_transcription` (STT) nebo `audio_speech` (TTS), jeho veřejné ID a kanál. `speech_spec` popisuje výchozí kanál TTS; hlasy a formáty se liší podle kanálu.

```bash
curl --fail 'https://openapi.felo.ai/api/platform/model-catalog?locale=en&fmt=full' \
  | jq '.data.models[] | select(.model_kind == "audio_transcription" or .model_kind == "audio_speech") | {id, model_kind, speech_spec, channels}'
```

### STT

`POST /api/v1/audio/transcriptions`

Pošlete `model` a `file` jako `multipart/form-data`: úplný mono PCM WAV, nejvýše 25,000,000 bajtů, při dodržení limitů vzorkovací frekvence a délky kanálu. Volitelné: `language` (dvě malá písmena, např. `en`) a `response_format=json` (jediný i výchozí formát). boundary vytvoří curl. URL, ID souboru, `prompt`, časové značky a `stream` nejsou podporovány.

```bash
curl --fail-with-body 'https://openapi.felo.ai/api/v1/audio/transcriptions' \
  -H "Authorization: Bearer $FELO_API_KEY" \
  --form-string 'model=YOUR_STT_MODEL_ID' \
  --form-string 'response_format=json' \
  -F 'file=@./sample.wav;type=audio/wav'
```

Synchronní JSON obsahuje `text` a volitelně `usage` v sekundách nebo tokenech. `usage.cost` je cena dodavatele, nikoli konečná platba Felo. Není třeba dotazovat stav úlohy.

### TTS

`POST /api/v1/audio/speech`

Pošlete JSON s poli `model` a `input` s neprázdným textem (až 4096 kódových bodů Unicode). `response_format` je standardně `pcm`; kanály pouze MP3 vyžadují výslovné `mp3`. Podporováno je jen `speed=1`; vynechte `instructions` a `stream`.

Pole `voice` můžete vynechat nebo zadat ID hlasu. Model poskytovatele určuje, zda je hlas povinný a která ID přijímá. Hlasy v katalogu jsou příklady.

```bash
curl --fail 'https://openapi.felo.ai/api/v1/audio/speech' \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H 'Content-Type: application/json' \
  --output speech.mp3 \
  --data '{"model":"YOUR_TTS_MODEL_ID","input":"Hello!","voice":"SUPPORTED_VOICE","response_format":"mp3"}'
```

Úspěch vrací zvukové bajty: MP3 jako `audio/mpeg` nebo surové PCM jako `audio/pcm`, ne WAV, JSON či SSE. Před přehráním ověřte HTTP stav a dokončení přenosu. `--fail` zabrání zápisu HTTP chyby do audiosouboru. Neúplný soubor po přerušení zahoďte. Parametry PCM ověřte u kanálu, neodhadujte je.

STT používá `input_audio_second` nebo tokeny, TTS `input_character`. V `speech_billing_unit` počítají `utf16_code_unit` a `unicode_code_point` emoji odlišně. Rezervace není limit útraty; vyúčtování může být asynchronní. Chybějící důkazy neznamenají nulovou cenu. Obě API přijímají `X-Felo-Channel` a odesílají jednou do zvoleného kanálu. Vypněte automatická opakování včetně SDK po timeoutu nebo odpojení; uchovejte `X-Request-Id` a dostupné `X-Generation-Id`. Console Playground zatím zvuk nepodporuje. `configured_rates` používá zmrazené sazby a ověřenou spotřebu; `upstream_cost` ověřené náklady dodavatele s publikovanou přirážkou a slevou.

- [Přepis řeči API](https://openapi.felo.ai/cs/docs/model-api/operations/createAudioTranscription)
- [Syntéza řeči API](https://openapi.felo.ai/cs/docs/model-api/operations/createAudioSpeech)

## Související

- [Reference Model API](https://openapi.felo.ai/cs/docs/model-api)
- [Nahrávání souborů](https://openapi.felo.ai/cs/docs/guides/file-uploads.md)
- [Modely a ceny](https://openapi.felo.ai/cs/docs/guides/models-and-pricing.md)
- [Průvodce LLM API](https://openapi.felo.ai/cs/docs/guides/protocols.md)
- [Nastavení AI nástrojů](https://openapi.felo.ai/cs/docs/agent-clients/other-tools.md)
