Azure modelli di generazione di immagini OpenAI

Importante

Il DALL-E modello dall-e-3 di generazione di immagini è stato ritirato il 4 marzo 2026 e non è più disponibile per le nuove distribuzioni. Le implementazioni esistenti non funzionano. Usare invece un gpt-image- modello di serie per la generazione di immagini. Per istruzioni aggiornate, vedere la guida pratica alla generazione di immagini .

I modelli di generazione di immagini openAI creano immagini da richieste di testo fornite dall'utente e immagini facoltative. Questo articolo illustra come usare questi modelli, configurare le opzioni e trarre vantaggio dalle funzionalità avanzate di generazione di immagini in Azure.

È possibile eseguire la generazione di immagini tramite l'API di generazione di immagini o l'API delle risposte. In alternativa, è possibile sperimentare la generazione di immagini nel portale foundry

Per selezionare l'approccio e il modello API preferiti, usare le schede all'inizio di questa pagina.

Modelli e funzionalità

Usare questa tabella per apprendere le differenze tra i diversi modelli di generazione di immagini e per scegliere il modello migliore per le esigenze di generazione delle immagini.

Aspetto GPT-Image-2 GPT-Image-1.5 GPT-Image-1 GPT-Image-1-Mini
Disponibilità Anteprima pubblica Anteprima di accesso limitato (fai domanda per l'accesso GPT-image-1.5) Anteprima dell'accesso limitato (richiedi accesso a GPT-image-1) Anteprima dell'accesso limitato (richiedi accesso a GPT-image-1)
Punti di forza Ideale per la generazione a risoluzione elevata e 4K, la modifica delle immagini migliorata e il supporto di proporzioni estese Ideale per il realismo, l'esecuzione delle istruzioni, il contesto multidimensionale e la velocità/costo migliorata Ideale per il realismo, seguire istruzioni e il contesto multimodale Ideale per la creazione rapida di prototipi, la generazione in blocco o i casi d'uso sensibili ai costi
Modalità di input/output e formato Accetta input di testo e immagine ; restituisce le immagini solo in base64 (nessuna opzione URL). Accetta input di testo e immagine ; restituisce le immagini solo in base64 (nessuna opzione URL). Accetta input di testo e immagine ; restituisce le immagini solo in base64 (nessuna opzione URL). Accetta input di testo e immagine ; restituisce le immagini solo in base64 (nessuna opzione URL).
Dimensioni immagine/risoluzioni Risoluzioni arbitrarie: entrambi i bordi devono essere multipli di 16 px; bordo lungo fino a 3.840 px (4K); proporzioni fino a 3:1; numero di pixel 655.360-8.294.400 1024×1024, 1024×1536, 1536×1024 1024×1024, 1024×1536, 1536×1024 1024×1024, 1024×1536, 1536×1024
Opzioni di qualità Controlli qualitativi rielaborati: low, medium, high; low è ottimizzato per i casi d'uso sensibili alla latenza low, medium, high (impostazione predefinita = alta) low, medium, high (impostazione predefinita = alta) low, medium, high (impostazione predefinita = media)
Numero di immagini per richiesta 1-10 immagini per richiesta (n parametro) 1-10 immagini per richiesta (n parametro) 1-10 immagini per richiesta (n parametro) 1-10 immagini per richiesta (n parametro)
Modifica (inpainting/varianti) ✅ Miglioramento delle prestazioni di modifica con inpainting e varianti ✅ Supporta l'inpainting e le variazioni con maschera + prompt ✅ Supporta l'inpainting e le variazioni con maschera + prompt ✅ Supporta l'inpainting e le variazioni con maschera + prompt
Conservazione dei volti ✅ Conservazione avanzata dei volti per risultati realistici e coerenti ✅ Conservazione avanzata dei volti per risultati realistici e coerenti ✅ Conservazione avanzata dei volti per risultati realistici e coerenti ❌ Nessuna preservazione del volto dedicata; migliore per immagini creativi non di ritratto/generali
Prestazioni e costi Modello altamente fedele e ottimizzato per il realismo ; latenza e costi più elevati Modello altamente fedele e ottimizzato per il realismo ; maggiore efficienza e latenza su GPT-Image-1 Modello altamente fedele e ottimizzato per il realismo ; latenza e costi più elevati Costi efficienti e veloci per la generazione iterativa o su larga scala

Avvio rapido

Usare questa guida per iniziare a chiamare le API REST per la generazione di immagini di Azure OpenAI nei modelli Foundry di Microsoft utilizzando Python.

Prerequisiti

Installazione

Recuperare la chiave e l'endpoint

Per chiamare correttamente le API OpenAI Azure, sono necessarie le informazioni seguenti sulla risorsa OpenAI Azure:

Variabile Nome Valore
Endpoint api_base Il valore dell'endpoint si trova in Keys and Endpoint per la risorsa nel portale di Azure. È anche possibile trovare l'endpoint tramite la pagina Distribuzioni nel portale di Foundry. Un endpoint di esempio è: https://docs-test-001.openai.azure.com/.
Chiave api_key Il valore della chiave si trova anche in Chiavi ed Endpoint per la risorsa nel portale di Azure. Azure genera due chiavi per la risorsa. È possibile usare uno dei due valori.

Passare alla risorsa nel portale di Azure. Nel riquadro di spostamento selezionare Chiavi ed endpoint in Gestione risorse. Copiare il valore endpoint e un valore della chiave di accesso. È possibile usare il valore KEY 1 o KEY 2 . Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.

Screenshot che mostra la pagina Chiavi ed endpoint per una risorsa OpenAI Azure nel portale Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Si raccomanda l'autenticazione di Microsoft Entra ID con identità gestite delle risorse Azure per evitare di archiviare le credenziali nelle applicazioni in esecuzione nel cloud.

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non pubblicarla mai pubblicamente. Se si usano chiavi API, archiviarli in modo sicuro in Azure Key Vault, ruotare regolarmente le chiavi e limitare l'accesso alle Azure Key Vault usando il controllo degli accessi in base al ruolo e le restrizioni di accesso alla rete. Per altre informazioni sull'uso sicuro delle chiavi API nelle app, vedere ChiaviAPI con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi di intelligenza artificiale, vedere Autorizzazione delle richieste a Servizi di Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creare una nuova applicazione Python

Creare un nuovo file di Python denominato quickstart.py. Aprire il nuovo file nell'editor o nell'IDE preferito.

  1. Sostituire il contenuto di quickstart.py con il codice seguente. Modifica il valore di prompt con il testo di tua preferenza. Imposta deployment anche sul nome del deployment che hai scelto quando hai distribuito il modello di generazione di immagini.

    import os
import requests
import base64
from PIL import Image
from io import BytesIO

# set environment variables
endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
subscription_key = os.getenv("AZURE_OPENAI_API_KEY")

deployment = "gpt-image-1.5" # the name of your GPT-image series deployment
api_version = "2025-04-01-preview" # or later version

def decode_and_save_image(b64_data, output_filename):
  image = Image.open(BytesIO(base64.b64decode(b64_data)))
  image.show()
  image.save(output_filename)

def save_all_images_from_response(response_data, filename_prefix):
  for idx, item in enumerate(response_data['data']):
    b64_img = item['b64_json']
    filename = f"{filename_prefix}_{idx+1}.png"
    decode_and_save_image(b64_img, filename)
    print(f"Image saved to: '{filename}'")

base_path = f'openai/deployments/{deployment}/images'
params = f'?api-version={api_version}'

generation_url = f"{endpoint}{base_path}/generations{params}"
generation_body = {
  "prompt": "girl falling asleep",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  # "background": "transparent",  # "auto" or "transparent" (GPT-image-1 only; requires PNG output)
  # "output_compression": 100,  # 0-100 compression level (JPEG output only)
}
generation_response = requests.post(
  generation_url,
  headers={
    'Api-Key': subscription_key,
    'Content-Type': 'application/json',
  },
  json=generation_body
).json()
save_all_images_from_response(generation_response, "generated_image")

# In addition to generating images, you can edit them.
edit_url = f"{endpoint}{base_path}/edits{params}"
edit_body = {
  "prompt": "girl falling asleep",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium"
}
files = {
  "image": ("generated_image_1.png", open("generated_image_1.png", "rb"), "image/png"),
  # You can use a mask to specify which parts of the image you want to edit.
  # The mask must be the same size as the input image.
  # "mask": ("mask.png", open("mask.png", "rb"), "image/png"),
}
edit_response = requests.post(
  edit_url,
  headers={'Api-Key': subscription_key},
  data=edit_body,
  files=files
).json()
save_all_images_from_response(edit_response, "edited_image")

    Lo script esegue una chiamata API di generazione di immagini sincrona.

    Importante

    Ricordarsi di rimuovere la chiave dal codice al termine e non pubblicare mai la chiave pubblicamente. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali. Per altre informazioni, vedere Azure Key Vault.

  2. Eseguire l'applicazione con il python comando :

    python quickstart.py

    Attendere alcuni istanti per ottenere la risposta.

Output

L'output di una chiamata API di generazione di immagini corretta è simile all'esempio seguente. Il b64_json campo contiene i dati dell'immagine di output con codifica Base64.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
}

