Blog

Tutoriel

Comment appeler minimax-h3-image image-to-image avec curl et Python sur hiapi

Nov 13, 2026
Image de couverture du blog hiapi.ai : composition géométrique abstraite en prismes, divisée en aplats de couleur par de fines lignes diagonales sur un fond vert forêt profond
Sur cette page

Ce qu'attend le point de terminaison image-to-image

Avant d'écrire la moindre ligne de code, il est utile de comprendre la structure d'un appel image-to-image. Le point de terminaison image-to-image de minimax-h3-image reçoit votre ou vos images de référence ainsi qu'une invite textuelle, et renvoie une image nouvellement générée qui suit l'invite tout en restant ancrée sur l'image de référence.

Conceptuellement, chaque requête comporte trois parties :

  • Routage du modèle — vous adressez minimax-h3-image avec la tâche image-to-image, le tout via un unique point de terminaison hiapi. Vous n'avez pas besoin d'identifiants ni d'hôtes distincts pour chaque capacité.
  • Entrée — une chaîne d'invite, une ou plusieurs images de référence (URL ou charge utile base64), ainsi que des contrôles de génération tels que le palier de résolution.
  • Contrat de sortie — l'appel est asynchrone. Vous récupérez un identifiant de tâche, puis interrogez l'état, et récupérez l'URL de l'image générée lorsque la tâche est terminée.

Ce dernier point est important. L'image-to-image n'est pas un appel bloquant qui vous renvoie les pixels dans la même réponse. Considérez l'appel de soumission comme « mettre la tâche en file d'attente », et concevez votre client autour du cycle de vie de la tâche dès le départ. Si vous concevez d'abord pour un comportement synchrone, vous devrez réécrire votre intégration plus tard.

Comme tout transite par la même interface hiapi, les en-têtes, l'authentification et l'enveloppe de réponse restent cohérents entre les modèles et les tâches. Apprenez-le une fois pour minimax-h3-image, et le même schéma s'applique partout ailleurs sur la plateforme.

Une requête minimale exécutable

Commencez par la plus petite requête qui prouve que vos identifiants, votre point de terminaison et la structure de votre charge utile sont corrects. Ne vous précipitez pas pour ajouter tous les champs facultatifs dès le départ.

Le corps de requête minimal contient :

  • le nom du modèle minimax-h3-image
  • le type de tâche image-to-image
  • un prompt décrivant la transformation souhaitée
  • un champ d'image de référence unique
  • un palier de résolution

Conceptuellement, la charge utile ressemble à ceci :

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Transforme ce croquis en un rendu produit propre sur fond blanc",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}

Envoyez-la, vérifiez qu'un identifiant de tâche est renvoyé, puis interrogez manuellement une ou deux fois pour observer les transitions d'état. Si vous obtenez un identifiant de tâche, la connectivité et l'authentification sont bonnes et vous pouvez passer à la construction d'un vrai client. Sinon, arrêtez-vous et lisez le corps de la réponse d'erreur — il indique généralement directement le champ en cause.

Conservez cette requête comme test de fumée. Lorsque de futures modifications casseront votre pipeline, relancer cette requête minimale vous dira immédiatement si le problème vient de votre charge utile ou du code environnant.

Appeler avec curl

curl est le moyen le plus rapide de voir la requête et la réponse brutes. Écrivez le corps JSON dans un fichier, afin de ne pas avoir à vous battre avec les guillemets du shell lors des modifications.

cat > payload.json <<'JSON'
{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Transforme cette photo en illustration à l'aquarelle",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}
JSON

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @payload.json

Deux en-têtes font l'essentiel du travail : Authorization avec le jeton bearer et Content-Type: application/json. Gardez les deux hors du contrôle de version — lisez la clé depuis une variable d'environnement plutôt que de la coller dans la commande.

En cas de soumission réussie, capturez l'identifiant de tâche renvoyé et interrogez-le :

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

La réponse contient un champ d'état et, une fois terminée, un résultat. Utilisez jq pour n'extraire que les champs qui vous intéressent :

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'

C'est aussi la manière la plus simple de déboguer une charge utile : curl montre exactement ce que vous avez envoyé et ce qui a été renvoyé, sans rien masquer par une bibliothèque cliente.

Appeler avec Python

La version Python doit reproduire le flux curl : soumettre, capturer l'identifiant, interroger jusqu'à l'état terminal, récupérer le résultat. Utilisez requests et une Session, afin de ne gérer la réutilisation des connexions et les en-têtes par défaut qu'une seule fois.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

def submit(prompt: str, image: str, resolution: str = "1024") -> str:
    body = {
        "model": "minimax-h3-image",
        "task": "image-to-image",
        "input": {
            "prompt": prompt,
            "image": image,
            "resolution": resolution,
        },
    }
    resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]

