Interface de synthèse vocale

La plateforme fournit une interface de synthèse vocale compatible AI Platform. Sa disponibilité dépend du groupe et du catalogue de modèles de la clé API actuelle : vérifiez d'abord avec GET /v1/models qu'un modèle audio disponible existe, puis appelez cette interface.

Requête

Élément	Valeur
Méthode	`POST`
Chemin	`/v1/audio/speech`
Authentification	`Authorization: Bearer <API_KEY>`
En-tête de requête	`Content-Type: application/json`
Réponse	Audio binaire (pas du JSON)

La réponse est de l'audio binaire, pas du JSON — utilisez donc --output (ou -o) pour écrire directement la réponse dans un fichier. Si vous la traitez comme du JSON, vous obtiendrez un corps de réponse vide.

Les valeurs disponibles de voice dépendent du modèle actuel ; tous les modèles n'acceptent pas alloy.

Requête

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Paramètres de requête

Paramètre	Type	Description
`model`	string	Obligatoire. `data[].id` du modèle audio renvoyé par `GET /v1/models`.
`input`	string	Obligatoire. Texte à synthétiser. La limite de longueur dépend du modèle réel.
`voice`	string	Nom de la voix. Les voix disponibles dépendent du modèle actuel ; fiez-vous aux détails du modèle.
`response_format`	string	Format audio de sortie, par exemple `mp3`. Les formats pris en charge dépendent du modèle réel.
`speed`	number	Vitesse de la parole. La prise en charge et la plage de valeurs dépendent du modèle réel.

La plage disponible pour la voix, le format et la vitesse varie selon le modèle. Ne supposez pas que tous les modèles prennent en charge alloy ou mp3, et ne codez pas en dur la liste des voix d'un modèle.

Réponse

Succès

Le corps d'une réponse réussie est constitué de données audio binaires, pas de JSON. Écrivez-le directement dans un fichier ou transmettez-le en streaming au client.

# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3

Échec

En cas d'échec, une réponse non 2xx contenant un objet error est renvoyée, avec une structure identique à celle des interfaces de modèles :

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

Causes d'échec courantes :

Situation	Symptôme	Traitement
Aucun modèle audio dans le groupe	`model_not_found` ou modèle indisponible	Vérifiez les modèles audio disponibles avec `GET /v1/models`
Voix non prise en charge par le modèle	`invalid_parameter`	Utilisez une voix prise en charge par ce modèle
Format non pris en charge par le modèle	`invalid_parameter`	Utilisez un `response_format` pris en charge
Requêtes trop fréquentes	HTTP `429`	Réessayez après un backoff, comme indiqué

Recommandations d'intégration côté serveur

La synthèse vocale est une interface synchrone dont la réponse est directement constituée des données audio ; lors de l'intégration, veillez à :

ne la traitez pas comme du JSON. Vérifiez d'abord le statut HTTP et le Content-Type, et ne lisez l'error au format JSON qu'en cas d'échec ;
n'oubliez pas de définir le Content-Type lorsque vous transmettez l'audio directement au navigateur, sinon le navigateur le traitera comme du texte ;
contrôlez la longueur de input. Pour les textes très longs, découpez-les côté métier, synthétisez chaque segment puis concaténez le résultat, afin d'éviter de dépasser la limite d'une requête ;
copiez de préférence les fichiers audio dans votre propre stockage, plutôt que de dépendre durablement des résultats temporaires renvoyés par la plateforme ;
le backend métier doit mettre en cache les résultats de synthèse fréquemment répétés afin d'éviter une double facturation.

Tâches audio asynchrones

Outre cette interface synchrone, la plateforme propose également une génération audio asynchrone (par exemple musique de fond, effets sonores). Le statut et les artefacts de ces tâches se consultent dans « Journal des tâches » de la console ; le traitement est similaire à celui des tâches vidéo : enregistrez l'ID de tâche après création, interrogez jusqu'à un état final via l'interface de consultation, et ne recréez pas la tâche.

Facturation

Le mode de facturation de l'interface audio dépend des détails du modèle sur la place de marché des modèles ; il peut être facturé au token, à l'appel ou à la durée. Pour les règles de facturation et de règlement, voir Facturation et relevés.

Interface de synthèse vocale

Interface de synthèse vocale

Requête

Paramètres de requête

Réponse

Succès

Échec

Recommandations d'intégration côté serveur

Tâches audio asynchrones

Facturation

Documentation associée

Sur cette page