Una risposta positiva include:

  • Timestamp created (ora dell'epoca Unix)
  • Matrice data con almeno un oggetto immagine: un valore b64_json (dati immagine codificati in base64) per ogni immagine generata

Errori comuni

Errore Causa Risoluzione
DeploymentNotFound Il nome della distribuzione non esiste o è digitato in modo errato Verificare il nome della distribuzione nel portale di Azure o nel portale foundry
401 Unauthorized Chiave API non valida o mancante Verificare che la AZURE_OPENAI_API_KEY variabile di ambiente sia impostata correttamente
429 Too Many Requests Limite di velocità superato Implementare la logica di ripetizione dei tentativi con backoff esponenziale
content_policy_violation Richiesta o output generato bloccato dal filtro contenuto Modificare il prompt per conformarsi alla politica sui contenuti
InvalidPayload Parametri obbligatori mancanti o valori non validi Verificare che prompt, sizee n siano specificati correttamente

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non genera un'immagine. Per altre informazioni, vedere Filtro del contenuto. Per esempi di risposte agli errori, vedere la guida pratica relativa alla generazione di immagini.

Il sistema restituisce lo stato dell'operazione Failed e il error.code valore nel messaggio è impostato su contentFilter. Ecco un esempio:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Your task failed as a result of our safety system."
    }
}

È anche possibile che l'immagine generata sia filtrata. In questo caso, il messaggio di errore è impostato su Generated image was filtered as a result of our safety system.. Ecco un esempio:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Generated image was filtered as a result of our safety system."
    }
}

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK per Python.

Della libreria codice sorgente | Pacchetto | Esempi

Prerequisiti

Per altre informazioni, vedere Creare una risorsa e distribuire un modello con Azure OpenAI.

Installazione

Recuperare la chiave e l'endpoint

Per chiamare correttamente le API OpenAI Azure, sono necessarie le informazioni seguenti sulla risorsa OpenAI Azure:

Variabile Nome Valore
Endpoint api_base Il valore dell'endpoint si trova in Keys and Endpoint per la risorsa nel portale di Azure. È anche possibile trovare l'endpoint tramite la pagina Deployments nel portale di Microsoft Foundry. Un endpoint di esempio è: https://docs-test-001.openai.azure.com/.
Chiave api_key Il valore della chiave si trova anche in Chiavi ed Endpoint per la risorsa nel portale di Azure. Azure genera due chiavi per la risorsa. È possibile usare uno dei due valori.

Passare alla risorsa nel portale di Azure. Nel riquadro di spostamento selezionare Chiavi ed endpoint in Gestione risorse. Copiare il valore endpoint e un valore della chiave di accesso. È possibile usare il valore KEY 1 o KEY 2 . Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.

