Media IA: URL di upload temporanei, risultati di breve durata e consegna affidabile via API

Se stai sviluppando un prodotto di immagini o video IA senza censura, tre fatti determinano la progettazione dell’archiviazione. I file di riferimento caricati durano 1 giorno. I media generati dalle attività API, SDK e Playground durano circa 14 giorni (i media dei cortometraggi Studio hanno un limite separato di circa 60 giorni), e ogni link di download che ricevi funziona solo per circa 20 minuti. Sono tutti limiti massimi: puoi soltanto ridurli, per l’intero account o per una singola richiesta, e distruggere su richiesta i contenuti di un’attività terminata. Nessuna impostazione li prolunga.

Il flusso affidabile è quindi: carica direttamente con un ticket di breve durata, conferma il file, invia un’attività asincrona con il riferimento privato spicy://, recupera il link del risultato al termine e copia il risultato in un archivio che controlli oppure lascialo scadere intenzionalmente. Non mettere il caricamento di un cliente in un bucket pubblico e non salvare un URL di download restituito come se fosse permanente.

Caricare un riferimento su SpicyAPI è gratuito; l’attività di generazione che lo usa viene addebitata separatamente. Rinnovare il link di download di un risultato esistente non esegue né acquista di nuovo la generazione. Un nuovo tentativo di generazione ha il proprio costo del modello, mentre archiviazione, richieste e trasferimento della copia nel tuo bucket seguono i prezzi del tuo fornitore di archiviazione.

Leggi le scadenze di conservazione accettate prima di promettere un periodo di archiviazione ai clienti; la documentazione sulla conservazione spiega le impostazioni. Un esempio pratico di copia locale è in trasformare i media IA temporanei in risorse durature per un prodotto.

Prova prima in Playground

1. Apri la pagina da testo a immagine di z-image, resta in Workbench, su Form, scrivi un Prompt, scegli un Aspect ratio e seleziona Run model (accedi prima; questa immagine è una normale generazione a pagamento). Controllala in Preview e salvala con Download.
2. In Console, apri Logs e trova l’attività per vedere quanto dura la conservazione del suo output.
3. Apri Data protection, poi Retention, per vedere i quattro periodi e abbreviarli.
4. Quando hai la tua copia, seleziona Destroy outputs sull’attività terminata per eliminarne i contenuti.

Cosa conserva SpicyAPI e per quanto tempo

Abbrevia la conservazione o distruggi tu i contenuti

1. Periodi di conservazione dell’account. In Retention, nella pagina Data protection della console, ci sono quattro periodi separati:

Il periodo dei file caricati ha tre limiti importanti:

• Delete when the job ends: un caricamento viene rimosso quando tutte le attività che lo usano raggiungono uno stato finale, normalmente entro un minuto. Una nuova generazione con quel riferimento eliminato richiede un altro caricamento.
• Solo file esistenti: l’interruttore si applica ai file presenti quando salvi. I caricamenti successivi mantengono attualmente la scadenza standard di 1 giorno indicata nella risposta di conferma.
• Opzioni di 1 ora e 24 ore: attualmente non cambiano nulla; il caricamento resta utilizzabile fino al valore expiresAt restituito.

Avvertenza prima di abbreviare qualsiasi periodo: un’impostazione più breve può riguardare attività già eseguite. Impostare Prompt text su 1 o 24 ore, per esempio, cancella il testo del prompt e i risultati generati di tutte le attività terminate da più di un giorno, anche se Generated results resta a 14 giorni. I contenuti eliminati non sono recuperabili. Scarica prima ciò che vuoi tenere; allungare un’impostazione influisce solo sul futuro.

2. Una richiesta alla volta. Invia l’header X-Spicy-Retention (secondi) quando crei un’attività; la documentazione sulla conservazione mostra la richiesta. Il periodo effettivo è il più breve tra quello della richiesta, l’impostazione dell’account e il limite della piattaforma. Leggi le scadenze accettate dall’attività invece di promettere la durata richiesta.

Non usare l’eliminazione immediata per un prodotto che promette la consegna o una libreria salvata. Può rimuovere il risultato prima che la copia sia terminata. Lascia un margine per il recupero dopo la consegna.

3. Distruggi un’attività terminata. Quando hai copiato ciò che serve, o quando un cliente chiede la cancellazione, rimuovi i contenuti creativi di quell’attività.

