Come usare l'API Qwen Image 3 Pro tramite DashScope: un tutorial per sviluppatori

Come usare l'API Qwen Image 3 Pro tramite DashScope: un tutorial per sviluppatori

qwen-image-3.0-pro di Alibaba è il modello di punta per la generazione di immagini offerto tramite Model Studio, noto anche come DashScope o Bailian. Si rivolge agli sviluppatori backend che necessitano di un endpoint affidabile per la conversione da testo a immagine con prezzi prevedibili. L'ID del modello ufficiale qwen-image-3.0-pro è documentato nel catalogo Model Studio di Alibaba (documenti Alibaba Cloud Model Studio, 2026), e puoi chiamarlo da qualsiasi client HTTP.

Questo tutorial illustra l'integrazione completa. Alla fine, avrai una chiave API, una chiamata cURL funzionante, un frammento di codice Python e una chiara visione della struttura dei costi per immagine.

Punti chiave

• ID modello: qwen-image-3.0-pro, fornito su Alibaba Cloud Model Studio / DashScope all'indirizzo https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).
• Autenticazione: imposta DASHSCOPE_API_KEY come variabile d'ambiente, quindi inviala come token Bearer (Promptfoo, 2026).
• Prezzo di riferimento: il predecessore qwen-image-2.0-pro costa $0.075 per immagine generata sui prezzi ufficiali di Alibaba (prezzi Alibaba Cloud, 2026).
• Ogni modello di immagine ha una quota gratuita per i test prima di pagare un centesimo (FAQ API Immagini Alibaba, 2026).

Prerequisiti

Prima di scrivere qualsiasi codice, conferma di avere un account Alibaba Cloud con accesso a Model Studio. La guida ufficiale "Prima chiamata API a Qwen" elenca tre cose di cui ogni sviluppatore ha bisogno: una chiave API generata nella console di Model Studio, un ID Workspace legato al tuo progetto e l'accesso all'endpoint HTTP di DashScope (Alibaba Cloud, 2026).

Hai anche bisogno di strumenti di base. Un terminale con cURL, Python 3.9 o più recente e la libreria requests coprono tutto in questo tutorial. Non è richiesto alcun SDK proprietario. Se hai mai chiamato l'API OpenAI da uno script, il modello DashScope ti sembrerà familiare, poiché entrambi utilizzano token Bearer e corpi di richiesta JSON.

Un modello consigliato è quello di mantenere un Workspace dedicato per ambiente, in modo che le chiavi di staging non tocchino mai le quote di produzione. Questa separazione rende anche più pulita l'attribuzione dei costi alla fine del mese.

Passaggio 1: Ottieni la tua chiave API e l'ID Workspace

La chiave API è la credenziale che autorizza ogni chiamata che fai a qwen-image-3.0-pro. La guida introduttiva di Alibaba istruisce gli sviluppatori a creare la chiave all'interno della console di Model Studio e quindi a copiare l'ID Workspace dalla stessa dashboard (Alibaba Cloud, 2026). Tratta entrambi i valori come segreti.

Per recuperarli:

1. Accedi alla console di Model Studio nel portale Alibaba Cloud.
2. Apri la sezione API Keys e clicca su Create API Key.
3. Copia immediatamente la chiave generata. La console nasconde il valore completo dopo la creazione.
4. Annota l'ID Workspace visualizzato nella parte superiore della dashboard.

Memorizza la chiave in un gestore di password o nel backend segreto del tuo team. Non incollarla nei file sorgente. L'ID Workspace è meno sensibile ma vale comunque la pena di tenerlo nella configurazione piuttosto che in linea.

Capsula di citazione: La guida ufficiale di Alibaba "Prima chiamata API a Qwen" istruisce gli sviluppatori a creare una chiave API nella console di Model Studio, copiare l'ID Workspace dalla stessa dashboard e chiamare i modelli tramite l'endpoint DashScope all'indirizzo https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).

Passaggio 2: Imposta la variabile d'ambiente DASHSCOPE_API_KEY

Caricare la chiave in una variabile d'ambiente la tiene fuori dal tuo codice e fuori dal controllo di versione. Il modello della community documentato da Promptfoo è quello di impostare una variabile chiamata DASHSCOPE_API_KEY prima di eseguire il tuo script, che viene poi letta dal client HTTP al momento della richiesta (Promptfoo, 2026).

Su macOS e Linux:

export DASHSCOPE_API_KEY="sk-la-tua-chiave-qui"

Su Windows PowerShell:

$env:DASHSCOPE_API_KEY = "sk-la-tua-chiave-qui"

