Come usare recraft/creative-upscale tramite l'API HiAPI: guida alle richieste con curl e Python

Il ruolo di recraft/creative-upscale nel flusso di lavoro degli sviluppatori

recraft/creative-upscale è un endpoint image-to-image: invii un'immagine esistente e il modello restituisce una versione più grande, ricostruita dal modello stesso. La parola chiave qui è creativo (creative). Un classico passaggio di upscaling (bilineare, Lanczos o un modello di super-risoluzione generico) preserva l'input il più fedelmente possibile. L'upscaling creativo invece consente di rigenerare dettagli che non sono mai esistiti nei pixel di origine: i bordi vengono risintetizzati, le texture inferite, le piccole aree sfocate possono essere nitidizzate in contenuti plausibili, non solo interpolati.

Questo lo distingue da un semplice strumento di ridimensionamento e ne determina una collocazione diversa nella pipeline.

Quando usarlo

• Aggiornamento degli asset. Una miniatura o un'immagine di prodotto di vecchia generazione deve essere mostrata a una dimensione di visualizzazione maggiore, e un ridimensionamento normale apparirebbe sfocato rispetto a elementi nativi alla stessa risoluzione.
• Lavori su reference e rendering. Concept art, storyboard o immagini segnaposto devono essere mostrati a grandi dimensioni senza rivelare la loro origine a bassa risoluzione.
• Upscaling all'interno di un ciclo di generazione. Hai generato un'immagine a una dimensione di lavoro ridotta e vuoi un asset finale senza rieseguire l'intera pipeline di generazione su una tela più grande.

Quando non usarlo

Se l'esigenza è la fedeltà byte per byte — scansioni d'archivio, documenti, atlas di texture in cui i valori dei pixel sono i dati — non usare un modello creativo. I dettagli rigenerati sono supposizioni plausibili, non ricostruzioni; per scopi di misurazione o archiviazione, questa supposizione è un difetto. In questi casi usa un ricampionatore deterministico e lascia il modello creativo agli output percettivi.

La forma della chiamata

L'endpoint segue lo stesso schema di richiesta degli altri endpoint immagine di HiAPI: una POST JSON autenticata verso il percorso del modello, contenente un'immagine di input e un oggetto di parametri. Se hai già integrato qualsiasi altro modello immagine sulla piattaforma, questo modello mentale si trasferisce direttamente — è proprio questo il senso di instradare queste chiamate attraverso un'interfaccia unificata. Una chiamata curl funzionante diventa il tuo modello per ogni endpoint immagine che incontrerai in seguito.

Un modo utile di intendere questo passaggio: consuma un'immagine di cui ti fidi già (composizione, contenuto e colori sono già decisi) e restituisce una variante più grande e più dettagliata. Le decisioni sul contenuto appartengono alle fasi a monte; recraft/creative-upscale è la fase di rifinitura.

Prerequisiti e configurazione dell'endpoint

Prima di scrivere la prima richiesta, raccogli quattro cose. Nessuna richiede un SDK speciale — l'intera integrazione è pura comunicazione HTTPS con un corpo di richiesta JSON.

1. Chiave API

Ti serve una chiave API HiAPI con accesso ai modelli immagine. Trattala come un segreto: caricala da una variabile d'ambiente, non incollarla negli script e non salvarla mai nel repository.

export HIAPI_API_KEY="your-key-here"

La chiave viene trasmessa tramite un header, non nell'URL né nel corpo JSON. Tenerla fuori dalla query string significa anche tenerla fuori dalla cronologia della shell e dai log dei proxy.

2. URL di base

L'URL di base è il tuo host dell'API HiAPI. Tutte le chiamate ai modelli sono percorsi relativi sotto di esso, quindi puoi impostarlo come variabile e riutilizzarlo in ogni script:

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

Consulta la documentazione di riferimento dell'API della piattaforma per ottenere l'URL di base canonico e il prefisso del percorso del tuo account, e salvali in questa singola variabile. Così un cambio di host o di versione è una modifica di una riga.

