Comment utiliser recraft/creative-upscale via l'API HiAPI : guide des requêtes curl et Python

Le rôle de recraft/creative-upscale dans le flux de travail d'un développeur

recraft/creative-upscale est un endpoint image-vers-image : vous envoyez une image existante, le modèle renvoie une version plus grande et reconstruite par le modèle. Le mot clé ici est créatif (creative). Une étape d'upscaling classique (bilinéaire, Lanczos ou un modèle de super-résolution générique) préserve l'entrée aussi fidèlement que possible. L'upscaling créatif, lui, autorise la régénération de détails qui n'ont jamais existé dans les pixels source — les contours sont resynthétisés, les textures sont inférées, les petites zones floues peuvent être nettement améliorées en contenu plausible, plutôt que simplement interpolées.

Cela le distingue d'un simple outil de redimensionnement et détermine sa place différente dans un pipeline.

Quand l'utiliser

• Mise à niveau d'assets. Une vignette ou une ancienne image produit doit être affichée à une taille d'affichage plus grande, alors qu'un redimensionnement ordinaire paraîtrait flou comparé à ses voisins en résolution native.
• Travail sur des références et des rendus. De l'art conceptuel, un storyboard ou une image de remplacement doit être présenté en grand format sans révéler sa source basse résolution.
• Upscaling dans une boucle de génération. Vous avez généré des images à une taille de travail réduite et souhaitez un asset final sans relancer tout le processus de génération sur un canevas plus grand.

Quand ne pas l'utiliser

Si le besoin est une fidélité octet par octet — scans d'archives, documents, atlas de textures dont les valeurs de pixels constituent les données — n'utilisez pas un modèle créatif. Les détails régénérés sont des suppositions plausibles, pas des reconstructions ; pour des fins de mesure ou d'archivage, cette supposition est un défaut. Dans ce cas, utilisez un rééchantillonneur déterministe et réservez le modèle créatif aux sorties perceptuelles.

La forme de l'appel

Cet endpoint suit le même schéma de requête que les autres endpoints d'image HiAPI : une requête POST JSON authentifiée envoyée au chemin du modèle, contenant une image d'entrée et un objet de paramètres. Si vous avez déjà intégré n'importe quel autre modèle d'image de la plateforme, ce modèle mental se transpose directement — c'est précisément l'intérêt de router ces appels via une interface unifiée. Un appel curl fonctionnel devient le modèle de chaque endpoint d'image que vous aborderez ensuite.

Une façon utile de comprendre cette étape : elle consomme une image à laquelle vous faites déjà confiance (composition, contenu et couleurs déjà fixés) et renvoie une variante plus grande et plus détaillée. Les décisions de contenu appartiennent à l'amont ; recraft/creative-upscale est la phase de finition.

Prérequis et configuration de l'endpoint

Avant d'écrire la première requête, rassemblez quatre éléments. Aucun ne nécessite de SDK spécial — toute l'intégration est une simple communication HTTPS avec un corps de requête JSON.

1. Clé API

Vous avez besoin d'une clé API HiAPI donnant accès aux modèles d'image. Traitez-la comme un secret : chargez-la depuis une variable d'environnement plutôt que de la coller dans un script, et ne la validez jamais dans un dépôt de version.

export HIAPI_API_KEY="your-key-here"

La clé est transmise via un en-tête, ni dans l'URL ni dans le corps JSON. La garder hors de la chaîne de requête la garde aussi hors de l'historique du shell et des journaux de proxy.

2. URL de base

L'URL de base est votre hôte d'API HiAPI. Tous les appels de modèle sont des chemins relatifs sous celle-ci, vous pouvez donc la définir dans une variable et la réutiliser dans chaque script :

export HIAPI_BASE_URL="https://api.hiapi.ai"

Consultez la documentation de référence de l'API de la plateforme pour obtenir l'URL de base canonique et le préfixe de chemin de votre compte, et stockez-les dans cette variable unique. Ainsi, un changement d'hôte ou de version se limite à une seule ligne à modifier.

3. Identifiant du modèle

L'ID du modèle est un segment de chemin qui doit être orthographié exactement tel que publié : recraft/creative-upscale. Il contient une barre oblique, ce qui compte dans certains outils — la section de débogage le détaille. La casse et les traits d'union comptent. Un caractère erroné produit une erreur de modèle introuvable qui ressemble à un problème d'authentification si l'on ne fait que survoler le message.

4. Image de test

