Riferimento all'API REST del servizio Azure OpenAI

  • Articolo

Questo articolo fornisce informazioni dettagliate sugli endpoint dell'API REST di inferenza per OpenAI di Azure.

Autenticazione

OpenAI di Azure fornisce due metodi di autenticazione. È possibile usare chiavi API o MICROSOFT Entra ID.

  • Autenticazione con chiave API: per questo tipo di autenticazione, tutte le richieste API devono includere la chiave API nell'intestazione HTTP api-key. La guida di avvio rapido fornisce indicazioni su come effettuare chiamate con questo tipo di autenticazione.

  • Autenticazione dell'ID Microsoft Entra: è possibile autenticare una chiamata API usando un token Microsoft Entra. I token di autenticazione vengono inclusi in una richiesta come intestazione Authorization. Il token specificato deve essere preceduto da Bearer, ad esempio: Bearer YOUR_AUTH_TOKEN. È possibile leggere la guida pratica sull'autenticazione con Microsoft Entra ID.

Controllo delle versioni dell'API REST

Le API del servizio sono sottoposte al controllo delle versioni usando il parametro di query api-version. Tutte le versioni seguono la struttura di data AAAA-MM-GG. Ad esempio:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01

Completamenti

Con l'operazione Completamento, il modello genera uno o più completamenti stimati in base a una richiesta fornita. Il servizio può anche restituire le probabilità di token alternativi in ogni posizione.

Creare un completamento

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione scelto quando è stato distribuito il modello.
api-version string Richiesto Versione dell'API da usare per questa operazione. Segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
prompt Stringa o matrice Facoltativo <\|endoftext\|> Viene richiesto di generare completamenti, codificati come stringa o matrice di stringhe. <\|endoftext\|> è il separatore di documento visualizzato dal modello durante il training, pertanto se non viene specificato un prompt, il modello viene generato come se dall'inizio di un nuovo documento.
max_tokens integer Facoltativo 16 Numero massimo di token da generare nel completamento. Il numero di token della richiesta più max_tokens non può superare la lunghezza del contesto del modello. La maggior parte dei modelli ha una lunghezza di contesto di 2048 token (ad eccezione dei modelli più recenti, che ne supportano 4096).
temperature Numero Facoltativo 1 Temperatura di campionamento da usare, compresa tra 0 e 2. Valori più elevati indicano che il modello assume più rischi. Provare 0.9 per applicazioni più creative e 0 (argmax sampling) per quelle con una risposta ben definita. In genere è consigliabile modificare questo o top_p, ma non entrambi.
top_p Numero Facoltativo 1 Un'alternativa al campionamento con temperatura, denominata campionamento del nucleo, in cui il modello considera i risultati dei token con massa di probabilità top_p. Quindi 0,1 significa che vengono considerati solo i token che comprendono la massa di probabilità superiore del 10%. In genere è consigliabile modificare questo o la temperatura, ma non entrambi.
logit_bias mappa Facoltativo Null Modificare la probabilità che i token specificati vengano visualizzati nel completamento. Accetta un oggetto JSON che esegue il mapping dei token (specificato dal relativo ID token nel tokenizer GPT) con un valore di distorsione associato compreso tra -100 e 100. È possibile usare questo strumento tokenizer (che funziona sia per GPT-2 che per GPT-3) per convertire il testo in ID token. Matematicamente, la distorsione viene aggiunta ai logits generati dal modello prima del campionamento. L'effetto esatto varia per modello, ma i valori compresi tra -1 e 1 devono diminuire o aumentare la probabilità di selezione; i valori come -100 o 100 devono comportare un divieto o una selezione esclusiva del token pertinente. Ad esempio, è possibile passare {"50256": -100} per impedire la generazione del token <|endoftext|>.
user string Facoltativo Identificatore univoco che rappresenta l'utente finale, che consente di monitorare e rilevare gli abusi
n integer Facoltativo 1 Il numero di completamenti da generare per ogni richiesta. Nota: poiché questo parametro genera molti completamenti, può utilizzare rapidamente la quota del token. Farne un uso accurato e assicurarsi di avere impostazioni ragionevoli per max_tokens e stop.
stream boolean Facoltativo Falso Indica se eseguire il flusso di avanzamento parziale. Se impostato, i token vengono inviati come eventi inviati dal server solo dati man mano che diventano disponibili, con il flusso terminato da un messaggio : [DONE].
logprobs integer Facoltativo Null Includere le probabilità di log nei token logprobs più probabili, nonché i token scelti. Ad esempio, se logprobs è 10, l'API restituirà un elenco dei 10 token più probabili. L'API restituirà sempre il logprob del token campionato, quindi potrebbero essere presenti fino a logprobs+1 elementi nella risposta. Questo parametro non può essere usato con gpt-35-turbo.
suffix string Facoltativo Null Suffisso che segue un completamento del testo inserito.
echo boolean Facoltativo Falso Ripetere il prompt oltre al completamento. Questo parametro non può essere usato con gpt-35-turbo.
stop Stringa o matrice Facoltativo Null Fino a quattro sequenze in cui l'API smetterà di generare altri token. Il testo restituito non conterrà la sequenza di interruzione. Per GPT-4 Turbo con Visione sono supportate fino a due sequenze.
presence_penalty number Facoltativo 0 Numero compreso tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base al fatto che vengano visualizzati o meno nel testo fino a questo momento, aumentando la probabilità del modello di parlare di nuovi argomenti.
frequency_penalty Numero Facoltativo 0 Numero compreso tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base alla frequenza esistente nel testo fino a quel momento, riducendo la probabilità che il modello ripeta testualmente la stessa riga.
best_of integer Facoltativo 1 Genera completamenti best_of sul lato server e restituisce il valore "migliore" (quello con la probabilità di log più bassa per token). I risultati non possono essere trasmessi in streaming. Se usato con n, best_of controlla il numero di completamenti candidati e n specifica quanti best_of da restituire devono essere maggiori di n. Nota: poiché questo parametro genera molti completamenti, può utilizzare rapidamente la quota del token. Farne un uso accurato e assicurarsi di avere impostazioni ragionevoli per max_tokens e stop. Questo parametro non può essere usato con gpt-35-turbo.

