API ElevenLabs Music sur HiAPI : générer de la musique avec curl, Python et des recettes de prompts

Pourquoi appeler elevenlabs/music-v2.5 via HiAPI

Si vous devez ajouter la génération musicale à un produit, le chemin le plus rapide n'est souvent pas le plus propre. Brancher votre backend directement sur un fournisseur de modèle signifie que vous prenez en charge la configuration du compte, le schéma d'authentification, la sémantique des nouvelles tentatives et la structure des requêtes de ce fournisseur. Chaque nouveau modèle ajoute un nouvel ensemble de ces décisions, et chaque expérimentation laisse derrière elle une branche d'intégration.

Appeler elevenlabs/music-v2.5 via HiAPI change la forme de ce travail. Il vous faut une seule URL de base, un seul en-tête d'authentification et une convention de requête qui reste stable lorsque vous passez d'un modèle à l'autre. L'identifiant du modèle (elevenlabs/music-v2.5) n'est qu'une chaîne dans le corps de la requête : basculer entre modèles musicaux, ou tester un second modèle à des fins de comparaison, ne demande qu'une modification d'une ligne, sans importer un nouveau SDK.

Pour les développeurs qui choisissent un mode d'intégration, trois avantages concrets méritent l'attention :

• Un point unique de gestion des identifiants. La gestion des clés, la rotation et l'isolation des environnements (développement/préproduction/production) sont centralisées en un seul endroit, au lieu de se multiplier par fournisseur.
• Un schéma de requête portable. Les extraits curl et Python ci-dessous sont cohérents avec ce que vous utilisez pour d'autres modèles sur HiAPI. Apprendre le schéma une seule fois suffit.
• Une consommation regroupée au même endroit. La génération musicale est facturée à la durée de sortie ; la regrouper avec l'usage des autres modèles permet de suivre les coûts dans un seul tableau de bord plutôt que face à des factures éparpillées.

Le coût est de traverser une couche d'abstraction, de sorte que les particularités propres au fournisseur sont normalisées. Pour une première intégration et la plupart des cas d'usage en production, cette normalisation est précisément ce que vous voulez. Lorsque vous avez besoin de comprendre le comportement précis du modèle, la page de détails sur le site fait autorité.

Préparer le terrain avant la première requête musicale

Vérifiez quatre choses avant d'écrire du code, afin que le premier appel renvoie de l'audio plutôt qu'une erreur 401 ou une erreur de validation.

1. La clé API

Vous avez besoin d'une clé API obtenue depuis votre compte HiAPI. Traitez-la comme n'importe quelle autre clé : conservez-la dans une variable d'environnement, ne la validez jamais dans le code source, et utilisez des clés distinctes pour le développement local et la production, afin de pouvoir révoquer l'une sans affecter l'autre.

export HIAPI_API_KEY="your_key_here"

2. L'URL de base et la convention de point de terminaison

Tous les appels de modèle passent par la même URL de base, et le modèle est identifié à l'intérieur de la requête, non dans le chemin. Conservez une constante pour l'URL de base dans votre projet, afin de ne modifier qu'un seul endroit si votre environnement diffère.

3. Un prompt rédigé en langage naturel

elevenlabs/music-v2.5 accepte un prompt textuel décrivant la musique que vous souhaitez. Vous n'avez pas besoin de partition ni de fichier MIDI. Une ou deux phrases précisant le genre, l'orchestration, l'ambiance et la durée souhaitée suffisent pour commencer. Les sections suivantes fournissent des recettes réutilisables.

4. Des attentes correctes sur la sortie

La génération musicale renvoie de l'audio, et non une partition JSON. Prévoyez la manière de traiter la charge utile de la réponse : écriture dans un fichier en développement, diffusion en continu ou stockage en production. Décidez à l'avance de la durée approximative souhaitée du segment, car la durée influence à la fois la requête et la facturation.

Une dernière chose avant la première requête : consultez le panneau de tarification du site pour connaître les limites de débit et le prix actuels de elevenlabs/music-v2.5, plutôt que de coder en dur des hypothèses. Les prix et les limites évoluent ; votre intégration doit les lire comme de la configuration, non comme des constantes enfouies dans un script.

Lancer le premier appel avec curl

Commencez par curl, car il supprime toutes les couches entre vous et la requête HTTP. Si l'appel curl réussit, toute défaillance dans l'application est un problème de l'application, pas de l'API.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

Voici le rôle de chaque partie :

