Generare immagini di prodotto per l'e-commerce con gpt-6-astra tramite l'API hiapi

GPT-6 Astra non genera immagini: ecco a cosa serve davvero nello stack e-commerce

Se sei arrivato qui sperando che GPT-6 Astra generi foto di prodotto, non può farlo: è un modello puramente testuale e di ragionamento, accessibile tramite l'endpoint /v1/responses, che non produce alcun output di immagini, audio o video. Per i team e-commerce, però, non è un vicolo cieco. Ogni immagine di prodotto vive all'interno di una pagina, e quella pagina ha bisogno anche di descrizioni, testi alt, risposte all'assistenza clienti e tre versioni dello stesso messaggio di vendita per tre canali pubblicitari diversi: ed è esattamente per questo livello che è nato GPT-6 Astra. Questa guida copre la parte testuale del flusso di lavoro sulle immagini di prodotto: generazione di descrizioni in batch, estrazione di dati strutturati per le schede prodotto e domande e risposte dei clienti, con esempi reali di richieste all'API Responses. Se ti servono le fotografie vere e proprie, abbinalo a un modello di immagini come GPT Image 2 e lascia che GPT-6 Astra gestisca tutto il testo che circonda la foto.

Perché usare Responses API e non Chat Completions

GPT-6 Astra è esposto solo tramite POST /v1/responses — la stessa famiglia di endpoint che OpenAI utilizza per i suoi modelli di ragionamento più recenti — e non nella forma più datata di Chat Completions. Se devi integrarlo in una pipeline di prodotto, ci sono tre differenze importanti:

• Usa input invece di messages. Passi un array di elementi di input, non una lista messages. Adatta il tuo client Chat Completions invece di riutilizzare così com'è il codice che costruisce le richieste.
• In pratica stream=true è il valore predefinito e lo stato usa store=false. Il modello emette in streaming gli eventi response.output_text.delta man mano che il testo arriva, e response.output_item.done quando un elemento strutturato è completo. Con store=false il servizio non conserva nulla tra una chiamata e l'altra: se stai gestendo una conversazione di assistenza multi-turno, devi reinviare tu stesso i turni utente/assistente precedenti nel successivo array input.
• Usa reasoning.effort invece di temperature. Questa integrazione non ha parametri di regolazione temperature, top_p o max_output_tokens. Controlli la qualità/latenza dell'output tramite reasoning.effort, con valori low, medium, high, xhigh o max (non esiste none: il ragionamento non può essere disattivato). Per attività brevi e deterministiche come la generazione di descrizioni, low o medium di solito bastano; riserva high e superiori ai casi che richiedono capacità di giudizio, come la stesura di risposte all'assistenza su questioni sensibili alle policy.

L'URL di base è https://api.hiapi.ai/v1 e la chiave è la stessa degli altri modelli hiapi.

Caso d'uso 1: generazione in batch di descrizioni di prodotto con output strutturato

L'aggancio e-commerce più diretto è trasformare su larga scala le schede tecniche in testi di listino in linea con il tono del brand. Invece di analizzare il testo libero restituito dal modello, usa text.format.type=json_schema per far sì che ogni risposta torni in una forma che il tuo CMS possa acquisire direttamente: titolo, descrizione breve, descrizione lunga ed elenco puntato, tutto in un'unica chiamata.

import json
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {HIAPI_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-6-astra",
        "store": False,
        "reasoning": {"effort": "low"},
        "input": [
            {
                "role": "system",
                "content": "You write concise, factual e-commerce listing copy. "
                            "Never invent specs that aren't in the input.",
            },
            {
                "role": "user",
                "content": "Product: ceramic pour-over coffee dripper, 400ml, "
                            "matte white, dishwasher safe, fits standard filters. "
                            "Write listing copy for this product.",
            },
        ],
        "text": {
            "format": {
                "type": "json_schema",
                "name": "listing_copy",
                "schema": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "short_description": {"type": "string"},
                        "long_description": {"type": "string"},
                        "bullet_points": {
                            "type": "array",
                            "items": {"type": "string"},
                        },
                    },
                    "required": [
                        "title",
                        "short_description",
                        "long_description",
                        "bullet_points",
                    ],
                    "additionalProperties": False,
                },
            }
        },
    },
    stream=False,
)
data = resp.json()

Esegui questo codice sul tuo database prodotti per SKU e otterrai testi coerenti e validati dallo schema, invece di prosa copiata e incollata da una finestra di chat. Assicurati che il prompt di sistema vieti rigorosamente di inventare specifiche: se lo lasci fare, il modello sarà felice di scrivere in modo vivido di funzionalità che non gli hai nemmeno fornito.

Caso d'uso 2: domande e risposte dell'assistenza clienti basate sui tuoi documenti

Per un assistente di assistenza clienti, il modello chiave è il ciclo di replay con store=false. A ogni turno rimandi nella input la conversazione corrente più eventuali risultati di strumenti; tutto ciò che non invii, il modello non lo ricorda. È un compromesso voluto: costa un po' di più in token di input reinviati, ma significa che lo stato della conversazione appartiene alla tua applicazione, non al fornitore (utile se devi filtrare dati sensibili, diramare o ripristinare conversazioni dal tuo database).

history = [
    {"role": "system", "content": "Answer only from the provided product FAQ context. "
                                    "If the answer isn't in context, say so and offer to escalate."},
]