Screenshot che mostra la pagina Chiavi ed endpoint per una risorsa OpenAI Azure nel portale Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Si raccomanda l'autenticazione di Microsoft Entra ID con identità gestite delle risorse Azure per evitare di archiviare le credenziali nelle applicazioni in esecuzione nel cloud.

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non pubblicarla mai pubblicamente. Se si usano chiavi API, archiviarli in modo sicuro in Azure Key Vault, ruotare regolarmente le chiavi e limitare l'accesso alle Azure Key Vault usando il controllo degli accessi in base al ruolo e le restrizioni di accesso alla rete. Per altre informazioni sull'uso sicuro delle chiavi API nelle app, vedere ChiaviAPI con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi di intelligenza artificiale, vedere Autorizzazione delle richieste a Servizi di Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Installare Python SDK

Apri un prompt dei comandi e naviga fino alla cartella del tuo progetto. Installare OpenAI Python SDK usando il comando seguente:

pip install openai

Installare anche le librerie seguenti:

pip install requests
pip install pillow

Generare immagini

Creare un nuovo file Python , quickstart.py. Aprirlo nell'editor o nell'IDE preferito.

Sostituire il contenuto di quickstart.py con il codice seguente.

from openai import AzureOpenAI
import os
import base64
from PIL import Image

client = AzureOpenAI(
    api_version="2025-04-01-preview",  
    api_key=os.environ["AZURE_OPENAI_API_KEY"],  
    azure_endpoint=os.environ['AZURE_OPENAI_ENDPOINT']
)

result = client.images.generate(
    model="gpt-image-1", # the name of your GPT-image series deployment
    prompt="a close-up of a bear walking through the forest",
    n=1,
    size="1024x1024",
    quality="high",
    output_format="png",
    # background="transparent",  # Set to "transparent" for transparent backgrounds (GPT-image-1 only; requires PNG)
    # output_compression=100,  # 0-100 compression level (JPEG output only)
)

# Set the directory for the stored image
image_dir = os.path.join(os.curdir, 'images')

# If the directory doesn't exist, create it
if not os.path.isdir(image_dir):
    os.mkdir(image_dir)

# Initialize the image path (note the filetype should be png)
image_path = os.path.join(image_dir, 'generated_image.png')

# GPT-image-1 models always return base64-encoded image data
image_base64 = result.data[0].b64_json
generated_image = base64.b64decode(image_base64)
with open(image_path, "wb") as image_file:
    image_file.write(generated_image)

# Display the image in the default image viewer
image = Image.open(image_path)
image.show()
  1. Assicurarsi che le AZURE_OPENAI_ENDPOINT variabili di ambiente e AZURE_OPENAI_API_KEY siano impostate.
  2. Modifica il valore di prompt con il testo di tua preferenza.
  3. Modificare il valore di model impostando il nome del modello di serie GPT-image distribuito.

Importante

Ricordarsi di rimuovere la chiave dal codice al termine e non pubblicare mai la chiave pubblicamente. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali. Per altre informazioni, vedere Azure Key Vault.

Eseguire l'applicazione con il python comando :

python quickstart.py

Attendere alcuni istanti per ottenere la risposta.

Output

Azure OpenAI archivia l'immagine di output nel file generated_image.png nella directory specificata. Lo script visualizza anche l'immagine nel visualizzatore di immagini predefinito.

Una risposta positiva include:

  • Un created timestamp
  • Matrice data con almeno un oggetto immagine
  • Un b64_json campo con dati di immagine con codifica Base64 (i modelli GPT-image-1 restituiscono sempre base64)

Errori comuni

Errore Causa Risoluzione
DeploymentNotFound Il nome della distribuzione non esiste o è digitato in modo errato Verificare il nome della distribuzione nel portale di Azure o nel portale foundry
AuthenticationError Chiave API non valida o mancante Verificare che la AZURE_OPENAI_API_KEY variabile di ambiente sia impostata correttamente
RateLimitError Limite di velocità superato Implementare la logica di ripetizione dei tentativi con backoff esponenziale
content_policy_violation Richiesta o output generato bloccato dal filtro contenuto Modificare il prompt per conformarsi alla politica sui contenuti

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non genera un'immagine. Per altre informazioni, vedere Filtro del contenuto.

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK per C#.

codice sorgente Library | Package (NuGet) | Samples

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Configurare

  1. Creare una nuova cartella image-quickstart e passare alla cartella di avvio rapido con il comando seguente:

    mkdir image-quickstart && cd image-quickstart

  2. Creare una nuova applicazione console con il comando seguente:

    dotnet new console

  3. Installare la libreria client OpenAI .NET con il comando dotnet add package:

    dotnet add package Azure.AI.OpenAI --version 1.0.0-beta.6

  4. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, installare il pacchetto Azure.Identity con:

    dotnet add package Azure.Identity

  5. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, effettuare l'accesso ad Azure con il comando seguente:

    az login

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Eseguire l'avvio rapido

Il codice di esempio in questa guida introduttiva usa Microsoft Entra ID per l'autenticazione senza chiave consigliata. Se si preferisce usare una chiave API, è possibile sostituire l'oggetto DefaultAzureCredential con un AzureKeyCredential oggetto .

AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());

Per eseguire il quickstart, seguire questa procedura:

  1. Sostituire il contenuto di Program.cs con il codice seguente e aggiornare i valori segnaposto con i propri.

    using Azure;
using Azure.AI.OpenAI;
using OpenAI.Images;
using static System.Environment;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? "https://<your-resource-name>.openai.azure.com/";
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? "<your-key>";

// Use the recommended keyless credential instead of the AzureKeyCredential credential.
AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 
//AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

// This must match the custom deployment name you chose for your model
ImageClient chatClient = openAIClient.GetImageClient("gpt-image-1");

var imageGeneration = await chatClient.GenerateImageAsync(
        "a happy monkey sitting in a tree, in watercolor",
        new ImageGenerationOptions()
        {
            Size = GeneratedImageSize.W1024xH1024
        }
    );

Console.WriteLine(imageGeneration.Value.ImageUri);

  2. Eseguire l'applicazione usando il comando dotnet run o il pulsante Esegui nella parte superiore di Visual Studio:

    dotnet run

Output

I dati dell'immagine con codifica base64 vengono stampati nella console.

Importante

GPT-image-1 e GPT-image-2 supportano anche parametri aggiuntivi, quality ad esempio (low, medium, high), output_format (png, jpeg), background (auto, transparent) e output_compression (solo 0-100, JPEG). Per informazioni dettagliate, vedere Opzioni API.

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non restituirà un'immagine generata. Per altre informazioni, vedere l'articolo relativo al filtro del contenuto .

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa. Prima di eliminare la risorsa, è necessario eliminare i modelli distribuiti.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK per Java.

codice sorgente Library | Artifact (Maven) | Samples

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Configurare

  1. Creare una nuova cartella image-quickstart e passare alla cartella di avvio rapido con il comando seguente:

    mkdir image-quickstart && cd image-quickstart

  2. Installare Apache Maven. Eseguire quindi mvn -v per confermare l'installazione avvenuta con successo.

  3. Creare un nuovo pom.xml file nella radice del progetto e copiarne il codice seguente:

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.azure.samples</groupId>
     <artifactId>quickstart-image-generation</artifactId>
     <version>1.0.0-SNAPSHOT</version>
     <build>
         <sourceDirectory>src</sourceDirectory>
         <plugins>
         <plugin>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.7.0</version>
             <configuration>
             <source>1.8</source>
             <target>1.8</target>
             </configuration>
         </plugin>
         </plugins>
     </build>
     <dependencies>    
         <dependency>
             <groupId>com.azure</groupId>
             <artifactId>azure-ai-openai</artifactId>
             <version>1.0.0-beta.3</version>
         </dependency>
         <dependency>
             <groupId>com.azure</groupId>
             <artifactId>azure-core</artifactId>
             <version>1.53.0</version>
         </dependency>
         <dependency>
             <groupId>com.azure</groupId>
             <artifactId>azure-identity</artifactId>
             <version>1.15.1</version>
         </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>
             <version>1.7.9</version>
         </dependency>
     </dependencies>
 </project>

  4. Installare Azure OpenAI SDK e le dipendenze.

    mvn clean dependency:copy-dependencies

  5. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, effettuare l'accesso ad Azure con il comando seguente:

    az login

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Eseguire l'app

Il codice di esempio in questa guida introduttiva usa Microsoft Entra ID per l'autenticazione senza chiave consigliata. Se si preferisce usare una chiave API, è possibile sostituire l'oggetto DefaultAzureCredential con un AzureKeyCredential oggetto .

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

Seguire questa procedura per creare un'applicazione console per la generazione di immagini.

  1. Creare un nuovo file denominato Quickstart.java nella stessa directory radice del progetto.

  2. Copiare il codice seguente in Quickstart.java:

    import com.azure.ai.openai.OpenAIAsyncClient;
import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.models.ImageGenerationOptions;
import com.azure.ai.openai.models.ImageLocation;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.models.ResponseError;

import java.util.concurrent.TimeUnit;

public class Quickstart {

    public static void main(String[] args) throws InterruptedException {

        String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");

        // Use the recommended keyless credential instead of the AzureKeyCredential credential.

        OpenAIAsyncClient client = new OpenAIClientBuilder()
            .endpoint(endpoint)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildAsyncClient();

        ImageGenerationOptions imageGenerationOptions = new ImageGenerationOptions(
            "A drawing of the Seattle skyline in the style of Van Gogh");
        client.getImages(imageGenerationOptions).subscribe(
            images -> {
                for (ImageLocation imageLocation : images.getData()) {
                    ResponseError error = imageLocation.getError();
                    if (error != null) {
                        System.out.printf("Image generation operation failed. Error code: %s, error message: %s.%n",
                            error.getCode(), error.getMessage());
                    } else {
                        System.out.printf(
                            "Image location URL that provides temporary access to download the generated image is %s.%n",
                            imageLocation.getUrl());
                    }
                }
            },
            error -> System.err.println("There was an error getting images." + error),
            () -> System.out.println("Completed getImages."));

        // The .subscribe() creation and assignment isn't a blocking call.
        // The thread sleeps so the program does not end before the send operation is complete. 
        // Use .block() instead of .subscribe() for a synchronous call.
        TimeUnit.SECONDS.sleep(10);
    }
}

  3. Eseguire la nuova applicazione console per generare un'immagine:

    javac Quickstart.java -cp ".;target\dependency\*"
java -cp ".;target\dependency\*" Quickstart

Output

L'URL dell'immagine generata viene stampato sulla console.

Image location URL that provides temporary access to download the generated image is <SAS URL>.
Completed getImages.

Importante

GPT-image-1 supporta anche parametri aggiuntivi, quality ad esempio (low, medium, high), output_format (png, jpeg), background (auto, transparent) e output_compression (solo 0-100, JPEG). Per informazioni dettagliate, vedere Opzioni API.

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non restituirà un'immagine generata. Per altre informazioni, vedere l'articolo relativo al filtro del contenuto .

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa. Prima di eliminare la risorsa, è necessario eliminare i modelli distribuiti.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK per JavaScript.

Documentazione di riferimento | Codice sorgente | Package (npm) | Esempi

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Installazione

  1. Creare una nuova cartella image-quickstart e passare alla cartella di avvio rapido con il comando seguente:

    mkdir image-quickstart && cd image-quickstart

  2. Crea il package.json con il seguente comando:

    npm init -y

  3. Installare la libreria client OpenAI per JavaScript con:

    npm install openai

  4. Per l'autenticazione senza password consigliata :

    npm install @azure/identity

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Attenzione

Per usare l'autenticazione senza chiave consigliata con l'SDK, assicurarsi che la AZURE_OPENAI_API_KEY variabile di ambiente non sia impostata.

Generare immagini

  1. Creare il index.js file con il codice seguente:

    const { AzureOpenAI } = require("openai");
const { 
    DefaultAzureCredential, 
    getBearerTokenProvider 
} = require("@azure/identity");
const fs = require("fs");

// You will need to set these environment variables or edit the following values
const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "Your endpoint";

// Required Azure OpenAI deployment name and API version
const apiVersion = process.env.OPENAI_API_VERSION || "2025-04-01-preview";
const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-image-1";

// The prompt to generate images from
const prompt = "a monkey eating a banana";
const numberOfImagesToGenerate = 1;

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

