Comment appeler grok-imagine/image-to-image via l'API HiAPI : guide curl et Python

Ce que grok-imagine/image-to-image offre aux développeurs

grok-imagine/image-to-image est un point de terminaison de transformation d'image : vous lui fournissez une image de référence et un prompt, et il renvoie une nouvelle image qui suit le prompt tout en restant visuellement liée à l'image de référence. Voyez-le comme une génération guidée, et non une génération à partir de zéro. L'identifiant du modèle que vous appelez sur HiAPI est simplement grok-imagine/image-to-image, et le reste de la requête sert à décrire la modification souhaitée.

Choisissez ce point de terminaison plutôt qu'un appel de génération texte-image dès que la sortie doit conserver certains éléments d'un matériel existant — une photo de produit dont il faut changer l'arrière-plan, un croquis de personnage à rendre, une composition à changer de style. La génération texte-image convient lorsque vous n'avez pas d'image source et seulement une description ; image-to-image convient lorsque l'image source elle-même fait partie des spécifications.

Comme HiAPI l'expose via une interface unifiée unique, votre travail d'intégration se limite à construire une seule structure de requête et à traiter une seule structure de réponse. Vous n'avez pas besoin d'introduire un SDK distinct pour chaque famille de modèles, ni de réapprendre l'authentification pour chaque point de terminaison.

Anatomie d'une requête : modèle, image de référence et prompt

Chaque appel valide comporte conceptuellement quatre parties. Bien régler chacune avant d'écrire du code vous épargnera l'essentiel du débogage ultérieur.

Identifiant du modèle

Le champ model contient la chaîne grok-imagine/image-to-image. Traitez-la comme une constante dans votre client, plutôt que comme un littéral codé en dur éparpillé dans la base de code — si vous voulez essayer d'autres modèles HiAPI plus tard, vous voudrez un seul endroit à modifier.

Image de référence

L'image de référence est l'ancre. La manière de la fournir dépend du mode de transport choisi : une URL récupérable par l'API, ou des données base64 en ligne, adaptées aux images générées à la volée ou inaccessibles publiquement. Privilégiez l'URL pour les éléments que vous hébergez déjà ; privilégiez les données en ligne pour les téléversements d'utilisateurs qui ne sont encore persistés nulle part publiquement. Quel que soit le mode de transport, validez l'image avant l'envoi : format pris en charge, taille non nulle, dimensions suffisamment significatives.

Prompt

Le prompt décrit la transformation, et non la scène entière. Si l'image de référence contient déjà le sujet, décrivez ce qui doit changer — style, éclairage, arrière-plan, matière — et laissez implicite ce qui reste inchangé. Surspécifier ce qui est déjà visible dans l'image de référence entre souvent en conflit avec le conditionnement par image plutôt que d'aider.

Gestion du ratio d'aspect

La partie restante concerne la façon dont la taille de sortie est déterminée, sujet de la section suivante. Séparez ces quatre parties dans le code qui construit la requête, afin que chacune puisse être validée et journalisée indépendamment.

Utiliser l'option auto aspect

L'option auto aspect laisse l'API choisir la taille de sortie au lieu que vous fixiez une largeur et une hauteur explicites. Une fois activée, le service déduit un ratio d'aspect approprié à partir du contexte de la requête — surtout l'image de référence — afin que la forme de la sortie soit plus cohérente par rapport à votre entrée, au lieu d'être contrainte dans un format par défaut.

Cela compte plus qu'il n'y paraît. Si vous fixez une taille incompatible avec le ratio de l'image de référence, vous obtiendrez des artefacts de type letterbox, un recadrage maladroit du sujet, ou une composition qui ignore le cadrage de l'image source. auto aspect évite ce type d'incohérence en laissant la géométrie suivre l'entrée.

Quand laisser auto activé

• Les images de référence proviennent des utilisateurs et ont des formes variées.
• Vous prototyper et ne savez pas encore quelle taille convient à ce cas d'usage.
• La sortie alimente un pipeline qui la recadrera ou la redimensionnera de toute façon en aval.

Quand fixer explicitement une taille

• Vous avez un emplacement fixe dans une UI ou une cible imprimée, nécessitant une géométrie de sortie précise.
• Vous générez un lot d'images qui doivent être visuellement cohérentes en taille.

