Come cambiare stile a un'immagine con l'IA: guida al trasferimento di stile image-to-image con l'API hiapi

Cambiare stile a una foto con l'IA — trasformare uno scatto improvvisato in un fotogramma d'animazione, in una foto prodotto da studio o in un'illustrazione ad acquerello — non è un endpoint speciale di "style transfer". È semplicemente una normale chiamata image-to-image: invii un'immagine sorgente e un'istruzione testuale che indica lo stile desiderato, e il modello restituisce una nuova immagine. Ciò che determina se ottieni un cambio di stile pulito o una semi-rigenerazione è come scrivi quell'istruzione, non un qualche parametro regolabile. Questa guida illustra il meccanismo di richiesta sull'API unificata tasks di hiapi, i pattern di prompt che impediscono al cambio di stile di trasformarsi in una nuova immagine, e come scegliere tra due modelli image-to-image verificati in base a quanta libertà creativa desideri.

Cosa ti serve

1. Una chiave API hiapi — ottienila dalla tua dashboard. Va inserita nell'header Authorization: Bearer sk-... di ogni richiesta.
2. Un URL di immagine sorgente accessibile pubblicamente. I server di hiapi scaricano l'immagine da soli, quindi un percorso localhost o un bucket privato senza URL firmato non funzionerà. Gli URL pre-firmati di S3/R2/GCS vanno bene.

Ogni id di modello e campo riportato di seguito è stato riverificato sull'API di produzione prima della pubblicazione, inclusa una sonda di errore forzato per confermare i valori enum attuali.

Perché il cambio di stile richiede una "clausola di conservazione"

Nessuno dei due modelli di questa guida offre un parametro numerico di intensità o forza — inviarne uno (strength: 0.5) viene rifiutato direttamente con l'errore additional properties 'strength' not allowed. L'intensità dello stile è controllata interamente dalla formulazione del prompt, il che significa che un'istruzione come "make this a Studio Ghibli anime frame" dice solo al modello cosa aggiungere, senza dirgli cosa mantenere invariato — l'identità del soggetto, la posa e la composizione possono essere reinterpretate liberamente dal modello.

La soluzione è scrivere sempre due clausole nel prompt:

1. Lo stile target, espresso con un riferimento visivo concreto (un medium, un genere artistico, un aspetto specifico — "anime cel-shading", "1970s film photography", "clean studio product shot on white"), non con un aggettivo vago come "cooler".
2. Una clausola di conservazione esplicita — che nomini ciò che non deve cambiare: "keep the same subject, pose, and composition", "keep the text and logo unchanged", "keep the camera angle".

Un prompt come "Restyle this photo as a woodblock print. Keep the subject's pose, framing, and the position of every object in the scene." fornisce al modello, in un'unica istruzione, un obiettivo e un vincolo: è la leva più efficace per ottenere un cambio di stile anziché una rigenerazione.

Esempio minimo funzionante: curl

Questo esempio usa seedream-5.0-pro/image-to-image, che gestisce molto bene il cambio di stile e ha uno schema rigoroso e completamente verificato:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Restyle this portrait as a watercolor painting with visible brush texture and soft bleeding edges. Keep the subject'\''s pose, expression, and framing exactly as in the source.",
      "image_urls": ["https://your-bucket.example.com/portrait.jpg"],
      "aspect_ratio": "3:4",
      "resolution": "2K"
    }
  }'

aspect_ratio è obbligatorio e proviene da un enum fisso — attualmente 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9. Questo endpoint non ha un'opzione "match source", quindi scegli il valore più vicino alle proporzioni reali dell'immagine sorgente (foto verticale → 3:4 o 9:16, non 16:9) per evitare che il modello aggiunga bordi o ritagli la composizione per adattarla.

Una creazione riuscita restituisce l'id del task in data.taskId:

{ "data": { "taskId": "<your-task-id>" } }

Esegui il polling fino allo stato terminale:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Alla fine data.status sarà success (output in data.output[0].url) oppure fail (dettagli in data.error).

Script Python completo: creazione, polling, download

Usa solo la libreria standard:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the restyle task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": (
            "Restyle this street photo as a 1980s film-grain photograph with warm, "
            "faded colors. Keep the same subject, pose, and every object in the "
            "same position in the frame."
        ),
        "image_urls": ["https://your-bucket.example.com/street.jpg"],
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "restyled.png")
print("saved restyled.png")

Scegliere il modello in base alla libertà creativa desiderata

Entrambi i modelli sono stati riverificati online e nessuno dei due accetta un parametro strength, ma differiscono per quanto puoi controllare l'influenza dell'immagine sorgente:

	seedream-5.0-pro/image-to-image	grok-imagine-quality/image-to-image