def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"La tâche {task_id} ne s'est pas terminée en {timeout} secondes")

if __name__ == "__main__":
    task_id = submit(
        "Transforme cette image en affiche vectorielle plate",
        "https://example.com/reference.png",
    )
    print("Soumis :", task_id)
    result = poll(task_id)
    print(result)

Détails clés : raise_for_status() transforme les erreurs HTTP en exceptions plutôt qu'en échecs silencieux ; la boucle d'interrogation a à la fois une échéance et un intervalle ; l'état terminal est évalué explicitement. Ne parsez l'URL de l'image depuis l'objet de résultat qu'une fois l'état terminal atteint, jamais avant.

Utiliser plusieurs images de référence

Une seule image de référence ne suffit souvent pas. Vous pouvez vouloir conserver le visage d'une photo tout en empruntant la composition d'une autre, ou fusionner une texture et une silhouette. Minimax-h3-image image-to-image prend en charge plusieurs entrées de référence via le champ au pluriel image.

Structurellement, l'objet input peut porter une seule image de référence avec le champ image, et un tableau images lorsque vous en avez plusieurs :

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Conserve la personne de la première image, utilise le style d'arrière-plan de la seconde",
    "images": [
      "https://example.com/person.png",
      "https://example.com/background.png"
    ],
    "resolution": "1024"
  }
}

L'ordre a un sens. L'index de référence 0 est votre sujet principal, les entrées suivantes sont un contexte auxiliaire, donc formulez l'invite en accord avec l'ordre d'envoi. Si le résultat ignore une image de référence, la cause habituelle est une invite ambiguë plutôt qu'un champ défectueux — faites dire explicitement à l'invite quelle image détermine quel attribut.

Règles pratiques pour le travail multi-références :

  • Gardez le nombre réduit. N'utilisez que les images de référence réellement nécessaires à l'invite concernée ; en ajouter dilue le contrôle.
  • Faites correspondre les ratios d'aspect autant que possible, afin que le modèle n'ait pas à réconcilier des compositions contradictoires.
  • Utilisez de manière cohérente des URL publiques ou du base64 dans une même requête, ne mélangez pas les modes de transport.

Pendant l'intégration, envoyez une fois une requête à deux images pour vérifier que les deux références influencent visiblement la sortie, puis construisez une logique plus complexe par-dessus.

Choisir le palier de résolution

Le champ resolution sélectionne le palier de sortie pour minimax-h3-image image-to-image. Ce n'est pas qu'un simple réglage esthétique — il modifie le volume de calcul, la latence de réponse et la taille de la charge utile que vous finirez par traiter.

Comment arbitrer :

  • Choisissez le plus petit palier qui convient au cas d'usage. Une vignette pour une vue en liste n'a pas besoin du même palier qu'une bannière visuelle principale. Sous-échantillonner après coup une sortie haute résolution fait perdre du temps et de l'argent.
  • Attendez-vous à ce que la latence augmente avec la résolution. Un palier plus élevé effectue plus de travail par requête, donc votre budget de délai d'attente et d'intervalle d'interrogation doit refléter le palier choisi.
  • Surveillez la taille des charges utiles. Les entrées de référence en base64 et les sorties haute résolution augmentent le volume transféré ; si vous déplacez beaucoup d'images, surveillez les corps de requête et de réponse.

La facturation suit le palier de résolution demandé — les requêtes sont facturées selon le palier utilisé, donc un palier trop élevé pour un petit cas d'usage coûte discrètement plus cher. Consultez les tarifs en temps réel sur le panneau de tarification plutôt que de coder en dur des hypothèses.