3. Identificatore del modello

L'ID del modello è un segmento di percorso e deve essere scritto esattamente come pubblicato: recraft/creative-upscale. Contiene una barra, cosa che conta in alcuni strumenti — la sezione di debug lo spiega in dettaglio. Maiuscole e minuscole e i trattini contano. Un carattere errato produce un errore di modello non trovato che, se si legge il messaggio solo superficialmente, sembra un problema di autenticazione.

4. Immagine di test

Tieni un'immagine sul disco e conosci il suo percorso esatto e il tipo MIME. Alla prima esecuzione usa un file piccolo, così un fallimento è chiaramente un problema di richiesta e non di dimensione del payload o di timeout. Riutilizzerai la stessa immagine per le esecuzioni di confronto, quindi scegli qualcosa con dettagli visibili (tessuto, vegetazione, insegne senza testo), non un gradiente piatto.

Checklist degli header

Ogni richiesta da qui in avanti porta gli stessi header:

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

Se invii l'immagine nel corpo JSON come base64 o data URI, questi due header sono sufficienti. Se invece carichi prima il file per ottenere un URL, tratta quel caricamento come una chiamata separata e conserva l'URL generato separatamente dalla richiesta al modello.

Con chiave, URL di base, ID del modello e un'immagine di test, puoi effettuare una chiamata reale in meno di un minuto.

Una richiesta funzionante con curl

Ecco una chiamata eseguibile direttamente. Sostituisci il valore dell'immagine con il tuo input — può essere un URL pubblicamente raggiungibile o un data URI codificato in base64, a seconda di ciò che la modalità di input del modello accetta.

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

Usare -o per scrivere la risposta in un file, invece di lasciarla fluire nel terminale, mantiene il JSON integro per il parsing e rende la chiamata scriptabile.

Cosa fa ogni parte

• -X POST — l'endpoint è POST; una GET restituisce un errore di metodo, facilmente fraintendibile come problema di permessi.
• URL — l'URL di base, poi il percorso del modello con l'ID completo. Poiché l'ID stesso contiene una barra, il percorso ha due segmenti dopo la collezione di modelli; mantienilo come un'unica stringa e, a meno che la documentazione non indichi che è il comportamento previsto, non lasciare che la libreria client lo ricodifichi in recraft%2Fcreative-upscale.
• Authorization — il token bearer. Se vedi 401 su questo esatto comando, la chiave o il formato dell'header sono errati; nessun altro contenuto del corpo è ancora stato validato.
• Content-Type: application/json — obbligatorio. Senza di esso, alcuni gateway trattano il corpo come form data e la richiesta non arriva mai al modello.
• input.image — l'immagine sorgente. Durante l'iterazione preferisci un URL: mantiene il comando breve e le differenze chiare.
• parameters.upscale — il controllo di upscaling. Parti da un fattore moderato e aumentalo dopo aver confermato la risposta.

Due varianti utili

Per inviare un file locale in base64 invece di un 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

Per vedere insieme il codice di stato HTTP e il corpo della risposta durante il debug, aggiungi -w '\nHTTP %{http_code}\n' e rimuovi -o.

Considera questo singolo comando come il tuo modello. Una volta che restituisce un'immagine, ogni modifica successiva — fattore diverso, immagine sorgente diversa — è solo la modifica di due campi, non una nuova integrazione.

La stessa richiesta in Python

La versione Python non dovrebbe essere un copia-incolla del corpo curl; dovrebbe essere una piccola funzione riutilizzabile, così le successive esecuzioni di confronto richiedono una sola chiamata ciascuna. Usa solo la libreria standard — nessun SDK.

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:
    """Invia un'immagine a recraft/creative-upscale e restituisce il JSON analizzato."""
    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])

Perché questa forma

