Come si usa l'API di image-to-image di Grok Image 2.0? Basta un'immagine di riferimento e una frase per modificare l'immagine

Come si usa l'API di image-to-image di Grok Image 2.0? Invia un'immagine di riferimento accessibile pubblicamente insieme a un'istruzione di modifica, inviala con POST /v1/tasks e con il polling ottieni in data.output[0].url l'immagine modificata. Il prezzo è fisso a $0,065 per immagine, 1K e 2K hanno lo stesso prezzo, senza maschere né livelli.

Grok Image 2.0 è già disponibile su HiAPI. Apri la pagina del modello image-to-image, carica un'immagine e potrai modificarla. I nuovi utenti ricevono 200 crediti alla registrazione, sufficienti per 1 generazione image-to-image (130 crediti).

TL;DR

• Che cos'è: grok-imagine-image-2.0/image-to-image, realizzato da xAI, modifica un'immagine con una singola immagine di riferimento e istruzioni in linguaggio naturale: puoi cambiare lo sfondo, aggiungere piccoli oggetti, modificare materiali e colori.
• Quanto costa: $0,065 per immagine, stesso prezzo per 1K / 2K e per low / medium; si paga solo per le immagini generate con successo, in caso di errore il rimborso è automatico. Con $10 si generano circa 153 immagini.
• Come chiamarla al volo: solo prompt e image sono obbligatori; image è una stringa URL, non un array.

Quali parametri ha Grok Image 2.0 image-to-image?

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	stringa	Istruzione di modifica
image	Sì	stringa	URL pubblico di un'immagine JPG / JPEG / PNG / WebP, non un array
resolution	No	1k, 2k	Predefinito 1k
quality	No	low, medium	Predefinito medium; medium offre più dettagli, low è più veloce
aspect_ratio	No	gli stessi 14 valori del text-to-image	Si può passare, ma non ha effetto: il formato di output segue l'immagine di riferimento

Ogni richiesta può modificare una sola immagine di riferimento e un task produce un'immagine; per più immagini invia più task in parallelo. Le richieste con nomi di campo o valori non presenti nella tabella sopra restituiscono 400.

Due percorsi: prova online e API

Prova online (1 minuto)

1. Apri la pagina del modello image-to-image, accedi e carica l'immagine di riferimento.
2. Inserisci l'istruzione di modifica e scegli la risoluzione.
3. Clicca «Esegui» e, a task completato, confronta l'immagine di riferimento con il risultato.

Integrazione API (5 minuti)

1. Crea una API Key nella console.
2. Metti l'immagine di riferimento a un indirizzo accessibile pubblicamente (il tuo CDN o object storage).
3. Invia il task con POST /v1/tasks, poi esegui il polling o imposta un callback.
4. Appena il task è completato, scarica data.output[0].url.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Prova subito un prompt di modifica: sposta l'anziano liutaio dalla bottega piena di trucioli a un mercato soleggiato, lasciando invariata la persona. Genera con questo prompt → (il link precompila solo il prompt; l'immagine di riferimento va caricata nella pagina del modello, scegli 2K come risoluzione)

Immagine di riferimento	Immagine generata

curl e Python: la prima modifica di un'immagine

Imposta prima la API Key:

export HIAPI_API_KEY="sk-..."

Tutte le richieste includono Authorization: Bearer sk-<key>. La modifica delle immagini è asincrona e usa la stessa interfaccia task degli altri modelli HiAPI. L'immagine di riferimento viene recuperata dal server: i percorsi di file locali non vanno bene, serve un URL accessibile pubblicamente.

Passo 1, crea il task:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Restituisce subito taskId:

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

Passo 2, esegui il polling fino allo stato finale:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Controlla data.status: success indica successo, fail indica errore; per gli altri stati continua ad attendere. Esempio di risposta positiva:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Fai attenzione a storage: "temp" e expireAt: l'indirizzo dell'immagine generata è temporaneo, scaricala subito dopo il completamento del task oppure trasferiscila nel tuo object storage. Il formato di output segue l'immagine di riferimento; nell'esempio aspect_ratio è omesso perché non ha effetto.

Versione Python:

