La tua app di personaggi adulti promette una nuova immagine. Il cliente tocca Genera, l'indicatore gira per un po', poi la pagina segnala un timeout della connessione. Tocca di nuovo. Un minuto dopo compaiono due immagini e il saldo è sceso due volte.
La seconda può essere bellissima. Resta un modo costoso di scoprire che un timeout della connessione non è una generazione fallita.
Per un'API immagini NSFW, vengono chiamate «retry» tre azioni diverse: controllare un'attività esistente, ripetere l'invio originale e pagare un altro tentativo creativo. Tienile separate. Se hai un ID attività, controlla quell'attività. Se la risposta di creazione è scomparsa, ripeti la richiesta invariata con la chiave d'idempotenza originale. Se l'attività è completata ma l'immagine non rispetta il brief, un'altra generazione è un nuovo acquisto.
Quest'ultima distinzione conta soprattutto nelle immagini di personaggi adulti. Un modello può completare correttamente attenuando la scena, cambiando un abito o producendo un altro volto. Il successo dell'attività indica un risultato consegnato, non promette che vorrai usarlo.
Cosa è successo e quale pulsante offrire?
| Cosa vede il cliente | Cosa sai realmente | Prossima azione |
|---|---|---|
| Timeout prima di ricevere un ID | Accettazione incerta | Ripeti la stessa richiesta di creazione con la stessa chiave |
Hai un ID e l'attività è queued o running | Una generazione esiste già | Controlla lo stato, senza creare un'altra attività |
Attività failed o expired | Il tentativo ha raggiunto un esito finale | Leggi motivo e addebito liquidato prima di riprovare |
| Modello che rifiuta la richiesta NSFW | Quella richiesta specifica è stata rifiutata | Controlla comportamento sui contenuti e nota di fatturazione dell'attività precisa |
| Immagine arrivata, ma personaggio o scena sbagliati | Generazione riuscita, intento creativo mancato | Valuta se editing o nuova variante meritano un altro addebito |
| Immagine non scaricabile | Consegna guasta o link scaduto | Recupera il file esistente finché disponibile |
Attesa, recupero dell'invio e nuova variante sono azioni diverse.
Un'interfaccia utile per creatori adulti potrebbe chiamarle Controlla l'immagine esistente, Recupera l'invio, Genera un'altra variante e Riprova il download. Un unico «Riprova» nasconde la differenza tra controllo gratuito dello stato e autorizzazione di nuova spesa.
Se hai un ID attività, conserva l'attività originale
Il workflow asincrono di SpicyAPI accetta la richiesta, restituisce un ID e rende disponibile l'immagine in seguito. Una risposta di creazione accettata non è l'immagine finita. L'attività attraversa stati come queued, running e succeeded; anche failed, canceled e expired sono stati finali.
Salva l'ID appena il server lo riceve, prima di aggiornare il browser. Se il cliente ricarica, accede di nuovo o apre il progetto su un altro dispositivo, l'app deve recuperare l'attività salvata anziché reinviare il prompt.
Per esempio, un creatore richiede un ritratto serale del personaggio adulto immaginario. Il server riceve l'ID, ma il browser perde connessione prima di mostrare la scheda d'attesa. Al ritorno, la scheda deve riprendere quell'attività. Ricaricare la pagina non significa richiedere un secondo ritratto.
Usa GET /api/v1/jobs/recordInfo con l'ID per recuperare lo stato attuale. La documentazione delle attività descrive richiesta e risposta. Puoi usare webhook per le notifiche, ma un webhook ritardato non trasforma l'attività esistente in un fallimento. Il polling resta un percorso di recupero.
Non trasformare un limite locale d'attesa in una decisione di fatturazione. Il browser può smettere dopo 30 secondi, la richiesta HTTP uscente del server dopo 60, mentre l'attività remota continua. Il record restituito contiene una scadenza d'esecuzione, deadlineAt; descrive l'esecuzione remota, non quanto la pagina mantiene aperta una connessione. La scadenza del link di download è ancora un altro orologio.
Nella schermata d'attesa usa un messaggio come «L'immagine è ancora in elaborazione. Puoi lasciare la pagina e tornare alla stessa attività». Non promettere un tempo preciso senza misure del modello e carico specifici. La latenza misurata da un concorrente su immagini di prodotto normali non garantisce i tempi dei tuoi prompt NSFW.
Se la risposta di creazione è persa, ripeti lo stesso invio
Il caso difficile è la connessione che cade dopo l'invio del server e prima della conferma. Dall'errore di connessione non puoi sapere se la piattaforma ha accettato il lavoro.
SpicyAPI offre una protezione effettiva lato server: l'header facoltativo Idempotency-Key. Per stesso account e stessa chiave API, ripetere una chiave con modello normalizzato, input e URL callback invariati entro 24 ore restituisce l'attività originale senza riservare nuovamente fondi. Una richiesta cambiata entra in conflitto con quella chiave. Nemmeno un'altra chiave API dello stesso account può recuperare quella mappatura: riceve un conflitto senza divulgazione dell'ID originale.
Crea una chiave stabile per l'immagine richiesta dal cliente, non per ogni tentativo HTTP. Un valore dell'app come project-8-image-12-v1 illustra l'idea. Evita dati personali e testo grezzo del prompt. Generala e salvala prima della prima richiesta. Un nuovo tentativo di rete la riusa; una nuova immagine reale riceve una nuova versione o ID operazione.
Una sequenza minima di recupero è:
- Salva nell'app operazione d'immagine prevista, corpo della richiesta originale e chiave.
- Invia la richiesta con
Idempotency-Key. - Se perdi la conferma, segna l'operazione locale come in attesa di conferma.
- Ripeti corpo e chiave invariati con la stessa credenziale API.
- Salva l'ID restituito e passa al controllo dello stato.
Durante il recupero mantieni stabile la richiesta esatta inviata. Non farla ricostruire dall'interfaccia usando controlli che il cliente può aver cambiato. Passare da primo piano a composizione ampia, aumentare risoluzione, cambiare prompt o callback non è più l'invio originale.
La protezione ha un limite: 24 ore non sono conservazione indefinita della prevenzione duplicati dell'app. Dopo la finestra non presumere che la vecchia chiave recuperi un vecchio lavoro. La tua mappatura persistente fra operazione e attività deve gestire ritorni successivi. Se l'accettazione resta incerta e non trovi l'originale, riconcilia i record dell'account o chiedi supporto prima di creare automaticamente un sostituto.
Disattivare Genera aiuta, ma non basta
Un pulsante disattivato durante il caricamento evita un doppio tocco comune. Non impedisce invii duplicati da due schede browser, client mobile che si riconnette, worker in background o riavvio del server.
L'app deve collegare tutti questi eventi a una sola operazione logica. Una regola di unicità nel database impedisce a due worker di acquisire indipendentemente la stessa operazione. La chiave d'idempotenza protegge poi il confine della creazione remota. Sono protezioni diverse e servono entrambe se esistono più modi d'inviare un lavoro.
Considera un prodotto companion che genera facoltativamente un ritratto dopo una conversazione. L'utente preme anche il pulsante manuale prima della conferma automatica. Se entrambe le azioni soddisfano la stessa richiesta, collegale alla stessa operazione. Se il pulsante richiede esplicitamente una seconda variante, mostra che è una nuova generazione a pagamento. Non fondere silenziosamente due acquisti voluti né addebitare due volte una promessa singola.
La chiave non decide questa semantica di prodotto. È l'app a decidere cosa conta come stessa richiesta. Nemmeno una riga database deduplicata localmente aiuta se il client uscente usa una nuova chiave remota a ogni recupero. Il valore deve sopravvivere all'intero percorso.
Rifiuto, guasto tecnico e immagine indesiderata hanno conti diversi
Una richiesta adulta può finire in diversi modi. Evita sia di promettere che ogni generazione NSFW fallita sia gratuita sia di dire che ogni errore viene addebitato.
Stato dell'attività e soddisfazione creativa differiscono. Controlla il record liquidato e le eccezioni di fatturazione del modello.
SpicyAPI riserva un importo stimato quando accetta l'attività. Finché settled è false, cost è la stima trattenuta. Dopo la liquidazione rappresenta l'addebito finale. Un'attività riuscita viene addebitata fino all'importo riservato; i fondi inutilizzati vengono liberati.
Un'attività fallita o scaduta normalmente libera la trattenuta. Ci sono eccezioni nella policy di rimborso, compresi modelli le cui pagine dichiarano addebiti per richieste rifiutate o fallite e utilizzo consegnato prima di una richiesta interrotta. Per un rifiuto del modello, controlla nota di fatturazione e record finale liquidato. Non usare solo l'errore HTTP per spiegare il saldo.
Un'immagine riuscita ma attenuata è diversa. Immagina un personaggio adulto sicuro in una scena editoriale adulta specifica, sostituito da un ritratto convenzionale. Se l'attività è riuscita e ha consegnato il risultato, l'insoddisfazione non lo rende un guasto tecnico rimborsabile. Lo stesso vale per acconciatura sbagliata, accessorio non richiesto o espressione sgradita.
Per questo una policy utile di tentativi richiede un limite di spesa creativa, non solo un numero di retry di rete. Un worker che riprova ogni immagine sgradita può continuare a comprare output riusciti molto dopo la soluzione dei guasti.
Leggi la pagina del modello esatto usato. Un percorso text-to-image permissivo non dimostra editing identico e il nome della famiglia non predice ogni richiesta NSFW. Usa solo personaggi adulti e materiali che hai diritto d'inviare; riprovare non rende accettabili richieste vietate.
Riprovare un fallimento finale crea nuovo lavoro
L'API offre anche POST /api/v1/jobs/retry, che accetta un ID sorgente e crea una nuova attività da un fallimento finale idoneo. Non rimette in esecuzione quella vecchia. Input attuali, permessi, disponibilità, saldo e prezzo vengono valutati nuovamente. La sorgente richiede input conservato e riconciliazione completata; un'attività attiva o riuscita non è idonea.
Usa la stessa chiave API della sorgente. Se applichi una chiave d'idempotenza al retry, protegge quel nuovo tentativo ed è circoscritta all'attività sorgente. Ripetere il retry recupera l'attività appena creata; è diverso da ripetere la prima creazione per recuperare l'originale.
Nell'app mostra una nuova generazione con prezzo. Se va cambiato il prompt, crea una richiesta con input rivisto anziché aspettarti che il retry della sorgente lo modifichi. Anche un fallimento da riferimento scaduto necessita di un riferimento utilizzabile per riuscire. Il rilascio dell'addebito originale e la trattenuta del nuovo tentativo sono voci separate.
Quanto costano davvero i tentativi ripetuti
Ecco configurazioni iniziali attuali di tre endpoint. I prezzi descrivono la generazione, non garantiscono ogni risultato conforme al brief NSFW.
Esempio ipotetico: attività duplicate accidentali aggiungono $2.40 a $7.20 di tentativi creativi voluti.
| Endpoint e configurazione esplicita | Prezzo per immagine | Tre tentativi addebitati | Dieci tentativi addebitati |
|---|---|---|---|
| Z-Image Turbo text-to-image, espansione disattivata | $0.010 | $0.030 | $0.100 |
| Qwen Image 2.1 text-to-image, 1K | $0.024 | $0.072 | $0.240 |
| Seedream 5.0 Pro text-to-image, 1K selezionato | $0.036 | $0.108 | $0.360 |
I dettagli contano. Z-Image Turbo con espansione costa $0.016 invece di $0.010. Seedream 5.0 Pro usa 2K per predefinito, da $0.072 anziché $0.036 a 1K. Selezionare esplicitamente la fascia fa corrispondere calcolo e attività.
Supponi di pianificare 100 ritratti finali Qwen Image 2.1 a 1K. Se ciascuno richiede mediamente tre tentativi creativi addebitati, spendi $7.20: 100 × 3 × $0.024. Se un bug di conferma duplica anche un invio per ogni finale, aggiunge 100 × $0.024 = $2.40, portando la spesa a $9.60. Sono esempi di pianificazione, non un tasso misurato.
Non trasformi un processo creativo da tre tentativi in uno modificando il timeout HTTP. Puoi eliminare il quarto tentativo accidentale. Tieni separati varianti volute e duplicati per capire quale problema paghi.
Per un piccolo workflow, decidi il limite prima di generare: magari un'immagine iniziale più due revisioni per quello slot. È un consiglio di budget applicativo, non un limite della piattaforma. Se tutti e tre mancano lo stesso requisito, smetti di comprare richieste quasi identiche e cambia approccio.
Immagine NSFW completata fuori brief: cambia una cosa significativa
Se il volto è giusto ma stanza o abito sono sbagliati, un editing mirato può essere un acquisto migliore di una nuova generazione completa. Conserva il risultato utile, descrivi cosa cambiare e scegli un modello con l'attività adeguata. L'editing costa comunque: non è una correzione gratuita inclusa.
Se la stessa richiesta continua a produrre una scena attenuata, identifica prima se si tratta di rifiuto dei contenuti, richiesta consentita interpretata prudentemente o prompt sovraccarico. Reinviare lo stesso testo non spiega quale caso sia. Guarda immagine e codice d'errore stabile, se presente, invece di trattare NSFW come interruttore universale.
Come esempio non esplicito, un brief può richiedere un solo personaggio adulto immaginario, giacca scura di raso, posa seduta, luce calda laterale e stanza essenziale. Se compare sempre una stanza affollata, elimina dettagli secondari mantenendo personaggio e luce. Se compare il volto sbagliato, passa al workflow con riferimenti anziché aggiungere aggettivi a un prompt solo testuale.
Per una variante davvero nuova usa nuova operazione e chiave. Ripetere la prima richiesta accettata con la chiave originale recupera la prima attività; non chiede una seconda immagine migliore. Un cambio di seed va registrato come nuovo tentativo creativo. Il seed identifica la richiesta, non garantisce lo stesso personaggio tra modelli diversi.
Dopo i primi tentativi, confronta il costo delle immagini utilizzabili, non solo il prezzo iniziale pubblicizzato. Una generazione da $0.010 usata quattro volte costa $0.040. Una da $0.024 usata una volta costa $0.024. Il calcolo non prova che il secondo modello sia più affidabile: indica cosa misurare sul tuo brief.
Quando un'immagine esistente non si scarica
Non rigenerare un'immagine riuscita per un errore di download. Il file può esistere ancora con un link temporaneo non funzionante oppure l'app può essere fallita durante la copia.
Conserva attività completata e identità dell'asset. Recupera un percorso autorizzato attuale finché il file è conservato, poi riprova il trasferimento. Non aggiungere la chiave API a un URL firmato separato. Conferma i byte nella destinazione prima di mostrare «Salvata» nella libreria del cliente.
La guida alla consegna dei media tratta la copia in storage controllato da te. Per un creatore adulto è anche un confine di privacy: immagine o riferimento non diventano pubblici solo perché la copia riesce. Il recupero deve conservare l'accesso privato previsto.
Se l'output originale è già stato cancellato secondo la policy effettiva di conservazione, l'ID non ripristina i byte. Un sostituto è una nuova generazione e può apparire diverso. Spiega la distinzione al cliente anziché sostituire silenziosamente un vecchio ritratto con uno nuovo fatturato.
Fai corrispondere l'azione successiva all'addebito
Mostra insieme stato e addebito liquidato dell'attività esistente. Se è irrisolta, mantienila nel progetto senza presentare un nuovo retry pagato come unica strada. Se è fallita, mostra motivo e rilascio eventuale dell'importo. Se è riuscita, separa «Scarica di nuovo» da «Genera un'altra variante».
Per l'assistenza servono ID attività, ID richiesta se disponibile, orario, importo e breve descrizione. Due ID diversi non sono un'attività addebitata due volte. La policy chiede di segnalare doppi addebiti, addebiti sopra la trattenuta, output riusciti non consegnati o trattenute non restituite entro 24 ore dopo un fallimento. Non inserire chiavi API, link firmati o prompt sensibili nei normali log o screenshot d'assistenza.
Il creatore deve poter leggere la cronologia come «un ritratto richiesto, un invio recuperato, un risultato consegnato», non come una lista di tentativi HTTP invisibili. Questo è l'obiettivo: recuperare la rete conserva l'acquisto originale, mentre un altro tentativo creativo è una scelta intenzionale con prezzo visibile.