• Configurazione da variabili d'ambiente. URL di base e chiave vengono letti una volta all'import, quindi nel file non compare alcun segreto e cambiare ambiente richiede un solo export.
• Una funzione, una responsabilità. creative_upscale riceve un riferimento all'immagine e un fattore, e restituisce il JSON analizzato. Tutte le informazioni sui parametri restano visibili nel punto di chiamata.
• Timeout esplicito. I modelli immagine richiedono più tempo degli endpoint di testo. Imposta un timeout intenzionalmente, invece di ereditare un default troppo breve, e mantienilo abbastanza lungo perché una chiamata lenta ma riuscita non venga ritentata inutilmente.
• Una funzione ausiliaria per i file locali. as_data_uri significa che puoi passare un URL o un percorso locale senza modificare la logica della richiesta.

Se preferisci un client basato su sessione

La stessa chiamata con httpx richiede solo due righe di sostituzione — costruisci un client, imposta l'header Authorization predefinito, poi esegui post del corpo JSON. Le invarianti importanti non cambiano: l'ID del modello resta un unico segmento di percorso non codificato, la chiave resta negli header e il corpo mantiene la suddivisione input / parameters. Se rispetti questi tre punti, il tuo client è intercambiabile con qualsiasi altro client sulla piattaforma.

Quando lo colleghi a una pipeline, restituisci il dizionario analizzato e lascia che sia il chiamante a decidere come persistere l'immagine — questa separazione rende riutilizzabile la gestione della risposta della prossima sezione.

Parametri di upscaling e creatività

I valori che invii contano meno di dove li invii. Prima assicurati che la posizione sia corretta, poi ottimizza i numeri.

Due contenitori, un contratto

Ogni richiesta si divide in:

• input — l'immagine stessa. L'oggetto dell'operazione. Nulla che riguardi il comportamento del modello va qui.
• parameters — i controlli. Il fattore di upscaling e le impostazioni di creatività appartengono a questo oggetto, come fratelli.

Questa suddivisione è il contratto. La prima esecuzione deve confermare che il modello accetta il tuo posizionamento — cioè che la chiamata restituisca almeno un'immagine — prima di iniziare a ottimizzare i valori. Se un parametro finisce nel contenitore sbagliato, di solito ottieni un'immagine generata con i valori predefiniti, oppure un errore di validazione che indica un campo sconosciuto. In entrambi i casi è un errore di posizionamento, non di qualità, e inseguire le impostazioni di qualità non lo risolverà.

Il fattore di upscaling

Il fattore controlla la dimensione dell'output rispetto all'input. Alcune considerazioni:

• È un moltiplicatore, quindi costo e latenza crescono con esso. Passare da un fattore moderato al massimo non è un passo lineare nei tempi di rendering. Tratta ogni aumento come un nuovo esperimento, non come il trascinamento di uno slider.
• La risoluzione di input conta comunque. Quando esiste già una certa struttura, il modello creativo ha più margine di manovra. Un input minuscolo gli dà più libertà di inventare, il che a volte è l'obiettivo e a volte è un imprevisto.
• Scegli il fattore in base alla dimensione target, non al massimo. Se l'immagine richiede 2× per stare nel suo spazio, richiedi 2×. Richiedere il massimo e poi ridurre spreca i benefici e li paghi comunque.

Il controllo della creatività

La creatività è la manopola che decide quanto il modello può sostituire (invece di ingrandire). Impostazioni basse si comportano più come un upscaling fedele; impostazioni alte lasciano che il modello risintetizzi in modo più aggressivo, il che può salvare una sorgente sfocata o a blocchi, ma può anche introdurre dettagli che non desideri.

Considera questo parametro come una leva di fedeltà, con due letture concrete agli estremi:

• Preserva — loghi, volti, immagini di cataloghi di prodotti, qualsiasi cosa che lo spettatore possa confrontare con l'originale.
• Rigenera — concept art, sfondi, texture, immagini decorative, dove la plausibilità conta più della precisione.