La console offre la stessa azione come Destroy outputs su un’attività in Logs. Si applicano tre regole:

• Solo attività terminate. Purge è idempotente per taskId; non serve Idempotency-Key. Non annulla la generazione né rimborsa l’addebito e billingRetained resta true.
• L’eliminazione è programmata. contentState diventa purged, mentre mediaDeletionPending resta true finché la pulizia non termina, normalmente entro un minuto. Conferma il completamento prima di dire a un cliente che i dati sono spariti.
• Una risposta present non ha rimosso nulla. Esamina la risposta e le impostazioni di conservazione invece di dichiarare completata l’eliminazione.

contentState è expired quando il periodo di conservazione ha rimosso i contenuti, e purged quando li hai distrutti tu. Lo stato dell’attività expired significa tutt’altro: la generazione ha superato il tempo limite e non ha prodotto nulla. Riprovare aiuta solo in questo secondo caso.

Invia file di riferimento

Un’immagine, un video o un file audio di riferimento può arrivare a un’attività in tre modi. Un URL HTTPS pubblico deve restituire il file stesso: un link a una pagina di condivisione (unità cloud, album fotografico, post social) restituisce una pagina web e l’attività fallisce con invalid_asset, quindi scarica il file e caricalo. Una piccola immagine (fino a 1 MiB) può essere inclusa come URI di dati base64. Qualsiasi file privato o grande va caricato tramite SDK, CLI o Playground, che restituisce un riferimento privato spicy:// per l’attività.

Limiti di caricamento: JPEG, PNG, WebP e GIF fino a 10 MiB; WAV, MP3, WebM, MP4 e MOV fino a 90 MiB e 600 secondi, e un modello può accettare meno. Tieni una copia originale se ti servirà di nuovo l’input dopo il periodo di un giorno. Il backend deve solo autorizzare il caricamento e registrare la proprietà; il client può inviare direttamente i dati. Il caricamento è gratuito; la generazione è un acquisto separato. La documentazione sui media descrive il flusso.

Risultati: recuperali, poi copiali o lasciali scadere

Un manoscritto e fotogrammi di paesaggi convergono in un’unica scena proiettata.

Invia ogni nuova richiesta con una propria chiave di idempotenza, conserva l’ID dell’attività e recupera il risultato tramite polling o callback. Le risorse pronte contengono una url firmata; scaricala senza chiave API e invia un User-Agent come Mozilla/5.0, perché il CDN rifiuta l’agente predefinito di urllib di Python con un 403 che non significa che il link sia scaduto. Un’attività succeeded può ancora avere una risorsa pending, quindi continua a controllare finché l’URL è pronto. Un link scaduto si può rinnovare entro il periodo di conservazione; la documentazione sui media spiega come.

Conviene gestire esplicitamente tre stati di una risorsa:

Un modello solo testuale non ha alcun assets, e il suo testo in output.text viene cancellato con lo stesso calendario, quindi leggilo prima di supporre che esista un file.

L’eccezione di archiviazione senza addebito vale quando nessun output di un’attività è stato inizialmente archiviabile. Una vecchia risorsa unavailable da sola non dimostra il diritto a un rimborso; controlla il consuntivo di fatturazione dell’attività originale.

I callback contengono il tuo prompt e i link firmati dei risultati. Il tuo endpoint, proxy inverso, sistema di monitoraggio errori e pipeline di log ricevono quindi materiale che SpicyAPI cancella secondo un calendario: oscura i corpi dei callback nei log di accesso ed esegui la copia in un worker. Verifica delle firme, deduplicazione e nuovi tentativi sono nella documentazione sui webhook.

• Il tuo prodotto promette una libreria, condivisione o modifiche successive: trasferisci in streaming il risultato in un archivio privato che controlli appena vedi il successo, registra il tuo ID della risorsa e, se vuoi rimuovere la copia della piattaforma, chiama Purge dopo. Usa lo streaming invece di caricare un video grande in memoria e rendi la scrittura di destinazione idempotente per attività e risorsa.
• Consegna una tantum: non copiare. Mostra il risultato, comunica al cliente quanto dura e lascia che il periodo di conservazione, o un X-Spicy-Retention breve, lo elimini.

Un riferimento caricato dall’utente non è un materiale di marketing e un risultato riuscito non costituisce consenso alla pubblicazione. Indica qualcosa come “salvato dal cliente” solo dopo aver confermato la tua copia.

