Comment utiliser lyria-3.5 via l'API hiapi : curl, Python et une requête qui fonctionne

lyria-3.5 est le modèle de génération de musique à partir de texte de hiapi : envoyez une description musicale, des paroles, ou les deux, et vous obtenez une piste finie — avec en option un titre, une indication de tempo et un contrôle de durée. Ce guide détaille le schéma d'entrée complet, une requête qui renvoie une vraie piste, et les détails nécessaires pour passer d'un simple test à la production.

Ce dont vous avez besoin

• Une clé API hiapi. Obtenez-la depuis le dashboard — la clé commence par sk-.
• curl ou le module Python requests. Aucun SDK nécessaire ; hiapi utilise du REST pur.

lyria-3.5 s'exécute sur l'API unifiée de tâches asynchrones de hiapi : vous soumettez une tâche avec POST, récupérez immédiatement un taskId, puis interrogez le résultat ou recevez un callback lorsque la piste est prête.

Schéma d'entrée complet

lyria-3.5 accepte bien plus qu'un simple prompt. Tous les champs sont facultatifs, sauf que vous devez fournir au moins prompt ou lyrics :

Champ	Type	Description
prompt	string	Genre, instruments, ambiance, voix, structure du morceau. Fournissez prompt ou lyrics.
lyrics	string	Une phrase par ligne. Les balises de section — [Intro], [Verse], [Chorus], [Bridge], [Outro] — occupent chacune une ligne, suivies des paroles. Numérotez les sections répétées avec [Verse 1], [Verse 2].
title	string	Titre de la chanson générée.
bpm	string	Indication de tempo, doit être une chaîne numérique, par exemple "90".
length	integer	Durée demandée en secondes, 1–240. Sert à guider la longueur ; la durée réelle peut différer. Omettre pour ne pas la spécifier.
seed	string	Graine sous forme de chaîne numérique, par exemple "00123". Même avec une graine identique, obtenir exactement le même audio n'est pas garanti.

Deux points à garder en tête : bpm et seed sont des chaînes et non des nombres — envoyez "90", pas 90, sinon l'API renvoie un 400 (got number, want string). Et le schéma est strict : tout champ absent du tableau ci-dessus (duration, style, genre, negative_prompt, etc.) renvoie un 400 avec additional properties '...' not allowed.

Exemple minimal qui fonctionne

1. Créer la tâche

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

Une réponse réussie revient immédiatement, avant même que la piste ne soit réellement rendue :

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" }
}

2. Interroger le résultat

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Attendez quelques secondes avant la première interrogation, puis vérifiez toutes les 3 à 5 secondes. Le status passe d'abord par handling, puis atteint son état final. Voici la réponse réelle de la requête ci-dessus au bout d'environ 100 secondes :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

Notez que le format conteneur de la sortie peut varier selon la requête (ici .m4a ; d'autres modèles musicaux sur hiapi renvoient du .mp3) — lisez output[0].type/l'URL plutôt que de coder une extension en dur. Téléchargez output[0].url rapidement : le niveau de stockage temp par défaut expire après environ 7 jours (expireAt est un horodatage Unix). En cas d'échec, status vaut fail et data.error contient { code, message } au lieu de output.

3. Requête pilotée par les paroles en Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "lyria-3.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

Selon que vous voulez une piste instrumentale pure ou une piste chantée, remplacez lyrics par prompt (ou envoyez les deux).

Considérations pour la production

• Utilisez des callbacks plutôt que l'interrogation répétée. Ajoutez un objet callback de premier niveau : {"url": "https://yourapp.com/hook", "when": "final"}. when n'accepte que "final" — vous recevez un appel lorsque la tâche atteint son état final, et non des mises à jour de progression.
• Idempotence. L'API de tâches n'accepte pas de clé d'idempotence fournie par le client ; protégez-vous donc des problèmes de nouvelle tentative au niveau applicatif : persistez le taskId dès que vous le recevez et vérifiez l'état de la tâche avant de réessayer, afin d'éviter les requêtes en double.
• Erreurs. Une clé API absente ou invalide renvoie HTTP 401 et error_code: "permission_denied". Une violation du schéma renvoie HTTP 400 et error_code: "INVALID_REQUEST", avec le champ responsable indiqué dans le message — utile pour repérer avant la mise en production un duration superflu ou un bpm de type numérique.
• Stockage. Après une interrogation réussie ou la réception d'un callback, transférez immédiatement output[0].url vers votre propre stockage ; ne comptez pas sur le niveau temp au-delà de son expireAt.

Lectures associées

• Tutoriel sur l'API lyria-3-pro — un autre modèle Lyria de hiapi, au schéma plus simple (prompt uniquement) si vous n'avez pas besoin de paroles ni de contrôle du tempo.
• Guide de l'API MiniMax Music — un autre modèle de génération de musique à partir de texte sur hiapi, avec son propre ensemble d'options de paroles et d'échantillonnage.
• Référence du modèle lyria-3.5 — la documentation officielle des paramètres.
• Tarifs hiapi — les tarifs actuels de chaque modèle.

FAQ

Dois-je envoyer à la fois prompt et lyrics ? Non — l'API exige seulement au moins l'un des deux. Envoyez uniquement prompt pour obtenir une piste instrumentale, uniquement lyrics pour une piste entièrement pilotée par les paroles, ou les deux ensemble.

Quel format audio lyria-3.5 renvoie-t-il ? Cela varie selon la requête — vérifiez output[0].type et l'extension de l'URL, ne supposez ni .mp3 ni .m4a.

Puis-je imposer un tempo exact ? bpm est une indication, pas une contrainte stricte, et doit être envoyé sous forme de chaîne ("90", pas 90).

Quelle est la longueur maximale d'une piste générée ? length accepte de 1 à 240 secondes, mais ne fait que guider le modèle sans garantir une durée exacte — vérifiez la durée réelle du fichier renvoyé.

Le même seed me donnera-t-il deux fois la même piste ? Non. seed est une chaîne numérique qui permet d'affiner la génération, mais la documentation de hiapi précise explicitement que l'audio identique n'est pas garanti.

Que se passe-t-il si j'envoie un champ non reconnu, comme genre ou duration ? Le schéma est strict — vous recevez un 400 et additional properties '<field>' not allowed, et non un champ silencieusement ignoré.