Ayez une image prête sur le disque et connaissez son chemin exact et son type MIME. Pour une première exécution, utilisez un petit fichier, pour qu'un échec soit clairement un problème de requête et non de taille de charge utile ou de délai d'attente. Vous réutiliserez ensuite la même image pour des exécutions comparatives, alors choisissez quelque chose avec des détails visibles (tissu, végétation, panneaux sans texte) plutôt qu'un dégradé uniforme.

Liste de vérification des en-têtes

Chaque requête à partir d'ici porte les mêmes en-têtes :

• Authorization: Bearer $HIAPI_API_KEY
• Content-Type: application/json

Si vous envoyez l'image en base64 ou sous forme de data URI dans le corps JSON, ces deux en-têtes suffisent. Si vous préférez d'abord téléverser le fichier pour obtenir une URL, traitez ce téléversement comme un appel séparé et conservez l'URL générée séparément de la requête du modèle.

Avec une clé, une URL de base, un ID de modèle et une image de test, vous pouvez lancer un appel réel en moins d'une minute.

Une requête curl fonctionnelle

Voici un appel directement exécutable. Remplacez la valeur de l'image par votre propre entrée — soit une URL accessible publiquement, soit un data URI encodé en base64, selon ce qu'accepte le mode d'entrée du modèle.

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/recraft/creative-upscale" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://example.com/test-input.png"
    },
    "parameters": {
      "upscale": 2
    }
  }' \
  -o response.json

Utiliser -o pour écrire la réponse dans un fichier plutôt que de la laisser s'afficher en flux dans le terminal conserve le JSON intact pour l'analyse et rend l'appel scriptable.

Le rôle de chaque partie

• -X POST — cet endpoint est en POST ; un GET renvoie une erreur de méthode, facilement confondue avec un problème de permissions.
• L'URL — l'URL de base, puis le chemin du modèle avec l'ID complet. Comme l'ID contient lui-même une barre oblique, le chemin a deux segments après la collection de modèles ; gardez-le sous forme d'une seule chaîne et ne laissez pas la bibliothèque cliente le réencoder en recraft%2Fcreative-upscale, sauf si la documentation indique que c'est le comportement attendu.
• Authorization — le jeton bearer. Si vous voyez un 401 sur cette commande exacte, la clé ou le format de l'en-tête est erroné ; rien d'autre dans le corps n'a encore été validé.
• Content-Type: application/json — requis. Sans lui, certaines passerelles traitent le corps comme des données de formulaire et la requête n'atteint jamais le modèle.
• input.image — l'image source. Préférez une URL lors de l'itération : cela garde la commande courte et les différences nettes.
• parameters.upscale — le contrôle d'upscaling. Commencez par un facteur modéré, puis augmentez après avoir confirmé la réponse.

Deux variantes utiles

Pour envoyer un fichier local en base64 plutôt qu'une URL :

B64=$(base64 -w0 ./test-input.png)

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/recraft/creative-upscale" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"input\": { \"image\": \"data:image/png;base64,${B64}\" },
    \"parameters\": { \"upscale\": 2 }
  }" \
  -o response.json

Pour voir à la fois le code de statut HTTP et le corps de la réponse lors du débogage, ajoutez -w '\nHTTP %{http_code}\n' et retirez -o.

Considérez cette commande unique comme votre modèle. Une fois qu'elle renvoie une image, chaque modification ultérieure — un facteur différent, une image source différente — ne consiste qu'à éditer deux champs, pas à réaliser une nouvelle intégration.

La même requête en Python

La version Python ne doit pas être un copier-coller du corps curl ; elle doit être une petite fonction réutilisable, afin que les exécutions comparatives ultérieures ne nécessitent qu'un seul appel à chaque fois. Utilisez uniquement la bibliothèque standard — aucun SDK requis.

import base64
import json
import os
import pathlib
import urllib.request

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "recraft/creative-upscale"