Metodo di lavoro

Cambia un parametro alla volta, mantieni fisso l'input e registra i valori insieme agli output. Una piccola matrice — la stessa immagine con due fattori, e per ogni fattore due impostazioni di creatività — basta a caratterizzare l'endpoint sul tuo contenuto. Non prendere in prestito i valori "migliori" di altri; i modelli creativi interagiscono fortemente con l'input, e impostazioni adatte a una fotografia raramente lo sono per un'illustrazione piatta.

Se un valore viene rifiutato direttamente invece di produrre un risultato scadente, è il contratto che ti indica il dominio del parametro — consulta il riferimento dei parametri dell'endpoint per gli intervalli accettabili, invece di indovinare.

Leggere la risposta e salvare l'immagine

Analizza la risposta in modo difensivo. Il tipo di payload fa parte del contratto, ma può variare tra URL e blocco base64 inline, e il tuo client non dovrebbe andare in crash a seconda di quale riceve.

Prima, guarda il JSON grezzo

Prima di scrivere un parser, esegui una volta la chiamata curl con -o response.json e leggi il file. Identifica il campo che contiene l'immagine. Di solito è uno dei seguenti:

• un URL che punta al file generato, oppure
• una stringa inline, di solito base64 o un data URI.

Cerca anche i metadati che vale la pena registrare: dimensioni, l'ID del modello restituito e qualsiasi identificatore utile per aprire una richiesta di supporto.

Una funzione di salvataggio tollerante agli errori

import base64
import pathlib
import urllib.request


def extract_image(result: dict) -> str:
    """Trova il payload dell'immagine qualunque sia la forma restituita."""
    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"nessun campo immagine nella risposta: {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

Il punto non è che questo sia l'unico parser corretto — è che la funzione dichiara le sue assunzioni (data:, http(s)://, base64 puro) e solleva un errore chiaro quando nessuna corrisponde. Quando la forma della risposta cambia, basta aggiornare una funzione, non ogni script che consuma immagini.

Salvataggio sicuro nel flusso 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

Due abitudini da mantenere: scrivi un nuovo nome file a ogni esecuzione, così un fallimento o una scrittura parziale non sovrascrive mai un buon risultato; verifica le dimensioni dell'output dopo il salvataggio — un HTTP 200 riuscito ma con dimensioni inattese significa che i parametri non hanno avuto effetto, cosa molto più facile da scoprire qui che dopo tre fasi della pipeline.

Debug dei guasti più comuni

La maggior parte dei guasti alla prima esecuzione è banale. Affronta questa lista in ordine; copre la grande maggioranza dei casi.

401 / 403 — autenticazione

• La chiave è caricata nella stessa shell in cui esegui il comando? echo $HIAPI_API_KEY dovrebbe stampare un valore non vuoto.
• L'header è esattamente Authorization: Bearer <key> — con lo spazio e la parola Bearer?
• La chiave è finita nell'URL o nel corpo JSON invece che nell'header? Rimettila al suo posto.
• La chiave è limitata ai modelli immagine? Una chiave valida per un'area di prodotto potrebbe non funzionare con questo endpoint.

404 — modello o route non trovati

Questo è quasi sempre un problema di ID del modello. Confronta carattere per carattere con l'identificatore pubblicato recraft/creative-upscale: la barra, le minuscole e il trattino in creative-upscale sono tutti essenziali. Una trappola correlata è l'escaping dell'URL da parte del client — se sulla riga di richiesta vedi recraft%2Fcreative-upscale e la chiamata restituisce 404, il tuo livello HTTP ha codificato la barra; configuralo per non toccare i segmenti di percorso.

