Endpointy

Soubory a média

Převod dokumentů, tabulek, obrázků a zvuku na text a převod textu na řeč ve formátu MP3.

Zobrazit jako Markdown

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.
PDF 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

bash
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\"}"
json
{
  "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

bash
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\"}
      ]}"
json
{
  "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

bash
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
bash
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