function getClient() {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    apiVersion,
    deployment: deploymentName,
  });
}
async function main() {
  console.log("== Image Generation ==");

  const client = getClient();

  const results = await client.images.generate({
    prompt,
    size: "1024x1024",
    n: numberOfImagesToGenerate,
    model: "",
    quality: "high",
    // output_format: "png",  // "png" or "jpeg" (GPT-image-1 only)
    // background: "transparent",  // "auto" or "transparent" (GPT-image-1 only, requires PNG)
  });

  // GPT-image-1 models always return base64-encoded images
  for (const image of results.data) {
    const imageBuffer = Buffer.from(image.b64_json, "base64");
    fs.writeFileSync("generated_image.png", imageBuffer);
    console.log("Image saved to generated_image.png");
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Accedere a Azure con il comando seguente:

    az login

  3. Eseguire il file JavaScript.

    node index.js

Output

L'immagine generata viene salvata nella directory corrente generated_image.png.

== Image Generation ==
Image saved to generated_image.png

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non restituirà un'immagine generata. Per altre informazioni, vedere l'articolo relativo al filtro del contenuto .

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa. Prima di eliminare la risorsa, è necessario eliminare i modelli distribuiti.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK per JavaScript.

Documentazione di riferimento | Codice sorgente | Package (npm) | Esempi

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Installazione

  1. Creare una nuova cartella image-quickstart e passare alla cartella di avvio rapido con il comando seguente:

    mkdir image-quickstart && cd image-quickstart

  2. Crea il package.json con il seguente comando:

    npm init -y

  3. Aggiorna package.json a ECMAScript con il comando seguente:

    npm pkg set type=module

  4. Installare la libreria client OpenAI per JavaScript con:

    npm install openai

  5. Per l'autenticazione senza password consigliata :

    npm install @azure/identity

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Attenzione

Per usare l'autenticazione senza chiave consigliata con l'SDK, assicurarsi che la AZURE_OPENAI_API_KEY variabile di ambiente non sia impostata.

Generare immagini

  1. Creare il index.ts file con il codice seguente:

    import { AzureOpenAI } from "openai";
import { 
    DefaultAzureCredential, 
    getBearerTokenProvider 
} from "@azure/identity";
import * as fs from "fs";

// You will need to set these environment variables or edit the following values
const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "Your endpoint";

// Required Azure OpenAI deployment name and API version
const apiVersion = process.env.OPENAI_API_VERSION || "2025-04-01-preview";
const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-image-1";

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

function getClient(): AzureOpenAI {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    apiVersion,
    deployment: deploymentName,
  });
}
async function main() {
  console.log("== Image Generation ==");

  const client = getClient();

  const results = await client.images.generate({
    prompt,
    size: "1024x1024",
    n: numberOfImagesToGenerate,
    model: "",
    quality: "high",
    // output_format: "png",  // "png" or "jpeg" (GPT-image-1 only)
    // background: "transparent",  // "auto" or "transparent" (GPT-image-1 only, requires PNG)
  });

  // GPT-image-1 models always return base64-encoded images
  for (const image of results.data) {
    const imageBuffer = Buffer.from(image.b64_json!, "base64");
    fs.writeFileSync("generated_image.png", imageBuffer);
    console.log("Image saved to generated_image.png");
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Creare il file per eseguire la tsconfig.json transpile del codice TypeScript e copiare il codice seguente per ECMAScript.

    {
    "compilerOptions": {
      "module": "NodeNext",
      "target": "ES2022", // Supports top-level await
      "moduleResolution": "NodeNext",
      "skipLibCheck": true, // Avoid type errors from node_modules
      "strict": true // Enable strict type-checking options
    },
    "include": ["*.ts"]
}

  3. Transpile da TypeScript a JavaScript.

    tsc

  4. Accedere a Azure con il comando seguente:

    az login

  5. Eseguire il codice con il comando seguente:

    node index.js

Output

L'immagine generata viene salvata nella directory corrente generated_image.png.

== Image Generation ==
Image saved to generated_image.png

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non restituirà un'immagine generata. Per altre informazioni, vedere l'articolo relativo al filtro del contenuto .

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa. Prima di eliminare la risorsa, è necessario eliminare i modelli distribuiti.

Usare questa guida per iniziare a generare immagini con Azure OpenAI SDK for Go.

codice sorgente Library | Package | Samples

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Installazione

  1. Creare una nuova cartella dall-e-quickstart e passare alla cartella di avvio rapido con il comando seguente:

    mkdir dall-e-quickstart && cd dall-e-quickstart

  2. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, effettuare l'accesso ad Azure con il comando seguente:

    az login

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Eseguire l'avvio rapido

Il codice di esempio in questa guida introduttiva usa Microsoft Entra ID per l'autenticazione senza chiave consigliata. Se si preferisce usare una chiave API, è possibile sostituire l'implementazione NewDefaultAzureCredential con NewKeyCredential.

azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
credential, err := azidentity.NewDefaultAzureCredential(nil)
client, err := azopenai.NewClient(azureOpenAIEndpoint, credential, nil)

Per eseguire l'esempio:

  1. Creare un nuovo file denominato quickstart.go. Copiare il codice seguente nel file quickstart.go .

     package main

import (
	"context"
	"fmt"
	"net/http"
	"os"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
	azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
	modelDeploymentID := "gpt-image-1"

	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Printf("ERROR: %s", err)
		return
	}

	client, err := azopenai.NewClient(
		azureOpenAIEndpoint, credential, nil)
	if err != nil {
		log.Printf("ERROR: %s", err)
		return
	}

	resp, err := client.GetImageGenerations(context.TODO(), azopenai.ImageGenerationOptions{
		Prompt:         to.Ptr("A painting of a cat in the style of Dali."),
		ResponseFormat: to.Ptr(azopenai.ImageGenerationResponseFormatURL),
		DeploymentName: to.Ptr(modelDeploymentID),
	}, nil)

	if err != nil {
		// Implement application specific error handling logic.
		log.Printf("ERROR: %s", err)
		return
	}

	for _, generatedImage := range resp.Data {
		// The underlying type for the generatedImage is determined by the value of
		// ImageGenerationOptions.ResponseFormat. 
		// In this example we use `azopenai.ImageGenerationResponseFormatURL`,
		// so the underlying type will be ImageLocation.

		resp, err := http.Head(*generatedImage.URL)

		if err != nil {
			// Implement application specific error handling logic.
			log.Printf("ERROR: %s", err)
			return
		}

		fmt.Fprintf(os.Stderr, "Image generated, HEAD request on URL returned %d\nImage URL: %s\n", resp.StatusCode, *generatedImage.URL)
	}
}

  2. Eseguire il comando seguente per creare un nuovo modulo Go:

     go mod init quickstart.go

  3. Eseguire go mod tidy per installare le dipendenze necessarie:

    go mod tidy

  4. Eseguire il comando seguente per eseguire l'esempio:

     go run quickstart.go

Output

L'URL dell'immagine generata viene stampato sulla console.

Image generated, HEAD request on URL returned 200
Image URL: <SAS URL>

Importante

I modelli GPT-image-1 restituiscono sempre dati di immagine con codifica Base64 anziché URL. Se la versione dell'SDK restituisce un URL per i modelli di DALL-E, è necessario gestire la risposta base64 per le distribuzioni GPT-image-1. GPT-image-1 supporta anche parametri aggiuntivi, quality ad esempio (low, medium, high), output_format (png, jpeg), background (auto, transparent) e output_compression (solo 0-100, JPEG). Per informazioni dettagliate, vedere Opzioni API.

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non restituirà un'immagine generata. Per altre informazioni, vedere l'articolo relativo al filtro del contenuto .

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Usa questa guida per iniziare a chiamare le API di generazione di immagini dei modelli Azure OpenAI in Microsoft Foundry con PowerShell.

Prerequisiti

Microsoft Entra ID prerequisiti

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare il interfaccia della riga di comando di Azure usato per l'autenticazione senza chiave con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Access control (IAM)>Aggiungi assegnazione di ruolo.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI Azure:

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Keys e Endpoint quando si esamina la risorsa dal portale di Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Resource Management>Model Deployments nel portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Generare immagini

  1. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, effettuare l'accesso ad Azure con il comando seguente:

    az login

  2. Ottenere un token di autenticazione OpenAI Azure e impostarlo come variabile di ambiente per la sessione di PowerShell corrente:

    $Env:DEFAULT_AZURE_CREDENTIAL_TOKEN = az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv

  3. Creare un nuovo file di PowerShell denominato quickstart.ps1. Aprirlo quindi nell'editor o nell'IDE preferito.

  4. Sostituire il contenuto di quickstart.ps1 con il codice seguente. Assicurarsi che AZURE_OPENAI_ENDPOINT sia impostato e modificare il valore di prompt nel testo di preferenza.

    Per usare l'autenticazione con chiave API anziché l'autenticazione senza chiave, impostare AZURE_OPENAI_API_KEY e rimuovere il commento dalla 'api-key' riga.

     # Azure OpenAI metadata variables
 $openai = @{
     api_base    = $Env:AZURE_OPENAI_ENDPOINT 
     deployment  = 'gpt-image-1' # set to the name of your model deployment
 }

 # Use the recommended keyless authentication via bearer token.
 $headers = [ordered]@{
     #'api-key' = $Env:AZURE_OPENAI_API_KEY
     'Authorization' = "Bearer $($Env:DEFAULT_AZURE_CREDENTIAL_TOKEN)"
 }

 # Text to describe image
 $prompt = 'A painting of a dog'

 # Adjust these values to fine-tune completions
 $body = [ordered]@{
     model  = $openai.deployment  # required: the name of your model deployment
     prompt = $prompt
     size   = '1024x1024'
     n      = 1
     quality = 'high'
     output_format = 'png'
     # background = 'transparent'  # 'auto' or 'transparent' (GPT-image-1 only; requires PNG output)
     # output_compression = 100    # 0-100 compression level (JPEG output only)
 } | ConvertTo-Json

 # Call the API to generate the image and retrieve the response
 $url = "$($openai.api_base)/openai/v1/images/generations?api-version=preview"

 $response = Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Post -ContentType 'application/json'

 # Set the directory for the stored image
 $image_dir = Join-Path -Path $pwd -ChildPath 'images'

 # If the directory doesn't exist, create it
 if (-not(Resolve-Path $image_dir -ErrorAction Ignore)) {
     New-Item -Path $image_dir -ItemType Directory
 }

 # Initialize the image path (note the filetype should be png)
 $image_path = Join-Path -Path $image_dir -ChildPath 'generated_image.png'

 # Decode the base64 image and save to file
 $image_bytes = [Convert]::FromBase64String($response.data[0].b64_json)
 [IO.File]::WriteAllBytes($image_path, $image_bytes)
 return $image_path

    Importante

    Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Gestione dei segreti di PowerShell con Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

  5. Eseguire lo script con PowerShell:

    ./quickstart.ps1

    Lo script genera l'immagine e la salva.

Output

PowerShell richiede l'immagine da Azure OpenAI e archivia l'immagine di output nel file generated_image.png nella directory specificata. Per praticità, il percorso completo del file viene restituito alla fine dello script.

Le API Image sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non genera un'immagine. Per altre informazioni, vedere Filtro del contenuto.

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Usare questa guida per iniziare a generare immagini con Azure OpenAI nel browser con Microsoft Foundry.

Prerequisiti

Accedi a Foundry

Passare a Foundry e accedere con le credenziali associate alla risorsa OpenAI Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa Azure OpenAI.

Nella pagina di destinazione Foundry creare o selezionare un nuovo progetto. Passare alla pagina Modelli e endpoint nella barra di navigazione a sinistra. Selezionare Distribuisci modello e quindi scegliere uno dei modelli di generazione di immagini dall'elenco. Completare il processo di distribuzione.

Nella pagina del modello, seleziona Apri nel playground.

Provare la generazione di immagini

Inizia a esplorare le funzionalità di Azure OpenAI con un approccio senza scrivere codice tramite il Images playground. Inserisci il prompt dell'immagine nella casella di testo e seleziona Genera. Quando l'immagine generata dall'intelligenza artificiale è pronta, viene visualizzata nella pagina.

Nota

Le API Image sono dotate di un filtro di moderazione del contenuto. Se Azure OpenAI riconosce la richiesta come contenuto dannoso, non restituisce un'immagine generata. Per altre informazioni, vedere Filtro del contenuto.

Nel playground Images è anche possibile visualizzare esempi di codice Python e cURL, precompilati in base alle impostazioni. Selezionare Visualizza codice nella parte superiore della pagina. È possibile usare questo codice per scrivere un'applicazione che completa la stessa attività.

Pulire le risorse

Se si vuole pulire e rimuovere un Azure risorsa OpenAI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Quote e limiti

La generazione di immagini ha limiti di frequenza predefiniti per distribuzione:

Modello Quota predefinita (immagini/min)
Serie GPT-image-1 5
GPT-image-2 5

Per visualizzare la quota corrente o richiedere un aumento, vedere Gestire Azure quote OpenAI.

Chiamare l'API di generazione di immagini

Il comando seguente illustra il modo più semplice per usare un modello di immagine con codice. Se è la prima volta che si usano questi modelli a livello di codice, iniziare con la guida introduttiva.

Suggerimento

La generazione di immagini richiede in genere 10-30 secondi a seconda del modello, delle dimensioni e delle impostazioni di qualità.

Prerequisiti

Inviare una richiesta POST a:

https://<your_resource_name>.openai.azure.com/openai/v1/images/generations?api-version=preview

URL:

Sostituire <your_resource_name> con il nome della risorsa OpenAI Azure.

Intestazioni obbligatorie:

  • Content-Type: application/json
  • api-key: <your_API_key>

Corpo:

Di seguito è riportato un esempio di corpo della richiesta. È possibile specificare una serie di opzioni, definite nelle sezioni successive.

Nota

Impostare il model parametro sul nome della distribuzione del modello, ad esempio gpt-image-1.5.

{
    "prompt": "A multi-colored umbrella on the beach, disposable camera",
    "model": "gpt-image-1.5",
    "size": "1024x1024", 
    "n": 1,
    "quality": "high"
}

Suggerimento

Per i costi dei token di generazione di immagini, vedere Token di immagine.

Output

La risposta da una chiamata API di generazione di immagini corretta è simile all'esempio seguente. Il b64_json campo contiene i dati dell'immagine di output.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
}

