Endpoints

Files and media

Convert documents, spreadsheets, images and audio to text, and turn text into MP3 speech.

View as Markdown

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

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
}

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

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
}

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

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": "Your order has shipped. It will arrive on Friday.", "voice": "marin", "filename": "order-update.mp3"}' \
  --output order-update.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": "Welcome to the October news.", "voice": "cedar", "instructions": "Upbeat radio host, lively pace.", "format": "wav"}' \
  --output news.wav