Come utilizzare l'API Qwen Image 3.0: generazione, modifica e prezzi

TL;DR

Qwen Image 3.0 unifica la generazione da testo a immagine e l’editing guidato da immagini di riferimento nelle varianti Standard (qwen-image-3.0) e Pro (qwen-image-3.0-pro). Inizia con un prompt testuale, scegli una dimensione di output, invia una richiesta di generazione e salva subito l’output. Per l’editing, includi da una a tre immagini di riferimento e un’istruzione esplicita su cosa preservare. Su CometAPI, verifica il percorso effettivo e lo schema di richiesta compatibile prima di distribuire le chiamate di esempio.

Punti chiave

• L’API Qwen Image 3.0 supporta la generazione da testo a immagine e l’editing guidato da riferimenti tramite Standard (qwen-image-3.0) e Pro (qwen-image-3.0-pro); l’output nativo è PNG.
• L’accesso all’API Qwen Image 3.0 è disponibile tramite CometAPI. Gli sviluppatori possono ottenere una chiave API, verificare l’endpoint supportato e integrare la generazione di immagini nelle loro applicazioni.
• I prezzi dell’API Qwen Image 3.0 partono da $0.024/richiesta su CometAPI, a confronto con le tariffe Alibaba Cloud Singapore a partire da $0.030 per immagine Standard in output e $0.040 per immagine Pro 1K in output.
• L’editing di immagini con Qwen Image 3.0 supporta fino a tre immagini di riferimento tramite l’API nativa di Alibaba Cloud, mentre la generazione supporta da uno a sei output per richiesta.
• L’integrazione dell’API Qwen Image 3.0 richiede che gli sviluppatori verifichino parametri specifici del provider, autenticazione, unità di fatturazione e URL di immagini temporanei prima di mettere in produzione i flussi di lavoro.

Che cos’è l’API Qwen Image 3.0?

L’API Qwen Image 3.0 trasforma istruzioni testuali in immagini e può modificare fotografie o asset di design forniti. Gli scenari supportati includono poster multilingue, fotografia e-commerce, mockup di campagne, sostituzione dello sfondo ed editing composito.

Qwen Image 3.0 Standard (qwen-image-3.0) è la base orientata ai costi per la generazione da testo a immagine e l’editing guidato da riferimenti. Considerala prima per flussi ad alto volume come variazioni di sfondo per e-commerce, bozze visive per social media ed esplorazione di concept di campagna. Ad esempio, usa Standard per produrre più opzioni di sfondo prodotto, poi verifica la fedeltà al prodotto e seleziona le versioni da rifinire.

Qwen Image 3.0 Pro (qwen-image-3.0-pro) supporta generazione ed editing guidato da riferimenti, con un livello nativo di output 2K a prezzo superiore. Valutala per consegne sensibili alla qualità come immagini “hero” di campagna, composizioni prodotto dettagliate e poster promozionali. Ad esempio, prova un concept selezionato con Pro quando contano dettagli fini o layout e confronta i risultati accettati con Standard prima di impegnare un budget maggiore.

Come scegliere: parti da Standard per bozze e variazioni sensibili ai costi. Prova Pro sullo stesso brief per asset finali esigenti; selezionalo quando il miglioramento misurato giustifica il costo aggiuntivo. Nessuna delle due varianti sostituisce i test specifici dell’applicazione su tipografia, fedeltà al prodotto, conteggio oggetti o accuratezza del layout.

Quali parametri supporta l’API Qwen Image 3.0?

Usa questi parametri con l’interfaccia nativa di Alibaba Cloud compatibile con OpenAI. Aggiungi opzioni specifiche del provider alle richieste CometAPI solo quando il percorso selezionato le documenta.

Valido per entrambe le varianti: qwen-image-3.0 (Standard) e qwen-image-3.0-pro (Pro) supportano gli stessi parametri elencati di seguito sull’interfaccia nativa compatibile con OpenAI di Alibaba Cloud. Seleziona la variante con model; i controlli di generazione ed editing sono condivisi. Questo non implica qualità di output o prezzi identici, né garantisce che ogni percorso CometAPI esponga tutti i parametri nativi.