Nota

Il response_format parametro non è supportato per i modelli di serie GPT-image-1, che restituiscono sempre immagini con codifica Base64.

Streaming

Lo streaming consente di ricevere immagini parziali man mano che vengono generate, fornendo feedback visivo più rapido per gli utenti. Ciò è utile per le applicazioni in cui si vuole mostrare lo stato di avanzamento della generazione. Il partial_images parametro (1-3) controlla il numero di immagini intermedie restituite prima del risultato finale.

È possibile trasmettere le richieste di generazione di immagini a gpt-image-1-series e gpt-image-2 modelli impostando il stream parametro su truee impostando il partial_images parametro su un valore compreso tra 0 e 3.

import base64
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://RESOURCE-NAME-HERE/openai/v1/",  
  api_key=token_provider,
)

stream = client.images.generate(
    model="gpt-image-1.5",
    prompt="A cute baby sea otter",
    n=1,
    size="1024x1024",
    stream=True,
    partial_images = 2
)

for event in stream:
    if event.type == "image_generation.partial_image":
        idx = event.partial_image_index
        image_base64 = event.b64_json
        image_bytes = base64.b64decode(image_base64)
        with open(f"river{idx}.png", "wb") as f:
            f.write(image_bytes)

Specificare le opzioni api

I parametri del corpo dell'API seguenti sono disponibili per i modelli di generazione di immagini.

