Tutoriel
Comment appeler minimax-h3-image image-to-image avec curl et Python sur hiapi
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-imageavec la tâcheimage-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
promptdé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é
promptau niveau supérieur au lieu de l'intérieur deinput. - 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 →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage