Comment appeler muse-image-1.0/text-to-image via l'API HiAPI : curl et Python

Ce que cette intégration implique réellement

Sur HiAPI, un appel texte-vers-image est une simple requête HTTP synchrone : vous envoyez un corps JSON décrivant l'image souhaitée, et la réponse contient les données de l'image générée. Ce point de terminaison n'a ni boucle de polling ni file de tâches à gérer — une requête, une réponse.

Peu de composants sont impliqués :

• Votre clé API — authentifie la requête via l'en-tête Authorization.
• Le point de terminaison — un chemin d'URL fixe muse-image-1.0/text-to-image sur l'URL de base HiAPI.
• Le corps JSON — transporte votre prompt ainsi que tout paramètre optionnel accepté par le modèle.
• La charge utile de réponse — renvoie les données de l'image générée, que vous décodez ou transmettez.

C'est toute la surface d'interface. Les sections ci-dessous construisent la requête morceau par morceau avec curl, puis répètent le même processus en Python, afin que vous puissiez valider chaque partie avant d'ajouter de la complexité.

Prérequis et authentification

Avant d'envoyer votre première requête, assurez-vous de disposer de :

1. Une clé API, disponible depuis le tableau de bord de votre compte HiAPI. Traitez-la comme un mot de passe ; ne la committez jamais dans un système de contrôle de source.
2. Un client HTTP — curl suffit pour les tests ; l'environnement cible de la version script est Python 3.8+.
3. L'URL de base de l'API HiAPI, que vous trouverez dans la documentation du tableau de bord, avec la clé.

L'authentification utilise un jeton Bearer dans l'en-tête Authorization. Chaque requête vers muse-image-1.0/text-to-image en a besoin :

Authorization: Bearer $HIAPI_API_KEY

Stockez la clé dans une variable d'environnement plutôt que de la coder en dur dans le script :

export HIAPI_API_KEY="your-key-here"

Le chemin du point de terminaison de ce modèle est /muse-image-1.0/text-to-image, ajouté à l'URL de base. L'URL de base exacte est documentée dans votre tableau de bord HiAPI ; conservez-la également dans une variable d'environnement, ainsi vous pourrez changer d'environnement sans modifier le code :

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

Une fois ces deux variables définies, vous pouvez envoyer la requête.

Une requête curl fonctionnelle

Voici un appel muse-image-1.0/text-to-image minimal. Il envoie un prompt et écrit la réponse JSON brute dans un fichier, afin que vous puissiez l'inspecter avant d'écrire le moindre code de parsing.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

Quelques points à noter concernant le corps de la requête :

• prompt est obligatoire — c'est la description textuelle que le modèle rend.
• n est facultatif et contrôle le nombre d'images demandées. Si vous l'omettez, la valeur par défaut s'applique.
• N'incluez que les paramètres que vous avez confirmés pour ce modèle dans la documentation de référence de l'API HiAPI. Ne devinez pas de champs non documentés ; les paramètres inconnus peuvent être rejetés par la validation du serveur ou silencieusement ignorés.

Si la requête réussit, response.json contient les données de l'image. En cas d'échec, vous recevez un corps de réponse d'erreur et un code de statut non 2xx — voir la section sur la gestion des erreurs ci-dessous.

Vous pouvez vérifier le code de statut HTTP sans afficher tout le corps de la réponse :

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

Implémenter la même requête en Python

La version Python utilise requests et est identique à l'appel curl — même point de terminaison, mêmes en-têtes, même corps de requête. Extrayez-la dans une fonction réutilisable.

import os
import requests

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

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

Deux détails méritent d'être conservés :

• timeout=60 — définissez un délai d'expiration explicite. La génération d'images est plus lente qu'un appel d'API JSON classique ; sans délai d'expiration, votre processus risque de rester bloqué indéfiniment si la connexion stagne.
• raise_for_status() — expose les erreurs HTTP sous forme d'exceptions, plutôt que de vous laisser parser silencieusement un corps de réponse d'erreur comme s'il s'agissait d'une image.

Si vous utilisez déjà httpx ou aiohttp, la conversion est directe : mêmes en-têtes, même corps JSON. Cette requête ne dépend d'aucune bibliothèque HTTP particulière.

Lire la réponse synchrone

Comme muse-image-1.0/text-to-image est synchrone, les données de l'image arrivent dans la même réponse — aucun second appel n'est nécessaire pour récupérer le résultat. La réponse est en JSON ; inspectez sa structure une fois avant d'écrire votre parseur :

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