Une approche pratique : gardez auto aspect activé pendant le développement, examinez les tailles que l'API renvoie pour vos entrées réelles, puis décidez s'il faut verrouiller une taille pour la production. Journalisez les métadonnées de l'image renvoyée avec la requête, afin que cette décision repose sur des preuves plutôt que sur des suppositions.

Requête curl prête à l'emploi

La requête ci-dessous est complète hormis les espaces réservés, indiqués entre chevrons. Remplacez-les par vos propres valeurs et elle pourra être exécutée telle quelle.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

Espaces réservés à remplacer

• $HIAPI_API_KEY — lisez votre clé depuis une variable d'environnement plutôt que de la coller dans la commande. Si la variable n'est pas définie, la requête échoue avec une erreur d'authentification, et la clé ne finit jamais dans l'historique de votre shell.
• <describe the transformation you want> — une instruction courte et concrète, par exemple un changement de style ou d'arrière-plan.
• <publicly reachable URL of your reference image> — une URL que le service peut récupérer sans authentification. Si votre matériel est privé, utilisez plutôt des données base64 en ligne.

Lire la réponse

Pour la première exécution, passez la sortie dans un outil de formatage JSON afin de voir clairement la structure de la réponse. Surveillez deux choses : la charge utile de l'image (URL ou données encodées selon le mode de réponse) et l'identifiant de tâche lorsque l'appel est traité de manière asynchrone. Pendant le développement, conservez la réponse brute complète dans les journaux — c'est le moyen le plus rapide de répondre à « qu'a-t-on réellement reçu » quand quelque chose semble anormal.

La même requête en Python

La version Python doit correspondre champ par champ à la requête curl. L'intérêt de les garder alignées : un bug reproduit dans une version peut être confirmé dans l'autre, sans deviner la traduction.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Où placer la gestion des erreurs

Dans le wrapper, pas chez l'appelant. response.raise_for_status() convertit les réponses non-2xx en exceptions, de sorte qu'un seul try/except autour de generate_from_reference couvre à la fois les échecs de transport et les rejets de l'API. Si vous voulez une journalisation structurée des causes d'échec, inspectez response.status_code et le corps d'erreur à l'intérieur de la fonction avant de lever l'exception.

Garder le client propre

Lisez la clé API une seule fois au démarrage, définissez un timeout explicite, et renvoyez le JSON analysé plutôt que l'objet de réponse brut. Les appelants ne devraient pas avoir besoin de connaître les détails HTTP. Dans les tests, pointez API_URL vers un serveur factice, afin de valider la logique de construction de requête sans dépenser d'appels de génération réels.

Réponses synchrones et asynchrones

Certaines requêtes image-to-image se terminent assez vite pour renvoyer le résultat dans la même réponse HTTP. D'autres sont traitées comme des tâches : l'appel initial renvoie un identifiant, et l'image est disponible plus tard. Votre client ne doit présumer ni l'un ni l'autre.

Comment distinguer les deux

Inspectez le corps de la réponse après chaque appel. S'il contient directement la charge utile de l'image, vous êtes sur le chemin synchrone — extrayez-la et renvoyez-la. S'il contient un identifiant de tâche ou de job, vous êtes sur le chemin asynchrone, et vous devez interroger jusqu'à ce que la tâche atteigne un état terminal.

Concevoir pour les deux

Une petite fonction de répartition garde les deux chemins hors de votre logique métier :

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Règles d'interrogation pour éviter les ennuis

• Utilisez un backoff exponentiel plafonné, plutôt qu'une boucle serrée.
• Définissez un temps d'attente total maximal et échouez proprement en cas de dépassement.
• Traitez chaque état non terminal comme « continuer à attendre » ; seuls deux états sont finaux : succès et échec.
• Journalisez l'identifiant du job à chaque interrogation, afin de pouvoir retracer un job bloqué à partir des seuls journaux.

Cette approche de répartition signifie que le code appelant resolve_result n'aura jamais besoin de changer lorsqu'on bascule entre comportement synchrone et asynchrone.

Déboguer les codes d'erreur courants

La plupart des appels en échec sur ce point de terminaison se rangent dans quelques catégories. Parcourez la liste suivante dans l'ordre — elle va de la cause la plus fréquente à la plus rare.

