Comment appeler l'API mirelo-sfx-2.0 via HiAPI : curl, Python et interrogation asynchrone

Fonctionnalités et cas d'usage de mirelo-sfx-2.0

mirelo-sfx-2.0 est un modèle de texte-vers-effets sonores accessible via HiAPI. Vous lui fournissez une description en langage naturel — par exemple « une lourde porte en bois qui grince lentement en s'ouvrant » ou « une pièce qui tombe sur une table en marbre » — et il génère un court extrait audio correspondant à votre prompt.

C'est le point de terminaison à utiliser lorsque vous avez besoin de sound design généré à la demande, plutôt que de sons sous licence issus d'une bibliothèque d'échantillons :

• Prototypage de jeux et d'applications : générez des sons provisoires ou définitifs pour les interactions, les événements d'interface et les boucles d'ambiance.
• Post-production vidéo et podcast : comblez vos lacunes avec des audio de style foley sans réserver de studio d'enregistrement.
• Pipelines génératifs : récupérez des prompts à partir de scripts, de storyboards ou de saisies utilisateur, puis joignez le WAV généré à votre sortie.

Le modèle donne les meilleurs résultats lorsque la description sonore est claire et la durée courte. Si vous avez besoin de musique, de voix ou d'audio long, cela relève d'une autre famille de modèles — mirelo-sfx-2.0 se concentre sur les effets sonores discrets.

La génération étant asynchrone, planifiez votre intégration autour de tâches plutôt que d'appels HTTP bloquants. Le reste de ce tutoriel construit cette intégration, de la requête curl brute jusqu'au client Python qui interroge le service pour récupérer le WAV final.

Prérequis et configuration de l'authentification

Avant votre premier appel, assurez-vous de disposer de :

• Un compte HiAPI et une clé d'API. Vous pouvez créer et gérer vos clés dans la console HiAPI. Traitez votre clé comme un mot de passe : chargez-la depuis une variable d'environnement ou un gestionnaire de secrets, et ne la committez jamais dans un dépôt de code.
• Un outil pour envoyer des requêtes HTTP. curl suffit pour cette démonstration ; les exemples de code utilisent Python 3.8+.
• Un client HTTP en Python. Les exemples utilisent requests par souci de concision, mais n'importe quel client capable d'envoyer du JSON et des en-têtes fera l'affaire.

HiAPI utilise une URL de base unique et un mode d'authentification unique pour tous les modèles, de sorte que les conventions apprises ici s'appliquent également aux autres points de terminaison :

export HIAPI_API_KEY="your-api-key-here"

Chaque requête envoie la clé dans l'en-tête Authorization :

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

L'identifiant du modèle est transmis dans le corps de la requête via "model": "mirelo-sfx-2.0". Aucun SDK séparé à installer — tant que votre client HTTP peut atteindre l'URL de base de HiAPI, vous pouvez appeler le modèle.

Un conseil pratique : stockez l'URL de base dans une variable de configuration plutôt que de la coder en dur dans chaque fichier. Lorsque vous passerez d'un script local à un service de préproduction ou de production, vous voudrez la modifier à un seul endroit.

Décomposition pas à pas de la requête curl

La requête de génération est un POST HTTP authentifié envoyé au point de terminaison de création de tâches de HiAPI. Voici l'appel complet :

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "heavy wooden door creaking open slowly, old house ambience"
    }
  }'

Décomposons chaque partie :

• -X POST — la création de tâche est une opération d'écriture. Un GET sur ce chemin ne lancera pas de tâche.
• L'URL — ce point de terminaison accepte les nouvelles tâches de génération. L'URL de base est stockée dans HIAPI_BASE_URL, de sorte que la même commande fonctionne dans n'importe quel environnement.
• Authorization — le jeton bearer identifie votre compte et sert de base à la facturation. Un en-tête manquant ou mal formé est la cause la plus fréquente d'une réponse 401.
• Content-Type: application/json — le corps de la requête est du JSON ; sans cet en-tête, le serveur rejettera ou interprétera mal la charge utile.
• model — sélectionne mirelo-sfx-2.0. Comme HiAPI effectue le routage à partir de ce champ, vous pouvez changer de modèle sans modifier l'URL.
• input.prompt — la description textuelle du son. Des descriptions concrètes et physiques (matériau, action, environnement) produisent de meilleurs résultats que des descriptions abstraites.