La manière de traiter l'image dépend de ce que contient la réponse :

Si la réponse contient des données d'image base64

Décodez la chaîne et écrivez les octets dans un fichier :

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

Si la réponse contient une URL

Téléchargez-la avec un simple GET — l'URL est déjà autorisée pour la récupération, donc n'ajoutez pas la clé API à un hôte tiers :

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Les noms de champs exacts — b64_json contre url, ainsi que la structure englobante qui les contient — sont définis dans la documentation de référence de l'API HiAPI de ce modèle. Affichez la réponse une fois pour confirmer la structure, puis écrivez le code en conséquence. Ne supposez pas que la structure est la même d'un modèle à l'autre.

En service, n'écrivez pas aveuglément sur le disque local : diffusez les octets en streaming vers un stockage objet, ou transmettez-les directement là où l'image est consommée (étape d'upload, file d'attente, réponse à votre propre client). Avant de transmettre, vérifiez que les octets décodés ressemblent bien à une image (contrôle des octets magiques).

Gérer les codes d'erreur et les tentatives

HiAPI renvoie les codes de statut HTTP standard. Une règle de tri utile : si je renvoie la même requête sans la modifier, réussira-t-elle ?

Corriger la requête — ne pas réessayer

• 400 Bad Request — JSON mal formé ou paramètre non accepté par le modèle. Vérifiez que prompt est présent et que vous n'avez pas inventé de champs. Corrigez le corps de la requête ; réessayer tel quel échouera de la même manière.
• 401 Unauthorized — clé API manquante ou invalide. Vérifiez que HIAPI_API_KEY est définie et n'a pas été renouvelée.
• 403 Forbidden — la clé est valide mais n'a pas accès à ce point de terminaison. Vérifiez les droits d'accès de votre compte dans le tableau de bord.
• 404 Not Found — chemin incorrect. Confirmez que la chaîne du point de terminaison est exactement /muse-image-1.0/text-to-image et que l'URL de base est correcte.
• 422 Unprocessable Entity — JSON bien formé mais sémantiquement invalide, par exemple une valeur hors limites. Lisez le message d'erreur ; il indique généralement le nom du champ.

Réessayer avec backoff

• 429 Too Many Requests — vous êtes limité en débit. Appliquez un backoff exponentiel et réessayez ; si un en-tête Retry-After est présent, respectez-le.
• Erreurs 5xx — défaillance côté serveur. Réessayez avec un backoff exponentiel et une limite (par exemple trois tentatives), puis abandonnez et exposez l'erreur.

Une boucle de réessai compacte :

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

En cas d'échec, journalisez toujours le code de statut et le corps de la réponse d'erreur. Le message contenu dans le corps vous indiquera à laquelle des deux catégories appartient l'erreur donnée.

Checklist de production avant publication

Quelques habitudes rendent les appels à muse-image-1.0/text-to-image prévisibles, même une fois sortis de votre machine locale :

• Figez la structure de la requête. Validez le corps JSON par rapport aux champs documentés dans la référence de l'API. Si vous ajoutez un paramètre, confirmez d'abord qu'il est pris en charge.
• Définissez des délais d'expiration partout. Les appels de génération et tout téléchargement des données d'image renvoyées nécessitent un délai d'expiration explicite.
• Distinguez les catégories d'erreurs. Séparez les échecs réessayables (429, 5xx) des échecs définitifs (400, 401, 403, 404, 422), afin que vos alertes ne soient pas bruyantes et que les réessais ne soient pas gaspillés.
• Journalisez les informations clés. Si la réponse fournit un identifiant de requête, journalisez-le, ainsi que le code de statut, la latence et la longueur du prompt — mais pas le prompt lui-même si celui-ci peut contenir du texte sensible.
• Surveillez les facteurs de coût. La génération est facturée à la sortie — le nombre d'images, la taille et la fréquence de vos réessais influent sur le coût. Évitez de réessayer les erreurs définitives, et évitez de régénérer lorsque la mise en cache des résultats est viable.
• Gardez la clé côté serveur. N'incorporez jamais la clé API dans un navigateur ou un client mobile pour appeler directement le point de terminaison.

Avec cela, l'intégration devient une petite fonction banale que vous pouvez appeler depuis n'importe où — exactement ce que vous voulez. Pour la surface complète des paramètres et les champs de réponse actuels, consultez la documentation de référence de l'API HiAPI de ce modèle.