def creative_upscale(image: str, upscale: int = 2, timeout: int = 120) -> dict:
    """Envoie une image à recraft/creative-upscale et renvoie le JSON parsé."""
    payload = {
        "input": {"image": image},
        "parameters": {"upscale": upscale},
    }
    request = urllib.request.Request(
        url=f"{HIAPI_BASE_URL}/v1/models/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))


def as_data_uri(path: str) -> str:
    data = pathlib.Path(path).read_bytes()
    mime = "image/png" if path.lower().endswith(".png") else "image/jpeg"
    return f"data:{mime};base64,{base64.b64encode(data).decode('ascii')}"


if __name__ == "__main__":
    result = creative_upscale(as_data_uri("test-input.png"), upscale=2)
    print(json.dumps(result, indent=2)[:2000])

Pourquoi cette forme

• Configuration issue de variables d'environnement. L'URL de base et la clé sont lues une fois à l'import, donc aucun secret n'apparaît dans le fichier et changer d'environnement ne demande qu'un export.
• Une fonction, une responsabilité. creative_upscale reçoit une référence d'image et un facteur, et renvoie le JSON parsé. Toutes les informations sur les paramètres restent visibles au point d'appel.
• Délai d'attente explicite. Les modèles d'image prennent plus de temps que les endpoints texte. Définissez intentionnellement un délai, plutôt que d'hériter d'une valeur par défaut trop courte, et gardez-le suffisamment long pour qu'un appel lent mais réussi ne soit pas inutilement relancé.
• Un utilitaire pour les fichiers locaux. as_data_uri signifie que vous pouvez passer une URL ou un chemin local sans modifier la logique de requête.

Si vous préférez un client basé sur une session

Le même appel avec httpx ne demande que deux lignes de remplacement — construire un client, définir l'en-tête Authorization par défaut, puis post le corps JSON. Les invariants importants ne changent pas : l'ID du modèle reste un seul segment de chemin non encodé, la clé reste dans les en-têtes, le corps conserve la séparation input / parameters. Respectez ces trois points et votre client devient interchangeable avec n'importe quel autre client de la plateforme.

Lorsque vous l'intégrez dans un pipeline, renvoyez le dictionnaire parsé et laissez l'appelant décider comment persister l'image — cette séparation rend la gestion des réponses de la section suivante réutilisable.

Paramètres d'upscaling et de créativité

Les valeurs que vous envoyez comptent moins que l'endroit où vous les envoyez. Assurez-vous d'abord que l'emplacement est correct, puis ajustez les valeurs.

Deux compartiments, un contrat

Chaque requête se divise en :

• input — l'image elle-même. L'objet de l'opération. Rien concernant le comportement du modèle ne va ici.
• parameters — les contrôles. Le facteur d'upscaling et les réglages de créativité appartiennent à cet objet, en tant que frères.

Cette séparation est le contrat. Une première exécution doit confirmer que le modèle accepte votre placement — c'est-à-dire que l'appel renvoie au moins une image — avant de commencer à optimiser les valeurs. Si un paramètre est placé dans le mauvais compartiment, vous obtenez généralement une image générée avec les valeurs par défaut, ou une erreur de validation signalant un champ inconnu. Dans les deux cas, c'est une erreur de placement, pas de qualité, et peaufiner les réglages de qualité ne la corrigera pas.

Facteur d'upscaling

Le facteur contrôle la taille de la sortie par rapport à l'entrée. Raisonnez ainsi :

• C'est un multiplicateur, donc le coût et la latence augmentent avec lui. Passer d'un facteur modéré au maximum n'est pas une progression linéaire du temps de rendu. Traitez chaque augmentation comme une nouvelle expérience, pas comme un curseur à ajuster finement.
• La résolution d'entrée compte toujours. Les modèles créatifs ont plus de matière à exploiter quand une certaine structure existe. Une entrée minuscule leur donne plus de liberté d'invention, ce qui est parfois le but, parfois un accident.
• Choisissez le facteur selon la taille cible, pas selon le maximum. Si l'image a besoin d'un 2× pour tenir dans son emplacement, demandez 2×. Demander le maximum puis réduire jette le bénéfice et le fait payer.

Contrôle de créativité

La créativité est le bouton qui détermine combien le modèle peut remplacer (plutôt qu'agrandir). Un réglage bas se comporte plus comme un upscaling fidèle ; un réglage élevé laisse le modèle resynthétiser plus agressivement, ce qui peut sauver une source floue ou pixelisée, mais peut tout autant introduire des détails non désirés.

Considérez ce paramètre comme un levier de fidélité, avec deux interprétations concrètes :

• Préserver — logos, visages, images de catalogue produit, tout ce qu'un spectateur pourrait comparer à l'original.
• Régénérer — art conceptuel, arrière-plans, textures, images décoratives, où la plausibilité prime sur l'exactitude.

Méthode de travail

Modifiez un paramètre à la fois, gardez l'entrée fixe et consignez les valeurs avec les sorties. Une petite matrice — la même image à deux facteurs, chaque facteur avec deux réglages de créativité — suffit à caractériser l'endpoint sur votre propre contenu. N'empruntez pas les valeurs « optimales » d'autrui ; les modèles créatifs interagissent fortement avec l'entrée, et les réglages adaptés à une photo conviennent rarement à une illustration plate.

Si une valeur est directement rejetée plutôt que de produire un mauvais résultat, c'est le contrat qui vous indique le domaine du paramètre — consultez la référence des paramètres de l'endpoint pour connaître les plages acceptables, plutôt que de deviner.

Lire la réponse et enregistrer l'image

Analysez la réponse de manière défensive. Le type de charge utile fait partie du contrat, mais il peut varier entre URL et bloc base64 en ligne, et votre client ne doit pas planter selon celui qu'il reçoit.

D'abord, examinez le JSON brut

Avant d'écrire un analyseur, exécutez une fois l'appel curl avec -o response.json et lisez le fichier. Identifiez le champ qui porte l'image. C'est généralement l'un des suivants :

• une URL pointant vers le fichier généré, ou
• une chaîne en ligne, généralement base64 ou un data URI.

Cherchez aussi les métadonnées qu'il vaut la peine de consigner : dimensions, ID de modèle renvoyé en écho, et tout identifiant utilisable pour une demande d'assistance.

Une fonction d'enregistrement tolérante aux erreurs

import base64
import pathlib
import urllib.request


def extract_image(result: dict) -> str:
    """Trouve la charge utile de l'image, quelle que soit sa forme."""
    for container in (result, result.get("data"), result.get("output")):
        if isinstance(container, list) and container:
            container = container[0]
        if isinstance(container, dict):
            for key in ("image", "url", "b64_json", "image_url"):
                value = container.get(key)
                if isinstance(value, str) and value:
                    return value
    raise ValueError(f"no image field in response: {sorted(result)}")


def save_image(payload: str, out_path: str = "upscaled.png") -> pathlib.Path:
    path = pathlib.Path(out_path)
    if payload.startswith("data:"):
        payload = payload.split(",", 1)[1]
        path.write_bytes(base64.b64decode(payload))
    elif payload.startswith("http://") or payload.startswith("https://"):
        with urllib.request.urlopen(payload) as response:
            path.write_bytes(response.read())
    else:
        path.write_bytes(base64.b64decode(payload))
    return path

L'important n'est pas que ce soit le seul analyseur correct — mais que la fonction énonce ses hypothèses (data:, http(s)://, base64 pur) et lève une erreur claire quand aucune ne correspond. Quand la forme de la réponse change, il suffit de mettre à jour une fonction, pas chaque script qui consomme des images.

Enregistrement sûr dans le flux curl

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/recraft/creative-upscale" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

python - <<'PY'
import json
from save_image import extract_image, save_image
result = json.load(open("response.json"))
print(save_image(extract_image(result), "out.png"))
PY

Deux habitudes à conserver : écrivez dans un nouveau nom de fichier à chaque exécution, pour qu'un échec ou une écriture partielle n'écrase jamais un bon résultat ; vérifiez les dimensions de sortie après la sauvegarde — un HTTP 200 réussi mais des dimensions inattendues signifient que les paramètres n'ont pas pris effet, ce qui est plus facile à repérer ici qu'après trois étapes de pipeline.

Déboguer les pannes courantes

La plupart des pannes de première exécution sont banales. Parcourez cette liste dans l'ordre ; elle couvre la grande majorité des cas.

401 / 403 — authentification

• La clé est-elle chargée dans le même shell qui exécute la commande ? echo $HIAPI_API_KEY doit afficher une valeur non vide.
• L'en-tête est-il exactement Authorization: Bearer <key> — avec l'espace et le mot Bearer ?
• La clé s'est-elle retrouvée dans l'URL ou le corps JSON au lieu de l'en-tête ? Replacez-la.
• La clé est-elle limitée aux modèles d'image ? Une clé valable pour une zone de produit peut ne pas s'appliquer à cet endpoint.

404 — modèle ou route introuvable

C'est presque toujours une question d'ID de modèle. Comparez caractère par caractère avec l'identifiant publié recraft/creative-upscale : la barre oblique, les minuscules et le trait d'union dans creative-upscale sont essentiels. Un piège associé est l'échappement d'URL côté client — si vous voyez recraft%2Fcreative-upscale sur la ligne de requête et que l'appel renvoie 404, votre couche HTTP a encodé la barre oblique ; configurez-la pour ne pas toucher au segment de chemin.

Vérifiez aussi que vous n'avez pas dupliqué le préfixe de chemin (par exemple, l'URL de base se termine déjà par le segment de version et le chemin le répète). Utiliser une variable pour l'URL de base rend cela facile à repérer.

400 — requête comprise mais rejetée

Lisez le message plutôt que de deviner. Causes courantes :

• Format d'entrée d'image erroné. Du base64 tronqué (souvent parce que la variable shell a été tronquée, ou à cause du préfixe data:image/png;base64, manquant alors que le schéma attend un data URI complet), ou une URL non accessible publiquement.
• Paramètre hors plage ou mal placé. Un facteur non accepté par le modèle, ou upscale envoyé au niveau supérieur plutôt qu'à l'intérieur de parameters.
• Type de contenu manquant. Un Content-Type en text/plain ou absent transforme le corps JSON en document non analysable.

413 / 422 / délai d'attente — taille et durée

Des images source très volumineuses peuvent échouer la validation avant même que le modèle ne s'exécute. Réduisez modérément l'entrée, réessayez et confirmez que la forme de la requête est raisonnable avant d'envoyer le fichier en pleine résolution. Pour les délais d'attente, distinguez lent de défaillant : augmentez le délai client une fois, et si l'appel réussit ensuite, la correction relève de la configuration client, pas de la charge utile.

Règle de triage rapide

Si l'erreur mentionne l'authentification, le modèle ou le format d'entrée, vous n'avez pas du tout atteint la logique d'upscaling — aucune valeur de créativité ou de facteur n'entre encore en jeu. Corrigez l'enveloppe, réessayez la plus petite requête possible (une petite image de test, paramètres par défaut), puis commencez seulement à modifier les réglages. Déboguer dans cet ordre évite l'erreur classique : compenser des en-têtes défectueux en ajustant les paramètres.

Construire un test comparatif reproductible

L'upscaling créatif dépend fortement du jugement, donc utilisez un dispositif fixe plutôt que votre mémoire. L'objectif est un petit harnais de test qui répond à « ce réglage est-il vraiment utile ? » sans que vous ayez à réexaminer visuellement d'anciens fichiers.

Entrée fixe

• Une image de test versionnée. Choisissez quelque chose avec des détails récupérables — tissu, végétation, contours de bâtiments. Validez-la à côté du script, afin que chaque exécution et chaque membre de l'équipe utilise la même source.
• Paramètres fixes. Le facteur et les valeurs de créativité vivent dans une liste du script, pas dans votre tête ni dans un message de chat.
• ID de modèle fixe. Même raison que pour la liste de vérification des en-têtes : recraft/creative-upscale est orthographié une fois, dans une constante.

Un exécuteur de matrice minimal

import itertools, json, pathlib

FACTORS = [2, 4]
CREATIVITY = ["preserve", "regenerate"]  # utilisez les valeurs exactes acceptées par la documentation

src = as_data_uri("fixtures/test-input.png")
out_dir = pathlib.Path("runs"); out_dir.mkdir(exist_ok=True)

for factor, mode in itertools.product(FACTORS, CREATIVITY):
    result = creative_upscale(src, upscale=factor, creativity=mode)
    name = f"f{factor}-{mode}"
    save_image(extract_image(result), out_dir / f"{name}.png")
    (out_dir / f"{name}.json").write_text(json.dumps(result, indent=2))
    print(name, "ok")

Deux détails comptent plus que le code. Premièrement, conservez la réponse JSON brute à côté de chaque image — quand un résultat semble incorrect, la réponse vous dit si les paramètres ont été appliqués ou silencieusement ignorés. Deuxièmement, nommez les fichiers d'après les valeurs des paramètres, pour que la liste du répertoire soit la matrice et que vous ne doutiez jamais quel fichier vient de quel réglage.

Comparer de manière uniforme

• Examinez les sorties à la taille d'affichage prévue, pas en zoomant. Un détail créatif impressionnant à 400 % peut sembler artificiel à la taille où l'utilisateur le voit réellement.
• Vérifiez les dimensions par programme dans le cadre de l'exécution. Une incohérence signifie que le facteur n'a pas pris effet — c'est un rapport de bogue sur votre propre requête, pas une question esthétique.
• Jugez selon des critères définis : fidélité à la source contre netteté perçue, choisis selon la catégorie d'asset. Écrivez ce critère à côté de la matrice, afin que la personne suivante sache ce que signifie « meilleur ».

Une fois la matrice stable, le harnais devient un test de régression : relancez-le après toute modification du code client et comparez avec les répertoires d'exécution précédents. Comme chaque appel de ce guide partage la même forme de requête que les autres endpoints d'image de la plateforme, l'exécuteur que vous construisez ici se généralise à tout modèle que vous intégrerez ensuite.