You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/ai-foundry/openai/api-version-lifecycle.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ services: cognitive-services
5
5
manager: nitinme
6
6
ms.service: azure-ai-openai
7
7
ms.topic: conceptual
8
-
ms.date: 08/26/2025
8
+
ms.date: 09/05/2025
9
9
author: mrbullwinkle
10
10
ms.author: mbullwin
11
11
recommendations: false
@@ -22,14 +22,14 @@ This article is to help you understand the support lifecycle for Azure OpenAI AP
22
22
23
23
## API evolution
24
24
25
-
Previously, Azure OpenAI received monthly updates of new API versions. Taking advantage of new features required constantly updating code and environment variables with each new API release. Azure OpenAI also required the extra step of using Azure specific clients which created overhead when migrating code between OpenAI and Azure OpenAI.
25
+
Previously, Azure OpenAI received monthly updates of new API versions. Taking advantage of new features required constantly updating code and environment variables with each new API release. Azure OpenAI also required the extra step of using Azure specific clients which created overhead when migrating code between OpenAI and Azure OpenAI.
26
26
27
27
Starting in August 2025, you can now opt in to our next generation v1 Azure OpenAI APIs which add support for:
28
28
29
29
- Ongoing access to the latest features with no need specify new `api-version`'s each month.
30
30
- Faster API release cycle with new features launching more frequently.
31
31
- OpenAI client support with minimal code changes to swap between OpenAI and Azure OpenAI when using key-based authentication.
32
-
- OpenAI client support for token based authentication and automatic token refresh without the need to take a dependency on a separate Azure OpenAI client will be added for all currently supported languages. Adding support for this functionality is **coming soon** for the [Python](https://pypi.org/project/openai/), and the [TypeScript/JavaScript](https://github.com/openai/openai-node) libraries. .NET, Java, and Go support is currently available in preview.
32
+
- OpenAI client support for token based authentication and automatic token refresh without the need to take a dependency on a separate Azure OpenAI client.
33
33
34
34
Access to new API calls that are still in preview will be controlled by passing feature specific preview headers allowing you to opt in to the features you want, without having to swap API versions. Alternatively, some features will indicate preview status through their API path and don't require an additional header.
35
35
@@ -38,7 +38,7 @@ Examples:
38
38
-`/openai/v1/evals` is in preview and requires passing an `"aoai-evals":"preview"` header.
39
39
-`/openai/v1/fine_tuning/alpha/graders/` is in preview and requires no custom header due to the presence of `alpha` in the API path.
40
40
41
-
For the initial v1 GA API launch we're only supporting a subset of the inference and authoring API capabilities. We'll be rapidly adding support for more capabilities soon.
41
+
For the initial v1 Generally Available (GA) API launch we're only supporting a subset of the inference and authoring API capabilities. All GA features are supported for use in production. We'll be rapidly adding support for more capabilities soon.
> Handling automatic token refresh was previously handled through use of the `AzureOpenAI()` client. The v1 API will remove this dependency, but adding automatic token refresh support to the `OpenAI()` client is still in progress. The example below is the current proposed structure, but it may be subject to change. The code below is for example purposes only, and won't execute successfully until the updated OpenAI library is released.
119
+
> Handling automatic token refresh was previously handled through use of the `AzureOpenAI()` client. The v1 API removes this dependency, by adding automatic token refresh support to the `OpenAI()` client.
-`AzureOpenAI()` is used to take advantage of automatic token refresh provided by `azure_ad_token_provider`.
143
142
-`base_url` passes the Azure OpenAI endpoint and `/openai/v1` is appended to the endpoint address.
144
-
-`api_key` parameter will call `fetch_azure_token()`, enabling automatic retrieval and refresh of an authentication token instead of using a static API key.
143
+
-`api_key` parameter is set to `token_provider`, enabling automatic retrieval and refresh of an authentication token instead of using a static API key.
145
144
146
145
# [REST](#tab/rest)
147
146
@@ -269,6 +268,8 @@ curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api
269
268
270
269
### Status
271
270
271
+
Generally Available features are supported for use in production.
@@ -80,39 +80,39 @@ For more information on Translator service selected network and private endpoint
80
80
81
81
Request headers include:
82
82
83
-
| Headers | Description |
84
-
| --- | --- |
85
-
|**Authentication headers**|_Required request header_.<br/>See [available options for authentication](../reference/authentication.md). |
86
-
|**Content-Type**|_Required request header_.<br/>Specifies the content type of the payload. Accepted values are: `application/json`; `charset=UTF-8`|
87
-
|**Content-Length**|_Optional_.<br/>The length of the request body. |
88
-
|**X-ClientTraceId**|_Optional_.<br/>A client-generated GUID to uniquely identify the request. You can omit this optional header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
83
+
| Headers |Required|Description |
84
+
| --- | --- |---|
85
+
|**Authentication headers**|****True****|*See*[available options for authentication](../reference/authentication.md). |
86
+
|**Content-Type**|****True****|Specifies the content type of the payload. Accepted values are: `application/json`; `charset=UTF-8`|
87
+
|**Content-Length**|False|The length of the request body. |
88
+
|**X-ClientTraceId**|False|A client-generated GUID to uniquely identify the request. You can omit this optional header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
89
89
90
90
#### Request parameters
91
91
92
92
Request parameters passed with the request are as follows:
93
93
94
94
| Parameter | Type | Required | Description |
95
95
| --- | --- | --- | --- |
96
-
|**api-version**|string|True|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
97
-
|**text**| string | True | Source text for translation. |
96
+
|**api-version**|string|**True**|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
97
+
|**text**| string |**True**| Source text for translation. |
98
98
|**language**| string | False | Specifies the language code for the `source` text. If not specified, the system autodetects the language of the source text. Accepted values are list of language code supported by the specified model. |
99
99
|**script**| string | False | Specifies the script of the source text. |
100
100
|**textType**| string | False | Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Accepted values are: plain (default) or html. |
101
101
||||
102
-
|**targets**| array | True | User-specified values for the translated (target) text. |
103
-
|**targets.language**| string | True |The language code for the translated (target) text *specified in the targets array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
102
+
|**targets**| array |**True**| User-specified values for the translated (target) text. |
103
+
|**targets.language**| string |**True**|The language code for the translated (target) text *specified in the targets array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
104
104
105
105
#### Targets array (user-specified values for translated text)
106
106
107
107
| Parameter | Type | Required? | Description |
108
108
| --- | --- | --- | --- |
109
-
|**targets.language**| string | True |The language code for the translated (`target`) text *specified in the `targets` array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
109
+
|**targets.language**| string |**True**|The language code for the translated (`target`) text *specified in the `targets` array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
110
110
|**targets.script**| string | False | Specify the script of the transliterated text. |
111
111
|**targets.deploymentName**| string | False |• Default is `general`, which uses a neural machine translation (NMT) system.<br>•`your-model-name-gpt-4o-mini` is an example deployment name for the GPT-4o-mini model. For more information, *see*[Translate using GPT-4o mini and NMT deployments](translate-api.md#translate-using-gpt-4o-mini-deployment-and-nmt)<br>•`<categoryID>` uses the custom `NMT` model trained by customer. For more information, *see*[Train a custom model in Azure AI Foundry](../../custom-translator/azure-ai-foundry/how-to/train-model.md)<br> |
112
112
|**targets.tone**| string | False | Desired tone of target translation. Accepted values are `formal`, `informal`, or `neutral`. |
113
113
|**targets.gender** (For more information, *see*[Gender-specific translations](#gender-specific-translations))| string | False | Desired gender of target translation. Accepted values are `female`, `male`, or `neutral`.|
114
114
|**targets.adaptiveDatasetId**| string | False | Reference dataset ID having sentence pair to generate adaptive customized translation. The maximum number of reference text pairs to generate adaptive customized translation is five (5).|
115
-
|**targets.allowFallback**| string | False | If the desired model doesn't support a particular pair of source and target languages, an alternative approach may be employed. In such cases, the service may default to utilizing a general system as a substitute. This action ensures that translations can still be provided even when the preferred model is unavailable. Default is `true`. If `false` system returns an error if language pair isn't supported. |
115
+
|**targets.allowFallback**| string | False | If the desired model doesn't support a particular pair of source and target languages, an alternative approach may be employed. In such cases, the service may default to utilizing a general system as a substitute. This action ensures that translations can still be provided even when the preferred model is unavailable. Default is `True`. If `False` system returns an error if language pair isn't supported. |
116
116
|**targets.referenceTextPairs**| string | False | Reference text pairs to generate adaptive customized translation. |
117
117
|**targets.referenceTextPairs.source**| string | False | Source text in reference text pair. If provided, `adaptiveDatasetId` is ignored. |
118
118
|**targets.referenceTextPairs.target**| string | False | Target text in reference text pair. |
For more information on Translator service selected network and private endpoint configuration and support, *see*[**Virtual Network Support**](../reference/authentication.md#virtual-network-support).
31
+
***Linux or macOS***
26
32
27
-
## Request parameters
33
+
```bash
34
+
curl -X POST "https://api.cognitive.microsofttranslator.com/transliterate?api-version=2025-05-01-preview" \
Request parameters passed on the query string are:
42
+
Your custom domain endpoint is a URL formatted with your resource name and hostname and is available in the Azure portal. When you created your Translator resource, the value that you entered in the `Name` field is the custom domain name parameter for the endpoint.
30
43
31
-
| Query parameter | Description |
32
-
| --- | --- |
33
-
| api-version |*Required parameter*.<br/>Version of the API requested by the client. Value must be `3.0`. |
34
-
| language |*Required parameter*.<br/>Specifies the language of the text to convert from one script to another. Possible languages are listed in the `transliteration` scope obtained by querying the service for its [supported languages](get-languages.md). |
35
-
| fromScript |*Required parameter*.<br/>Specifies the script used by the input text. Look up [supported languages](get-languages.md) using the `transliteration` scope, to find input scripts available for the selected language. |
36
-
| toScript |*Required parameter*.<br/>Specifies the output script. Look up [supported languages](get-languages.md) using the `transliteration` scope, to find output scripts available for the selected combination of input language and input script. |
44
+
**Send a `POST` request**:
45
+
46
+
***Windows***
47
+
48
+
```bash
49
+
curl -X POST "https://<your-resource-name>.cognitiveservices.azure.com//transliterate?api-version=2025-05-01-preview"^
For more information on Translator service selected network and private endpoint configuration and support, *see*[**Virtual Network Support**](../reference/authentication.md).
| Content-Type |_Required request header_.<br/>Specifies the content type of the payload. Possible values are: `application/json`|
44
-
| Content-Length |_Optional_.<br/>The length of the request body. |
45
-
| X-ClientTraceId |_Optional_.<br/>A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
71
+
| Headers | Required| Description |
72
+
| --- | --- |---|
73
+
|**Authentication headers**|**True**|*See*[available options for authentication](../reference/authentication.md). |
74
+
|**Content-Type**|**True**| Specifies the content type of the payload. Accepted values are: `application/json`; `charset=UTF-8`|
75
+
|**Content-Length**|False| The length of the request body. |
76
+
|**X-ClientTraceId**|False| A client-generated GUID to uniquely identify the request. You can omit this optional header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
77
+
78
+
## Request parameters
79
+
80
+
Request parameters passed on the query string areas are as follows:
81
+
82
+
| Parameter |Type| Required | Description |
83
+
| --- | --- |---|---|
84
+
|**api-version**|string|**True**|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
85
+
|**fromScript**| string|**True**| Specifies the script used by the input text. Look up [supported languages](get-languages.md) using the `transliteration` scope, to find input scripts available for the selected language. |
86
+
|**toScript**|string|**True**| Specifies the output script. Look up [supported languages](get-languages.md) using the `transliteration` scope, to find output scripts available for the selected combination of input language and input script. |
87
+
|**language**| string | False | Specifies the language code for the `source` text. If not specified, the system autodetects the language of the source text. Accepted values are list of language code supported by the specified model. |
46
88
47
89
## Request body
48
90
@@ -82,7 +124,21 @@ An example JSON response is:
82
124
83
125
| Headers | Description |
84
126
| --- | --- |
85
-
| X-RequestId | Value generated by the service to identify the request and used for troubleshooting purposes. |
127
+
|**X-RequestId**| Value generated by the service to identify the request and used for troubleshooting purposes. |
128
+
129
+
## Example
130
+
131
+
The following example shows how to convert two Japanese strings into Romanized Japanese.
@@ -100,17 +156,9 @@ The following are the possible HTTP status codes that a request returns.
100
156
101
157
If an error occurs, the request also returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the [Status code reference page](../reference/status-response-codes.md).
102
158
103
-
## Examples
104
-
105
-
The following example shows how to convert two Japanese strings into Romanized Japanese.
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments