01
Il seed aiuta il confronto, senza garantire pixel identici
Se il modello accetta un seed, salvalo con prompt, versione, dimensioni e riferimenti. Alcuni endpoint producono immagini diverse anche con lo stesso seed.
Soluzione API immagini
Genera immagini con i comandi che il modello espone davvero.
Ogni endpoint immagine dichiara i propri campi. Alcuni accettano un prompt negativo, altri un seed, altri restituiscono quattro candidati per chiamata. Un modulo generico nasconde proprio i comandi che rendono ripetibile il risultato.
La sfida
I moduli generici perdono i comandi che contano
«Metti il prompt, esce l’immagine» regge una decina di secondi. Poi ti serve lo stesso personaggio due volte, un taglio 3:2 invece del quadrato, quattro candidati per chiamata e un seed da annotare.
02
La dimensione è un campo, non una preimpostazione
Alcuni endpoint accettano resolution o aspect_ratio, altri width e height in pixel. Mandare quello sbagliato è un 400, e sugli endpoint tariffati a megapixel la dimensione che scegli è anche il prezzo che paghi.
03
Una chiamata può restituire più immagini
Dove esiste num_outputs, l’addebito segue il numero di immagini e non il numero di richieste. Un valore predefinito di 4 costa quattro volte un valore predefinito di 1, e la stima è l’unico posto in cui quella differenza si vede prima dell’invio.
L’approccio
Leggi lo schema, tieni i campi, registra il seed
Crea gli input secondo lo schema dell’endpoint. Salva richiesta esatta, ordine dei riferimenti e versione con il risultato per confrontare varianti. Conserva l’originale: rigenerarlo identico non è garantito.
Le attività immagine usano lo stesso contratto «crea e segui» del video. Tutta la differenza vive dentro input.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-image",
"input": {
"prompt": "A ceramic teapot on linen, soft window light, muted palette",
"aspect_ratio": "3:2",
"num_outputs": 2,
"seed": 1337
}
}GET /api/v1/jobs/recordInfo?taskId=…
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "succeeded",
"output": {
"assets": [
{
"mime": "image/png",
"url": "https://…/result.png?X-Amz-Signature=…",
"expiresAt": "2026-09-12T12:20:08Z"
}
]
},
"cost": "0.040000",
"settled": true
}
}Contratto
Cosa conviene fissare fin dall’inizio
| Campo o header | Valore o limite |
|---|---|
| input | additionalProperties: false |
| seed · num_outputs · aspect_ratio | declared per endpoint |
| cost + settled: false | hold · final charge never exceeds it |
| errorCode | 9 stable values, content_rejected included |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Dalla prima chiamata alla produzione
- 01Apri la pagina del modello dell’endpoint e leggi quali fra seed, negative_prompt, num_outputs e i campi di dimensione dichiara.
- 02Costruisci il corpo dall’input_schema: additionalProperties è chiuso, quindi una chiave non dichiarata è un 400 e non un no-op silenzioso.
- 03Chiedi il preventivo, invia con una Idempotency-Key e salva taskId, seed e il valore di model risolto accanto al risultato.
- 04Raccogli output.assets dalla callback o da recordInfo e copia i file nel tuo bucket.
Scelta
Quando questa strada è quella giusta
Scegli questa via se
- Generi da testo e vuoi più produttori di modelli dietro una sola forma di richiesta, un solo saldo e una sola fattura.
- Vuoi confrontare varianti con una richiesta e una versione del modello registrate.
Cerca altrove se
- I tuoi utenti partono da una foto che hanno già. La modifica è un’attività separata, con il proprio contratto per l’immagine di riferimento.
- Vuoi un unico stile di casa su tutti i modelli. Lo stile vive nel modello, non in questo livello.
Verifiche
Cosa puoi verificare in autonomia
La richiesta del Playground è la richiesta di produzione
Il corpo che componi nella pagina del modello è il corpo che invii dal tuo server: stessi campi, stessa validazione, stessa stima. Non esiste una modalità anteprima semplificata che poi diverge.
I campi non dichiarati falliscono rumorosamente
L’input è validato sullo schema dell’endpoint con additionalProperties chiuso. Un parametro che il modello non dichiara restituisce 400 con un errorCode stabile invece di essere ignorato in silenzio.
L’output è servito dall’archivio della piattaforma
I risultati tornano come output.assets con una chiave, un tipo MIME, un url firmato e expiresAt. Niente punta in hot-link al posto in cui ha girato il modello.
Prima del lancio
Comportamenti della piattaforma da confermare
- Decidi dove salvi i seed prima del lancio: servono solo se li hai tenuti.
- Imposta il limite di spesa giornaliero per chiave, richiesto su ogni chiave nuova, più quello mensile e a vita dove servono.
- Tratta l’insieme chiuso di errorCode, content_rejected incluso, come normali stati di prodotto.
- Duplica i file nel tuo archivio entro la finestra di conservazione di 14 giorni.
Domande frequenti
Cosa ci chiedono su questa pagina
Riutilizza input, versione e seed se disponibile. Non garantisce pixel identici. Scarica e conserva l’output originale quando ti serve proprio quell’immagine.
Sugli endpoint che dichiarano num_outputs sì, e l’addebito scala con il numero. Chiedi il preventivo del corpo per vedere l’importo del numero che intendi inviare.
Quelli che l’endpoint dichiara: resolution, aspect_ratio, oppure width e height. La pagina del modello elenca i valori ammessi, e qualsiasi cosa fuori da quell’elenco viene respinta prima che l’attività esista.
La piattaforma non ne aggiunge. Il comportamento sui contenuti viene dal modello che hai scelto, e un rifiuto arriva come una normale attività terminata con errorCode content_rejected.
Modelli
I modelli che puoi chiamare per questo
Ogni link apre la pagina di quella famiglia di modelli: input, limiti, politica sui contenuti e prezzo attuale per unità.
ByteDanceSeedream 5.0 ProDa testo a immaginePolitica sui contenuti: Senza censuraAlibabaQwen Image 2.1Editing di immaginiPolitica sui contenuti: Senza censuraByteDanceSeedream 5.0 FlashDa testo a immaginePolitica sui contenuti: Senza censuraAlibabaQwen Image Edit SpicyEditing di immaginiPolitica sui contenuti: Senza censuraAlibabaZ-Image Spicy ProDa testo a immaginePolitica sui contenuti: Senza censuraAlibabaQwen Image 3.0 ProEditing di immaginiPolitica sui contenuti: Senza censura
Continua
Confronta gli endpoint immagine fianco a fianco
Confronta gli endpoint immagine per input accettati, controlli di dimensione e seed, numero di risultati e prezzo, poi riusa la richiesta che hai provato.