Immagini di riferimento	1–10 URL pubblici	1–3 URL pubblici
resolution	1K / 2K (maiuscolo)	1k / 2k (minuscolo) — opzionale
Controllo della composizione	enum fisso aspect_ratio a 8 valori, nessun adattamento automatico	aspect_ratio: "auto" segue l'inquadratura di input
Ideale per	Cambi di stile precisi, con un singolo riferimento, quando conosci già le proporzioni target	Cambi di stile rapidi in cui desideri che l'output erediti l'esatta composizione della sorgente senza dover scegliere tu le proporzioni

Se la tua clausola di conservazione include "same framing" e non vuoi calcolare manualmente il rapporto d'aspetto dell'immagine sorgente, usare grok-imagine-quality/image-to-image con aspect_ratio: "auto" è la strada più diretta — sostituiscilo nella richiesta qui sopra, imposta image_urls a un massimo di 3 elementi e resolution in minuscolo 2k.

Considerazioni per la produzione

Preferisci i callback al polling sui server. Aggiungi un oggetto callback al momento della richiesta e hiapi farà una POST una sola volta allo stato terminale, senza che tu debba fare polling:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Tratta il payload del callback come un segnale e non come fonte di verità — estrai l'id del task e, prima di agire, esegui tu stesso una nuova richiesta GET /v1/tasks/<id>. Per script e notebook, un polling ogni 5 secondi è sufficiente.

Rendi i retry idempotenti. Quando crei un task, memorizza la tua mappatura immagine sorgente → taskId. Se il tuo processo va in crash durante il polling, al riavvio devi ricollegarti al taskId memorizzato anziché inviare di nuovo la richiesta — l'invio ripetuto è un secondo task fatturato.

Errori che incontrerai realmente:

• 401 permission_denied — chiave malformata o mancante. L'header deve essere esattamente Authorization: Bearer sk-....
• 400 INVALID_REQUEST — violazione dello schema, ad esempio aspect_ratio: value must be one of '1:1', '4:3', ... oppure additional properties 'strength' not allowed. Gli schemi di entrambi i modelli sono rigorosi — non applicare parametri di una famiglia di modelli all'altra.
• image_urls must be an array — hai passato una stringa nuda anziché una lista, anche con una sola immagine di riferimento.

Letture correlate

• Riferimento completo campo per campo del modello principale di questa guida: Come usare seedream-5.0-pro/image-to-image.
• Prompt di cambio stile pronti da copiare con confronti reali prima/dopo: Ricette di prompt image-to-image per Grok Imagine Quality.
• Confronto della qualità dell'output tra modelli con la stessa modifica: Le migliori API image-to-image del 2026.
• Prezzi attuali per immagine: pagina dei prezzi.
• Riferimento API completo: documentazione hiapi.

Domande frequenti

Esiste un cursore di intensità o forza per il trasferimento di stile? No. Nessuno dei due modelli di questa guida accetta il campo strength — inviarlo viene rifiutato come proprietà non riconosciuta. L'intensità dello stile è controllata interamente dalla specificità e dalla forza della descrizione dello stile nel prompt.

Come impedisco al modello di cambiare la posa o l'identità del mio soggetto? Aggiungi al prompt una clausola di conservazione esplicita che nomini ciò che deve rimanere invariato — posa, espressione, composizione, posizione degli oggetti. Quando i vincoli sono scritti esplicitamente anziché impliciti, il modello è più conservativo nel cambio di stile.

Posso mantenere automaticamente l'esatto rapporto d'aspetto dell'immagine sorgente? Su grok-imagine-quality/image-to-image sì — imposta aspect_ratio: "auto". Su seedream-5.0-pro/image-to-image non esiste un'opzione automatica; scegli dall'enum fisso il valore più vicino alle proporzioni reali dell'immagine sorgente.

Le mie immagini sorgente devono essere URL pubblici? Devono essere raggiungibili via HTTPS dai server di hiapi. Gli URL pre-firmati di bucket privati vanno bene; percorsi localhost o non autenticati e irraggiungibili no.

Posso generare più varianti di stile da una foto in parallelo? Sì — ogni variante è un task indipendente. Avvia più chiamate POST /v1/tasks con gli stessi image_urls e istruzioni di stile diverse, poi esegui il polling di ciascun taskId separatamente o usa i callback.

Qual è la differenza tra cambio di stile e inpainting o rimozione di oggetti? Il cambio di stile modifica il modo in cui viene resa l'intera immagine mantenendo invariato il contenuto; l'inpainting/rimozione di oggetti modifica aree specifiche mantenendo invariato lo stile di rendering. Sono pattern di prompt diversi sugli stessi endpoint image-to-image — se ciò che ti serve realmente è inpainting e rimozione di oggetti, consulta la guida all'inpainting e alla rimozione di oggetti.