Two utility endpoints that work without a conversation: the data loader turns a file
into plain text (the same conversion AYETO uses for knowledge base uploads), and text to
speech turns text into an MP3 file. Both are paid from the user's
personal credits, or from the user's credit in an organization
when the request carries an organization_id.
Organizations and credits
Both endpoints accept an optional organization_id. The request then runs in that
organization, the same way a chat request does: the
user's credit in the organization pays for it (the organization's shared balance or the
user's individual budget, see credits) instead of the personal
credits. The key's user must be an admin or a member of the organization; guests and
users outside it get 403. Without organization_id the request is charged to the
personal credits. The ids of the user's organizations are returned by
list organization memberships.
Convert a file to text
| Endpoint | POST /api/v3/data-loader/load |
| Scope | ayeto.data_loader |
| Rate limit | default |
Send a file as base64; the response contains its text. Depending on the file type the text is extracted directly or read by an AI model:
| File type | MIME types | How the text is obtained |
|---|---|---|
| Plain text, CSV, Markdown, HTML, source code | any text/*, plus application/json, application/ld+json, application/xml, application/xhtml+xml, application/javascript, application/ics |
Decoded as is. UTF-8 is detected; other encodings are guessed. |
application/pdf |
The text layer is extracted, prefixed with PDF page: N for every page. When a PDF has too little text (a scanned document), its pages are rendered and read by a vision model. |
|
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx), application/msword (.doc) |
Text extracted. |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx), application/vnd.ms-excel (.xls) |
One section per sheet. For .xlsx, cell values with their addresses, formulas and named ranges; for .xls, cell values only. Very large workbooks are cut after 100,000 non-empty cells, with a note at the end. |
| Images | any image/* |
Text in the image is read by a vision model. When the image contains (almost) no text, the model describes the image instead. |
| Audio | audio/mpeg (.mp3), audio/wav, audio/wave, audio/x-wav (.wav) |
Transcribed by a speech-to-text model. Long recordings are split and transcribed in parts. |
Other file types (archives, video, other audio formats, presentations) are not
converted: the request is refused with 422 unsupported file type '<mime type>'
naming the type the file was processed as, and nothing is charged.
The MIME type is taken from, in this order: the mime_type field, the header of a data
URL in data, and finally detection from the file content. Send the type explicitly
when you know it, detection is not reliable for every format.
The endpoint sets no size limit of its own, but the whole file travels base64-encoded in one JSON body and is converted while the request is open. Large scanned PDFs, images and long recordings take time; keep files reasonably small and allow for a long response time.
Billing
Direct text extraction (text, PDF with a text layer, Word, Excel) uses no AI model.
Vision (images, scanned PDFs) and speech to text (audio) are charged at the price of the
models used. The server can also be configured with a minimum price per call; when a
call costs less than the minimum, the difference is charged as a fee. The credits a call
consumed are returned in credits.
Results of vision reading are cached for 24 hours: converting the same image or scanned PDF again within that time does not call the model again and costs only the minimum fee, if one is set.
The check whether the user (or, with organization_id, the organization) has credits
happens before the conversion; see credits. The call is charged to
the organization when organization_id is set, see organizations.
Request
| Field | Type | Required | Description |
|---|---|---|---|
data |
string | Yes | The file, base64-encoded. A data URL (data:application/pdf;base64,JVBERi0x...) is also accepted. |
mime_type |
string | No | MIME type of the file. Overrides the type in a data URL and the detection. |
organization_id |
UUID | No | Run the conversion in this organization and charge it to the user's credit there, see organizations. The user must be an admin or member (not a guest). Default: none (personal credits). |
Response
200 OK with:
| Field | Type | Description |
|---|---|---|
content |
string | The extracted text. |
size |
integer | For text input, the size of the input in bytes; for converted files, the length of content in characters. |
mime_type |
string | The MIME type the file was processed as. For an image whose text was read it is text/plain; for an image that was described it stays the image type. |
credits |
number | Credits the call consumed, including a minimum fee. |
The response also contains the fields filename, url, name, meta, path,
extension, is_chunk, binary and binary_data. For this endpoint they are always
empty or false; ignore them.
Errors
| Status | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
The key lacks the ayeto.data_loader scope, see authentication. |
403 |
User is not a member of the organization |
organization_id is not one of the user's organizations. |
403 |
User does not have write permissions in the organization |
The user is a guest in the organization. |
422 |
invalid base64 data |
data is not valid base64 or a valid data URL. |
422 |
invalid encoding |
A text file could not be decoded. |
422 |
unsupported file type '<mime type>' |
The file is of a type that is not converted (see the table above), for example unsupported file type 'application/zip'. |
422 |
not enough user credit |
The user's personal credits are used up. |
422 |
not enough organization credit |
With organization_id: the user's credit in the organization is used up. |
422 |
validation error | data is missing. |
500 |
error reading document |
A scanned PDF could not be rendered. |
500 |
Error while processing Word document |
The Word file could not be read. |
500 |
Error while processing Excel file |
The Excel file could not be read. |
500 |
Error while processing audio file, Error while processing WAV audio file |
The audio could not be converted or transcribed. |
Authentication, rate limit and server errors are described in conventions.
Example
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
}
Convert several files to text
| Endpoint | POST /api/v3/data-loader/load-batch |
| Scope | ayeto.data_loader |
| Rate limit | default |
The batch form of convert a file to text: send several files in one request and get the text of each. The files are converted the same way (same file types, same MIME type rules) and several of them at the same time, so a batch finishes sooner than the same files sent one after another.
A file that cannot be converted does not fail the request. The response is 200 OK and
the item of that file carries error with the status and detail the single-file
endpoint would answer with; the other files are converted normally. Always check
success of every item.
A batch may hold at most 20 files, 50 MB in total (the size of the files themselves, not
of their base64 text). The server can be configured with other limits. A batch over a
limit is refused with 422 before anything is converted. The whole batch is converted
while the request is open: with scanned PDFs, images or recordings allow for a long
response time, or send smaller batches.
Batch billing
Each file is charged as described for a single file, and credits is the
total for the batch. A minimum price, when the server has one, is applied once to the
whole batch, not to every file: when the batch costs less than the minimum, the
difference is charged as a fee. A batch in which no file was converted pays no minimum.
The credit check happens before the conversion. When the credits run out during a batch,
the remaining files that need an AI model fail with a credit error in their error.
Batch request
| Field | Type | Required | Description |
|---|---|---|---|
items |
array | Yes | The files, at least one. |
items[].data |
string | Yes | The file, base64-encoded, or a data URL. |
items[].mime_type |
string | No | MIME type of the file. Overrides the type in a data URL and the detection. |
items[].id |
string | No | Your own identifier of the file, at most 256 characters. Returned with the result. |
organization_id |
UUID | No | Run the batch in this organization and charge it to the user's credit there, see organizations. Default: none (personal credits). |
Batch response
200 OK with:
| Field | Type | Description |
|---|---|---|
items |
array | One result per file, in the order of the request. |
items[].index |
integer | Position of the file in the request, from 0. |
items[].id |
string or null | The id sent with the file. |
items[].success |
boolean | Whether the file was converted. |
items[].content |
string or null | The extracted text; null when the file failed. |
items[].size |
integer or null | As size of the single-file endpoint. |
items[].mime_type |
string or null | The MIME type the file was processed as. |
items[].error |
object or null | For a failed file: status (the HTTP status the single-file endpoint would return) and detail. |
credits |
number | Credits the whole batch consumed, including a minimum fee. |
Batch errors
Errors of a single file (invalid base64 data, invalid encoding,
unsupported file type '<mime type>', credit errors during the batch and the 500
errors listed for a single file) are reported in items[].error, not as the
status of the request. A file that failed for an unexpected reason has status 500 and
detail error while processing the file. The request itself fails with:
| Status | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
The key lacks the ayeto.data_loader scope, see authentication. |
403 |
User is not a member of the organization |
organization_id is not one of the user's organizations. |
403 |
User does not have write permissions in the organization |
The user is a guest in the organization. |
422 |
too many files (<count>, at most <limit>) |
The batch has more files than allowed. |
422 |
the batch is too large (<size> MB, at most <limit> MB) |
The files are larger together than allowed. |
422 |
not enough user credit, not enough organization credit |
The credits are used up, or lower than the minimum price. |
422 |
validation error | items is missing or empty, or an item has no data. |
Batch example
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
}
Text to speech
| Endpoints | POST /api/v3/tts/mp3, POST /api/v3/tts/audio, POST /api/v3/tts/voices |
| Scope | ayeto.tts |
| Rate limit | default |
Converts text to speech read by a natural voice. tts/mp3 returns an MP3 file,
tts/audio a file of the format you choose, tts/voices lists the models, their
voices and the speaking styles.
The text is spoken as given. It is split into parts (whole paragraphs, a longer
paragraph at sentence ends) and the audio of all parts is joined into one file. One
request takes at most 60,000 characters, about an hour of audio (the administrators
may change the limit; tts/voices returns the current one as max_chars).
Models, voices and styles
POST /api/v3/tts/voices (empty JSON body {}) returns what can be used:
| Field | Type | Description |
|---|---|---|
models |
array | Text-to-speech models: model_id, display_name, description, voices (voice ids), default_voice, instructions (whether the model follows speaking instructions), formats, is_recommended. |
default_model |
string | The model used when a request names none. |
default_voice |
string | The voice used when a request names none. |
styles |
array | Speaking style presets: id, name, instructions. |
max_chars |
integer | Most characters converted in one request. |
The recommended model is gpt-4o-mini-tts: 13 voices (alloy, ash, ballad, coral,
echo, fable, nova, onyx, sage, shimmer, verse, marin, cedar; marin and
cedar sound best) and a speaking style set by instructions (tone, pace, emotion,
accent). The older tts-1 and tts-1-hd have 9 voices (without ballad, verse,
marin, cedar) and ignore instructions. Which models are available depends on the
installation.
Billing
gpt-4o-mini-tts is charged by the text tokens it reads and the audio tokens it
produces, tts-1 and tts-1-hd by the number of characters. Prices follow the text-to-speech model (see
the tts type in models). A part spoken with the
same model, voice and style within the last hour is reused and not charged again.
Speech is paid from the user's personal credits, or from the
user's credit in an organization when organization_id is set (see
organizations). Before the speech is generated, the
balance is checked against the estimated price of the whole text.
Request
| Field | Type | Required | Description |
|---|---|---|---|
text |
string | Yes | The text to speak (at most max_chars characters). |
model |
string | No | A model_id from tts/voices. Default: the server's default model. |
voice |
string | No | A voice of the model. Default: the server's default voice (marin unless changed by the administrators), or the model's own default voice when it does not have that one. |
style |
string | No | id of a speaking style preset from tts/voices. Ignored by models without instructions. |
instructions |
string | No | Your own speaking instructions, at most 1,000 characters, e.g. "Speak calmly and warmly, like an audiobook narrator." Wins over style. Ignored by models without instructions. |
format |
string | No | tts/audio only: mp3 (default), opus, aac, flac or wav. |
filename |
string | No | File name for the Content-Disposition header. Default audio.mp3 (audio.<format> for tts/audio, audio.ogg for opus). |
organization_id |
UUID | No | Generate the speech in this organization and charge it to the user's credit there, see organizations. The user must be an admin or member (not a guest). Default: none (personal credits). |
Response
200 OK with the audio file as the body and a Content-Disposition: attachment
header carrying the file name. Content-Type is audio/mpeg (mp3), audio/ogg
(opus), audio/aac, audio/flac or audio/wav.
Errors
| Status | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
The key lacks the ayeto.tts scope, see authentication. |
403 |
permission denied |
The user's account is not allowed to use text to speech. |
403 |
User is not a member of the organization |
organization_id is not one of the user's organizations. |
403 |
User does not have write permissions in the organization |
The user is a guest in the organization. |
422 |
The text is empty |
text has no characters to speak. |
422 |
The text is too long: at most 60000 characters at once |
text is longer than max_chars. |
422 |
Unknown text-to-speech model: <model> |
model is not one of the models of tts/voices. |
422 |
The model <model> has no voice <voice> |
voice is not a voice of the model. |
422 |
The model <model> does not produce <format> |
format is not one of the model's formats. |
422 |
validation error | A field has the wrong type, instructions is too long, or format is not one of the listed formats. |
422 |
not enough user credit |
The user's personal credits do not cover the speech. |
422 |
not enough organization credit |
With organization_id: the user's credit in the organization does not cover the speech. |
500 |
Failed to generate audio |
Speech generation failed. |
Authentication, rate limit and server errors are described in conventions.
Examples
curl -X POST "https://ayeto.ai/api/v3/tts/mp3" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Your order has shipped. It will arrive on Friday.", "voice": "marin", "filename": "order-update.mp3"}' \
--output order-update.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": "Welcome to the October news.", "voice": "cedar", "instructions": "Upbeat radio host, lively pace.", "format": "wav"}' \
--output news.wav