Quando qualcosa non funziona

Mantieni log utili senza conservare materiale creativo

Controlla queste possibili copie accidentali:

• Segnalazioni di errori e log di accesso: oscura prompt, ticket e link firmati; evita di registrare i corpi delle rotte media.
• Analisi e code: usa ID opachi di operazione, attività e risorsa invece di URL o nomi di file, anche nell’archivio dei messaggi non recapitabili.
• Esportazioni del supporto e consegna pubblica: controlla screenshot, metadati delle pagine ed email. Indirizza i clienti a una pagina autenticata che emette un link nuovo dopo il controllo dell’accesso.
• Il tuo archivio e i backup: applica la tua politica di cancellazione. Un link scaduto non può revocare un file già scaricato da qualcuno.

Cosa non possono promettere le impostazioni di conservazione

• Il modello vede il prompt. Il modello che esegue la richiesta lo riceve in chiaro, quindi le impostazioni di SpicyAPI controllano solo per quanto tempo SpicyAPI stessa conserva qualcosa. Non inviare materiale che non serve.
• Purge è una richiesta di eliminazione asincrona. Conferma lo stato dei contenuti restituito e il completamento dell’eliminazione dei media. La pulizia del ciclo di vita dell’archiviazione e la rotazione dei backup hanno periodi separati; anche i tuoi file copiati e backup richiedono operazioni di eliminazione proprie. I registri di fatturazione restano comunque.

Se ti serve un periodo diverso scritto in un contratto, chiedilo prima di firmare invece di dedurlo da una pagina della documentazione.

Domande frequenti

Posso usare un URL di caricamento temporaneo come URL di immagine in una richiesta di generazione?

No. L’URL di caricamento autorizza solo la scrittura diretta. Carica, conferma e inserisci l’URI spicy:// confermato in un campo che lo schema attuale del modello indica come campo di caricamento.

Posso conservare un video generato su SpicyAPI per più di 14 giorni?

Per i risultati API, SDK e Playground, no: il limite è circa 14 giorni. I media dei cortometraggi Studio hanno un limite separato di circa 60 giorni. Copia il file nel tuo archivio dopo il successo per accedervi più a lungo.

Purge rimborsa l’attività?

No. Purge rimuove solo i contenuti; l’addebito e il record dell’attività restano.

Un webhook può sostituire del tutto il polling?

Può essere il percorso principale, con un controllo di riconciliazione limitato per le consegne mancate. Usa il request_id della consegna e l’ID dell’attività come chiavi del gestore.

Posso mettere un link del risultato in un’email?

Evitalo. Le email vengono inoltrate e archiviate ben oltre la scadenza di un link breve. Indirizza i clienti a una pagina autenticata che controlla l’accesso ed emette un nuovo link.

Cosa deve succedere quando un cliente elimina un risultato salvato?

Elimina o revoca la tua copia e il suo percorso di consegna e conserva una registrazione dell’operazione. La copia della piattaforma segue il proprio calendario; usa Destroy outputs se va rimossa prima.

Controlla un’attività esistente dal codice

Installa spicyapi, imposta SPICY_API_KEY e TASK_ID, poi esegui questo controllo in sola lettura. Non crea generazioni e non elimina contenuti.

import json
import os
from spicyapi import SpicyClient

client = SpicyClient()
task = client.get_task(os.environ["TASK_ID"])
print(json.dumps({"taskId": task["taskId"], "state": task["state"],
    "contentState": task.get("contentState"), "retention": task.get("retention"),
    "mediaDeletionPending": task.get("mediaDeletionPending")}, indent=2))

Il riferimento sulla conservazione descrive le impostazioni della richiesta e il contratto di eliminazione.

Lascia che un Agent gestisca la chiamata

Delega un controllo dell’archiviazione quando hai già un ID di attività; non serve una nuova generazione.

• CLI: npx @spicyapi/cli tasks get "$TASK_ID" legge le scadenze attuali. Consulta la guida CLI.
• MCP: chiedi a spicyapi_task_get di ispezionare l’attività. Usa spicyapi_task_purge solo dopo aver approvato esplicitamente la distruzione dei suoi contenuti; la guida MCP descrive la conferma.
• Skill: dopo npx skills add spicyapi-ai/spicy-skill, chiedi a $spicyapi di controllare la conservazione dell’attività e spiegare cosa scadrà. Consulta la guida Skill.