Endpoint /v1/images/edits: Modifica le tue immagini
In questa pagina
Aggiornato il 2 novembre 2026 — Imagine.
grok-imagine-image-qualityè stato rimosso il 2 novembre 2026 (le sue richieste sono gestite da Imagine 2.0 con qualitàlow): gli esempi ora utilizzanogrok-imagine-image(Imagine 1.0) egrok-imagine-image-2.0(Imagine 2.0, con qualitàlow,mediumoauto). Con l’SDK OpenAI,aspect_ratio,resolutionequalitypassano tramiteextra_body, mentre la modifica richiede l’SDK xAI o una richiesta HTTP diretta.
Modifica delle immagini con l’API Grok
Oltre alla generazione, l’API xAI offre un endpoint dedicato per modificare immagini esistenti: POST /v1/images/edits. Questo endpoint ti permette di alterare, trasformare o migliorare le immagini descrivendo le modifiche desiderate in un semplice prompt testuale.
Struttura della richiesta di modifica
La modifica funziona come la generazione, con una differenza che cambia tutto nel modo in cui scrivi i prompt: il prompt descrive la modifica, non l’immagine finale. “Una donna con gli occhiali da sole” rigenera un’intera immagine; “aggiungi occhiali da sole” mantiene la foto e interviene solo su quel punto. Questa è la confusione più comune al primo tentativo e spiega la maggior parte dei risultati deludenti.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Aggiungi un cappello rosso al personaggio",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
Perché usare requests invece dell’SDK OpenAI?
Ecco l’insidia tecnica di questa lezione, e vorrai saperlo prima di perdere un’ora: la compatibilità con l’SDK OpenAI, che funziona perfettamente per la generazione, si ferma alla modifica. L’endpoint di modifica xAI utilizza un formato JSON, mentre il metodo images.edit() dell’SDK invia multipart/form-data. Questa incompatibilità di tipo di contenuto significa che devi usare direttamente l’API REST con la libreria requests per le modifiche.
# NON FUNZIONA con l'API xAI
# client.images.edit(...) # Invia multipart, non JSON
# FUNZIONA: chiamata REST diretta
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Parametri dell’endpoint di modifica
model(obbligatorio):grok-imagine-image(Imagine 1.0) ogrok-imagine-image-2.0(Imagine 2.0, che accetta anchequality)prompt(obbligatorio): descrizione della modifica da applicareimage: oggetto contenente l’URL di una singola immagine sorgenteimages: array di oggetti per più immagini sorgente (mutuamente esclusivo conimage)mask: oggetto contenente l’URL della maschera dell’area da modificaren: numero di varianti da generare (da 1 a 10)response_format:urlob64_json
Tipi di modifiche possibili
Le cinque famiglie seguenti non condividono lo stesso tasso di successo, ed è utile saperlo prima di promettere un risultato. L’aggiunta di elementi e il cambio di atmosfera funzionano molto bene perché si basano su contenuti esistenti. La rimozione è più delicata: il modello deve ricostruire ciò che c’era dietro l’elemento rimosso, ed è qui che la maschera diventa essenziale, delimitando con precisione l’area da ricalcolare.
- Aggiunta di elementi: “Aggiungi occhiali da sole al personaggio”
- Rimozione: “Rimuovi lo sfondo e sostituiscilo con uno sfondo bianco”
- Trasformazione dello stile: “Converti questa foto in un’illustrazione ad acquerello”
- Modifica dell’atmosfera: “Cambia la scena dal giorno alla notte”
- Correzione: “Migliora l’illuminazione e aumenta il contrasto”
# Esempio: cambiare lo stile di un'immagine
payload = {
"model": "grok-imagine-image",
"prompt": "Trasforma questa foto in un'illustrazione in stile fumetto franco-belga",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Esercitazione pratica
Prova a modificare un’immagine in più passaggi. Inizia con una modifica semplice, poi affina:
# Passaggio 1: modifica lo sfondo
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Sostituisci lo sfondo con un tramonto sull'oceano",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Punti chiave
- L’endpoint di modifica è
POST /v1/images/edits - Usa
requestsin Python, non l’SDK OpenAI (incompatibilità di formato) - Puoi fornire fino a 5 immagini sorgente per richiesta
- Il prompt descrive la modifica desiderata in linguaggio naturale
- Entrambi i modelli (Imagine 1.0 e Imagine 2.0) sono disponibili per la modifica; con l’SDK OpenAI,
images.edit()non è supportato da xAI: usa l’SDK xAI o una richiesta HTTP