Per una configurazione permanente, aggiungi la riga di esportazione al tuo ~/.zshrc, ~/.bashrc o alle variabili d'ambiente utente di Windows. Riavvia il terminale in seguito. Verifica che la variabile sia caricata prima di procedere:

echo $DASHSCOPE_API_KEY

Una configurazione comune è un file .env più un caricatore come python-dotenv, in modo che la stessa configurazione funzioni su sviluppo locale, CI e distribuzioni di container. Ricorda di aggiungere .env a .gitignore in modo che la chiave non venga mai commessa.

Passaggio 3: Effettua la tua prima chiamata di generazione di immagini con cURL

L'endpoint DashScope all'indirizzo https://dashscope-us.aliyuncs.com/api/v1 è il punto di ingresso per ogni modello Qwen, incluso qwen-image-3.0-pro (Alibaba Cloud, 2026). Le chiamate utilizzano un token Bearer nell'intestazione Authorization e un corpo JSON che nomina il modello più il tuo prompt.

Di seguito è riportata una richiesta cURL illustrativa basata sull'endpoint documentato e sul modello di autenticazione. I nomi dei campi e i percorsi esatti delle richieste seguono la convenzione DashScope, ma dovresti confermare lo schema attuale rispetto al riferimento API ufficiale su API Qwen tramite DashScope prima di spedire in produzione.

# Esempio illustrativo. Conferma i nomi esatti dei campi e i percorsi rispetto a:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "Una accogliente caffetteria libreria in autunno, luce calda, molto dettagliata"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

Alcune note pratiche:

• Alcuni endpoint di immagine DashScope sono asincroni, il che significa che la prima risposta restituisce un ID attività e si interroga un secondo URL per recuperare l'immagine finita. Controlla il riferimento API per il comportamento esatto di qwen-image-3.0-pro.
• Mantieni i prompt al di sotto del limite di token documentato. I prompt lunghi possono essere troncati silenziosamente.
• Utilizza il parametro size corrispondente a uno dei rapporti di aspetto supportati, altrimenti la chiamata potrebbe ricadere su un valore predefinito.

Capsula di citazione: L'endpoint ufficiale DashScope all'indirizzo https://dashscope-us.aliyuncs.com/api/v1 serve qwen-image-3.0-pro, con un riferimento completo ai parametri di input e output documentato da Alibaba Cloud (Alibaba Cloud, 2026).

Passaggio 4: Analizza la risposta in Python

Python è il linguaggio più comune per avvolgere le API di immagini perché la libreria requests rende l'analisi JSON banale. Una volta che la chiamata restituisce, estrai l'URL dell'immagine generata, scaricala e persistila su disco o in un archivio oggetti.

Ecco un breve script illustrativo. Come con cURL, conferma i nomi dei campi di risposta rispetto al riferimento API ufficiale prima di farci affidamento.

# Esempio illustrativo. Conferma lo schema di risposta rispetto a:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "Una accogliente caffetteria libreria in autunno, luce calda, molto dettagliata"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# I nomi dei campi seguenti sono illustrativi. Verifica rispetto al riferimento API ufficiale.
image_url = data["output"]["results"][0]["url"]
print("URL dell'immagine generata:", image_url)

# Scarica il file
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

Alcuni suggerimenti di livello di produzione:

• Avvolgi la chiamata in retry con backoff esponenziale. Possono verificarsi interruzioni di rete.
• Aggiungi un timeout. La generazione di immagini può richiedere diversi secondi.
• Registra l'ID completo della richiesta, solitamente restituito in un'intestazione di risposta, in modo che il supporto Alibaba possa tracciare i fallimenti.

È utile aggiungere un sottile strato di astrazione tra il client API e la logica di business. In questo modo, lo scambio di modelli in seguito (ad esempio a un endpoint di modifica o a una versione più recente di Qwen) modifica solo un modulo.

Quanto costa Qwen Image 3 Pro?

Il prezzo è per immagine generata, e Alibaba ti fattura solo per le generazioni riuscite. La pagina ufficiale dei prezzi elenca qwen-image-2.0-pro a $0.075 per immagine (prezzi Alibaba Cloud, 2026). Fornitori di terze parti offrono modelli di immagini Qwen a diversi prezzi: Fal elenca un modello di immagine Qwen a circa $0.021 per immagine, e Replicate addebita circa $0.030 per immagine a 1024x1024 (analisi dei prezzi Puter, 2026; pricepertoken, 2026).

Per qwen-image-3.0-pro in particolare, tratta il prezzo di 2.0-pro come il riferimento ufficiale più vicino, quindi verifica la cifra attuale sulla pagina dei prezzi di Model Studio prima di fare il budget.

