Moderazione, incompatibilità SDK e controllo dei costi
In questa pagina
Aggiornato il 2 novembre 2026 — Imagine.
grok-imagine-image-qualityè stato rimosso il 2 novembre 2026 (le sue richieste sono servite da Imagine 2.0 in qualitàlow): gli esempi ora usanogrok-imagine-image(Imagine 1.0) egrok-imagine-image-2.0(Imagine 2.0, qualitàlow,mediumoauto). Con l’SDK OpenAI,aspect_ratio,resolutionequalitypassano tramiteextra_body, mentre la modifica avviene tramite l’SDK xAI o una richiesta HTTP.
Comprendere i limiti delle API per le immagini
Per costruire applicazioni affidabili con l’API di generazione immagini di Grok, devi conoscerne i limiti: moderazione automatica, incompatibilità con alcuni metodi dell’SDK OpenAI e meccanismi di controllo dei costi.
Moderazione dei contenuti
L’API modera automaticamente i prompt e le immagini generate. Alcuni tipi di contenuto vengono rifiutati:
- Contenuti esplicitamente violenti o cruenti
- Contenuti esplicitamente sessuali
- Contenuti d’odio o discriminatori
- Contenuti che coinvolgono minori in modo inappropriato
Quando scatta la moderazione, l’API restituisce un errore invece di un’immagine.
Gestire i rifiuti della moderazione
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
def generate_safe(prompt, **kwargs):
"""Genera un'immagine gestendo i rifiuti della moderazione."""
try:
response = requests.post(
"https://api.x.ai/v1/images/generations",
headers=headers,
json={"model": "grok-imagine-image", "prompt": prompt, **kwargs}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
except requests.exceptions.HTTPError as e:
if response.status_code == 400:
print(f"Prompt rifiutato dalla moderazione: {prompt[:50]}...")
return None
raise
Migliori pratiche per la moderazione
In pratica, gestisci la moderazione a monte piuttosto che in modo reattivo. Se un prompt legittimo viene bloccato, testa delle variazioni per identificare la parola trigger: «battaglia epica» passerà dove un termine più crudo no, e mappare queste sensibilità evita blocchi ricorrenti. Quando i prompt provengono dai tuoi utenti, aggiungi un pre-filtro lato server prima della chiamata API: intercetta le richieste palesemente fuori norma senza consumare una richiesta e ti mantiene il controllo sul messaggio visualizzato. Perché è proprio quest’ultimo punto a fare la differenza nell’esperienza: un blocco per moderazione non deve mai arrivare all’utente come un errore tecnico grezzo, ma come un messaggio chiaro — «questa richiesta non è conforme ai nostri termini d’uso» — che spiega senza esporre i dettagli dell’API.
Incompatibilità dell’SDK OpenAI per la modifica
Questo è un punto critico: il metodo images.edit() dell’SDK OpenAI non funziona con l’API xAI. L’SDK OpenAI invia i dati come multipart/form-data, mentre l’API xAI si aspetta application/json.
# NON FUNZIONA
from openai import OpenAI
client = OpenAI(api_key=os.getenv("XAI_API_KEY"), base_url="https://api.x.ai/v1")
client.images.edit(
model="grok-imagine-image",
image=open("photo.png", "rb"),
prompt="Edit this image"
)
# → Errore Content-type!
# FUNZIONA: chiamata REST diretta
import requests
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers={
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
},
json={
"model": "grok-imagine-image",
"prompt": "Edit this image",
"image": {"url": "https://exemple.com/photo.jpg"}
}
)
Riepilogo della compatibilità
| Operazione | SDK OpenAI | REST (requests) |
|---|---|---|
| images.generate() | Compatibile | Compatibile |
| images.edit() | Incompatibile | Compatibile |
Controllo dei costi
Monitorare i consumi
Imposta un contatore di spesa nel tuo codice:
class ImageBudgetTracker:
PRICES = {
"grok-imagine-image": 0.02,
"grok-imagine-image-2.0": 0.04, # bassa qualità; media a tariffa griglia
}
def __init__(self, budget_limit=10.0):
self.total_spent = 0.0
self.budget_limit = budget_limit
self.image_count = 0
def can_generate(self, model, n=1):
cost = self.PRICES[model] * n
return (self.total_spent + cost) <= self.budget_limit
def record(self, model, n=1):
cost = self.PRICES[model] * n
self.total_spent += cost
self.image_count += n
def report(self):
remaining = self.budget_limit - self.total_spent
print(f"Immagini generate: {self.image_count}")
print(f"Speso: ${self.total_spent:.2f}")
print(f"Budget residuo: ${remaining:.2f}")
# Utilizzo
tracker = ImageBudgetTracker(budget_limit=5.0)
if tracker.can_generate("grok-imagine-image", n=5):
response = client.images.generate(
model="grok-imagine-image",
prompt="My image",
n=5
)
tracker.record("grok-imagine-image", n=5)
tracker.report()
Ottimizzare i costi
La regola d’oro è separare l’esplorazione dalla produzione. Durante la ricerca del prompt, lavora con Imagine 1.0 ($0.02) con n=3-5 per confrontare le variazioni a costo ridotto; una volta stabilizzato il prompt, passa a Imagine 2.0 con n=1 per il rendering finale. Questa sequenza riserva la tariffa più alta solo alle immagini selezionate.
Due meccanismi completano la configurazione lato applicazione. Primo, una cache dei risultati: se lo stesso prompt ritorna — visual di catalogo, immagini standard rigenerate da più utenti — servi l’immagine già generata invece di pagare una nuova richiesta. Poi le quote, se sono i tuoi utenti a triggerare le generazioni: un limite giornaliero o orario protegge il tuo budget da usi irragionevoli e abusi. Infine, tieni d’occhio i rate limit (300 RPM standard, 30 RPM pro): una pipeline batch che li ignora accumula errori 429 e retry inutili.
Stima del budget mensile
Per un’app con 100 utenti che generano 10 immagini al giorno:
- Imagine 1.0: 100 x 10 x 30 x $0.02 = $600/mese
- Imagine 2.0 in
low: 100 x 10 x 30 x $0.04 = $1.200/mese - Misto (80/20): 24.000 x $0.02 + 6.000 x $0.04 = $720/mese
Endpoint di scoperta dei modelli
Per verificare programmaticamente i modelli immagine disponibili e i loro prezzi:
response = requests.get(
"https://api.x.ai/v1/image-generation-models",
headers={"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"}
)
for model in response.json()["data"]:
print(f"{model['id']} : ${model['image_price']}/immagine, "
f"max prompt : {model['max_prompt_length']} caratteri")
Tariffe al 5 agosto 2026 — i prezzi cambiano regolarmente: prima di qualsiasi calcolo di budget, verifica la griglia attuale sulla pagina ufficiale dei modelli e delle tariffe xAI.
Punti chiave
- La moderazione è automatica: gestisci i rifiuti nel tuo codice
images.edit()dell’SDK OpenAI è incompatibile con xAI: usarequestsimages.generate()dell’SDK OpenAI funziona normalmente- Implementa un tracker di budget per controllare le spese
- Verifica modelli e prezzi tramite l’endpoint
/v1/image-generation-models
Metti alla prova le tue conoscenze
Generazione e modifica di immagini: la panoramica operativa.
1. Cosa differenzia Imagine 1.0 da Imagine 2.0?
Risposta: Il compromesso qualità/costo: Imagine 1.0 ($0.02) per volumi e iterazioni, Imagine 2.0 ($0.04 in low, con impostazione quality) per i rendering finali — fai prototipi con il primo, finalizzi con il secondo.
2. Cosa rende un prompt per immagini efficace?
Risposta: Soggetto, stile, composizione e dettagli espliciti — descrivi la scena come un brief di direzione artistica, poi itera con aggiustamenti mirati invece di riscrivere tutto.
3. Cosa permette l'endpoint /v1/images/edits?
Risposta: Modificare immagini esistenti: editing mirato dal prompt, editing multi-immagine con riferimenti e editing multi-turno — ritocchi con precisione invece di rigenerare.
4. Come produrre in volume in modo efficiente?
Risposta: Il parametro n per i batch, il client async per il throughput — e dato che gli URL di output sono temporanei, scarica e archivia immediatamente.
5. Quali salvaguardie prima della produzione?
Risposta: Moderazione di prompt e output, conoscenza delle incompatibilità SDK e controllo dei costi (modello, risoluzione, volumi) — la creazione su scala richiede governance.
Prototipa, modifica, industrializza, governa: la pipeline completa per le immagini, con i costi sotto controllo a ogni passo.