Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Endpoint /v1/images/edits: Modifica le tue immagini

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Principiante
In questa pagina
  1. Modifica delle immagini con l’API Grok
  2. Struttura della richiesta di modifica
  3. Perché usare requests invece dell’SDK OpenAI?
  4. Parametri dell’endpoint di modifica
  5. Tipi di modifiche possibili
  6. Esercitazione pratica
  7. Punti chiave

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 utilizzano grok-imagine-image (Imagine 1.0) e grok-imagine-image-2.0 (Imagine 2.0, con qualità low, medium o auto). Con l’SDK OpenAI, aspect_ratio, resolution e quality passano tramite extra_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.

5
Immagini sorgente massime
2
Formati di input
JSON
Content-Type richiesto
∞
Cicli di modifica

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) o grok-imagine-image-2.0 (Imagine 2.0, che accetta anche quality)
  • prompt (obbligatorio): descrizione della modifica da applicare
  • image: oggetto contenente l’URL di una singola immagine sorgente
  • images: array di oggetti per più immagini sorgente (mutuamente esclusivo con image)
  • mask: oggetto contenente l’URL della maschera dell’area da modificare
  • n: numero di varianti da generare (da 1 a 10)
  • response_format: url o b64_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 requests in 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