Comment utiliser lyria-3-pro via l'API hiapi : curl, Python et exemples de requêtes exécutables

lyria-3-pro est un modèle de génération musicale disponible via l'API hiapi : envoyez une invite textuelle et obtenez une piste audio complète. Ce guide vous fait parcourir le flux de requête qui renvoie réellement un taskId, décrit le schéma d'entrée complet (très court), ainsi que les détails de production nécessaires une fois passé le test ponctuel.

Ce dont vous avez besoin

• Une clé API hiapi. Obtenez-la depuis la console — la clé commence par sk-.
• curl ou requests en Python. Aucun SDK n'est nécessaire ; hiapi utilise du REST standard.

lyria-3-pro s'exécute sur l'API unifiée de tâches asynchrones de hiapi : vous POSTez une tâche, recevez immédiatement un taskId, puis interrogez le résultat ou recevez un rappel lorsque la piste est prête.

Exemple minimal exécutable

1. Créer une 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-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

Une réponse normale revient immédiatement, avant que la piste ne soit réellement rendue :

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

2. Interroger le résultat

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -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 par des états intermédiaires comme archiving, puis atteint un état terminal :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

Téléchargez output[0].url dès que possible — le niveau de stockage temp par défaut expire au bout d'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. La même requête 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-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

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

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

Schéma d'entrée complet

input accepte exactement deux champs — tout ce qui sort de cette liste est rejeté avec un 400 INVALID_REQUEST :

Champ	Type	Obligatoire	Description
prompt	string	Oui	Décrivez le genre, l'orchestration, l'ambiance et le tempo — plus c'est précis, plus les résultats sont cohérents.
seed	integer	Non	Valeur minimale 0. Réutilisez la même seed avec la même invite pour obtenir des résultats plus reproductibles.

prompt est obligatoire — si vous l'omettez, la tâche n'est même pas créée :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Envoyez n'importe quel autre champ — duration, negative_prompt, sample_count ou des champs similaires acceptés par certains autres modèles musicaux — et la requête est directement rejetée :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

La durée de la piste générée est fixée par le modèle lui-même ; aucun paramètre duration n'est disponible pour la configurer.

Considérations de production

Les rappels valent mieux que l'interrogation répétée. Au-delà des tests rapides, passez un callback de niveau supérieur plutôt que d'interroger en boucle :

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

Lorsque la tâche atteint un état terminal (success ou fail), hiapi envoie un POST unique à callback.url — inutile de maintenir une boucle d'interrogation active. Conservez néanmoins l'interrogation comme filet de sécurité, au cas où la livraison du rappel échouerait.

Idempotence. Si l'appelant peut réessayer la même requête, envoyez l'en-tête Idempotency-Key (255 octets maximum) — un nouvel essai avec la même clé sur le même compte renvoie le taskId d'origine au lieu de créer (et facturer) une piste en double.

Conserver les sorties plus de 7 jours. Le stockage des sorties est par défaut temp (environ 7 jours). Définissez "storage": "persistent" au niveau supérieur lors de la création pour conserver les pistes à long terme (facturé à la taille), ou promouvez plus tard les sorties temp.

Gestion des erreurs. Une clé erronée ou non autorisée renvoie un HTTP 401 :

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

Une entrée mal formée renvoie 400 avec error_code: INVALID_REQUEST (comme montré ci-dessus) ; un solde insuffisant renvoie 402 ; un Content-Type non JSON renvoie 415. Si vous rencontrez des 503 intermittents, réessayez avec un backoff — cela indique que la plateforme est temporairement indisponible, et non que votre requête est erronée.

Le prix de lyria-3-pro (ainsi que de tous les autres modèles de la plateforme) est indiqué sur la page de tarification hiapi, et non codé en dur ici, car les paliers peuvent évoluer.

Ressources associées

• Référence du modèle lyria-3-pro — tarification et aire de jeu de ce modèle.
• Créer une tâche / Obtenir le détail d'une tâche (API asynchrone unifiée) — le contrat requête/réponse partagé par tous les modèles sur hiapi.
• API minimax-music-3 : guide curl et Python — un autre modèle texte-vers-musique, utile pour comparer les styles de sortie.
• Comment utiliser l'API MiniMax Music (minimax-music-1.5) — un modèle de génération musicale MiniMax plus ancien, adapté aux comparaisons coût/qualité.

Questions fréquentes

Peut-on définir la durée de la piste générée ? Non. Le schéma input de lyria-3-pro n'accepte que prompt et seed — il n'y a pas de champ duration, la durée de la piste est déterminée par le modèle lui-même.

lyria-3-pro prend-il en charge les invites négatives ou l'audio de référence de style ? Non. Contrairement à certains autres modèles de la plateforme, le schéma de lyria-3-pro est strictement limité à prompt et seed ; envoyer negative_prompt ou tout champ d'audio de référence renvoie 400 INVALID_REQUEST.

Quel est le format du fichier de sortie ? MP3, renvoyé dans output[0].url, avec un type valant "audio". Cette URL est un lien temporaire qui expire selon output[0].expireAt, sauf si vous définissez "storage": "persistent".

Comment obtenir des résultats reproductibles ? Utilisez la même prompt et passez la même seed (entier non négatif). Si vous omettez seed, chaque appel peut produire un résultat différent.

Quel est le moyen le plus rapide de déboguer une requête qui renvoie systématiquement 400 ? Lisez le message — il indique le champ précis manquant ou invalide. Le schéma est strict : envoyer des champs que ce modèle n'accepte pas (par exemple duration, que d'autres modèles musicaux de la plateforme acceptent effectivement) renvoie 400 avec une erreur "additional properties not allowed".