Endpoints

Fichiers et médias

Convertir des documents, des tableurs, des images et de l'audio en texte, et transformer du texte en voix au format MP3.

Afficher en Markdown

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

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
}

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

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
}

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

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": "Votre commande est en route. Elle arrivera vendredi.", "voice": "marin", "filename": "commande.mp3"}' \
  --output commande.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": "Bienvenue aux nouveautés d’octobre.", "voice": "cedar", "instructions": "Animateur radio énergique, rythme vif.", "format": "wav"}' \
  --output nouveautes.wav