Deux endpoints utilitaires qui fonctionnent sans conversation : la conversion de fichier en texte transforme un fichier
en texte brut (la même conversion qu'AYETO utilise pour les fichiers envoyés dans les bases de connaissances), et la synthèse
vocale transforme du texte en fichier MP3. Les deux sont payés avec les
crédits personnels de l'utilisateur, ou avec le crédit de l'utilisateur dans une organisation
lorsque la requête contient un organization_id.
Organisations et crédits
Les deux endpoints acceptent un organization_id facultatif. La requête s'exécute alors dans cette
organisation, de la même manière qu'une requête de chat : le
crédit de l'utilisateur dans l'organisation la paie (le solde partagé de l'organisation ou le
budget individuel de l'utilisateur, voir crédits) à la place des crédits
personnels. L'utilisateur de la clé doit être administrateur ou membre de l'organisation ; les invités et
les utilisateurs extérieurs à celle-ci obtiennent 403. Sans organization_id, la requête est débitée des
crédits personnels. Les identifiants des organisations de l'utilisateur sont renvoyés par
lister les appartenances aux organisations.
Convertir un fichier en texte
| Endpoint | POST /api/v3/data-loader/load |
| Portée | ayeto.data_loader |
| Limite de débit | par défaut |
Envoyez un fichier en base64 ; la réponse contient son texte. Selon le type de fichier, le texte est extrait directement ou lu par un modèle d'IA :
| Type de fichier | Types MIME | Obtention du texte |
|---|---|---|
| Texte brut, CSV, Markdown, HTML, code source | tout text/*, ainsi que application/json, application/ld+json, application/xml, application/xhtml+xml, application/javascript, application/ics |
Décodé tel quel. L'UTF-8 est détecté ; les autres encodages sont devinés. |
application/pdf |
La couche de texte est extraite, précédée de PDF page: N pour chaque page. Lorsqu'un PDF contient trop peu de texte (un document numérisé), ses pages sont rendues et lues par un modèle de vision. |
|
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx), application/msword (.doc) |
Texte extrait. |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx), application/vnd.ms-excel (.xls) |
Une section par feuille. Pour .xlsx, les valeurs des cellules avec leurs adresses, les formules et les plages nommées ; pour .xls, uniquement les valeurs des cellules. Les classeurs très volumineux sont tronqués après 100 000 cellules non vides, avec une note à la fin. |
| Images | tout image/* |
Le texte de l'image est lu par un modèle de vision. Lorsque l'image ne contient (presque) pas de texte, le modèle décrit l'image à la place. |
| Audio | audio/mpeg (.mp3), audio/wav, audio/wave, audio/x-wav (.wav) |
Transcrit par un modèle de reconnaissance vocale. Les enregistrements longs sont découpés et transcrits par parties. |
Les autres types de fichiers (archives, vidéo, autres formats audio, présentations) ne sont pas
convertis : la requête est refusée avec 422 unsupported file type '<mime type>'
indiquant le type sous lequel le fichier a été traité, et rien n'est facturé.
Le type MIME est déterminé, dans cet ordre, à partir du champ mime_type, de l'en-tête d'une data
URL dans data, et enfin par détection à partir du contenu du fichier. Envoyez le type explicitement
lorsque vous le connaissez, la détection n'est pas fiable pour tous les formats.
L'endpoint n'impose pas de limite de taille propre, mais le fichier entier transite encodé en base64 dans un seul corps JSON et est converti pendant que la requête est ouverte. Les gros PDF numérisés, les images et les enregistrements longs prennent du temps ; gardez des fichiers de taille raisonnable et prévoyez un temps de réponse long.
Facturation
L'extraction directe du texte (texte, PDF avec couche de texte, Word, Excel) n'utilise aucun modèle d'IA.
La vision (images, PDF numérisés) et la reconnaissance vocale (audio) sont facturées au prix des
modèles utilisés. Le serveur peut aussi être configuré avec un prix minimum par appel ; lorsqu'un
appel coûte moins que ce minimum, la différence est facturée sous forme de frais. Les crédits consommés
par un appel sont renvoyés dans credits.
Les résultats de la lecture par vision sont mis en cache pendant 24 heures : convertir à nouveau la même image ou le même PDF numérisé dans ce délai ne rappelle pas le modèle et ne coûte que les frais minimum, s'ils sont définis.
La vérification que l'utilisateur (ou, avec organization_id, l'organisation) dispose de crédits
a lieu avant la conversion ; voir crédits. L'appel est débité à
l'organisation lorsque organization_id est défini, voir organisations.
Requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
data |
chaîne | Oui | Le fichier, encodé en base64. Une data URL (data:application/pdf;base64,JVBERi0x...) est également acceptée. |
mime_type |
chaîne | Non | Type MIME du fichier. Prévaut sur le type d'une data URL et sur la détection. |
organization_id |
UUID | Non | Exécuter la conversion dans cette organisation et la débiter du crédit de l'utilisateur dans celle-ci, voir organisations. L'utilisateur doit être administrateur ou membre (pas invité). Par défaut : aucune (crédits personnels). |
Réponse
200 OK avec :
| Champ | Type | Description |
|---|---|---|
content |
chaîne | Le texte extrait. |
size |
entier | Pour une entrée texte, la taille de l'entrée en octets ; pour les fichiers convertis, la longueur de content en caractères. |
mime_type |
chaîne | Le type MIME sous lequel le fichier a été traité. Pour une image dont le texte a été lu, c'est text/plain ; pour une image qui a été décrite, il reste le type de l'image. |
credits |
nombre | Crédits consommés par l'appel, frais minimum compris. |
La réponse contient aussi les champs filename, url, name, meta, path,
extension, is_chunk, binary et binary_data. Pour cet endpoint, ils sont toujours
vides ou à false ; ignorez-les.
Erreurs
| Statut | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
La clé n'a pas la portée ayeto.data_loader, voir authentification. |
403 |
User is not a member of the organization |
organization_id ne fait pas partie des organisations de l'utilisateur. |
403 |
User does not have write permissions in the organization |
L'utilisateur est invité dans l'organisation. |
422 |
invalid base64 data |
data n'est pas du base64 valide ni une data URL valide. |
422 |
invalid encoding |
Un fichier texte n'a pas pu être décodé. |
422 |
unsupported file type '<mime type>' |
Le fichier est d'un type qui n'est pas converti (voir le tableau ci-dessus), par exemple unsupported file type 'application/zip'. |
422 |
not enough user credit |
Les crédits personnels de l'utilisateur sont épuisés. |
422 |
not enough organization credit |
Avec organization_id : le crédit de l'utilisateur dans l'organisation est épuisé. |
422 |
erreur de validation | data est absent. |
500 |
error reading document |
Un PDF numérisé n'a pas pu être rendu. |
500 |
Error while processing Word document |
Le fichier Word n'a pas pu être lu. |
500 |
Error while processing Excel file |
Le fichier Excel n'a pas pu être lu. |
500 |
Error while processing audio file, Error while processing WAV audio file |
L'audio n'a pas pu être converti ou transcrit. |
Les erreurs d'authentification, de limite de débit et du serveur sont décrites dans les conventions.
Exemple
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
}
Convertir plusieurs fichiers en texte
| Endpoint | POST /api/v3/data-loader/load-batch |
| Portée | ayeto.data_loader |
| Limite de débit | par défaut |
La forme par lot de convertir un fichier en texte : envoyez plusieurs fichiers dans une seule requête et recevez le texte de chacun. Les fichiers sont convertis de la même manière (mêmes types de fichiers, mêmes règles pour le type MIME) et plusieurs à la fois, si bien qu'un lot se termine plus vite que les mêmes fichiers envoyés l'un après l'autre.
Un fichier qui ne peut pas être converti ne fait pas échouer la requête. La réponse est 200 OK et
l'élément de ce fichier porte error avec le statut et le detail que l'endpoint pour un seul
fichier aurait renvoyés ; les autres fichiers sont convertis normalement. Vérifiez toujours
success pour chaque élément.
Un lot peut contenir au plus 20 fichiers, 50 Mo au total (la taille des fichiers eux-mêmes, pas de
leur texte base64). Le serveur peut être configuré avec d'autres limites. Un lot qui dépasse une
limite est refusé avec 422 avant toute conversion. Le lot entier est converti pendant que la
requête est ouverte : avec des PDF numérisés, des images ou des enregistrements, prévoyez un temps
de réponse long, ou envoyez des lots plus petits.
Facturation du lot
Chaque fichier est facturé comme décrit pour un seul fichier, et credits est le
total du lot. Un prix minimum, lorsque le serveur en a un, s'applique une seule fois au lot entier,
pas à chaque fichier : lorsque le lot coûte moins que le minimum, la différence est facturée comme
frais. Un lot dans lequel aucun fichier n'a été converti ne paie pas de minimum.
La vérification des crédits a lieu avant la conversion. Lorsque les crédits s'épuisent pendant un
lot, les fichiers restants qui ont besoin d'un modèle d'IA échouent avec une erreur de crédit dans
leur error.
Requête du lot
| Champ | Type | Requis | Description |
|---|---|---|---|
items |
tableau | Oui | Les fichiers, au moins un. |
items[].data |
chaîne | Oui | Le fichier encodé en base64, ou une data URL. |
items[].mime_type |
chaîne | Non | Type MIME du fichier. Prioritaire sur le type d'une data URL et sur la détection. |
items[].id |
chaîne | Non | Votre propre identifiant du fichier, 256 caractères au plus. Renvoyé avec le résultat. |
organization_id |
UUID | Non | Exécute le lot dans cette organisation et le débite du crédit de l'utilisateur dans celle-ci, voir organisations. Par défaut : aucune (crédits personnels). |
Réponse du lot
200 OK avec :
| Champ | Type | Description |
|---|---|---|
items |
tableau | Un résultat par fichier, dans l'ordre de la requête. |
items[].index |
entier | Position du fichier dans la requête, à partir de 0. |
items[].id |
chaîne ou null | L'id envoyé avec le fichier. |
items[].success |
booléen | Si le fichier a été converti. |
items[].content |
chaîne ou null | Le texte extrait ; null lorsque le fichier a échoué. |
items[].size |
entier ou null | Comme size de l'endpoint pour un seul fichier. |
items[].mime_type |
chaîne ou null | Le type MIME sous lequel le fichier a été traité. |
items[].error |
objet ou null | Pour un fichier en échec : status (le statut HTTP que l'endpoint pour un seul fichier renverrait) et detail. |
credits |
nombre | Crédits consommés par le lot entier, frais minimum compris. |
Erreurs du lot
Les erreurs d'un fichier (invalid base64 data, invalid encoding,
unsupported file type '<mime type>', les erreurs de crédit pendant le lot et les erreurs 500
listées pour un seul fichier) sont signalées dans items[].error, pas comme statut de
la requête. Un fichier qui a échoué pour une raison inattendue a le statut 500 et le détail
error while processing the file. La requête elle-même échoue avec :
| Statut | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
La clé n'a pas la portée ayeto.data_loader, voir authentification. |
403 |
User is not a member of the organization |
organization_id ne fait pas partie des organisations de l'utilisateur. |
403 |
User does not have write permissions in the organization |
L'utilisateur est invité dans l'organisation. |
422 |
too many files (<count>, at most <limit>) |
Le lot contient plus de fichiers qu'autorisé. |
422 |
the batch is too large (<size> MB, at most <limit> MB) |
Les fichiers sont ensemble plus volumineux qu'autorisé. |
422 |
not enough user credit, not enough organization credit |
Les crédits sont épuisés, ou inférieurs au prix minimum. |
422 |
erreur de validation | items est absent ou vide, ou un élément n'a pas de data. |
Exemple de lot
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
}
Synthèse vocale
| Points d'accès | POST /api/v3/tts/mp3, POST /api/v3/tts/audio, POST /api/v3/tts/voices |
| Portée | ayeto.tts |
| Limite de débit | default |
Convertit du texte en parole lue par une voix naturelle. tts/mp3 renvoie un fichier
MP3, tts/audio un fichier au format choisi, tts/voices liste les modèles, leurs voix
et les styles de parole.
Le texte est lu tel quel. Il est découpé en parties (des paragraphes entiers, un
paragraphe plus long aux fins de phrases) et l'audio de toutes les parties est réuni en un
seul fichier. Une requête convertit au plus 60 000 caractères, environ une heure d'audio
(les administrateurs peuvent changer la limite ; tts/voices renvoie la valeur actuelle
dans max_chars).
Modèles, voix et styles
POST /api/v3/tts/voices (corps JSON vide {}) renvoie ce qui peut être utilisé :
| Champ | Type | Description |
|---|---|---|
models |
tableau | Modèles de synthèse vocale : model_id, display_name, description, voices (identifiants des voix), default_voice, instructions (le modèle suit-il des instructions de parole), formats, is_recommended. |
default_model |
chaîne | Le modèle utilisé quand la requête n'en précise pas. |
default_voice |
chaîne | La voix utilisée quand la requête n'en précise pas. |
styles |
tableau | Préréglages de style de parole : id, name, instructions. |
max_chars |
entier | Nombre maximal de caractères convertis par requête. |
Le modèle recommandé est gpt-4o-mini-tts : 13 voix (alloy, ash, ballad, coral,
echo, fable, nova, onyx, sage, shimmer, verse, marin, cedar ; marin et
cedar sonnent le mieux) et un style de parole défini par des instructions (ton, rythme,
émotion, accent). Les anciens tts-1 et tts-1-hd ont 9 voix (sans ballad, verse,
marin, cedar) et ignorent les instructions. Les modèles disponibles dépendent de
l'installation.
Facturation
gpt-4o-mini-tts est facturé selon les jetons de texte qu'il lit et les jetons audio qu'il
produit, tts-1 et tts-1-hd selon le nombre de caractères. Les prix suivent le modèle de
synthèse vocale (voir le type tts dans les modèles).
Une partie prononcée avec le même modèle, la même voix et le même style au cours de la
dernière heure est réutilisée et n'est pas facturée à nouveau. La parole est payée avec les
crédits personnels de l'utilisateur, ou avec son crédit dans une
organisation lorsque organization_id est indiqué (voir
organisations). Avant la génération, le solde est comparé au
prix estimé de tout le texte.
Requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
text |
chaîne | Oui | Le texte à prononcer (au plus max_chars caractères). |
model |
chaîne | Non | Un model_id de tts/voices. Par défaut : le modèle par défaut du serveur. |
voice |
chaîne | Non | Une voix du modèle. Par défaut : la voix par défaut du serveur (marin sauf changement par les administrateurs), ou la voix par défaut du modèle s'il n'a pas celle-ci. |
style |
chaîne | Non | id d'un préréglage de style de tts/voices. Ignoré par les modèles sans instructions. |
instructions |
chaîne | Non | Vos propres instructions de parole, au plus 1 000 caractères, p. ex. "Parle calmement et chaleureusement, comme un narrateur de livre audio." Prioritaires sur style. Ignorées par les modèles sans instructions. |
format |
chaîne | Non | tts/audio uniquement : mp3 (par défaut), opus, aac, flac ou wav. |
filename |
chaîne | Non | Nom du fichier pour l'en-tête Content-Disposition. Par défaut audio.mp3 (audio.<format> pour tts/audio, audio.ogg pour opus). |
organization_id |
UUID | Non | Génère la parole dans cette organisation et la facture sur le crédit de l'utilisateur dans celle-ci, voir organisations. L'utilisateur doit être admin ou membre (pas invité). Par défaut : aucune (crédits personnels). |
Réponse
200 OK avec le fichier audio dans le corps et un en-tête Content-Disposition: attachment
portant le nom du fichier. Content-Type vaut audio/mpeg (mp3), audio/ogg (opus),
audio/aac, audio/flac ou audio/wav.
Erreurs
| Statut | detail |
Cause |
|---|---|---|
401 |
API key is invalid |
La clé n'a pas la portée ayeto.tts, voir authentification. |
403 |
permission denied |
Le compte de l'utilisateur n'a pas accès à la synthèse vocale. |
403 |
User is not a member of the organization |
organization_id n'est pas une organisation de l'utilisateur. |
403 |
User does not have write permissions in the organization |
L'utilisateur est invité dans l'organisation. |
422 |
The text is empty |
text ne contient rien à prononcer. |
422 |
The text is too long: at most 60000 characters at once |
text dépasse max_chars. |
422 |
Unknown text-to-speech model: <model> |
model ne fait pas partie des modèles de tts/voices. |
422 |
The model <model> has no voice <voice> |
voice n'est pas une voix du modèle. |
422 |
The model <model> does not produce <format> |
format ne fait pas partie des formats du modèle. |
422 |
validation error | Un champ a un mauvais type, instructions est trop long ou format n'est pas un des formats indiqués. |
422 |
not enough user credit |
Les crédits personnels de l'utilisateur ne couvrent pas la parole. |
422 |
not enough organization credit |
Avec organization_id : le crédit de l'utilisateur dans l'organisation ne couvre pas la parole. |
500 |
Failed to generate audio |
La génération de la parole a échoué. |
Les erreurs d'authentification, de limite de débit et de serveur sont décrites dans les conventions.
Exemples
curl -X POST "https://ayeto.ai/api/v3/tts/mp3" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Votre commande est en route. Elle arrivera vendredi.", "voice": "marin", "filename": "commande.mp3"}' \
--output commande.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": "Bienvenue aux nouveautés d’octobre.", "voice": "cedar", "instructions": "Animateur radio énergique, rythme vif.", "format": "wav"}' \
--output nouveautes.wav