HiAPI
Fr
Blog

Tutoriel

Comment utiliser grok-imagine image-to-image via l'API hiapi : curl, Python et une requête qui fonctionne

Jul 11, 2026
Comment utiliser grok-imagine image-to-image via l'API hiapi : curl, Python et une requête qui fonctionne

grok-imagine/image-to-image prend une ou plusieurs images de référence et un prompt texte, et renvoie une image modifiée — vous pouvez restyliser une photo produit, remplacer un arrière-plan, ou fusionner jusqu'à trois images de référence en une seule sortie. Sur hiapi, il s'exécute via l'API de tâches unifiée : créez une tâche, interrogez (ou recevez un callback), téléchargez le résultat. Ce guide vous montre la structure exacte de la requête, avec des exemples curl et Python prêts à copier-coller et fonctionnels dès le départ.

Ce que vous allez construire + prérequis

Objectif : soumettre une image de référence et un prompt, récupérer l'URL d'une image modifiée et la télécharger — d'abord de façon interactive par interrogation, puis avec une version de production utilisant un callback.

Vous n'avez besoin que d'une chose : une clé API hiapi. Obtenez-la depuis votre tableau de bord — elle ressemble à sk-... et se place dans l'en-tête Authorization: Bearer à chaque appel.

Vos images de référence doivent être des URL accessibles publiquement (le modèle les récupère côté serveur), alors hébergez-les d'abord sur votre CDN ou votre stockage objet.

Exemple minimal fonctionnel (curl)

Créer la tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Transformez cette photo produit en une prise de studio propre sur fond blanc sans raccord, avec des ombres douces",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

Deux champs obligatoires — prompt et image_urls — et c'est une requête complète. La réponse contient l'ID de tâche sous data.taskId :

{
  "data": {
    "taskId": "<task-id>"
  }
}

Interroger le résultat :

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

Pendant l'exécution de la tâche, data.status indique la progression. Quand il passe à success, l'URL de l'image se trouve dans data.output[0].url. S'il est à fail, data.error contient le code d'erreur et le message.

Un détail important : les URL de sortie sont signées et expirent (la charge utile contient expireAt). Téléchargez le fichier dès que la tâche réussit — ne stockez jamais et ne faites jamais de hotlink vers l'URL de sortie brute.

curl -o result.png "<data.output[0].url>"

Le même exemple en Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Transformez cette photo produit en une prise de studio propre "
            "sur fond blanc sans raccord, avec des ombres douces"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Créer la tâche
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Interroger jusqu'à un état terminal
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Télécharger immédiatement — les URL de sortie expirent
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

Le schéma d'entrée complet

Champ Obligatoire Type Description
prompt ✅ string Ce qu'il faut modifier / l'apparence cible
image_urls ✅ tableau d'URL 1 à 3 images de référence, accessibles publiquement
aspect_ratio facultatif enum auto, 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2
resolution facultatif enum 1k ou 2k — en minuscules
output_format facultatif enum jpeg, png ou webp

Ce schéma est strict : tout champ qu'il ne reconnaît pas est rejeté avec un 400. Pas de size, pas de seed, pas de n — si vous portez du code de modèle qui utilise des dimensions en pixels (par exemple size: "1024x1024"), utilisez ici aspect_ratio + resolution à la place. Chaque tâche renvoie une image ; pour obtenir des variantes, soumettez plusieurs tâches.

Références multiples : jusqu'à 3 images d'entrée

image_urls accepte jusqu'à trois images de référence, que le modèle fusionne — par exemple une image produit, une image de fond et une image de référence de style. Si vous en envoyez plus de trois, l'API rejette directement la requête :

invalid input: image_urls: maxItems: got 4, want 3

Placez l'image la plus importante (généralement le sujet) en premier, et précisez dans le prompt ce que chaque image de référence apporte.

Ratio d'aspect automatique

aspect_ratio: "auto" laisse le modèle déduire le ratio de sortie depuis vos images de référence, au lieu d'imposer un cadre fixe — c'est la valeur par défaut appropriée pour les photos produit et les retouches où l'on souhaite conserver la composition. Ne définissez un ratio explicite que lorsqu'un cas d'usage précis l'exige (par exemple 9:16 pour un emplacement de story, 16:9 pour une bannière hero).

Considérations pour la production