Richiesta di esempi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

Esempio di risposta

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

Nella risposta di esempio, finish_reason è uguale a stop. Se finish_reason è uguale content_filter, consultare la guida al filtraggio dei contenuti per capire perché ciò si verifica.

Incorporamenti

Ottenere una rappresentazione vettoriale di un determinato input che può essere facilmente utilizzato dai modelli di Machine Learning e da altri algoritmi.

Nota

OpenAI attualmente consente un numero maggiore di input di matrice con text-embedding-ada-002. Azure OpenAI supporta attualmente matrici di input fino a 16 per text-embedding-ada-002 (Version 2). Entrambi richiedono che il limite massimo di token di input per ogni richiesta API rimanga inferiore a 8191 per questo modello.

Creare un incorporamento

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello. Prima di poter effettuare chiamate, è necessario distribuire un modello.
api-version string Richiesto Versione dell'API da usare per questa operazione. Segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
input Stringa o matrice Sì N/D Testo di input per cui ottenere incorporamenti, codificati come matrice o stringa. Il numero di token di input varia a seconda del modello in uso. Supporta solo text-embedding-ada-002 (Version 2) l'input della matrice.
user string No Null Identificatore univoco che rappresenta l'utente finale. In questo modo, OpenAI di Azure monitora e rileva abusi. Non passare identificatori PII, ma usare valori con pseudonimi come GUID
encoding_format string No float Formato in cui restituire gli incorporamenti. Può essere float o base64. Il valore predefinito è float.

[Aggiunta in 2024-03-01-preview].
dimensions integer No Numero di dimensioni che devono essere presenti gli incorporamenti di output risultanti. Supportato solo nei text-embedding-3 modelli e versioni successive.

[Aggiunta in 2024-03-01-preview]

Richiesta di esempi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

Esempio di risposta

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

Completamenti della chat

Creare completamenti per i messaggi di chat con i modelli GPT-35-Turbo e GPT-4.

Creare completamenti chat

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello. Prima di poter effettuare chiamate, è necessario distribuire un modello.
api-version string Richiesto Versione dell'API da usare per questa operazione. Segue il formato AAAA-MM-GG o AAAA-MM-GG-Anteprima.

Versioni supportate