Controlla anche di non aver duplicato il prefisso del percorso (ad esempio l'URL di base termina già con il segmento di versione e il percorso lo ripete). Usare una variabile per l'URL di base rende questo facile da individuare.

400 — richiesta compresa ma rifiutata

Leggi il messaggio invece di indovinare. Cause comuni:

• Formato dell'immagine di input errato. Base64 troncato (spesso perché una variabile della shell viene troncata, o perché manca il prefisso data:image/png;base64, mentre la modalità si aspetta un data URI completo), oppure un URL non raggiungibile pubblicamente.
• Parametri fuori intervallo o posizionati male. Un fattore che il modello non accetta, oppure upscale inviato al livello superiore invece che dentro parameters.
• Content-Type mancante. Un Content-Type impostato a text/plain o del tutto assente trasforma il corpo JSON in un documento non analizzabile.

413 / 422 / timeout — dimensioni e durata

Immagini sorgente molto grandi possono fallire la validazione prima ancora che il modello parta. Riduci moderatamente l'input, riprova e conferma che la forma della richiesta sia ragionevole prima di inviare il file a piena risoluzione. Per i timeout, distingui tra lento e fallito: aumenta una volta il timeout del client e, se la chiamata poi riesce, la correzione appartiene alla configurazione del client, non al payload.

Regola di triage rapido

Se l'errore menziona autenticazione, modello o formato dell'input, non hai nemmeno raggiunto la logica di upscaling — non sono ancora coinvolti valori di creatività o fattori. Correggi il wrapper, riprova con la richiesta più piccola possibile (una piccola immagine di test, parametri predefiniti) e solo allora inizia a cambiare le impostazioni. Fare debug in questo ordine previene l'errore classico: compensare header rotti ritoccando i parametri.

Costruire un test di confronto ripetibile

L'upscaling creativo dipende molto dal giudizio, quindi usa un dispositivo fisso invece della memoria. L'obiettivo è un piccolo framework di test che risponda alla domanda "questa impostazione funziona davvero?" senza che tu debba rivedere visivamente vecchi file.

Input fissi

• Un'immagine di test, inserita nel repository. Scegli qualcosa con dettagli recuperabili — tessuto, vegetazione, bordi di edifici. Salvala accanto agli script, così ogni esecuzione e ogni membro del team usa la stessa sorgente.
• Parametri fissi. Il fattore e i valori di creatività vivono in liste nello script, non nella tua testa o nei messaggi di chat.
• ID del modello fisso. Stessa logica della checklist degli header: recraft/creative-upscale scritto una volta, in una costante.

Un esecutore di matrice minimale

import itertools, json, pathlib

FACTORS = [2, 4]
CREATIVITY = ["preserve", "regenerate"]  # usa i valori esattamente come accettati dalla documentazione

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

Due dettagli contano più del codice. Primo, salva la risposta JSON grezza accanto a ogni immagine — quando un risultato sembra sbagliato, la risposta ti dice se i parametri sono stati applicati o silenziosamente ignorati. Secondo, nomina i file in base ai valori dei parametri, così il listato della directory è la matrice e non devi mai dubitare quale file provenga da quale impostazione.

Confrontare in modo fisso

• Guarda l'output alla dimensione di visualizzazione prevista, non ingrandito. Dettagli creativi impressionanti al 400% possono sembrare innaturali alla dimensione che l'utente vede davvero.
• Controlla le dimensioni a livello di codice come parte dell'esecuzione. Una discrepanza significa che il fattore non ha avuto effetto, il che è una segnalazione di bug sulla tua richiesta, non una questione estetica.
• Valuta secondo criteri definiti: fedeltà alla sorgente rispetto a nitidezza percepita, scelti per categoria di asset. Scrivi il criterio accanto alla matrice, così la prossima persona sa cosa significa "meglio".

Una volta che la matrice è stabile, il framework diventa un test di regressione: rieseguilo dopo qualsiasi modifica al codice del client e confrontalo con le precedenti directory di esecuzione. Poiché ogni chiamata di questa guida condivide la stessa forma di richiesta degli altri endpoint immagine della piattaforma, l'esecutore che costruisci qui si generalizza a qualsiasi modello integrerai in seguito.