Synthèse vocale

Informations communes

• Base URL : https://api.routeapi.ai
• Authentification : Authorization: Bearer $ROUTEAPI_KEY avec une clé API commençant par sk- (à créer sur la page API Keys de la console). Les clés de gestion commençant par rat_ ne peuvent pas appeler les modèles.
• Format d’erreur : {"error": {"message": "...", "type": "...", "code": "..."}}. Voir Erreurs courantes pour la signification de chaque code d’état.

La synthèse vocale lit un texte et renvoie un fichier audio. Elle suit l’API audio d’OpenAI : le corps de la requête est du JSON, le corps de la réponse est l’audio lui-même, et il n’y a ni tâche asynchrone ni étape d’interrogation.

Si la Base URL de votre client est configurée sans /v1, POST /audio/speech fonctionne également ; la passerelle la réécrit en interne vers /v1/audio/speech.

La liste des modèles ne distingue pas les modèles audio

Les types de point de terminaison intégrés de RouteAPI ne contiennent aucune valeur audio ; un modèle de synthèse vocale n’est donc pas distinguable d’un modèle de chat dans GET /v1/models : son supported_endpoint_types reflète le type de canal qui le sert (le plus souvent openai). Choisissez l’ID de modèle dans la liste, puis appelez le chemin audio avec celui-ci. Voir Modèles.

Point de terminaison

POST /v1/audio/speech

https://api.routeapi.ai/v1/audio/speech

Paramètres de la requête

Le corps est en JSON. Seul model est validé par RouteAPI lui-même ; les autres champs sont transmis au modèle en amont, et les valeurs acceptées dépendent de ce modèle.

Champ	Type	Requis	Description
model	string	Oui	ID du modèle de synthèse vocale, par exemple tts-1, tts-1-hd ou gpt-4o-mini-tts. Il doit être présent dans le corps : une valeur vide ou absente renvoie 400 avec Missing required field: model (le routage dispose d’un repli tts-1, mais la validation s’exécute en premier)
input	string	Requis en amont	Texte à synthétiser. La passerelle estime aussi les tokens d’entrée à partir de ce champ pour la facturation
voice	string	Requis en amont	Nom de la voix. L’ensemble des voix valides dépend du modèle
response_format	string	Non	Conteneur audio, transmis à l’amont. Lorsqu’il est omis, la valeur par défaut de l’amont s’applique. La passerelle utilise aussi cette valeur pour mesurer la durée de l’audio renvoyé à des fins de facturation et traite une valeur omise comme mp3 ; pcm est mesuré à 24 kHz, 16 bits, mono
speed	number	Non	Multiplicateur de vitesse de lecture, transmis tel quel lorsqu’il est présent
instructions	string	Non	Instruction de débit ou de style pour les modèles qui la prennent en charge (comme gpt-4o-mini-tts)
stream_format	string	Non	Définissez sse pour recevoir l’audio sous forme de Server-Sent Events au lieu d’un seul corps binaire. La valeur est transmise ; seuls les amonts prenant en charge le streaming de synthèse vocale diffuseront réellement en flux
metadata	object	Non	Champs supplémentaires que certains types de canal fusionnent dans leur propre requête en amont (par exemple Volcengine TTS ou MiniMax)

Exemples

curl

curl https://api.routeapi.ai/v1/audio/speech \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "voice": "alloy",
    "input": "RouteAPI aggregates many AI providers behind a single API.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python (SDK OpenAI)

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alloy",
    input="RouteAPI aggregates many AI providers behind a single API.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

client.audio.speech.create(...) fonctionne également et renvoie response.content, les octets audio bruts. Enregistrez-les avec open("speech.mp3", "wb").write(response.content).

Réponse

Le corps est le fichier audio lui-même, pas du JSON. La passerelle lit le corps de l’amont pour en mesurer la durée à des fins de facturation, puis l’écrit avec un Content-Length correspondant à ce que vous recevez réellement. Seule une courte liste blanche d’en-têtes d’amont est transmise — notamment Content-Type (par exemple audio/mpeg), sur lequel vous pouvez vous appuyer pour choisir une extension de fichier ; les autres en-têtes d’amont comme Server sont supprimés. Content-Encoding n’est transmis que lorsque le corps de l’amont n’a pas été décompressé par la passerelle.