Une stratégie d'intégration raisonnable : utilisez un palier moyen pendant le développement pour gagner en vitesse, puis une fois l'invite et le jeu de références stabilisés, passez les actifs critiques à un palier plus élevé. Changer la résolution tardivement invalide vos mesures de latence, donc faites vos benchmarks au palier que vous prévoyez réellement de mettre en production.

Gérer le cycle de vie asynchrone

Chaque appel image-to-image sur hiapi suit la même boucle : soumettre, capturer l'identifiant de tâche, interroger jusqu'à l'état terminal, puis récupérer le résultat. Rendre cette boucle robuste constitue l'essentiel du travail d'un client de niveau production.

Soumettre et enregistrer

Traitez l'identifiant de tâche comme votre poignée persistante. Enregistrez-le dès que la réponse de soumission arrive, avant toute autre chose — si le processus plante en cours d'interrogation, cet identifiant vous permet de reprendre plutôt que de régénérer.

Interroger avec backoff

Une interrogation fixe toutes les deux secondes convient à un usage interactif, mais est gaspilleuse pour de longs lots. Commencez par un intervalle court et augmentez-le progressivement, tout en plafonnant l'intervalle maximal, afin de détecter quand même la fin en temps utile.

def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
    return min(current * factor, cap)

Respecter l'état terminal

Ne sortez de la boucle qu'en cas de succès ou d'échec. Traiter toute réponse non vide comme « terminée » est le bug asynchrone le plus courant — vous iriez lire un résultat qui n'existe pas encore.

Borner chaque chose

Définissez un délai d'attente pour chaque appel HTTP, et une échéance globale pour la tâche. Si l'échéance est dépassée, levez une erreur claire plutôt que de tourner à vide. Pour les erreurs réseau transitoires, réessayez l'interrogation avec backoff ; ne resoumettez pas aveuglément, cela créerait du travail en double.

Nettoyage

Une fois le résultat obtenu, persistez rapidement l'URL de l'image ou les octets dans votre propre stockage. Les résultats de tâche sont des poignées temporaires, pas le CDN à long terme de votre application.

Dépannage et liste de contrôle de production

Voici les échecs que les développeurs rencontrent le plus tôt avec minimax-h3-image image-to-image, et les vérifications pour les éviter.

Échecs au premier lancement

  • 401 / 403 — jeton bearer manquant, expiré, ou entouré d'espaces. Vérifiez que la variable d'environnement est bien exportée dans le shell qui exécute la requête.
  • 422 ou erreur de validation — examinez le corps de la réponse d'erreur ; il indique généralement le champ. Une cause courante est d'avoir placé prompt au niveau supérieur au lieu de l'intérieur de input.
  • JSON malformé — validez votre fichier de charge utile avec jq . avant l'envoi.

Échecs en cours d'exécution

  • La tâche ne se termine jamais — vérifiez que vous interrogez avec l'identifiant réellement reçu, pas un espace réservé. Vérifiez que votre échéance est suffisamment longue pour le palier de résolution choisi.
  • Résultat vide pour une tâche « terminée » — lisez précisément le champ d'état ; les états d'échec renvoient aussi un corps de réponse.
  • Image de référence ignorée — avant d'incriminer le modèle, revoyez la formulation de l'invite et l'ordre des images de référence.

Liste de contrôle avant mise en production

  • La clé API et l'URL de base sont lues depuis des variables d'environnement, jamais commitées dans le dépôt.
  • Chaque appel HTTP a un délai d'attente explicite.
  • L'interrogation utilise un backoff borné, avec une échéance globale stricte.
  • Les états terminaux sont gérés explicitement ; on ne tombe pas dans la branche de parsing du résultat.
  • Le résultat est téléchargé et stocké par votre application, plutôt que lié à chaud depuis la réponse de la tâche.
  • Les invites multi-références précisent quelle image contrôle quel attribut.
  • Le palier de résolution a été benchmarké aux valeurs que vous prévoyez de mettre en production.
  • Les journaux enregistrent l'identifiant de tâche, afin que les tâches échouées soient traçables et reprenables.

Chaque fois qu'un problème survient, relancez la requête minimale ci-dessus — elle isole si le problème vient de votre charge utile ou du code environnant. Avec la structure de requête, les clients curl et Python, la gestion multi-références et une boucle d'interrogation disciplinée, vous disposez de tout le nécessaire pour mettre en production de manière fiable minimax-h3-image image-to-image sur hiapi.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API