• -sS garde la sortie de progression silencieuse tout en affichant les erreurs. Utile lorsque vous redirigez la sortie vers un fichier.
• L'URL est le point de terminaison unifié. Notez que le nom du modèle n'apparaît pas dans le chemin, mais dans le corps de la requête.
• Authorization: Bearer $HIAPI_API_KEY lit la clé depuis l'environnement, afin qu'elle ne reste pas en clair dans l'historique du shell. Sous Windows, définissez la variable avec set ou la syntaxe PowerShell $env: selon le cas.
• Content-Type: application/json est obligatoire ; le point de terminaison n'accepte pas l'encodage de formulaire.
• model est l'identifiant exact elevenlabs/music-v2.5. Une faute de frappe ici produit une erreur de modèle introuvable plutôt qu'un échec générique, ce qui aide au débogage.
• messages transmet votre prompt comme contenu d'un message utilisateur. Placez le prompt dans un seul message ; les prompts longs et structurés fonctionnent mieux que s'ils sont répartis sur plusieurs messages.

Le corps de la réponse contient l'audio généré ainsi que des métadonnées sur la requête. En développement, redirigez la sortie vers un fichier afin de pouvoir écouter le résultat immédiatement :

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

Placer la charge utile dans request.json et la lire avec -d @request.json est une habitude à prendre tôt. Elle rend les requêtes comparables, vérifiables et faciles à rejouer lorsqu'on modifie un seul paramètre à la fois.

Reproduire l'appel en Python

Une fois que l'appel curl renvoie de l'audio, portez-le en Python. L'objectif n'est pas seulement un script qui fonctionne, mais une fonction appelable depuis une file de tâches, un gestionnaire d'API ou un notebook, sans dérives de copier-coller.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """Envoie un prompt musical à elevenlabs/music-v2.5 via HiAPI."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

À mesure que la fonction grandit, quelques décisions méritent d'être conservées :

• Privilégier la bibliothèque standard. urllib évite les variations de dépendances dans le tutoriel. Si votre projet utilise déjà requests ou httpx, la conversion est mécanique : passez json=payload, headers=headers et timeout.
• Le délai d'attente est obligatoire. La génération musicale prend plus de temps que les complétions de chat. Fixez un délai explicite, ne dépendez pas des valeurs par défaut. Choisissez une valeur supérieure au temps de génération attendu pour le segment le plus long que vous demandez.
• Lire la clé au moment de l'appel, et non à l'import, afin que le même module fonctionne en local et dans un conteneur où l'environnement est injecté à l'exécution.
• Renvoer des données structurées, et non des chaînes imprimées. C'est à l'appelant de décider s'il écrit l'audio sur disque, le téléverse vers un stockage objet ou le transmet au client.

Avant de construire quoi que ce soit dessus, vérifiez que la fonction Python et l'appel curl produisent des résultats équivalents pour le même prompt. Cette cohérence est votre base de régression.

Recettes de prompts pour le style, l'ambiance et la durée

Les prompts musicaux fonctionnent mieux lorsqu'ils répondent dans l'ordre à trois questions : quel genre et quelle orchestration, quelle tonalité émotionnelle, quelle durée. Un prompt vague produit une sortie générique ; un prompt trop long dilue les descripteurs importants. Visez une phrase dense, ou trois courtes propositions.

Utilisez-les comme points de départ à copier-coller, et n'ajustez qu'une dimension à la fois.

Recettes axées sur le style

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

Recettes axées sur l'ambiance

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

Recettes axées sur la durée

La durée doit figurer dans le prompt comme un objectif explicite, et elle doit être cohérente avec l'arrangement. Une requête de 15 secondes avec une montée lente et une longue coda sera coupée brutalement.

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

Exemple combiné

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

Quand la sortie ne correspond pas aux attentes

N'ajustez qu'une variable à la fois, afin de comprendre ce qui change réellement le résultat.

• Trop générique : remplacez les mots d'ambiance par une orchestration et un tempo précis. « Energetic » est moins efficace que « driving 16th-note bass at 128 BPM ».
• Trop chargé ou confus : retirez explicitement des instruments (no drums, no vocals, sparse arrangement) plutôt que d'ajouter d'autres descripteurs positifs.
• Durée qui semble incorrecte : si le segment s'arrête net, demandez une cible plus courte avec une fin explicite ; s'il semble précipité, réduisez le nombre de sections demandées.
• Dérive de style : placez le genre et l'orchestration en tête du prompt. Les tokens du début ont plus de poids.

Conservez dans votre dépôt un petit fichier de prompts qui documente les recettes qui fonctionnent. Ce fichier vaut plus que n'importe quel segment généré isolément, car il transforme l'écriture de prompts en artefact d'ingénierie reproductible.

Erreurs courantes et comment les corriger

La plupart des premières intégrations échouent de quelques manières prévisibles. Parcourez cette liste avant de commencer à deviner.

Échecs d'authentification

