Come usare l'API Recraft Creative Upscale: curl, Python e un'esecuzione reale

TL;DR

• recraft/creative-upscale ingrandisce l'immagine e ne ridisegna texture e dettagli. Il corpo della richiesta ha un solo campo, image_url. Nessun prompt, nessuna impostazione di scala.
• Segue il flusso unificato /v1/tasks: POST per ottenere un taskId, polling con GET /v1/tasks/<taskId>, download da data.output[0].url.
• Nella nostra esecuzione, un PNG da 1254×1254 è tornato dopo circa 60 secondi come WebP da 4096×4096, circa 19,8 MB. Metti in conto i tempi di attesa e la dimensione del file.

Cosa ti serve

Una hiapi API key dalla console, e un URL di immagine accessibile pubblicamente. La pagina del modello elenca i limiti di input: PNG consigliato, massimo 20 MB, da 256 a 4096 px per lato, massimo 16 MP.

Se hai bisogno che testo, logo o dettagli di prodotto restino identici, usa Recraft Crisp Upscale. Creative Upscale ridisegna, quindi i piccoli elementi possono cambiare.

La richiesta curl minima

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 risposta è un handle di attività:

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

Esegui il polling finché data.status non è success:

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

Python: inviare, fare polling, salvare

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")

In produzione due dettagli sono importanti. Primo, dopo un timeout non inviare mai di nuovo la richiesta: ogni invio crea una nuova attività fatturata, quindi conserva il taskId e continua a fare polling su quello. Secondo, salva subito il file; l'URL di output contiene un expireAt e l'host è temporaneo.

Note per la produzione

• Usa i callback per i processi in batch. Invece del polling, puoi passare callback: {"url": "...", "when": "final"} nel corpo dell'attività, così hiapi ti chiama al termine. Usa taskId come chiave di deduplicazione.
• Un intervallo di polling di 5 secondi basta. Un'attività richiede circa un minuto, quindi fare polling più spesso aggiunge solo richieste.
• Valida l'URL prima di inviare. La piattaforma rifiuta in anticipo gli URL malformati (vedi sotto), ma un URL https:// non raggiungibile è un altro tipo di errore, che faresti meglio a intercettare in anticipo dalla tua parte con una rapida richiesta HEAD.

Cosa abbiamo visto in un'esecuzione reale

Abbiamo eseguito una richiesta reale usando l'immagine di input di esempio della pagina del modello (un PNG da 1254×1254 di una baita di montagna).

Elemento	Osservazione
Risposta all'invio	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
Sequenza degli stati	handling → archiving → success
Tempo da created a completed	61 secondi (1792721625 → 1792721686)
Output	Un'immagine, WebP, https://temp.hiapi.ai/.../...-0.webp, con un expireAt a circa 7 giorni
Dimensione input	PNG 1254×1254, 2,7 MB
Dimensione output	WebP 4096×4096, circa 19,8 MB

Cose da sapere da quell'esecuzione:

1. La fase archiving non ha ancora output. Prima che il risultato venga spostato nello storage, l'attività riporta completed e status: "archiving" per alcuni polling. Solo status == "success" porta con sé output[0].url, quindi non leggere l'URL alla prima volta che vedi il timestamp completed.
2. Il risultato non è un 2× pulito. Un input da 1254 px è diventato 4096 px, circa 3,3× per lato. La pagina del modello mostra la stessa coppia e non espone alcun campo di scala, quindi metti in conto che la dimensione dell'output la decide il modello, non tu. Se ti serve esattamente 2×, Crisp Upscale è l'endpoint che rispetta questa convenzione.
3. Il file di output è grande. 19,8 MB per un'immagine superano il limite di input di 20 MB che ti permetterebbe di reinviarla direttamente, quindi non concatenare un secondo passaggio sull'output senza ridimensionarlo.
4. I dettagli vengono ridisegnati, non solo nitidizzati. La descrizione della pagina del modello per questa coppia di immagini dice che composizione, illuminazione e colori sono in gran parte conservati, mentre tronchi, muratura e ringhiere vengono ridisegnati e alcuni piccoli elementi (ad esempio un albero accanto al portico) cambiano. Rivedi l'output prima di sostituire asset di brand.
5. Un URL errato fallisce rapidamente. Inviando "image_url": "not-a-url" si ottiene subito HTTP 400: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}. Quel pattern è l'unico controllo che abbiamo verificato; non abbiamo testato il minimo di 256 px né il limite di 16 MP.

Abbiamo eseguito una sola attività, quindi il dato di 61 secondi è un singolo campione, non un benchmark.

Creative Upscale o Crisp Upscale?

Entrambi accettano solo un image_url e non richiedono prompt. La differenza sta in come trattano i pixel e nel prezzo.

	Creative Upscale	Crisp Upscale
Id modello	recraft/creative-upscale	recraft/crisp-upscale
Comportamento	Ingrandisce e ridisegna texture e dettagli	Raddoppia larghezza e altezza, conservando contenuto e testo
Ideale per	Vecchie illustrazioni, immagini artistiche piccole o a bassa risoluzione	Foto di prodotto, poster con testo, asset di design
Prezzo	Molto più alto per immagine; vedi prezzi	Vedi l'articolo sui prezzi di Crisp

Il prezzo per immagine di Creative Upscale è molto più alto di quello di Crisp (confronta i numeri aggiornati nella pagina dei prezzi), quindi usalo solo quando desideri davvero che i dettagli vengano rigenerati. Per un flusso di lavoro generico sulla risoluzione tra modelli diversi, vedi Aumentare la risoluzione delle immagini con hiapi.

Correlati

• Pagina del modello Recraft Creative Upscale
• Guida all'API Recraft Crisp Upscale
• Guida all'API Recraft Remove Background: prima ingrandisci, poi ritaglia il soggetto
• Aumentare la risoluzione delle immagini con l'API hiapi
• Prezzi di hiapi

FAQ

Serve un prompt? No. La pagina del modello descrive un input a immagine singola, senza prompt né altre impostazioni, e la nostra richiesta ha usato solo image_url.

Posso scegliere la dimensione dell'output? Non tramite l'API. Non c'è alcun campo di scala; il nostro input da 1254 px è tornato a 4096 px.

Testo e logo vengono conservati? Non è garantito. I dettagli vengono rigenerati e i piccoli elementi possono cambiare, quindi per gli asset con testo usa Crisp Upscale.

Che formato di output otterrò? Nella nostra esecuzione è stato WebP, consegnato da un URL temporaneo che scade, quindi scaricalo subito.

Quanto tempo ci vuole? La nostra singola esecuzione ha richiesto circa un minuto; costruisci il tuo client aspettandoti attese di questo ordine di grandezza.