Une soumission réussie ne renvoie pas l'audio. Elle renvoie un objet tâche contenant un identifiant (généralement le champ id) que vous utilisez pour vérifier l'état. Récupérez cet ID dans la réponse ; c'est votre clé pour récupérer le WAV par la suite.

Si vous souhaitez confirmer la structure de la requête avant d'écrire du code, exécutez d'abord cette commande exacte dans votre terminal. Une fois qu'elle fonctionne, la conversion en Python devient mécanique.

Le même appel en Python

La version Python conserve la même URL, les mêmes en-têtes et le même corps — simplement représentés sous forme de dictionnaires et d'appels client :

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

Les différences avec la version shell :

• Accès aux variables d'environnement — os.environ remplace l'expansion du shell, de sorte que la clé n'apparaît jamais dans le code source.
• json= au lieu de -d — requests sérialise le dictionnaire et définit le type de contenu à votre place. Vous pouvez supprimer les en-têtes manuels, même s'il n'est pas gênant de les conserver.
• raise_for_status() — transforme les réponses non 2xx en exceptions ; c'est là que doit se situer la gestion des erreurs.
• timeout — un délai d'expiration côté client évite qu'une connexion bloquée ne suspende votre processus de travail. La création de tâche est rapide ; les longues attentes se produisent pendant l'interrogation.

La valeur de retour est l'ID de tâche. Conservez-le — c'est votre unique référence pour cette génération. À ce stade, le chemin Python et le chemin curl convergent : les deux nécessitent une étape d'interrogation avant que l'audio n'existe.

Comme le corps de la requête n'est que des données, vous pouvez paramétrer le prompt et parcourir une liste de descriptions pour générer des effets sonores en lot, en créant une tâche par prompt et en collectant les ID.

Gérer les tâches asynchrones et interroger les résultats

La génération sonore prend du temps — des secondes, pas des millisecondes — c'est pourquoi HiAPI la modélise sous forme de tâche. L'appel de création renvoie immédiatement un ID ; un second point de terminaison indique si cette tâche est toujours en cours, terminée ou échouée.

La boucle typique est la suivante :

1. Créer la tâche et récupérer l'ID.
2. Interroger le point de terminaison d'état de la tâche avec cet ID.
3. Si l'état est toujours en cours de traitement, attendre brièvement puis interroger à nouveau.
4. Lorsque l'état signale un succès, lire la sortie dans la réponse.
5. Si l'état signale un échec, arrêter et lever une erreur.

En Python :

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

Quelques points méritent d'être soulignés :

• Intervalle d'interrogation. Deux secondes est une valeur par défaut raisonnable pour des effets sonores. Une boucle serrée gaspille du quota et peut déclencher des limites de débit sans accélérer le résultat.
• Échéance globale. Fixez toujours une limite supérieure à la boucle. Une tâche bloquée doit faire échouer votre job plutôt que suspendre indéfiniment le processus de travail.
• Valeurs d'état. Traitez les valeurs d'état inconnues comme « toujours en cours » plutôt que de supposer un succès, et branchez explicitement sur les états de succès et d'échec.
• Webhooks (si disponibles). Si votre compte HiAPI prend en charge les callbacks de fin, privilégiez-les à l'interrogation dans le code de production côté serveur ; pour les scripts et les prototypes, l'interrogation reste l'option la plus simple.

Conservez l'ID de tâche avec le prompt dans votre propre base de données, afin de pouvoir réessayer, auditer ou récupérer à nouveau la sortie plus tard sans régénérer.

Lire la réponse WAV renvoyée

Lorsqu'une tâche signale un succès, la réponse contient l'audio généré. Selon la version du point de terminaison, la sortie peut prendre la forme d'une URL de fichier WAV ou de données audio inline ; considérez les deux cas comme « des octets stockables ».