Avec "stream_format": "sse", la réponse est text/event-stream. Chaque fragment audio arrive sous forme de trame data:, et si l’amont envoie un fragment d’usage final, la passerelle le lit pour la facturation ; sinon, elle facture l’estimation.

Facturation

Les appels audio utilisent le même mécanisme de solde et de quota que tout autre appel de l’API des modèles : un montant estimé est prélevé au préalable, l’appel est réglé après la réponse de l’amont, et un appel échoué est remboursé. Les prix proviennent de la configuration du modèle — voir Tarification des modèles pour savoir comment les prix sont affichés sur la page de détail d’un modèle.

La méthode applicable dépend de la façon dont le modèle est tarifé, et la page de détail du modèle l’indique :

• Prix fixe par requête. Si le modèle a un prix par requête configuré, la requête est facturée à ce prix multiplié par le multiplicateur de votre groupe, et les tokens n’influent pas sur le montant. Dans les valeurs par défaut intégrées, gpt-4o-mini-tts est déjà configuré ainsi — vérifiez la page de détail plutôt que de supposer une tarification au token.
• Au token. Sinon, le montant est calculé à partir de l’usage décrit ci-dessous.

Entrée

L’entrée est estimée à partir de input. La passerelle compte les caractères pour la plupart des modèles et utilise un tokenizer pour les modèles dont l’ID contient gpt, puis facture ce décompte au multiplicateur du modèle.

Sortie

L’audio généré est mesuré en tokens à raison de 1000 tokens par minute d’audio : la passerelle lit la durée dans l’audio renvoyé et facture ceil(duration) / 60 × 1000 tokens de sortie, au prix du multiplicateur du modèle multiplié par son multiplicateur audio puis par son multiplicateur de complétion audio. Si la durée de l’audio ne peut pas être mesurée, elle se rabat sur environ un token par kilooctet d’audio.

Le multiplicateur de complétion audio intégré vaut 0 pour la famille tts-1 / tts-1-hd : en tarification au token, l’audio généré n’ajoute donc rien pour ces modèles, et l’entrée calculée sur les caractères constitue en pratique l’intégralité du coût. Les modèles dont le multiplicateur de complétion audio n’est pas nul sont également facturés pour l’audio généré.

La mesure de la durée dépend de response_format : pcm n’a pas d’en-tête de conteneur, sa durée est donc calculée à partir du nombre d’octets à 24 kHz / 16 bits / mono ; les autres formats sont analysés à partir du conteneur.

Comme les tokens de sortie dérivent du fichier renvoyé, le montant suit ce qui a réellement été généré, et non la seule longueur de input.

Erreurs

Les erreurs utilisent le corps standard { "error": { ... } }, et le message contient un request ID que vous pouvez rechercher dans les journaux de la console. Voir Erreurs courantes pour la liste complète.

Statut	Code	Cause
400	invalid_request	model est absent ou vide (Missing required field: model)
403	insufficient_user_quota / pre_consume_token_quota_failed	Le solde du compte ou le quota de la clé ne couvre pas le coût estimé
403	—	Le modèle est hors de la liste blanche de modèles de la clé (This token has no access to model ...)
429	—	La limite de débit a été dépassée
503	model_not_found	Aucun canal utilisable pour le modèle (No valid upstream service)
500	convert_request_failed	La requête ne peut pas être convertie pour le canal — par exemple un canal dont l’adaptateur n’implémente pas la synthèse vocale
4xx / 5xx	code de l’amont	Le fournisseur a rejeté la requête ; le statut et le message sont transmis tels quels

{
  "error": {
    "message": "Missing required field: model (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

Lorsqu’une requête échoue, le montant pré-réservé est remboursé.

Étapes suivantes

• Transcription de la parole — transcrivez ou traduisez des fichiers audio.
• Modèles — vérifiez que l’ID de modèle est visible pour votre clé avant de l’appeler.
• Tarification des modèles — comment les prix d’entrée et de sortie audio sont affichés.
• Erreurs courantes — codes de statut, corps d’erreur et ordre de dépannage.