Per le richieste native, il rapporto d’aspetto dell’output deve rimanere tra 1:8 e 8:1. Le immagini di riferimento devono essere al massimo 10 MB, con ciascun lato tra 1 e 8.000 pixel e un rapporto lato lungo/lato corto non superiore a 10:1. Usa un data URI per l’input Base64. Thinking richiede prompt_extend=true; l’enhancement agent supporta solo il text-to-image.

Una richiesta immagine compatibile colloca i campi di generazione al livello superiore del JSON e formatta le dimensioni come 1024x1024. La DashScope nativa usa input/parameters annidati e scrive spesso le dimensioni come 1024*1024. Una richiesta copiata tra questi endpoint senza conversione può fallire.

Come chiamare l’API Qwen Image 3.0 con CometAPI?

Questa guida presuppone Python 3, un terminale compatibile Bash, un account CometAPI con accesso al modello e saldo sufficiente. La prima richiesta usa solo i campi model e prompt mostrati nell’esempio del provider. Documentazione verificata il 16 ottobre 2026; questi esempi non sono stati eseguiti su un account a pagamento.

Creare le credenziali

Crea una chiave API lato server nella dashboard CometAPI. Non inserirla mai in un client web o mobile.

export COMETAPI_KEY="your_api_key"python -m pip install requests

Inviare una richiesta di generazione minima

Gli sviluppatori possono accedere all’API Qwen Image 3.0 in CometAPI usando il percorso documentato per la generazione di immagini. Inizia con la richiesta minima qui sotto prima di introdurre parametri opzionali.

curl --fail-with-body https://api.cometapi.com/v1/images/generations \  -H "Authorization: Bearer $COMETAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"model":"qwen-image-3.0","prompt":"Premium skincare bottle on a stone pedestal, gentle studio lighting"}'

Salvare ogni immagine restituita

Salva il seguente script come generate.py ed esegui python generate.py. Invia una richiesta, gestisce risultati immagine tramite URL o Base64 e scrive localmente ogni immagine. Se la risposta contiene informazioni di task anziché un array data, si interrompe invece di indovinare un endpoint di polling; usa il contratto asincrono specifico dell’account per recuperare il risultato completato.