Un 401 signifie presque toujours un en-tête mal formé ou une clé absente de l'environnement du processus. Vérifiez s'il y a des espaces parasites après Bearer, si la clé est chargée depuis le mauvais fichier .env, ou si le export a été exécuté dans une autre session que celle qui lance le script. Affichez la longueur de la clé (pas la clé elle-même) pour confirmer qu'elle est bien remplie.

Identifiant de modèle incorrect

Une erreur de modèle introuvable ou de validation signifie généralement que la chaîne model n'est pas une correspondance exacte. elevenlabs/music-v2.5 est sensible à la casse et contient une barre oblique. Si vous le copiez depuis une fenêtre de chat, vérifiez la présence de guillemets typographiques ou de sauts de ligne résiduels.

Corps de requête mal formé

Si curl fonctionne mais pas Python, la différence est presque toujours un problème de sérialisation. Passer directement un dict Python là où une chaîne JSON est attendue, double-encoder avec json.dumps, ou oublier Content-Type: application/json produit des erreurs d'analyse côté serveur qui semblent sans rapport avec la vraie cause. Journalisez le corps exact envoyé par le code et comparez-le caractère par caractère avec la charge utile curl qui fonctionne.

Délais d'attente sur les segments longs

Des durées plus longues demandent des temps de génération plus longs. Un délai d'attente client adapté aux requêtes de chat tronquera les requêtes musicales longues. Augmentez le délai d'attente spécifiquement pour ce point de terminaison, et n'ajoutez des nouvelles tentatives avec backoff que pour les échecs au niveau de la connexion, jamais de manière aveugle sur une requête qui a peut-être déjà été facturée.

Longueur et contenu du prompt

Les prompts extrêmement longs, ou contenant des instructions sur l'API elle-même, produisent souvent une musique de moins bonne qualité. Gardez le prompt centré sur la musique. Si un prompt qui fonctionnait hier ne fonctionne plus, réduisez-le à son squelette style/ambiance/durée, puis reconstruisez-le.

Traiter la réponse comme du texte

Le point de terminaison renvoie des données audio, non une transcription lisible. Écrire le corps brut de la réponse dans un fichier .txt puis se demander pourquoi il ne se lit pas est une erreur courante du premier jour. Enregistrez avec l'extension audio correcte et vérifiez que le fichier s'ouvre dans un lecteur avant d'aller plus loin.

Lorsqu'une erreur reste vraiment obscure, reproduisez-la avec la plus petite requête curl possible. Cela isole si le problème vient du contrat de l'API ou de votre code.

D'un appel de test à un flux de travail reproductible

Un appel de test réussi est un point de départ, pas une intégration. Utilisez cette liste pour en faire quelque chose sur lequel l'équipe peut compter.

• Externalisez la configuration. L'URL de base, l'identifiant du modèle, les délais d'attente et les durées cibles par défaut vont dans la configuration, pas dans des littéraux de chaîne dispersés. Les valeurs propres à l'environnement proviennent de l'environnement.
• Centralisez le client. Une fonction ou une classe cliente légère est responsable des requêtes. Aucun module ne doit construire lui-même des appels HTTP vers le point de terminaison musical, sinon vous divergerez sur les en-têtes et la gestion des erreurs.
• Gérez les erreurs par catégorie. Distinguez authentification, validation, délai d'attente et erreurs serveur. Ne réessayez que les erreurs transitoires, avec backoff et plafond. Ne réessayez jamais une requête qui a peut-être déjà produit une sortie facturée.
• Stockez l'audio correctement. Écrivez dans un stockage objet avec des clés déterministes, rangez le prompt à côté de l'actif généré et consignez l'identifiant du modèle. Reproduire un résultat plus tard dépend de la connaissance exacte de ce qui avait été demandé.
• Suivez la durée comme un paramètre de premier ordre. Comme la facturation suit la durée de sortie, indiquez la durée cible dans le modèle de prompt et consignez-la par requête, afin que les rapports de coûts s'alignent sur l'usage.
• Construisez une bibliothèque de prompts. Versionnez les recettes validées avec une courte note sur l'usage de chacune. Les nouveaux membres de l'équipe partent de prompts qui fonctionnent, plutôt que de deviner.
• Séparez les chemins synchrone et asynchrone. La génération peut être lente. Pour une fonctionnalité destinée aux utilisateurs, soumettez un job, persistez la requête et laissez un worker appeler le modèle. Un gestionnaire HTTP ne doit pas rester ouvert pendant toute la génération.
• Validez par un test de fumée. Un test qui envoie un prompt court fixe et vérifie que la réponse audio a le bon format détecte tôt les dérives d'identifiants et de contrat.

Lorsque vous êtes prêt à approfondir les paramètres et les limites, la page du modèle elevenlabs/music-v2.5 sur HiAPI est l'endroit où vérifier les capacités actuelles avant de coder en dur des hypothèses.