Come si usa l'API Recraft Crisp Upscale? Un solo campo per ingrandire 2 volte

TL;DR

• Recraft Crisp Upscale (recraft/crisp-upscale) fa una sola cosa: raddoppia larghezza e altezza dell'immagine, rendendo bordi e texture più nitidi, mantenendo intatti contenuto e testo.Nessun prompt, il body della richiesta contiene solo un image_url.Apri la pagina del modello, carica un'immagine e provalo: i nuovi utenti ricevono 200 crediti alla registrazione.
• $0.004 per immagine: 1.000 immagini a $4.00, con $10 se ne ottengono circa 2.500; la dimensione dell'immagine di input non influisce sul prezzo (prezzi completi nella pagina dei prezzi).
• La chiamata passa dall'interfaccia /v1/tasks di HiAPI: invia il task e ottieni taskId, poi interroga il risultato e, in caso di successo, scarica da output[0].url (JPEG, senza canale alfa).

Cosa sa fare

• Ingrandimento fedele, non ridisegno: texture del quadrante, rughe della pelle, scritte piccole dei poster diventano più chiare, ma contenuto, composizione e testo non cambiano di una virgola: i materiali con testo non vengono «trasformati in un'altra immagine».
• Si controlla con un solo campo: in image_url passi un indirizzo pubblico (JPEG / PNG / WebP, ≤10 MB), senza prompt e senza opzioni di fattore di scala.
• Adatto a immagini prodotto, poster con testo, materiali di design: qualsiasi scenario in cui «l'originale è già giusto, solo la risoluzione non basta».
• Anche gli scenari non adatti sono chiari: se vuoi dettagli ridisegnati a livello 4K o vuoi cambiare anche il contenuto, usa il ridisegno generativo (vedi anche la guida in inglese per aumentare la risoluzione con modelli image-to-image); Crisp Upscale ingrandisce solo di 2 volte, senza ridisegnare il contenuto.
• Restituisce 1 JPEG; per un risultato trasparente prima ingrandisci, poi rimuovi lo sfondo (per l'uso della rimozione sfondo vedi la guida in inglese sulla rimozione dello sfondo).

Ecco una coppia reale «originale → 2x»:

Originale 640×640	Risultato ingrandito 1280×1280

recraft/crisp-upscale, 640×640 → 1280×1280, $0.004. La ghiglioscé del quadrante, la cassa in acciaio spazzolato e le scritte piccole del quadrante restano nitide anche al doppio delle dimensioni.

Apri la pagina del modello e caricane una per provare →

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → carica l'immagine → clicca ingrandisci, $0.004 per immagine.

API in 3 passi: invia con POST /v1/tasks → ottieni taskId → interroga con GET /v1/tasks/<taskId> e, dopo success, scarica. Per il batch basta ripetere questi tre passi, un task per immagine.

curl: la prima immagine

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft/crisp-upscale",
  "input": {
    "image_url": "https://static.hiapi.ai/gallery/2026/10/4fdfd6b43b638849.jpg"
  }
}'

Il body della richiesta è tutto qui: qualsiasi campo in più (come prompt, scale) restituisce direttamente un 400.

Python: invio, polling, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft/crisp-upscale",
    "input": {
        "image_url": "https://example.com/your-image.jpg",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # indirizzo temporaneo, scarica e salva al più presto
    img = requests.get(image_url, timeout=60)
    with open("upscaled.jpg", "wb") as f:
        f.write(img.content)
    print("saved upscaled.jpg")

Tabella dei parametri

Campo	Obbligatorio	Valori	Descrizione
image_url	Sì	Indirizzo http/https pubblico	JPEG / PNG / WebP, singola ≤10 MB

Solo questo campo. Il fattore di ingrandimento è fisso a 2x in larghezza e altezza, non selezionabile; niente prompt, niente parametri per il formato di output.

Gli errori che incontrerai

Codice di stato	Significato	Come risolvere
400 INVALID_REQUEST	image_url mancante, non è un indirizzo http/https, oppure sono stati passati campi inesistenti come prompt / scale	Lascia nel body della richiesta solo image_url
402 INSUFFICIENT_QUOTA	Saldo insufficiente (nessun addebito)	Ricarica e riprova
429 RATE_LIMITED	Limite di frequenza raggiunto	Riduci la frequenza di invio
409 / 422 IDEMPOTENCY_KEY_*	Invio duplicato con la stessa chiave di idempotenza	Usa un nuovo Idempotency-Key

In caso di fallimento allo stato finale ci sono anche codici come TASK_FAILED, TASK_TIMEOUT; i fallimenti non comportano addebiti.

Da sapere prima della messa in produzione

• Callback: passa al livello superiore del body "callback": {"url": "https://..."} per ricevere la notifica automatica allo stato finale.
• Salva subito: output[0].url è un indirizzo temporaneo, scarica appena lo ricevi.
• Durata: di solito da 10 secondi a circa 1 minuto per immagine, non impostare intervalli di polling troppo brevi.
• Canale alfa: l'output è JPEG senza trasparenza; per materiali con sfondo trasparente prima ingrandisci, poi rimuovi lo sfondo (se inverti l'ordine, i bordi del ritaglio risultano sfocati).
• Il conto per i batch è semplice: ingrandire tutte e cinque le immagini di un SKU costa $0.02; un ciclo su 1.000 materiali dell'intero negozio costa $4.00, basta inviare in batch, ogni immagine ha il proprio tempo di elaborazione.
• La qualità dell'originale determina il limite: l'ingrandimento 2x rende i bordi più nitidi, ma le parti sfocate dell'originale non generano dettagli dal nulla; per i materiali critici fai prima una prova con un'immagine e poi procedi in batch.

Domande frequenti

È davvero solo 2x?

Sì. Larghezza e altezza raddoppiano (640×640 → 1280×1280, 480×640 → 960×1280), il fattore è fisso, non esiste l'opzione 4x; se serve più grande, ingrandisci di nuovo il risultato.

Il testo nell'immagine cambia?

No. Nei poster con testo i caratteri restano identici dopo l'ingrandimento: nessuna riscrittura, nessun testo aggiunto.

Quanto costa un'immagine?

$0.004 per immagine, 1.000 immagini a $4.00; la dimensione dell'immagine di input non influisce sul prezzo. I fallimenti non comportano addebiti e gli errori di validazione dei parametri non entrano nella fatturazione.

Si può passare base64?

No. image_url richiede un indirizzo http/https pubblico; per i file locali prima caricali sul tuo storage e poi fornisci l'indirizzo.

Quanto tempo serve per un'immagine?

Di solito da 10 secondi a circa 1 minuto; i task in batch vengono messi in coda in base al numero di immagini, se hai fretta invia a lotti.

Passo successivo: prendi un'immagine del tuo prodotto e ingrandiscila sulla pagina del modello per vedere l'effetto; cinque coppie reali «originale → 2x» sono nella pagina dei casi; il confronto con il ridisegno generativo sulla stessa immagine originale è nella pagina di confronto.