Capsula di citazione: Model Studio di Alibaba prezza qwen-image-2.0-pro a $0.075 per immagine generata, fatturando solo le generazioni riuscite, mentre fornitori di terze parti come Fal e Replicate elencano modelli di immagini Qwen a circa $0.021 e $0.030 per immagine rispettivamente (Alibaba Cloud, 2026; Puter, 2026).

Un budget mensile approssimativo per una piccola app potrebbe essere simile a questo:

Prezzi a luglio 2026.

Quota gratuita e limiti

Ogni modello di immagine su Model Studio viene fornito con una quota gratuita, in modo da poter testare prima di impegnare la spesa (FAQ API Immagini Alibaba, 2026). La quota si resetta secondo un programma documentato nelle FAQ.

Alcuni suggerimenti pratici:

• Utilizza la quota gratuita per convalidare i modelli di prompt e le combinazioni di parametri.
• Monitora l'utilizzo nella dashboard di Model Studio per evitare bollette a sorpresa una volta passato ai livelli a pagamento.
• Se i tuoi test iniziano improvvisamente a fallire con errori di quota, ricontrolla se il livello gratuito è scaduto o se hai cambiato Workspace.

Oltre il testo-a-immagine: l'API di modifica

La famiglia Qwen include anche un endpoint dedicato per la modifica delle immagini. Supporta input e output multi-immagine, modifica del testo all'interno dell'immagine, aggiunta, rimozione e spostamento di oggetti e modifiche di posa (API di modifica Qwen-Image, 2026).

Questo è importante perché le chiamate di modifica utilizzano una forma di richiesta diversa dalle chiamate testo-a-immagine. Se il tuo prodotto necessita di scambio di sfondo o rimozione di oggetti, dovrai accedere a un endpoint separato con i suoi parametri e prezzi. Pianifica due percorsi di integrazione: uno per la generazione, uno per la modifica.

FAQ

Qual è l'ID del modello per Qwen Image 3 Pro?

L'ID del modello ufficiale è qwen-image-3.0-pro, servito su Alibaba Cloud Model Studio / DashScope all'indirizzo https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026). Utilizza questa stringa esatta nel campo model del corpo della tua richiesta.

Come autentico le chiamate API DashScope?

Imposta la variabile d'ambiente DASHSCOPE_API_KEY, quindi inviala come token Bearer nell'intestazione Authorization di ogni richiesta (Promptfoo, 2026). Non codificare mai la chiave nei file sorgente o commetterla al controllo di versione.

Quanto costa Qwen Image 3 Pro per immagine?

Alibaba prezza il predecessore qwen-image-2.0-pro a $0.075 per immagine e fattura solo le generazioni riuscite (prezzi Alibaba Cloud, 2026). Fornitori di terze parti come Fal e Replicate elencano i modelli di immagini Qwen a circa $0.021 e $0.030 per immagine. Verifica i prezzi attuali di 3.0-pro sulla pagina ufficiale.

C'è una quota gratuita?

Sì. Ogni modello di immagine su Model Studio ha una quota gratuita che puoi utilizzare per i test prima che inizi la fatturazione a pagamento (FAQ API Immagini Alibaba, 2026). Controlla le FAQ per la cadenza di reset e i limiti, che variano a seconda del modello.

Qwen Image 3 Pro supporta la modifica delle immagini?

La modifica è gestita da un endpoint separato chiamato Qwen-Image Edit, che supporta I/O multi-immagine, modifica del testo all'interno delle immagini, aggiunta, rimozione e spostamento di oggetti e modifiche di posa (API di modifica Qwen-Image, 2026). Le API testo-a-immagine e di modifica hanno forme di richiesta diverse.

Conclusione

Ora hai il percorso completo per la tua prima chiamata a qwen-image-3.0-pro: una chiave API dalla console di Model Studio, la variabile d'ambiente DASHSCOPE_API_KEY caricata, una richiesta cURL funzionante e un frammento di codice Python che analizza e scarica il risultato. Il modello di prezzo per immagine, a partire da $0.075 sui prezzi ufficiali di Alibaba, rende il costo prevedibile man mano che si scala.

Due passaggi successivi affineranno la tua integrazione. Primo, conferma i nomi esatti dei campi di richiesta e risposta rispetto al riferimento API ufficiale su API Qwen tramite DashScope, poiché i dettagli dello schema possono cambiare tra le versioni del modello. Secondo, se il tuo prodotto necessita di modifiche piuttosto che di pura generazione, esplora l'API di modifica Qwen-Image, che sblocca la rimozione di oggetti, la modifica del testo e le modifiche di posa tramite un endpoint dedicato.

Costruisci in piccolo, controlla la tua quota e spedisci.