Testo della richiesta

Il corpo della richiesta è costituito da una serie di messaggi. Il modello genererà una risposta all'ultimo messaggio, usando i messaggi precedenti come contesto.

Parametro Type Obbligatorio? Default Descrizione
messages array Sì N/D Serie di messaggi associati a questa richiesta di completamento della chat. Deve includere i messaggi precedenti nella conversazione. Ogni messaggio ha un role e content.
role string Sì N/D Indica chi sta dando il messaggio corrente. Può essere system,user,assistant,tool o function.
content Stringa o matrice Sì N/D Contenuto del messaggio. Deve essere una stringa, a meno che non si tratti di uno scenario abilitato alla visione. Se fa parte del user messaggio, usando il modello GPT-4 Turbo con Visione, con la versione più recente dell'API, content deve essere una matrice di strutture, in cui ogni elemento rappresenta il testo o un'immagine:
  • text: il testo di input è rappresentato come una struttura con le proprietà seguenti:
    • type = "text"
    • text = testo di input
  • images: un'immagine di input è rappresentata come struttura con le proprietà seguenti:
    • type = "image_url"
    • image_url = una struttura con le proprietà seguenti:
      • url = l'URL dell'immagine
      • (facoltativo) detail = high, o lowauto
contentPart object No N/D Parte del messaggio multi modale di un utente. Può essere di tipo testo o di immagine. Se il testo sarà una stringa di testo. Se immagine, sarà un contentPartImage oggetto .
contentPartImage object No N/D Rappresenta un'immagine caricata dall'utente. Ha una url proprietà, ovvero un URL dell'immagine o i dati dell'immagine con codifica base 64. Ha anche una detail proprietà che può essere auto, lowo high.
enhancements object No N/D Rappresenta le funzionalità di miglioramento della visione richieste per la chat. grounding Ha proprietà e ocr , ognuna ha una proprietà booleanaenabled. Usare questi elementi per richiedere il servizio OCR e/o il servizio di rilevamento/terra degli oggetti [questo parametro di anteprima non è disponibile nell'API 2024-02-01 GA e non è più disponibile nelle API di anteprima dopo 2024-03-01-preview.]
dataSources object No N/D Rappresenta dati aggiuntivi delle risorse. Visione artificiale i dati delle risorse sono necessari per migliorare la visione. Ha una type proprietà , che deve essere "AzureComputerVision" e una parameters proprietà , che ha una endpoint proprietà e key . Queste stringhe devono essere impostate sull'URL dell'endpoint e sulla chiave di accesso della risorsa Visione artificiale.

Richiesta di esempi

Chat solo testo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

Chat con la visione

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

Chat avanzata con la visione

  • Non supportato con la versione del modellogpt-4GPT-4 Turbo GA:turbo-2024-04-09
  • Non supportato con le2024-02-01versioni api e2024-04-01-preview versioni più recenti.
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

Esempio di risposta

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

Formattazione dell'output regolata per facilitare la lettura; l'output effettivo è un singolo blocco di testo senza interruzioni di riga.

Nella risposta di esempio, finish_reason è uguale a stop. Se finish_reason è uguale content_filter, consultare la guida al filtraggio dei contenuti per capire perché ciò si verifica.

Importante

I functions parametri e function_call sono stati deprecati con il rilascio della 2023-12-01-preview versione dell'API. La sostituzione di functions è il tools parametro . La sostituzione di function_call è il tool_choice parametro . La chiamata di funzione parallela introdotta come parte di 2023-12-01-preview è supportata solo con gpt-35-turbo (1106) e gpt-4 (1106-preview) nota anche come GPT-4 Turbo Preview.

Parametro Type Obbligatorio? Default Descrizione
messages array Richiesto Raccolta di messaggi di contesto associati a questa richiesta di completamento della chat. L'utilizzo tipico inizia con un messaggio di chat per il ruolo Sistema che fornisce istruzioni per il comportamento dell'assistente, seguito da messaggi alternati tra i ruoli Utente e Assistente.
temperature number Facoltativo 1 Temperatura di campionamento da usare, compresa tra 0 e 2. Valori più elevati come 0.8 renderanno l'output più casuale, mentre valori più bassi come 0.2 lo renderanno più mirato e deterministico. In genere si consiglia di modificare questo valore o top_p ma non entrambi.
n integer Facoltativo 1 Quante opzioni di completamento della chat generare per ogni messaggio di input.
stream boolean Facoltativo false Se impostato, verranno inviati delta di messaggi parziali, come in ChatGPT. I token verranno inviati come eventi solo dati inviati dal server man mano che diventano disponibili, con il flusso terminato da un messaggio data: [DONE].
stop Stringa o matrice Facoltativo Null Fino a 4 sequenze in cui l'API smetterà di generare altri token.
max_tokens integer Facoltativo inf Numero massimo di token consentiti per la risposta generata. Per impostazione predefinita, il numero di token che il modello può restituire sarà (4096 - token di richiesta).
presence_penalty Numero Facoltativo 0 Numero compreso tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base al fatto che vengano visualizzati o meno nel testo fino a questo momento, aumentando la probabilità del modello di parlare di nuovi argomenti.
frequency_penalty Numero Facoltativo 0 Numero compreso tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base alla frequenza esistente nel testo fino a quel momento, riducendo la probabilità che il modello ripeta testualmente la stessa riga.
logit_bias oggetto Facoltativo Null Modificare la probabilità che i token specificati vengano visualizzati nel completamento. Accetta un oggetto JSON che esegue il mapping dei token (specificato dal relativo ID token nel tokenizer) con un valore di distorsione associato compreso tra -100 e 100. Matematicamente, la distorsione viene aggiunta ai logits generati dal modello prima del campionamento. L'effetto esatto varia per modello, ma i valori compresi tra -1 e 1 devono diminuire o aumentare la probabilità di selezione; i valori come -100 o 100 devono comportare un divieto o una selezione esclusiva del token pertinente.
user string Facoltativo Identificatore univoco che rappresenta l'utente finale, che consente a OpenAI di Azure di monitorare e rilevare gli abusi.
function_call Facoltativo [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]Controlla la modalità di risposta del modello alle chiamate di funzione. "nessuno" indica che il modello non chiama una funzione e risponde all'utente finale. auto indica che il modello può scegliere tra un utente finale o una chiamata a una funzione. Specificando una funzione specifica tramite {"name": "my_function"} forza il modello a chiamare tale funzione. "none" è l'impostazione predefinita quando non sono presenti funzioni. auto è l'impostazione predefinita se sono presenti funzioni. Questo parametro richiede la versione dell'API 2023-07-01-preview
functions FunctionDefinition[] Facoltativo [Deprecated in 2023-12-01-preview replacement paremeter is tools] Un elenco di funzioni per cui il modello può generare input JSON. Questo parametro richiede la versione dell'API 2023-07-01-preview
tools string (tipo dello strumento. È supportato solo function . Facoltativo Un elenco di strumenti che il modello può chiamare. Attualmente, solo le funzioni sono supportate come strumento. Usare questa opzione per fornire un elenco di funzioni per cui il modello può generare input JSON. Questo parametro richiede la versione dell'API 2023-12-01-preview
tool_choice stringa o oggetto Facoltativo nessuna è l'impostazione predefinita quando non sono presenti funzioni. auto è l'impostazione predefinita se sono presenti funzioni. Controlla la funzione (se presente) chiamata dal modello. Nessuno significa che il modello non chiamerà una funzione e genera invece un messaggio. auto indica che il modello può scegliere tra la generazione di un messaggio o la chiamata di una funzione. Specificando una funzione specifica tramite {"type: "function", "function": {"name": "my_function"}} forza il modello a chiamare tale funzione. Questo parametro richiede la versione 2023-12-01-preview dell'API o versioni successive.

ChatMessage

Un singolo messaggio con attributi ruolo all'interno di un'interazione di completamento della chat.

Nome Tipo Descrizione
content string Testo associato a questo payload del messaggio.
function_call FunctionCall Nome e argomenti di una funzione che deve essere chiamata, come generato dal modello.
name string Oggetto name dell'autore del messaggio. name è obbligatorio se il ruolo è functione deve essere il nome della funzione la cui risposta si trova in content. Può contenere caratteri a-z, A-Z, 0-9 e caratteri di sottolineatura, con una lunghezza massima di 64 caratteri.
ruolo ChatRole Ruolo associato a questo payload del messaggio

ChatRole

Descrizione dello scopo previsto di un messaggio all'interno di un'interazione di completamento della chat.

Nome Tipo Descrizione
assistant string Ruolo che fornisce risposte all'input richiesto dall'utente richiesto dal sistema.
function string Ruolo che fornisce i risultati della funzione per i completamenti della chat.
operativo string Ruolo che indica o imposta il comportamento dell'assistente.
utente string Ruolo che fornisce l'input per i completamenti della chat.

Funzione

Viene usato con il parametro aggiunto nella versione 2023-12-01-previewdell'API tools .

Nome Tipo Descrizione
description stringa Descrizione delle operazioni della funzione, usate dal modello per scegliere quando e come chiamare la funzione
name string Nome della funzione da chiamare. Deve essere a-z, A-Z, 0-9 o contenere caratteri di sottolineatura e trattini, con una lunghezza massima di 64
parameters oggetto I parametri accettati dalle funzioni, descritti come oggetto Schema JSON. Vedere le informazioni di riferimento sullo schema JSON per la documentazione sul formato."

FunctionCall-Deprecato

Nome e argomenti di una funzione che deve essere chiamata, come generato dal modello. Questa operazione richiede la versione dell'API 2023-07-01-preview

Nome Tipo Descrizione
argomenti string Argomenti con cui chiamare la funzione, come generato dal modello in formato JSON. Il modello non genera sempre codice JSON valido e potrebbe creare parametri non definiti dallo schema della funzione. Convalidare gli argomenti nel codice prima di chiamare la funzione.
name string Nome della funzione da chiamare.

FunctionDefinition-Deprecated

Definizione di una funzione specificata dal chiamante che i completamenti della chat possono richiamare in risposta all'input dell'utente corrispondente. Questa operazione richiede la versione dell'API 2023-07-01-preview

Nome Tipo Descrizione
description stringa Descrizione delle operazioni che la funzione esegue. Il modello usa questa descrizione quando si seleziona la funzione e ne interpreta i parametri.
name string Nome della funzione da chiamare.
parameters I parametri accettati dalle funzioni, descritti come oggetto Schema JSON.

Estensioni di completamento

La documentazione per questa sezione è stata spostata. Vedere invece la documentazione di riferimento di Azure OpenAI sui dati.

Creazione di immagini

Richiedere un'immagine generata (DALL-E 3)

Generare e recuperare un batch di immagini da un didascalia di testo.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello DALL-E 3, ad esempio MyDalle3. Prima di poter effettuare chiamate, è necessario distribuire un modello DALL-E 3.
api-version string Richiesto Versione dell'API da usare per questa operazione. Segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
prompt stringa Richiesto Descrizione testuale delle immagini desiderate. La lunghezza massima è di 4000 caratteri.
n integer Facoltativo 1 Numero di immagini da generare. È supportato solo n=1 per DALL-E 3.
size string Facoltativo 1024x1024 Dimensioni delle immagini generate. Può essere uno tra 1792x1024, 1024x1024 o 1024x1792.
quality string Facoltativo standard Qualità delle immagini generate. Deve essere hd o standard.
response_format string Facoltativo url Il formato in cui vengono restituite le immagini generate deve essere url (un URL che punta all'immagine) o b64_json (il codice a 64 byte di base in formato JSON).
style string Facoltativo vivid Stile delle immagini generate. Deve essere natural o vivid (per immagini iper-realistiche/drammatiche).
user string Facoltativo Identificatore univoco che rappresenta l'utente finale, che consente di monitorare e rilevare l'abuso.

Richiesta di esempi

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

Esempio di risposta

L'operazione restituisce un codice di stato 202 e un oggetto JSON GenerateImagesResponse contenente l'ID e lo stato dell'operazione.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

Richiedere un'immagine generata (anteprima DALL-E 2)

Generare un batch di immagini da una didascalia di testo.

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
api-version string Richiesto Versione dell'API da usare per questa operazione. Segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
prompt stringa Richiesto Descrizione testuale delle immagini desiderate. La lunghezza massima è di 1000 caratteri.
n integer Facoltativo 1 Numero di immagini da generare. Deve essere compreso tra 1 e 5.
size string Facoltativo 1024x1024 Dimensioni delle immagini generate. Può essere uno tra 256x256, 512x512 o 1024x1024.

Richiesta di esempi

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

Esempio di risposta

L'operazione restituisce un codice di stato 202 e un oggetto JSON GenerateImagesResponse contenente l'ID e lo stato dell'operazione.

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

Ottenere un risultato di immagine generato (anteprima DALL-E 2)

Usare questa API per recuperare i risultati di un'operazione di generazione di immagini. La generazione di immagini è attualmente disponibile solo con api-version=2023-06-01-preview.

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
operation-id string Richiesto GUID che identifica la richiesta di generazione immagini originale.

Versioni supportate

Richiesta di esempi

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Esempio di risposta

Al termine dell'operazione, viene restituito un codice di stato 200 e un oggetto JSON OperationResponse. Il campo status può essere "notRunning" (l'attività è in coda ma non è ancora stata avviata), "running", "succeeded", "canceled" (l’attività ha raggiunto il timeout), "failed" o "deleted". Uno stato succeeded indica che l'immagine generata è disponibile per il download nell'URL specificato. Se sono state generate più immagini, tutti gli URL vengono restituiti nel campo result.data.

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

Eliminare un'immagine generata dal server (anteprima DALL-E 2)

È possibile usare l'ID operazione restituito dalla richiesta per eliminare l'immagine corrispondente dal server di Azure. Le immagini generate vengono eliminate automaticamente dopo 24 ore per impostazione predefinita, ma è possibile attivare l'eliminazione precedentemente.

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
operation-id string Richiesto GUID che identifica la richiesta di generazione immagini originale.

Versioni supportate

Richiesta di esempi

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Response

Se ha esito positivo, l'operazione restituisce un codice di stato 204. Questa API ha esito positivo solo se l'operazione si trova in uno stato finale (non running).

Riconoscimento vocale

È possibile usare un modello Whisper nel servizio OpenAI di Azure per la trascrizione vocale o la traduzione vocale. Per altre informazioni sull'uso di un modello Whisper, vedere la guida introduttiva e la panoramica del modello Whisper.

Richiedere una trascrizione vocale al testo

Trascrive un file audio.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello Whisper, ad esempio MyWhisperDeployment. Prima di poter effettuare chiamate, è necessario distribuire un modello Whisper.
api-version string Richiesto Versione dell'API da usare per questa operazione. Questo valore segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
file file Sì N/D Oggetto file audio (non nome file) da trascrivere, in uno dei formati seguenti: flac, , mp4mpegmp3, mpga, m4aogg, wav, o .webm

Il limite di dimensioni del file per il modello Whisper nel servizio OpenAI di Azure è di 25 MB. Se è necessario trascrivere un file di dimensioni superiori a 25 MB, suddividerlo in blocchi. In alternativa, è possibile usare l'API di trascrizione batch di Riconoscimento vocale di Azure per intelligenza artificiale.

È possibile ottenere file audio di esempio dal repository di Azure AI Speech SDK in GitHub.
language string No Null Lingua dell'audio di input, frad esempio . Fornire il linguaggio di input nel formato ISO-639-1 migliora l'accuratezza e la latenza.

Per l'elenco delle lingue supportate, vedere la documentazione di OpenAI.
prompt string No Null Testo facoltativo per guidare lo stile del modello o continuare un segmento audio precedente. Il prompt deve corrispondere alla lingua audio.

Per altre informazioni sui prompt, inclusi i casi d'uso di esempio, vedere la documentazione di OpenAI.
response_format string No JSON Formato dell'output della trascrizione, in una delle opzioni seguenti: json, text, srt, verbose_json o vtt.

Il valore predefinito è json.
temperature number No 0 Temperatura di campionamento, compresa tra 0 e 1.

Valori più elevati come 0,8 rendono l'output più casuale, mentre i valori inferiori come 0,2 rendono l'output più mirato e deterministico. Se impostato su 0, il modello usa la probabilità di log per aumentare automaticamente la temperatura fino a raggiungere determinate soglie.

Il valore predefinito è 0.
timestamp_granularities array Facoltativo segment Granularità del timestamp da popolare per questa trascrizione. response_format deve essere impostato verbose_json per usare le granularità del timestamp. Sono supportate entrambe o entrambe le opzioni seguenti: wordo segment. Nota: non esiste una latenza aggiuntiva per i timestamp dei segmenti, ma la generazione di timestamp delle parole comporta una latenza aggiuntiva. [Aggiunta nel 2024-04-01-prevew]

Richiesta di esempi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

Esempio di risposta

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

Richiedere una traduzione vocale

Converte un file audio da un'altra lingua in inglese. Per l'elenco delle lingue supportate, vedere la documentazione di OpenAI.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello Whisper, ad esempio MyWhisperDeployment. Prima di poter effettuare chiamate, è necessario distribuire un modello Whisper.
api-version string Richiesto Versione dell'API da usare per questa operazione. Questo valore segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
file file Sì N/D Oggetto file audio (non nome file) da trascrivere, in uno dei formati seguenti: flac, mp3, mp4, mpeg, mpeg, mpega, m4a, ogg, wav o webm.

Il limite di dimensioni del file per il modello Azure OpenAI Whisper è di 25 MB. Se è necessario trascrivere un file di dimensioni superiori a 25 MB, suddividerlo in blocchi.

È possibile scaricare file audio di esempio dal repository di Azure AI Speech SDK in GitHub.
prompt string No Null Testo facoltativo per guidare lo stile del modello o continuare un segmento audio precedente. Il prompt deve corrispondere alla lingua audio.

Per altre informazioni sui prompt, inclusi i casi d'uso di esempio, vedere la documentazione di OpenAI.
response_format string No JSON Formato dell'output della trascrizione, in una delle opzioni seguenti: json, text, srt, verbose_json o vtt.

Il valore predefinito è json.
temperature number No 0 Temperatura di campionamento, compresa tra 0 e 1.

Valori più elevati come 0,8 rendono l'output più casuale, mentre i valori inferiori come 0,2 rendono l'output più mirato e deterministico. Se impostato su 0, il modello usa la probabilità di log per aumentare automaticamente la temperatura fino a raggiungere determinate soglie.

Il valore predefinito è 0.

Richiesta di esempi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

Esempio di risposta

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

Sintesi vocale

Eseguire la sintesi vocale.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

Parametri del percorso

Parametro Type Obbligatorio? Descrizione
your-resource-name stringa Richiesto Nome della risorsa OpenAI di Azure.
deployment-id string Richiesto Nome della distribuzione del modello di sintesi vocale, ad esempio MyTextToSpeechDeployment. Prima di poter effettuare chiamate, è necessario distribuire un testo nel modello di riconoscimento vocale , ad esempio tts-1 o tts-1-hd.
api-version string Richiesto Versione dell'API da usare per questa operazione. Questo valore segue il formato AAAA-MM-GG.

Versioni supportate

Testo della richiesta

Parametro Type Obbligatorio? Default Descrizione
model string Sì N/D Uno dei modelli TTS disponibili: tts-1 o tts-1-hd
input string Sì N/D Testo per cui generare l'audio. La lunghezza massima è di 4096 caratteri. Specificare il testo di input nella lingua desiderata.1
voice string Sì N/D Voce da usare durante la generazione dell'audio. Le voci supportate sono alloy, echo, fable, onyx, novae shimmer. Le anteprime delle voci sono disponibili nella Guida al riconoscimento vocale openAI.

1 I modelli di sintesi vocale supportano in genere le stesse lingue del modello Whisper. Per l'elenco delle lingue supportate, vedere la documentazione di OpenAI.

Richiesta di esempi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

Esempio di risposta

Il riconoscimento vocale viene restituito come file audio dalla richiesta precedente.

API di gestione

Azure OpenAI viene distribuito come parte dei servizi di intelligenza artificiale di Azure. Tutti i servizi di intelligenza artificiale di Azure si basano sullo stesso set di API di gestione per operazioni di creazione, aggiornamento ed eliminazione. Le API di gestione vengono usate anche per la distribuzione di modelli all'interno di una risorsa OpenAI di Azure.

Documentazione di riferimento sulle API di gestione

Passaggi successivi

Informazioni sui modelli e sull'ottimizzazione con l'API REST. Altre informazioni sui modelli sottostanti che alimentano OpenAI di Azure.