Échecs d'authentification

Si la réponse indique un problème d'authentification, la clé est absente, mal formée ou non envoyée. Vérifiez que la variable d'environnement est réellement définie dans le processus qui effectue l'appel, et que l'en-tête est exactement Authorization: Bearer <key>. Une clé valide dans votre shell mais invalide dans le service signifie généralement que l'environnement du service diffère de celui de votre shell.

Erreurs de validation de l'image de référence

Un rejet lié à l'image signifie généralement l'une de quatre choses : l'URL n'est pas récupérable publiquement, le format n'est pas pris en charge, la charge utile est trop volumineuse, ou l'image est trop petite ou corrompue. Testez l'URL dans un navigateur sans identifiants — si elle ne se charge pas là, l'API ne pourra pas non plus la récupérer. Pour du base64 en ligne, vérifiez que l'encodage est du base64 pur, sans préfixe data-URL (sauf si le paramètre l'attend).

Erreurs de prompt et de paramètres

Un prompt vide ou trop long, ou une valeur de paramètre inconnue, produit une réponse de validation. Journalisez la charge utile exacte que vous envoyez avec l'erreur — une bonne partie des échecs sont des fautes de frappe dans les noms de champs, et non des problèmes de valeurs.

Limitation de débit

Une réponse de limitation de débit signifie un backoff, et non un nouvel essai immédiat. Suivez les indications de réessai fournies dans les en-têtes de réponse, ajoutez du jitter, et limitez le nombre de tentatives. Réessayer sans backoff transforme une limitation temporaire en limitation persistante.

Erreurs côté serveur

Les réponses 5xx incombent au service. Réessayez un nombre limité de fois avec backoff ; si le problème persiste, capturez l'identifiant de requête et l'horodatage depuis la réponse, et réduisez la concurrence pendant l'investigation.

Liste de vérification en production avant la mise en ligne

Une requête qui fonctionne n'est qu'un début, pas une fin. Avant que ce point de terminaison ne traite du trafic réel, confirmez chacun des points suivants.

Validez les entrées aux frontières

Avant que la requête ne quitte votre service, vérifiez le format et la taille de l'image de référence, la longueur du prompt et les valeurs des paramètres. Rejeter localement une mauvaise entrée est plus rapide, moins coûteux, et produit des messages d'erreur plus clairs pour l'utilisateur.

Ne réessayez que les requêtes réessayables sans risque

Réessayez avec backoff exponentiel et jitter pour les échecs de transport, les limitations de débit et les réponses 5xx. Ne réessayez pas les erreurs de validation ou d'authentification — elles échoueront de la même manière et ne feront qu'ajouter de la charge.

Journalisez assez d'informations pour reconstituer un échec

Journalisez l'identifiant du modèle, une forme hachée ou tronquée du prompt, l'identifiant de l'image de référence (et non la charge utile complète), le statut de réponse, l'identifiant de job (s'il existe) et l'identifiant de requête. Cet ensemble suffit généralement à répondre à « que s'est-il passé » sans stocker de contenu sensible.

Gardez les clés hors du code

Lisez la clé API depuis l'environnement ou un gestionnaire de secrets, jamais depuis un littéral dans le code source. Faites tourner les clés régulièrement et révoquez immédiatement en cas de suspicion de fuite.

Surveillez le comportement des coûts

La facturation de ce point de terminaison est pilotée par la génération ; les principaux leviers sont donc le volume de requêtes, les réessais et la fréquence d'interrogation. Évitez les tempêtes de réessais, appliquez un backoff aux interrogations, et mettez en cache les résultats par prompt et image de référence pour les scénarios où la même transformation est demandée à répétition. Consultez le panneau de tarification HiAPI pour les tarifs actuels, plutôt que de coder en dur des hypothèses.

Testez les chemins qui se passent mal

Écrivez des tests pour les URL d'image invalides, les réponses de limitation de débit et les jobs asynchrones qui ne se terminent jamais. Ces trois cas couvrent les échecs les plus susceptibles d'atteindre la production sans être remarqués.

Avec la construction de requête, la répartition des réponses et la gestion des erreurs en place, grok-imagine/image-to-image deviendra une partie routinière de votre pipeline, et non un cas particulier.