Un objet tâche réussi porte sa sortie dans un champ tel que output, généralement accompagné de métadonnées comme le nom du modèle, le prompt d'origine et des informations temporelles. L'audio lui-même est un conteneur WAV standard, ce qui signifie que vous pouvez le confier à n'importe quelle bibliothèque audio sans décodeur personnalisé.

Pour persister un résultat fourni sous forme d'URL :

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Si l'audio arrive sous forme de données encodées, décodez-le en base64 avant de l'écrire :

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Une fois les octets en main :

• Vérifiez l'en-tête. Les fichiers WAV commencent par la signature magique RIFF. Vérifier les quatre premiers octets permet d'intercepter un téléchargement tronqué avant qu'il n'atteigne le stockage.
• Stockez durablement. Écrivez dans un stockage objet et conservez la clé dans votre base de données avec l'ID de tâche. Traitez l'audio généré comme un artefact cacheable, et non comme une réponse éphémère.
• Lisez ou traitez. Les outils standard — wave, soundfile ou n'importe quel lecteur audio — ouvrent le fichier directement. Vous pouvez ensuite découper le silence, normaliser le volume ou convertir vers un autre format pour la livraison.

Comme le fichier est un WAV ordinaire, son intégration dans un point de terminaison web ou un pipeline d'assets de moteur de jeu ne nécessite aucun traitement particulier.

Points de défaillance courants et comment les corriger

La plupart des problèmes d'intégration se rangent dans quelques catégories prévisibles.

Erreurs d'authentification (401 / 403)

401 signifie presque toujours que l'en-tête Authorization est manquant, mal formé ou construit à partir d'une variable d'environnement vide. Vérifiez que HIAPI_API_KEY est exportée dans le shell où s'exécute le processus — pas seulement dans votre éditeur — et que l'en-tête se lit Bearer <key>, avec un seul espace. 403 signifie généralement que la clé est valide mais n'a pas accès à ce modèle ; vérifiez les autorisations de modèle de votre compte.

Charge utile mal formée (400 / 422)

La cause la plus fréquente est un corps de requête qui n'est pas du JSON valide — un déséquilibre de guillemets dans la commande curl en est l'exemple typique. Validez avec un inspecteur JSON avant d'envoyer. La deuxième cause la plus fréquente est un champ model manquant ou un mauvais niveau d'imbrication du prompt ; le modèle attend input.prompt, pas un prompt de premier niveau. Enfin, vérifiez que le prompt n'est pas vide et que sa longueur respecte les limites définies dans la documentation du modèle.

Interrogation trop fréquente

Une boucle while serrée sans sommeil génère un grand nombre de requêtes d'état, peut déclencher des limites de débit et ralentit la tâche que vous attendez. Utilisez un intervalle fixe d'une à deux secondes, ajoutez de la gigue lorsque plusieurs jobs s'exécutent en parallèle, et imposez toujours une durée d'attente maximale.

Confondre création et achèvement

La réponse de création ressemble à un succès et renvoie 200, mais ne contient pas l'audio. Si votre code lit immédiatement le champ output, il échouera ou écrira un fichier vide. Passez toujours par le point de terminaison d'état avant de toucher au résultat.

Délais d'expiration silencieux et nouvelles tentatives

Réessayer après un délai réseau lors de la création de tâche est sans danger, mais réessayer l'appel de création après un délai alors qu'il avait en réalité réussi produit une tâche en double. Si le point de terminaison prend en charge les clés d'idempotence, utilisez-les ; sinon, listez les tâches récentes avant de réessayer pour vérifier.

Cas limites de disque et de stockage

Lors de l'écriture des octets WAV, ouvrez le fichier en mode binaire ("wb"). Le mode texte corromprait l'en-tête. Si vous nommez les sorties d'après le prompt, deux tâches avec le même prompt s'écraseront mutuellement — utilisez l'ID de tâche comme clé de fichier.

Avec ces garde-fous, l'intégration de mirelo-sfx-2.0 se résume à un court pipeline : créer, interroger, persister. Commencez par l'appel curl, portez-le en Python, et considérez l'ID de tâche comme votre source de vérité.