Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Moderazione, incompatibilità SDK e controllo dei costi

Lezione 14 di 14 Aggiornata il 3 novembre 2026 Principiante
In questa pagina
  1. Comprendere i limiti delle API per le immagini
  2. Moderazione dei contenuti
  3. Incompatibilità dell’SDK OpenAI per la modifica
  4. Controllo dei costi
  5. Endpoint di scoperta dei modelli
  6. Punti chiave
  7. Metti alla prova le tue conoscenze

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