Comment utiliser l'API Recraft Creative Upscale : curl, Python et une exécution réelle

TL;DR

• recraft/creative-upscale agrandit une image et redessine ses textures et ses détails. Le corps de la requête ne contient qu'un seul champ : image_url. Pas de prompt, pas de réglage d'échelle.
• Il suit le flux unifié /v1/tasks : POST pour obtenir un taskId, interroger GET /v1/tasks/<taskId>, puis télécharger depuis data.output[0].url.
• Lors de notre exécution, un PNG de 1254×1254 a été renvoyé après environ 60 secondes sous forme de WebP 4096×4096, environ 19,8 Mo. Prévoyez le temps d'attente et la taille du fichier.

Ce dont vous avez besoin

Une clé d'API hiapi obtenue depuis la console, ainsi qu'une URL d'image accessible publiquement. La page du modèle indique les limites d'entrée : PNG recommandé, 20 Mo maximum, 256 à 4096 px par côté, 16 MP maximum.

Si vous avez besoin que le texte, les logos ou les détails produits restent intacts, utilisez plutôt Recraft Crisp Upscale. Creative Upscale redessine, donc les petits éléments peuvent changer.

Requête curl minimale

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

La réponse est un identifiant de tâche :

{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"},"message":"success"}

Interrogez-la jusqu'à ce que data.status vaille success :

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python : soumettre, interroger, enregistrer

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: keep polling the SAME taskId
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

Deux détails importants en production. Premièrement, ne soumettez jamais à nouveau après un délai d'attente : chaque soumission crée une nouvelle tâche facturée, donc conservez le taskId et interrogez-le à nouveau. Deuxièmement, enregistrez le fichier immédiatement ; l'URL de sortie comporte un expireAt et l'hôte est temporaire.

Points d'attention en production

• Utilisez des callbacks pour les tâches par lots. Au lieu d'interroger, vous pouvez passer callback: {"url": "...", "when": "final"} dans le corps de la tâche pour que hiapi vous appelle à la fin de la tâche. Utilisez le taskId comme clé de déduplication.
• Un intervalle d'interrogation de 5 secondes suffit. Une tâche prend environ une minute, donc interroger plus souvent ne fait qu'ajouter des requêtes.
• Validez l'URL avant de soumettre. La plateforme rejette d'emblée les URL mal formées (voir ci-dessous), mais une URL https:// inaccessible est un autre type d'échec, mieux capturé de votre côté avec une rapide requête HEAD.

Ce que nous avons observé lors d'une exécution réelle

Nous avons exécuté une vraie requête avec l'image d'entrée d'exemple de la page du modèle (un PNG de 1254×1254 représentant un chalet de montagne).

Élément	Observation
Réponse de soumission	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
Séquence des statuts	handling → archiving → success
Durée de created à completed	61 secondes (1792721625 → 1792721686)
Sortie	une image, WebP, https://temp.hiapi.ai/.../...-0.webp, avec un expireAt à environ 7 jours
Taille d'entrée	PNG 1254×1254, 2,7 Mo
Taille de sortie	WebP 4096×4096, environ 19,8 Mo

Ce qu'il faut retenir de cette exécution :

1. La phase archiving n'a pas encore d'output. Avant que le résultat ne soit déplacé vers le stockage, la tâche signale completed avec status: "archiving" pendant quelques interrogations. Seul status == "success" comporte output[0].url, donc ne lisez pas l'URL dès la première fois que vous voyez l'horodatage completed.
2. Le résultat n'est pas un doublement propre. Une entrée de 1254 px est devenue 4096 px, soit environ 3,3 fois par côté. La page du modèle montre la même paire et n'expose aucun champ d'échelle, donc attendez-vous à ce que la taille de sortie soit décidée par le modèle, pas par vous. Si vous avez besoin d'exactement 2×, Crisp Upscale est le point de terminaison qui respecte cette convention.
3. Le fichier de sortie est volumineux. Une image de 19,8 Mo dépasse la limite d'entrée de 20 Mo qui vous permettrait de la renvoyer directement, donc ne chaînez pas une seconde passe sur la sortie sans la redimensionner.
4. Les détails sont redessinés, pas seulement accentués. La description de cette paire d'images sur la page du modèle indique : la composition, la lumière et les couleurs sont largement préservées, tandis que les rondins, la maçonnerie et les garde-corps sont redessinés, et certains petits éléments (par exemple un arbre près du porche) changent. Examinez la sortie avant de remplacer des éléments de marque.
5. Une URL erronée échoue rapidement. Envoyer "image_url": "not-a-url" renvoie immédiatement HTTP 400 : {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}. Ce motif est la seule vérification que nous avons validée ; nous n'avons pas testé le minimum de 256 px ni le plafond de 16 MP.

Nous n'avons exécuté qu'une seule tâche, donc le chiffre de 61 secondes est un échantillon unique, pas un benchmark.

Creative Upscale ou Crisp Upscale ?

Les deux n'acceptent qu'un image_url et ne nécessitent pas de prompt. Ils diffèrent par leur traitement des pixels et par leur prix.

	Creative Upscale	Crisp Upscale
ID du modèle	recraft/creative-upscale	recraft/crisp-upscale
Comportement	Agrandit et redessine les textures et les détails	Double la largeur et la hauteur, préserve le contenu et le texte
Idéal pour	Anciennes illustrations, illustrations de petite taille ou à basse résolution	Photos de produits, affiches avec du texte, éléments de design
Prix	Beaucoup plus élevé par image ; voir la tarification	Voir l'article sur la tarification de Crisp

Le prix par image de Creative Upscale est bien plus élevé que celui de Crisp (comparez les chiffres à jour sur la page de tarification), donc ne l'utilisez que si vous souhaitez réellement que les détails soient régénérés. Pour un flux de travail générique de résolution d'image tous modèles confondus, voir Augmenter la résolution d'image avec hiapi.

Articles liés

• Page du modèle Recraft Creative Upscale
• Guide de l'API Recraft Crisp Upscale
• Guide de l'API Recraft Remove Background : agrandissez d'abord, puis détourez le sujet
• Augmenter la résolution d'image avec l'API hiapi
• Tarification hiapi

FAQ

Ai-je besoin d'un prompt ? Non. La page du modèle décrit une entrée composée d'une seule image, sans prompt ni autre réglage ; notre requête n'a utilisé que image_url.

Puis-je choisir la taille de sortie ? Pas via l'API. Il n'y a pas de champ d'échelle ; notre entrée de 1254 px est revenue en 4096 px.

Le texte et les logos sont-ils préservés ? Ce n'est pas garanti. Les détails sont régénérés et les petits éléments peuvent changer, donc utilisez Crisp Upscale pour les éléments contenant du texte.

Quel format de sortie vais-je obtenir ? Lors de notre exécution, du WebP, livré depuis une URL temporaire qui expire, donc téléchargez immédiatement.

Combien de temps cela prend-il ? Environ une minute lors de notre exécution unique ; dimensionnez votre client pour ce niveau d'attente.