Dimensione

Per i modelli della serie GPT-image-1, specificare le dimensioni delle immagini generate come 1024x1024, 1024x1536 o 1536x1024. Le immagini quadrate sono più veloci da generare.

Per gpt-image-2, le risoluzioni arbitrarie sono supportate con i vincoli seguenti:

  • Entrambi i bordi devono essere un multiplo di 16 pixel.
  • Bordo lungo fino a 3840 px (supporto 4K).
  • Rapporto d'aspetto fino a 3:1.
  • Numero totale di pixel compreso tra 655.360 e 8.294.400.

Qualità

Sono disponibili tre opzioni per la qualità dell'immagine: low, mediume high. Le immagini di qualità inferiore possono essere generate più velocemente.

Il valore predefinito è high.

Numero

È possibile generare tra una e 10 immagini in una singola chiamata API. Il valore predefinito è 1.

ID utente

Usare il parametro utente per specificare un identificatore univoco per l'utente che effettua la richiesta. Questo identificatore è utile per tenere traccia e monitorare i modelli di utilizzo. Il valore può essere qualsiasi stringa, ad esempio un ID utente o un indirizzo di posta elettronica.

Formato di output

Usare il parametro output_format per specificare il formato dell'immagine generata. I formati supportati sono PNG e JPEG. Il valore predefinito è PNG.

Nota

Le immagini WEBP non sono supportate nella Azure OpenAI in Microsoft Foundry Models.

Compressione

Usare il parametro output_compression per specificare il livello di compressione per l'immagine generata. Immettere un numero intero compreso tra 0 e , dove 100 non è alcuna compressione ed 0 è 100la compressione massima. Il valore predefinito è 100.

Streaming

Usare il parametro stream per abilitare le risposte di streaming. Se impostato su true, l'API restituisce immagini parziali man mano che vengono generate. Questa funzionalità offre un feedback visivo più rapido per gli utenti e migliora la latenza percepita. Impostare il parametro partial_images per controllare il numero di immagini parziali generate (1-3).

Trasparenza

Impostare il parametro di sfondo su transparent e output_format su PNG su su una richiesta di generazione dell'immagine per ottenere un'immagine con uno sfondo trasparente.

Chiamare l'API di modifica dell'immagine

L'API Modifica immagine consente di modificare le immagini esistenti in base alle richieste di testo fornite. La chiamata API è simile alla chiamata API di generazione di immagini, ma è anche necessario fornire un'immagine di input.

