Dva pomocné endpointy, které fungují bez konverzace: data loader převede soubor na
prostý text (stejný převod, jaký AYETO používá při nahrávání do znalostní báze),
a převod textu na řeč vytvoří z textu soubor MP3. Oba se platí z
osobních kreditů uživatele, nebo z kreditu uživatele
v organizaci, když požadavek nese organization_id.
Organizace a kredity
Oba endpointy přijímají volitelné organization_id. Požadavek pak běží v této
organizaci stejně jako požadavek chatu: platí ho kredit
uživatele v organizaci (sdílený zůstatek organizace nebo individuální rozpočet
uživatele, viz kredity) místo osobních kreditů. Uživatel klíče
musí být administrátor nebo člen organizace; hosté a uživatelé mimo ni dostanou 403.
Bez organization_id se požadavek účtuje z osobních kreditů. Id organizací uživatele
vrací výpis členství v organizacích.
Převod souboru na text
| Endpoint | POST /api/v3/data-loader/load |
| Rozsah | ayeto.data_loader |
| Limit požadavků | default |
Pošlete soubor jako base64; odpověď obsahuje jeho text. Podle typu souboru se text extrahuje přímo, nebo ho přečte AI model:
| Typ souboru | Typy MIME | Jak se text získá |
|---|---|---|
| Prostý text, CSV, Markdown, HTML, zdrojový kód | jakýkoli text/* a dále application/json, application/ld+json, application/xml, application/xhtml+xml, application/javascript, application/ics |
Dekóduje se tak, jak je. UTF-8 se rozpozná; jiná kódování se odhadnou. |
application/pdf |
Extrahuje se textová vrstva, každá stránka s prefixem PDF page: N. Když má PDF příliš málo textu (naskenovaný dokument), jeho stránky se vykreslí a přečte je model s viděním. |
|
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx), application/msword (.doc) |
Text se extrahuje. |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx), application/vnd.ms-excel (.xls) |
Jedna sekce na list. U .xlsx hodnoty buněk s jejich adresami, vzorce a pojmenované oblasti; u .xls jen hodnoty buněk. Velmi velké sešity se oříznou po 100 000 neprázdných buňkách, s poznámkou na konci. |
| Obrázky | jakýkoli image/* |
Text v obrázku přečte model s viděním. Když obrázek neobsahuje (téměř) žádný text, model místo toho obrázek popíše. |
| Zvuk | audio/mpeg (.mp3), audio/wav, audio/wave, audio/x-wav (.wav) |
Přepíše ho model pro převod řeči na text. Dlouhé nahrávky se rozdělí a přepisují po částech. |
Jiné typy souborů (archivy, video, jiné zvukové formáty, prezentace) se nepřevádějí:
požadavek se odmítne s 422 unsupported file type '<mime type>' s uvedením typu,
jako který byl soubor zpracován, a nic se neúčtuje.
Typ MIME se bere v tomto pořadí: z pole mime_type, z hlavičky data URL v data
a nakonec rozpoznáním z obsahu souboru. Pokud typ znáte, pošlete ho explicitně;
rozpoznání není spolehlivé pro každý formát.
Endpoint nestanovuje vlastní limit velikosti, ale celý soubor putuje zakódovaný v base64 v jednom těle JSON a převádí se, dokud je požadavek otevřený. Velká naskenovaná PDF, obrázky a dlouhé nahrávky zaberou čas; udržujte soubory rozumně malé a počítejte s dlouhou dobou odezvy.
Účtování
Přímá extrakce textu (text, PDF s textovou vrstvou, Word, Excel) nepoužívá žádný AI
model. Vidění (obrázky, naskenovaná PDF) a převod řeči na text (zvuk) se účtují podle
ceny použitých modelů. Server může mít také nastavenou minimální cenu za volání; když
volání stojí méně než minimum, rozdíl se účtuje jako poplatek. Kredity, které volání
spotřebovalo, se vracejí v credits.
Výsledky čtení pomocí vidění se ukládají do cache na 24 hodin: opětovný převod stejného obrázku nebo naskenovaného PDF během této doby model znovu nevolá a stojí jen minimální poplatek, pokud je nastaven.
Kontrola, zda má uživatel (nebo, s organization_id, organizace) kredity, proběhne
před převodem; viz kredity. Volání se účtuje organizaci, když je
nastaveno organization_id, viz organizace.
Požadavek
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data |
řetězec | Ano | Soubor zakódovaný v base64. Přijímá se i data URL (data:application/pdf;base64,JVBERi0x...). |
mime_type |
řetězec | Ne | Typ MIME souboru. Má přednost před typem v data URL i před rozpoznáním. |
organization_id |
UUID | Ne | Provést převod v této organizaci a účtovat ho z kreditu uživatele v ní, viz organizace. Uživatel musí být administrátor nebo člen (ne host). Výchozí: žádná (osobní kredity). |
Odpověď
200 OK s:
| Pole | Typ | Popis |
|---|---|---|
content |
řetězec | Extrahovaný text. |
size |
celé číslo | U textového vstupu velikost vstupu v bajtech; u převáděných souborů délka content ve znacích. |
mime_type |
řetězec | Typ MIME, jako který byl soubor zpracován. U obrázku, jehož text byl přečten, je to text/plain; u obrázku, který byl popsán, zůstává typ obrázku. |
credits |
číslo | Kredity, které volání spotřebovalo, včetně minimálního poplatku. |
Odpověď obsahuje také pole filename, url, name, meta, path, extension,
is_chunk, binary a binary_data. U tohoto endpointu jsou vždy prázdná nebo
false; ignorujte je.
Chyby
| Stav | detail |
Příčina |
|---|---|---|
401 |
API key is invalid |
Klíči chybí rozsah ayeto.data_loader, viz autentizace. |
403 |
User is not a member of the organization |
organization_id není mezi organizacemi uživatele. |
403 |
User does not have write permissions in the organization |
Uživatel je v organizaci host. |
422 |
invalid base64 data |
data nejsou platný base64 ani platná data URL. |
422 |
invalid encoding |
Textový soubor se nepodařilo dekódovat. |
422 |
unsupported file type '<mime type>' |
Soubor je typu, který se nepřevádí (viz tabulka výše), například unsupported file type 'application/zip'. |
422 |
not enough user credit |
Osobní kredity uživatele jsou vyčerpané. |
422 |
not enough organization credit |
S organization_id: kredit uživatele v organizaci je vyčerpaný. |
422 |
chyba validace | Chybí data. |
500 |
error reading document |
Naskenované PDF se nepodařilo vykreslit. |
500 |
Error while processing Word document |
Soubor Word se nepodařilo přečíst. |
500 |
Error while processing Excel file |
Soubor Excel se nepodařilo přečíst. |
500 |
Error while processing audio file, Error while processing WAV audio file |
Zvuk se nepodařilo převést nebo přepsat. |
Chyby autentizace, limitů požadavků a serveru jsou popsány v konvencích.
Příklad
curl -X POST "https://ayeto.ai/api/v3/data-loader/load" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"data\": \"$(base64 -w0 invoice.pdf)\", \"mime_type\": \"application/pdf\"}"
{
"content": "PDF page: 1\nInvoice 2026-0412\nNorthwind Trading s.r.o.\nTotal due: 12 400 CZK\n\n",
"size": 76,
"filename": "",
"url": "",
"name": "",
"meta": "",
"path": "",
"extension": "",
"is_chunk": false,
"mime_type": "application/pdf",
"binary": false,
"binary_data": "",
"credits": 0.0
}
Převod více souborů na text
| Endpoint | POST /api/v3/data-loader/load-batch |
| Rozsah | ayeto.data_loader |
| Limit požadavků | default |
Dávková podoba převodu souboru na text: pošlete několik souborů v jednom požadavku a dostanete text každého z nich. Soubory se převádějí stejně (stejné typy souborů, stejná pravidla pro MIME typ) a několik jich běží současně, takže dávka skončí dřív než tytéž soubory poslané jeden po druhém.
Soubor, který se nepodaří převést, neshodí celý požadavek. Odpověď je 200 OK a položka
toho souboru nese error se stavem a detail, kterými by odpověděl endpoint pro jeden
soubor; ostatní soubory se převedou normálně. Vždy kontrolujte success každé položky.
Dávka smí obsahovat nejvýš 20 souborů, dohromady 50 MB (velikost samotných souborů, ne
jejich base64 textu). Server může mít nastavené jiné limity. Dávka nad limit je odmítnuta
s 422 dřív, než se cokoliv převede. Celá dávka se převádí, dokud je požadavek
otevřený: u naskenovaných PDF, obrázků a nahrávek počítejte s dlouhou dobou odezvy, nebo
posílejte menší dávky.
Účtování dávky
Každý soubor se účtuje tak, jak je popsáno u jednoho souboru, a credits
je součet za dávku. Minimální cena, pokud ji server má, se uplatní jednou na celou
dávku, ne na každý soubor: když dávka stojí méně než minimum, rozdíl se naúčtuje jako
poplatek. Dávka, ve které se nepřevedl žádný soubor, minimum neplatí.
Kontrola kreditů probíhá před převodem. Když kredity dojdou během dávky, zbývající
soubory, které potřebují AI model, selžou s chybou kreditu ve svém error.
Požadavek dávky
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
items |
pole | Ano | Soubory, alespoň jeden. |
items[].data |
řetězec | Ano | Soubor zakódovaný v base64, nebo data URL. |
items[].mime_type |
řetězec | Ne | MIME typ souboru. Má přednost před typem v data URL i před detekcí. |
items[].id |
řetězec | Ne | Váš vlastní identifikátor souboru, nejvýš 256 znaků. Vrací se s výsledkem. |
organization_id |
UUID | Ne | Spustí dávku v této organizaci a naúčtuje ji z kreditu uživatele v ní, viz organizace. Výchozí: žádná (osobní kredity). |
Odpověď dávky
200 OK s:
| Pole | Typ | Popis |
|---|---|---|
items |
pole | Jeden výsledek na soubor, v pořadí požadavku. |
items[].index |
celé číslo | Pozice souboru v požadavku, od 0. |
items[].id |
řetězec nebo null | id poslané se souborem. |
items[].success |
boolean | Zda se soubor převedl. |
items[].content |
řetězec nebo null | Extrahovaný text; null, když soubor selhal. |
items[].size |
celé číslo nebo null | Jako size u endpointu pro jeden soubor. |
items[].mime_type |
řetězec nebo null | MIME typ, jako který byl soubor zpracován. |
items[].error |
objekt nebo null | U souboru, který selhal: status (HTTP stav, který by vrátil endpoint pro jeden soubor) a detail. |
credits |
číslo | Kredity, které spotřebovala celá dávka, včetně minimálního poplatku. |
Chyby dávky
Chyby jednoho souboru (invalid base64 data, invalid encoding,
unsupported file type '<mime type>', chyby kreditu během dávky a chyby 500 uvedené
u jednoho souboru) se hlásí v items[].error, ne jako stav požadavku. Soubor,
který selhal z nečekaného důvodu, má stav 500 a detail
error while processing the file. Samotný požadavek selže s:
| Stav | detail |
Příčina |
|---|---|---|
401 |
API key is invalid |
Klíči chybí rozsah ayeto.data_loader, viz autentizace. |
403 |
User is not a member of the organization |
organization_id není mezi organizacemi uživatele. |
403 |
User does not have write permissions in the organization |
Uživatel je v organizaci host. |
422 |
too many files (<count>, at most <limit>) |
Dávka má víc souborů, než je povoleno. |
422 |
the batch is too large (<size> MB, at most <limit> MB) |
Soubory jsou dohromady větší, než je povoleno. |
422 |
not enough user credit, not enough organization credit |
Kredity jsou vyčerpané, nebo nižší než minimální cena. |
422 |
chyba validace | items chybí nebo je prázdné, nebo položka nemá data. |
Příklad dávky
curl -X POST "https://ayeto.ai/api/v3/data-loader/load-batch" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"items\": [
{\"id\": \"invoice\", \"data\": \"$(base64 -w0 invoice.pdf)\", \"mime_type\": \"application/pdf\"},
{\"id\": \"archive\", \"data\": \"$(base64 -w0 archive.zip)\", \"mime_type\": \"application/zip\"}
]}"
{
"items": [
{
"index": 0,
"id": "invoice",
"success": true,
"content": "PDF page: 1\nInvoice 2026-0412\nNorthwind Trading s.r.o.\nTotal due: 12 400 CZK\n\n",
"size": 76,
"mime_type": "application/pdf",
"error": null
},
{
"index": 1,
"id": "archive",
"success": false,
"content": null,
"size": null,
"mime_type": null,
"error": {"status": 422, "detail": "unsupported file type 'application/zip'"}
}
],
"credits": 0.0
}
Převod textu na řeč
| Endpointy | POST /api/v3/tts/mp3, POST /api/v3/tts/audio, POST /api/v3/tts/voices |
| Rozsah | ayeto.tts |
| Limit požadavků | default |
Převede text na řeč přirozeným hlasem. tts/mp3 vrátí soubor MP3, tts/audio soubor
ve zvoleném formátu, tts/voices vypíše modely, jejich hlasy a styly řeči.
Text se čte tak, jak je zadaný. Rozdělí se na části (celé odstavce, delší odstavec na
koncích vět) a zvuk všech částí se spojí do jednoho souboru. Jeden požadavek převede
nejvýš 60 000 znaků, zhruba hodinu zvuku (administrátoři mohou limit změnit; tts/voices
vrací aktuální hodnotu jako max_chars).
Modely, hlasy a styly
POST /api/v3/tts/voices (prázdné JSON tělo {}) vrátí, co lze použít:
| Pole | Typ | Popis |
|---|---|---|
models |
pole | Modely pro převod textu na řeč: model_id, display_name, description, voices (id hlasů), default_voice, instructions (zda se model řídí pokyny k řeči), formats, is_recommended. |
default_model |
řetězec | Model použitý, když ho požadavek neuvede. |
default_voice |
řetězec | Hlas použitý, když ho požadavek neuvede. |
styles |
pole | Předvolby stylu řeči: id, name, instructions. |
max_chars |
celé číslo | Nejvyšší počet znaků převedených jedním požadavkem. |
Doporučený model je gpt-4o-mini-tts: 13 hlasů (alloy, ash, ballad, coral, echo,
fable, nova, onyx, sage, shimmer, verse, marin, cedar; nejlépe znějí marin
a cedar) a styl řeči podle pokynů (tón, tempo, emoce, přízvuk). Starší tts-1
a tts-1-hd mají 9 hlasů (bez ballad, verse, marin, cedar) a pokyny ignorují. Které
modely jsou k dispozici, záleží na instalaci.
Účtování
gpt-4o-mini-tts se účtuje podle textových tokenů, které čte, a zvukových tokenů, které
vytvoří, tts-1 a tts-1-hd podle počtu znaků. Ceny odpovídají modelu pro převod textu na
řeč (viz typ tts u modelů). Část namluvená stejným
modelem, hlasem a stylem během poslední hodiny se použije znovu a znovu se neúčtuje. Řeč se
platí z osobních kreditů uživatele, nebo z kreditu uživatele
v organizaci, když je nastaveno organization_id (viz organizace).
Před vygenerováním řeči se zůstatek porovná s odhadovanou cenou celého textu.
Požadavek
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
text |
řetězec | Ano | Text k namluvení (nejvýš max_chars znaků). |
model |
řetězec | Ne | model_id z tts/voices. Výchozí: výchozí model serveru. |
voice |
řetězec | Ne | Hlas modelu. Výchozí: výchozí hlas serveru (marin, pokud ho administrátoři nezmění), nebo výchozí hlas modelu, když model tento hlas nemá. |
style |
řetězec | Ne | id předvolby stylu řeči z tts/voices. Modely bez pokynů ho ignorují. |
instructions |
řetězec | Ne | Vlastní pokyny k řeči, nejvýš 1 000 znaků, např. "Mluv klidně a vřele jako vypravěč audioknihy." Mají přednost před style. Modely bez pokynů je ignorují. |
format |
řetězec | Ne | Jen tts/audio: mp3 (výchozí), opus, aac, flac nebo wav. |
filename |
řetězec | Ne | Název souboru pro hlavičku Content-Disposition. Výchozí audio.mp3 (u tts/audio audio.<formát>, u opus audio.ogg). |
organization_id |
UUID | Ne | Vygeneruje řeč v této organizaci a naúčtuje ji z kreditu uživatele v ní, viz organizace. Uživatel musí být admin nebo člen (ne host). Výchozí: žádná (osobní kredity). |
Odpověď
200 OK se zvukovým souborem v těle a hlavičkou Content-Disposition: attachment
s názvem souboru. Content-Type je audio/mpeg (mp3), audio/ogg (opus), audio/aac,
audio/flac nebo audio/wav.
Chyby
| Status | detail |
Příčina |
|---|---|---|
401 |
API key is invalid |
Klíč nemá rozsah ayeto.tts, viz autentizace. |
403 |
permission denied |
Účet uživatele nesmí převádět text na řeč. |
403 |
User is not a member of the organization |
organization_id není organizace uživatele. |
403 |
User does not have write permissions in the organization |
Uživatel je v organizaci host. |
422 |
The text is empty |
text neobsahuje nic k namluvení. |
422 |
The text is too long: at most 60000 characters at once |
text je delší než max_chars. |
422 |
Unknown text-to-speech model: <model> |
model není mezi modely z tts/voices. |
422 |
The model <model> has no voice <voice> |
voice není hlas modelu. |
422 |
The model <model> does not produce <format> |
format není mezi formats modelu. |
422 |
validation error | Pole má špatný typ, instructions jsou příliš dlouhé nebo format není mezi uvedenými formáty. |
422 |
not enough user credit |
Osobní kredity uživatele řeč nepokryjí. |
422 |
not enough organization credit |
S organization_id: kredit uživatele v organizaci řeč nepokryje. |
500 |
Failed to generate audio |
Generování řeči selhalo. |
Chyby autentizace, limitu požadavků a serveru jsou popsané v konvencích.
Příklady
curl -X POST "https://ayeto.ai/api/v3/tts/mp3" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Vaše objednávka je na cestě. Dorazí v pátek.", "voice": "marin", "filename": "objednavka.mp3"}' \
--output objednavka.mp3
curl -X POST "https://ayeto.ai/api/v3/tts/audio" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Vítejte u říjnových novinek.", "voice": "cedar", "instructions": "Energický rozhlasový moderátor, svižné tempo.", "format": "wav"}' \
--output novinky.wav