import base64import osfrom pathlib import Pathimport requests​response = requests.post(    "https://api.cometapi.com/v1/images/generations",    headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"},    json={"model": "qwen-image-3.0", "prompt": "A sunny bookstore cafe, editorial photograph"},    timeout=(15, 600),)response.raise_for_status()result = response.json()images = result.get("data")if not isinstance(images, list) or not images:    raise RuntimeError(f"No synchronous images; inspect task/error fields: {list(result)}")for index, item in enumerate(images, 1):    if item.get("url"):        download = requests.get(item["url"], timeout=(15, 120))        download.raise_for_status()        content = download.content    elif item.get("b64_json"):        content = base64.b64decode(item["b64_json"], validate=True)    else:        raise RuntimeError(f"Image {index} has no URL or Base64 payload")    path = Path(f"qwen_image_{index}.png")    path.write_bytes(content)    print(f"Saved {path}")

Un’esecuzione riuscita produce file immagine locali. Aprili per confermare che siano leggibili e corrispondano alla scena richiesta. Conserva l’identificatore della richiesta e i campi usage nei log del server senza registrare le credenziali.

Come generare più immagini con Qwen Image 3.0?

Sull’interfaccia nativa di Alibaba Cloud, imposta n tra due e sei per variazioni creative. Per CometAPI, abilita n solo dopo aver confermato il supporto sul percorso selezionato. Valida separatamente ogni asset restituito; un n più alto non garantisce che ogni risultato superi la revisione a valle.

Puoi generare fino a 6 immagini in una singola richiesta con Qwen Image 3.0 impostando il parametro n. Funziona con entrambe le varianti qwen-image-3.0 e qwen-image-3.0-pro, sia per generazione da testo a immagine sia per editing di immagini. L’impostazione predefinita è una sola immagine.

Ci sono due modi principali: usa un’interfaccia grafica se la tua piattaforma lo consente, oppure chiama direttamente l’API.

Generare più immagini tramite API

1. Apri la documentazione dell’API.
2. Ottieni una chiave API dalla console QwenCloud/ CometAPI.
3. Seleziona qwen-image-3.0 o qwen-image-3.0-pro.
4. Imposta n al numero di immagini desiderato, da 1 a 6.
5. Invia il prompt e salva le immagini restituite.

Ad esempio, imposta "n": 4 per richiedere quattro variazioni dello stesso prompt.

Esempio Python

Ecco un esempio pronto da adattare usando l’API compatibile con OpenAI.

from openai import OpenAIimport requestsclient = OpenAI(    api_key="YOUR_QWEN_API_KEY",    base_url="https://maas.qwencloudapi.com/compatible-mode/v1")
result = client.images.generate(    model="qwen-image-3.0-pro",    
prompt=(        "A cozy Japanese cafe on a rainy evening, "        "warm glowing lights, cinematic photography, "        "rich details, realistic reflections"    ),    
n=4,    
size="1024x1024")# Save each generated image
for i, item in enumerate(result.data, start=1):    response = requests.get(item.url)    response.raise_for_status()    with open(f"qwen_image_{i}.png", "wb") 
as f:        
f.write(response.content)print("Finished generating images!")

Installa prima i pacchetti necessari:

pip install openai requests

L’API restituisce un URL immagine per ogni risultato. Gli URL delle immagini generate sono temporanei, quindi scarica le immagini tempestivamente.

Impostazioni importanti

Il numero massimo di output è sei per richiesta. Tieni presente che richiedere più immagini aumenta il costo di generazione.

Una distinzione importante: n=4 richiede quattro variazioni di un unico prompt. Se vuoi quattro prompt diversi, devi effettuare richieste separate o automatizzare un ciclo sui tuoi prompt.

Come modificare immagini con Qwen Image 3.0?

Un editing combina da una a tre immagini di riferimento con istruzioni. Spiega sia la trasformazione desiderata sia ciò che non deve cambiare, ad esempio l’etichetta del prodotto, il colore, l’angolo di ripresa o la geometria del packaging.

Il prossimo esempio usa credenziali Alibaba Cloud e il suo campo immagine JSON per l’editing. Crea una chiave Model Studio regionale, ottieni l’ID del tuo workspace e configura l’endpoint corrispondente. Non sostituire una chiave CometAPI in questa richiesta.

export DASHSCOPE_API_KEY="your_model_studio_key"export ALIBABA_WORKSPACE_ID="your_workspace_id"export ALIBABA_IMAGE_ENDPOINT="https://${ALIBABA_WORKSPACE_ID}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations"

L’immagine di riferimento qui sotto proviene direttamente dall’esempio ufficiale dell’API. È un’immagine di input, non un risultato generato da questo articolo.

import os, requests
endpoint = os.environ["ALIBABA_IMAGE_ENDPOINT"]  
# documented regional .../images/generations endpoint
payload = {
"model": "qwen-image-3.0", 
"prompt": "Change the outfit to a charcoal business suit in a cafe. Preserve the face and hairstyle.", 
"image": ["https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"], 
"size": "1024x1024", 
"n": 1}
r = requests.post(endpoint, headers={
"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}, json=payload, timeout=(15, 600))
r.raise_for_status()
print(r.json())

L’endpoint nativo compatibile usa JSON su /images/generations, non upload multipart su /images/edits. Non supporta maschere o streaming. Leggi l’array data restituito e salva ciascun URL usando lo stesso ciclo di download mostrato sopra.

Per due riferimenti, includi due URL nell’array image e specifica i loro ruoli nel prompt (ad es., prodotto dalla prima immagine, ambientazione della stanza dalla seconda). La serie Qwen Image 3.0 accetta non più di tre immagini di riferimento; usa un modello diverso o un pre-processing per set di sorgenti più ampi.

Quanto costa l’API Qwen Image 3.0?

I prezzi dell’API Qwen Image 3.0 variano in base alla variante del modello, alla risoluzione dell’output e al provider. La tabella seguente integra il confronto originale di Alibaba Cloud Singapore con le tariffe CometAPI mostrate nella tabella prezzi allegata dal revisore. L’allegato elenca i prezzi di output in USD per immagine e uno sconto del 20% per tutte e quattro le combinazioni modello/risoluzione. Queste tariffe fornite non sono state indipendentemente riverificate rispetto alla fatturazione di un account reale; conferma il listino applicabile prima dell’uso in produzione.

*Gli esempi di volume sopra coprono solo le immagini di output: 100 immagini Standard 1K costano $2.40 e 100 immagini Pro 1K costano $3.20; 1,000 immagini Standard 2K costano $24.00 e 1,000 immagini Pro 2K costano $60.00. Per l’editing, aggiungi $0.0024 per ogni immagine di riferimento in input fatturabile. Sono esclusi le regole per job falliti, le tasse e gli adeguamenti specifici dell’account.

Usando le tariffe di input e output fornite, stima i costi immagine per ciascun provider come segue:

Costo totale = (immagini di riferimento fatturabili × prezzo immagine di input) + (output riusciti × prezzo immagine di output).

Per un job fatturato con due immagini di riferimento in input e tre output Standard 1K riusciti, i costi immagine su Alibaba Cloud sono (2 × $0.0030) + (3 × $0.0300) = $0.0960. I corrispondenti costi immagine su CometAPI sono (2 × $0.0024) + (3 × $0.0240) = $0.0768, in base alle tariffe fornite.

CometAPI addebita $0.0024 per immagine di riferimento in input per entrambe le varianti. I prezzi di output sono $0.0240 per immagine Standard a 1K o 2K, $0.0320 per immagine Pro a 1K e $0.0600 per immagine Pro a 2K. La tabella fornita elenca ogni tariffa di input e output al 20% in meno rispetto alla corrispondente tariffa ufficiale. Per gli stessi conteggi di immagini fatturabili, questi costi immagine sono quindi inferiori del 20%; commissioni aggiuntive o termini dell’account possono modificare la fattura finale.

Per il budgeting in produzione, verifica la variante selezionata, la risoluzione dell’immagine, gli addebiti per immagini di riferimento, il numero di output per richiesta e gli sconti applicabili all’account prima di stimare i costi totali di utilizzo.

Come gestire gli errori dell’API Qwen Image 3.0?

FAQ

Devo ritentare una richiesta Qwen Image 3.0 dopo un timeout?

Un timeout del client non prova che la generazione si sia fermata. Conserva qualsiasi identificatore di richiesta o task, controlla lo storico dei job del provider o l’API di stato documentata e determina se l’output esiste già prima di reinviare. I retry alla cieca possono creare job duplicati e costi aggiuntivi. Usa retry limitati per errori transitori e segui le linee guida di idempotenza del provider quando disponibili.

Come posso usare immagini di riferimento locali con Qwen Image 3.0?

Per l’interfaccia nativa compatibile, leggi il file come byte, codificalo in Base64 e anteponi un data URI come data:image/png;base64,. Inserisci quella stringa completa in image. L’input Base64 deve comunque rispettare i limiti di dimensione e dimensioni dell’immagine; un percorso del filesystem locale non è un URL recuperabile dal servizio.

Come passo opzioni specifiche di Qwen tramite un SDK OpenAI?

Mantieni i campi immagine standard nei soliti argomenti dell’SDK e inserisci i campi estensione di Model Studio, come image e prompt_extend, dentro extra_body. Le richieste HTTP raw collocano questi campi direttamente al livello superiore del JSON. Questa indicazione si applica all’interfaccia nativa compatibile; verifica il percorso CometAPI selezionato prima di inoltrare opzioni specifiche del provider.

Cosa devo fare quando Qwen Image 3.0 restituisce meno immagini di quelle richieste?

Salva prima gli output riusciti e registra il conteggio effettivo. Per la fatturazione nativa di Alibaba Cloud, gli addebiti di output seguono le immagini generate con successo. Se servono altri asset, richiedi solo la quantità mancante dopo aver controllato la risposta e il record di utilizzo; la fatturazione su CometAPI deve essere riconciliata in base ai termini del relativo account.

Conclusione

Qwen Image 3.0 è una scelta pratica per i team che necessitano di generazione ed editing guidato da riferimenti all’interno di un’unica famiglia di modelli. Usa Standard come base orientata ai costi, prova Pro per task 2K o creativi più esigenti e misura il costo degli output accettati invece di valutare il solo prezzo per richiesta. Parti dalla chiamata minima di generazione, conserva i relativi output, quindi aggiungi editing o output multipli tramite il contratto del provider appropriato. Mantieni separati credenziali e schemi di richiesta, gestisci gli errori in modo esplicito e riconcilia l’utilizzo delle immagini con il listino selezionato.