Importante

L'immagine di input deve avere dimensioni inferiori a 50 MB e deve essere un file PNG o JPG.

Inviare una richiesta POST a:

https://<your_resource_name>.openai.azure.com/openai/deployments/<your_deployment_name>/images/edits?api-version=<api_version>

URL:

Sostituire i valori seguenti:

  • <your_resource_name> è il nome della risorsa OpenAI Azure.
  • <your_deployment_name> è il nome della distribuzione del modello della serie di immagini GPT.
  • <api_version> è la versione dell'API che si vuole usare. Ad esempio, 2025-04-01-preview.

Intestazioni obbligatorie:

  • Content-Type: multipart/form-data
  • api-key: <your_API_key>

Corpo:

Di seguito è riportato un esempio di corpo della richiesta. È possibile specificare una serie di opzioni, definite nelle sezioni successive.

Importante

L'API Modifica immagine accetta dati multipart/form, non dati JSON. L'esempio seguente mostra i dati del modulo di esempio che verrebbero collegati a una richiesta cURL.

-F "image[]=@beach.png" \
-F 'prompt=Add a beach ball in the center' \
-F "model=gpt-image-1" \
-F "size=1024x1024" \
-F "n=1" \
-F "quality=high"

Output della risposta API

La risposta da una chiamata API di modifica delle immagini ha un aspetto simile all'esempio seguente. Il b64_json campo contiene i dati dell'immagine di output.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
}

Specificare le opzioni api di modifica delle immagini

I parametri del corpo dell'API seguenti sono disponibili per i modelli di modifica delle immagini, oltre a quelli disponibili per i modelli di generazione di immagini.

Immagine

Il valore dell'immagine indica il file di immagine che si desidera modificare.

Fedeltà dell'input

Il parametro input_fidelity controlla quanto sforzo il modello inserisce nella corrispondenza dello stile e delle caratteristiche, in particolare delle caratteristiche facciali, delle immagini di input.

Questo parametro consente di apportare modifiche minime a un'immagine senza modificare le aree non correlate. Quando si usa una fedeltà di input elevata, i visi vengono mantenuti in modo più accurato rispetto alla modalità standard.

Importante

Il modello gpt-image-1-mini non supporta la fedeltà dell'input.

Maschera

Il parametro mask usa lo stesso tipo del parametro di input dell'immagine principale. Definisce l'area dell'immagine che si desidera modificare dal modello, usando pixel completamente trasparenti (alfa di zero) in tali aree. La maschera deve essere un file PNG e avere le stesse dimensioni dell'immagine di input.

Streaming

Usare il parametro stream per abilitare le risposte di streaming. Se impostato su true, l'API restituisce immagini parziali man mano che vengono generate. Questa funzionalità offre un feedback visivo più rapido per gli utenti e migliora la latenza percepita. Impostare il parametro partial_images per controllare il numero di immagini parziali generate (1-3).

Trasparenza

Solo GPT-image-1: impostare il parametro di sfondo su transparent e output_format su PNG in una richiesta di generazione dell'immagine per ottenere un'immagine con uno sfondo trasparente.

Scrivere richieste di testo per immagini efficaci

Le richieste devono descrivere il contenuto che si vuole visualizzare nell'immagine e lo stile di visualizzazione dell'immagine.

Quando si scrivono richieste, tenere presente che le API immagine sono dotate di un filtro di moderazione del contenuto. Se il servizio riconosce la richiesta come contenuto dannoso, non genera un'immagine. Per altre informazioni, vedere Filtro del contenuto.

Suggerimento

Per un'analisi approfondita del modo in cui è possibile modificare le richieste di testo per generare diversi tipi di immagini, vedere la Guida alla progettazione del prompt delle immagini.

IA responsabile e generazione di immagini

I modelli di generazione di immagini di Azure OpenAI includono protezioni di IA responsabile (RAI) predefinite per garantire un uso sicuro e conforme.

Inoltre, Azure fornisce la moderazione dell'input e dell'output in tutti i modelli di generazione di immagini, insieme a misure di sicurezza specifiche Azure, ad esempio il filtro del contenuto e il monitoraggio degli abusi. Questi sistemi consentono di rilevare e prevenire la generazione o l'uso improprio di contenuto dannoso, non sicuro o violazione dei criteri.

I clienti possono ottenere altre informazioni su queste misure di sicurezza e su come personalizzarle qui:

Considerazioni speciali per la generazione di immagini di minori

Le immagini fotorealistiche dei minori sono bloccate per impostazione predefinita. I clienti possono richiedere l'accesso a questa funzionalità del modello. I clienti di livello Enterprise vengono approvati automaticamente.

Risoluzione dei problemi

Rifiuto delle chiamate API

Le richieste e le immagini vengono filtrate in base alle nostre norme sui contenuti. L'API restituisce un errore quando viene contrassegnata una richiesta o un'immagine.

Se il prompt viene contrassegnato, il valore error.code nel messaggio viene impostato su contentFilter. Ecco un esempio:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Your task failed as a result of our safety system."
    }
}

È anche possibile che l'immagine generata sia filtrata. In questo caso, il messaggio di errore è impostato su L'immagine generata è stata filtrata a causa del nostro sistema di sicurezza. Ecco un esempio:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Generated image was filtered as a result of our safety system."
    }
}

Errori di limitazione della velocità

Se viene visualizzato un errore 429, è stato superato il limite di frequenza. Attendere prima di riprovare o richiedere un aumento della quota nel portale di Azure.

Errori di autenticazione

Se viene visualizzato un errore 401:

  • Autenticazione della chiave API: verificare che la chiave API sia corretta e non scaduta.
  • Identità gestita: assicurarsi che l'identità possieda il ruolo Utente OpenAI di Servizi cognitivi nella risorsa.

Errori di timeout

La generazione di immagini può richiedere fino a 60 secondi per richieste complesse. Nel caso si verifichino timeout:

  • Usare lo streaming per ottenere risultati parziali prima.
  • Semplifica la richiesta.
  • Provare un'immagine di dimensioni più piccole.

Contenuto correlato

  • Last updated on