def ask(user_message: str, faq_context: str) -> str:
    history.append({"role": "user", "content": f"Context:\n{faq_context}\n\nQuestion: {user_message}"})
    resp = requests.post(
        "https://api.hiapi.ai/v1/responses",
        headers={"Authorization": f"Bearer {HIAPI_KEY}", "Content-Type": "application/json"},
        json={
            "model": "gpt-6-astra",
            "store": False,
            "reasoning": {"effort": "medium"},
            "input": history,
        },
    )
    answer = resp.json()["output"][-1]["content"][0]["text"]
    history.append({"role": "assistant", "content": answer})
    return answer

Per qualsiasi operazione che richieda di verificare lo stato di un ordine o avviare un reso, dichiarala come funzione in tools: il modello restituirà una function_call, il tuo backend la eseguirà e poi, prima che il modello prosegua, gli restituirai il risultato tramite function_call_output con lo stesso call_id. Così il modello non entra mai direttamente in contatto con il tuo database ordini.

Caso d'uso 3: varianti di copy marketing per canali diversi

Lo stesso insieme di informazioni sul prodotto richiede formulazioni diverse nella pagina prodotto, nell'oggetto di un'email e in un titolo pubblicitario da 30 caratteri. Poiché GPT-6 Astra emette in streaming gli eventi response.output_text.delta, puoi generare più varianti di canale in un'unica chiamata e renderizzarle man mano che arrivano, senza attendere la risposta completa: utile se questo alimenta un'anteprima in tempo reale in uno strumento interno. Anche qui mantieni reasoning.effort su low: abbinare il tono di testi brevi non richiede un ragionamento più potente, e così mantieni bassa la latenza mentre i marketer iterano in tempo reale.

Come vengono calcolati i costi

GPT-6 Astra viene fatturato a token e presenta un brusco salto di fascia, non un aumento marginale: vale la pena capirlo prima di elaborare in batch un grande catalogo prodotti in un'unica richiesta:

Fascia	Input	Output	Input in cache	Scrittura in cache
Standard (≤272.000 token di input/richiesta)	$2,50 / 1 milione di token	$12,50 / 1 milione di token	$0,25 / 1 milione di token	$3,125 / 1 milione di token
Contesto lungo (>272.000 token di input/richiesta)	$5,00 / 1 milione di token	$18,75 / 1 milione di token	$0,50 / 1 milione di token	$6,25 / 1 milione di token

La soglia viene verificata sul totale complessivo dell'input della richiesta — incluse le letture e le scritture in cache — e una volta superata l'intera richiesta viene fatturata alla tariffa di contesto lungo, non solo la parte di token oltre i 272.000. Per i casi d'uso descritti sopra (generazione di descrizioni per singolo prodotto, una conversazione di assistenza, una variante di copy) sei ancora molto lontano da questa soglia; conta soprattutto quando inserisci un intero catalogo prodotti o un lungo documento in un'unica chiamata. Prima di impegnarti in attività in batch, controlla hiapi.ai/pricing per le tariffe aggiornate, poiché sono basate sull'utilizzo e possono cambiare.

Come si integra con il resto dello stack

Nessuna delle soluzioni sopra sostituisce un vero modello di immagini: GPT-6 Astra non ha accesso a /v1/tasks e non può produrre output visivi. Se il tuo flusso di lavoro richiede foto di prodotto o immagini in contesto da abbinare a questi testi, serve una chiamata separata a un modello di immagini come GPT Image 2, e i formati delle richieste e gli endpoint dei due non sono interoperabili. Per tutti i dettagli di configurazione, inclusi l'ID del modello e la forma esatta delle richieste, vedi la guida all'API di GPT-6 Astra e la pagina del modello.

Domande frequenti

GPT-6 Astra può generare immagini di prodotto? No. È un modello puramente testuale accessibile tramite /v1/responses e non produce immagini, audio o video. Per la parte visiva delle schede prodotto abbinalo a un modello di immagini.

Qual è la differenza tra input e l'array messages che uso in Chat Completions? input è il campo di richiesta che Responses API usa per i turni di conversazione e i contenuti: non è un sostituto diretto di messages, quindi il codice del client Chat Completions va adattato, non solo il nome del campo.

Per attività semplici come la generazione di descrizioni, devo disattivare il ragionamento? Non puoi disattivarlo: non esiste reasoning.effort=none. Per attività di generazione brevi e a basso rischio usa low: è la più veloce ed economica delle cinque fasce.

store=false significa che perderò la cronologia della conversazione? No, significa che la piattaforma non la memorizza per te. La tua applicazione reinvia nel successivo array input i turni di cui ha bisogno, il che ti dà il controllo su quale contesto includere (e ti permette di filtrare dati sensibili o diramare le conversazioni), al costo di pagare di nuovo quei token come input.

Ripetere lo stesso prompt di sistema in molte chiamate di descrizione prodotto dà diritto a uno sconto sulla cache? Non è garantito. I riscontri in cache dipendono dalla politica e dai tempi lato server, non solo dalla ripetizione letterale: controlla cached_tokens nell'oggetto usage della risposta invece di dare per scontato che lo sconto si applichi.

Cosa succede se inserisco in batch un intero catalogo prodotti in un'unica richiesta? Se il totale dei token di input (compresi eventuali contenuti in cache) supera 272.000, l'intera richiesta — input, output e utilizzo della cache — viene fatturata alla tariffa di contesto lungo, non solo la parte oltre la soglia. Per la maggior parte delle chiamate su singolo prodotto o singola conversazione non si applica, ma prima di inserire in batch un grande catalogo in un'unica chiamata vale la pena controllare il numero di token.