Installa prima requests (python3 -m pip install requests) e imposta la HIAPI_API_KEY come sopra. Lo script esegue il polling per un massimo di 10 minuti; allo scadere conserva il taskId per continuare a interrogarlo.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

A cosa fare attenzione prima della messa in produzione?

• Metti prima l'immagine di riferimento sul web pubblico. Se l'immagine caricata dall'utente si trova in un bucket privato o su localhost, la piattaforma non riesce a recuperarla e il task fallisce in modo asincrono; prima di inviare verifica che il link sia accessibile pubblicamente e usa un indirizzo a lunga scadenza (non link firmati che scadono).

• Scrivi l'istruzione come "cosa mantenere, cosa cambiare". Indica prima le parti che devono restare invariate, poi quelle da modificare: più ristretto è l'ambito della modifica, più il risultato è stabile. Per altri esempi vedi i template di prompt per image-to-image.

• Per il batch usa i callback, non un ciclo stretto di polling.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" notifica quando il task raggiunge lo stato finale di successo o errore; il destinatario deduplica in base a taskId.

• Trasferisci subito l'immagine generata. data.output[0].url è un indirizzo temporaneo che scade secondo expireAt.

• Invia un task una sola volta. Dopo aver ricevuto la risposta, salva la corrispondenza tra taskId e il task di business; invii ripetuti possono creare più task e addebitare ciascuno. Se la richiesta di creazione va in timeout senza restituire l'ID, controlla prima i record dei task e poi decidi se reinviare.

• Specifica sempre resolution. Il valore predefinito è 1k; 1K e 2K costano uguale ($0,065), quindi per il risultato finale passa direttamente "2k".

• Gestione degli errori. Controlla prima lo stato HTTP e i campi code e message della risposta, poi leggi data. Gli errori di parametri o autenticazione vanno corretti prima di reinviare; se il task restituisce fail, registra l'errore e interrompi il polling.

Letture correlate

• Pagina del modello text-to-image di Grok Image 2.0: stessa famiglia, genera nuove immagini solo da testo.
• Quanto costa l'API di Grok Image 2.0?
• Integrazione dell'API text-to-image di Grok Image 2.0
• Template di prompt per image-to-image di Grok Image 2.0
• Autenticazione e Avvio rapido

Domande frequenti

image accetta un URL o un array? Un singolo URL come stringa. Passare un array genera un errore di tipo. Se ti serve fondere più immagini, usa un modello che supporta più immagini di riferimento.

Cosa fare se ricevo "additional properties not allowed"? input accetta solo prompt, image, aspect_ratio, resolution e quality. Campi comuni in altri modelli di editing come image_urls, strength, mask, seed e negative_prompt qui non sono disponibili: rimuovili.

Il browser apre l'immagine di riferimento, perché il task può comunque fallire? La piattaforma recupera l'immagine lato server: l'immagine di riferimento deve essere accessibile dalla rete pubblica senza login e i link firmati devono restare validi fino al completamento del recupero. Controlla permessi di accesso, formato e validità del link prima di inviare.

Si possono modificare più immagini alla volta? No, un'immagine in ingresso e una in uscita. Per il batch invia più task in parallelo.

Perché image-to-image costa più di text-to-image? Image-to-image costa $0,065, text-to-image $0,052, il 25% in più, che corrisponde alla capacità di "modificare un'immagine partendo da un'immagine di riferimento".

Per quanto tempo è valido l'indirizzo di output? Lo storage è temporaneo; expireAt nella risposta è un timestamp Unix. Scarica o trasferisci subito l'immagine dopo il completamento del task.

Bisogna attendere il risultato in modo sincrono? No. L'API di creazione restituisce immediatamente dopo l'accodamento del task; per script brevi usa il polling su GET /v1/tasks/<taskId>, in produzione imposta callback.

Modifica ora la tua prima immagine

Imposta prima HIAPI_API_KEY, poi sostituisci l'indirizzo image negli esempi curl e Python con l'URL pubblico della tua immagine. Se vuoi prima vedere l'effetto, apri la pagina del modello image-to-image, carica un'immagine e incolla il prompt qui sopra.