Utiliser des callbacks plutôt que d'interroger

Pour les traitements par lots ou les charges de travail côté serveur, évitez la boucle d'interrogation — enregistrez un callback à la création de la tâche et hiapi enverra le résultat final en POST à votre endpoint :

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when ne prend en charge que "final" — vous recevez un appel lorsque la tâche atteint success ou fail, pas les événements de progression intermédiaires.

Règle empirique : interrogation pour les outils interactifs (un utilisateur regarde ; une boucle avec sleep de 5 secondes convient), callbacks pour les pipelines (des dizaines de tâches en cours ; vous ne voudrez pas d'un poller par tâche). Votre gestionnaire de callback doit toujours télécharger la sortie immédiatement — l'URL qu'il reçoit expire comme les autres.

Idempotence et nouvelles tentatives

L'API de tâches sépare « la soumission » de « le résultat », ce qui rend les nouvelles tentatives sûres et simples :

  • Persistez le taskId dès que create le renvoie. Si votre processus plante ensuite, reprenez en interrogeant l'ID stocké — ne recréez pas.
  • Ne réessayez que si l'appel create échoue sans renvoyer de taskId (erreur réseau, 5xx). Resoumettre une requête qui a déjà renvoyé un ID crée une seconde tâche facturée séparément.
  • Considérez status: "fail" comme terminal. Corrigez l'entrée (ou basculez vers une solution de repli) et soumettez une nouvelle tâche ; une tâche échouée ne redémarre pas.

Erreurs courantes

Ce que vous voyez Signification Correction
401 — permission_denied Clé incorrecte, ou clé sans accès à ce modèle Vérifiez la clé dans le tableau de bord
400 INVALID_REQUEST — missing required field "prompt" / "image_urls" Entrée obligatoire manquante Les deux champs sont obligatoires
400 INVALID_REQUEST — additional properties '...' not allowed Champ inconnu (par exemple size, seed, n) Schéma strict — utilisez uniquement les champs du tableau ci-dessus
400 INVALID_REQUEST — image_urls: maxItems Plus de 3 images de référence Réduisez à 3
404 — task not found Lors du GET, taskId incorrect ou appartenant à un autre compte Vérifiez l'ID stocké
status: "fail" lors de l'interrogation Accepté mais la génération a échoué Lisez data.error, ajustez l'entrée, resoumettez

Notez qu'un échec d'authentification est un 401 avec "code": "permission_denied" dans le corps d'erreur — il vaut la peine de le gérer explicitement, car il couvre aussi le cas où la clé existe mais n'a pas accès à ce modèle.

Étapes suivantes

Questions fréquentes

Combien d'images de référence puis-je passer ? Jusqu'à 3 dans image_urls. L'API en rejette catégoriquement davantage (maxItems: got N, want 3).

Puis-je définir la taille de sortie en pixels ? Non. Il n'y a pas de champ size — vous contrôlez la forme avec aspect_ratio (14 valeurs d'enum) et la définition avec resolution (1k ou 2k, en minuscules). Tout autre contenu renvoie un 400.

Que fait aspect_ratio: "auto" ? Il laisse le modèle suivre le ratio de l'image de référence au lieu d'imposer un cadre fixe — c'est le choix courant pour les retouches qui doivent conserver la composition.

Combien de temps les URL de résultat sont-elles valides ? Ce sont des URL signées avec une durée de validité (expireAt dans la charge utile de sortie). Téléchargez les octets dès que la tâche réussit ; ne faites pas de hotlink dessus.

Dois-je interroger ou utiliser un callback ? Pour un usage interactif, une interrogation toutes les ~5 secondes convient. Pour un pipeline par lots, passez callback: {"url": ..., "when": "final"} et traitez un POST par tâche — "final" est le seul déclencheur pris en charge.

Puis-je obtenir plusieurs variantes en un seul appel ? Non — il n'y a pas de paramètre n. Soumettez une tâche par variante ; elles s'exécuteront de toute façon en parallèle.

Quelle différence avec grok-imagine-quality/image-to-image ? La même structure de requête, avec un palier de rendu de fidélité supérieure (et de coût plus élevé). Prototypez sur le palier standard, puis relancez les références conservées sur le palier qualité ; comparez le coût par image sur la page tarifs.

TagsAPI d'imageTutoriel

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