Azure OpenAI completions

API Version: v1

Server: {endpoint}/openai/v1 — Azure AI Foundry Models APIs

Server Variables:

Variable Default Description
endpoint A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).

Authentication

ApiKeyAuth (API Key)

Pass your API key in the api-key header.

ApiKeyAuth_ (API Key)

Pass your API key in the authorization header.

OAuth2Auth (OAuth 2.0)

Flow: implicit

Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes:

  • https://cognitiveservices.azure.com/.default

Security Requirements

Endpoints accept any one of the following authentication methods:

  1. ApiKeyAuth
  2. ApiKeyAuth_
  3. OAuth2Auth (scopes: https://cognitiveservices.azure.com/.default)

Create completion

POST {endpoint}/openai/v1/completions

Creates a completion.

URI Parameters

Name In Required Type Description
endpoint server Yes string A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).
api-version query No string
Possible values: v1, preview		 The explicit Azure AI Foundry Models API version to use for this request.
v1 if not otherwise specified.

Request Body

Content-Type: application/json

Name Type Description Required Default
best_of integer or null Generates best_of completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.
When used with n, best_of controls the number of candidate completions and n specifies how many to return – best_of must be greater than n.
Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max_tokens and stop.
Constraints: min: 0, max: 20		 No
echo boolean or null Echo back the prompt in addition to the completion No
frequency_penalty number or null Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
Constraints: min: -2, max: 2		 No
logit_bias object or null Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
As an example, you can pass {"50256": -100} to prevent the <|endoftext|> token from being generated.		 No
logprobs integer or null Include the log probabilities on the logprobs most likely output tokens, as well the chosen tokens. For example, if logprobs is 5, the API will return a list of the 5 most likely tokens. The API will always return the logprob of the sampled token, so there may be up to logprobs+1 elements in the response.
The maximum value for logprobs is 5.
Constraints: min: 0, max: 5		 No
max_tokens integer or null The maximum number of tokens that can be generated in the completion.
The token count of your prompt plus max_tokens cannot exceed the model's context length. Example Python code for counting tokens.
Constraints: min: 0		 No
model string ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them. Yes
n integer or null How many completions to generate for each prompt.
Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max_tokens and stop.
Constraints: min: 1, max: 128		 No
presence_penalty number or null Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
Constraints: min: -2, max: 2		 No
prompt string or array of string or null No
seed integer or null If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend.		 No
stop OpenAI.StopConfiguration or null No
stream boolean or null Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message. . No
stream_options OpenAI.ChatCompletionStreamOptions or null No
suffix string or null The suffix that comes after a completion of inserted text.
This parameter is only supported for gpt-3.5-turbo-instruct.		 No
temperature number or null What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
We generally recommend altering this or top_p but not both.
Constraints: min: 0, max: 2		 No
top_p number or null An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
Constraints: min: 0, max: 1		 No
user string A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. No

Responses

Status Code: 200

Description: The request has succeeded.

Content-Type Type Description
application/json object
Name Type Description Required Default
choices array of OpenAI.CreateCompletionResponseChoices The list of completion choices the model generated for the input prompt. Yes
created integer (unixtime) The Unix timestamp (in seconds) of when the completion was created. Yes
id string A unique identifier for the completion. Yes
model string The model used for completion. Yes
object enum The object type, which is always "text_completion"
Possible values: text_completion		 Yes
prompt_filter_results array of AzureContentFilterResultForPrompt No
system_fingerprint string This fingerprint represents the backend configuration that the model runs with.
Can be used in conjunction with the seed request parameter to understand when backend changes have been made that might impact determinism.		 No
usage OpenAI.CompletionUsage Usage statistics for the completion request. No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Status Code: default

Description: An unexpected error response.

Content-Type Type Description
application/json object
Name Type Description Required Default
code string or null Yes
inner_error No
message string Yes
param string or null No
type string No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Examples

Example

POST {endpoint}/openai/v1/completions?api-version=latest&azure-beta=v1=preview

{
  "model": "gpt-4o-mini",
  "prompt": [
    "tell me a joke about mango"
  ],
  "max_tokens": 32,
  "temperature": 1.0,
  "n": 1
}

Responses:

Status Code: 200

{
  "id": "cmpl-7QmVI15qgYVllxK0FtxVGG6ywfzaq",
  "created": 1686617332,
  "choices": [
    {
      "text": "What do you call a mango who's in charge?\n\nThe head mango.\n",
      "index": 0,
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "completion_tokens": 20,
    "prompt_tokens": 6,
    "total_tokens": 26
  }
}

Components

AzureAIFoundryModelsApiVersion

Property Value
Type string
Values v1
preview

AzureContentFilterBlocklistResult

A collection of true/false filtering results for configured custom blocklists.

Name Type Description Required Default
details array of object The pairs of individual blocklist IDs and whether they resulted in a filtering action. No
filtered boolean A value indicating whether any of the detailed blocklists resulted in a filtering action. Yes

AzureContentFilterCompletionTextSpan

A representation of a span of completion text as used by Azure OpenAI content filter results.

Name Type Description Required Default
completion_end_offset integer (int32) Offset of the first UTF32 code point which is excluded from the span. This field is always equal to completion_start_offset for empty spans. This field is always larger than completion_start_offset for non-empty spans. Yes
completion_start_offset integer (int32) Offset of the UTF32 code point which begins the span. Yes

AzureContentFilterCompletionTextSpanDetectionResult

Name Type Description Required Default
details array of AzureContentFilterCompletionTextSpan Detailed information about the detected completion text spans. Yes
detected boolean Whether the labeled content category was detected in the content. Yes
filtered boolean Whether the content detection resulted in a content filtering action. Yes

AzureContentFilterCustomTopicResult

A collection of true/false filtering results for configured custom topics.

Name Type Description Required Default
details array of object The pairs of individual topic IDs and whether they are detected. No
filtered boolean A value indicating whether any of the detailed topics resulted in a filtering action. Yes

AzureContentFilterDetectionResult

A labeled content filter result item that indicates whether the content was detected and whether the content was filtered.

Name Type Description Required Default
detected boolean Whether the labeled content category was detected in the content. Yes
filtered boolean Whether the content detection resulted in a content filtering action. Yes

AzureContentFilterPersonallyIdentifiableInformationResult

A content filter detection result for Personally Identifiable Information that includes harm extensions.

Name Type Description Required Default
detected boolean Whether the labeled content category was detected in the content. Yes
filtered boolean Whether the content detection resulted in a content filtering action. Yes
redacted_text string The redacted text with PII information removed or masked. No
sub_categories array of AzurePiiSubCategoryResult Detailed results for individual PIIHarmSubCategory(s). No

AzureContentFilterResultForChoice

A content filter result for a single response item produced by a generative AI system.

Name Type Description Required Default
custom_blocklists AzureContentFilterBlocklistResult A collection of true/false filtering results for configured custom blocklists. No
└─ details array of object The pairs of individual blocklist IDs and whether they resulted in a filtering action. No
└─ filtered boolean A value indicating whether the blocklist produced a filtering action. Yes
└─ id string The ID of the custom blocklist evaluated. Yes
└─ filtered boolean A value indicating whether any of the detailed blocklists resulted in a filtering action. Yes
custom_topics AzureContentFilterCustomTopicResult A collection of true/false filtering results for configured custom topics. No
└─ details array of object The pairs of individual topic IDs and whether they are detected. No
└─ detected boolean A value indicating whether the topic is detected. Yes
└─ id string The ID of the custom topic evaluated. Yes
└─ filtered boolean A value indicating whether any of the detailed topics resulted in a filtering action. Yes
error object If present, details about an error that prevented content filtering from completing its evaluation. No
└─ code integer (int32) A distinct, machine-readable code associated with the error. Yes
└─ message string A human-readable message associated with the error. Yes
hate AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
personally_identifiable_information AzureContentFilterPersonallyIdentifiableInformationResult A content filter detection result for Personally Identifiable Information that includes harm extensions. No
└─ redacted_text string The redacted text with PII information removed or masked. No
└─ sub_categories array of AzurePiiSubCategoryResult Detailed results for individual PIIHarmSubCategory(s). No
profanity AzureContentFilterDetectionResult A labeled content filter result item that indicates whether the content was detected and whether the content was
filtered.		 No
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
protected_material_code object A detection result that describes a match against licensed code or other protected source material. No
└─ citation object If available, the citation details describing the associated license and its location. No
└─ URL string (uri) The URL associated with the license. No
└─ license string The name or identifier of the license associated with the detection. No
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
protected_material_text AzureContentFilterDetectionResult A labeled content filter result item that indicates whether the content was detected and whether the content was
filtered.		 No
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
self_harm AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
sexual AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
ungrounded_material AzureContentFilterCompletionTextSpanDetectionResult No
violence AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes

AzureContentFilterResultForPrompt

A content filter result associated with a single input prompt item into a generative AI system.

Name Type Description Required Default
content_filter_results object The content filter category details for the result. No
└─ custom_blocklists AzureContentFilterBlocklistResult A collection of true/false filtering results for configured custom blocklists. No
└─ details array of object The pairs of individual blocklist IDs and whether they resulted in a filtering action. No
└─ filtered boolean A value indicating whether the blocklist produced a filtering action. Yes
└─ id string The ID of the custom blocklist evaluated. Yes
└─ filtered boolean A value indicating whether any of the detailed blocklists resulted in a filtering action. Yes
└─ custom_topics AzureContentFilterCustomTopicResult A collection of true/false filtering results for configured custom topics. No
└─ details array of object The pairs of individual topic IDs and whether they are detected. No
└─ detected boolean A value indicating whether the topic is detected. Yes
└─ id string The ID of the custom topic evaluated. Yes
└─ filtered boolean A value indicating whether any of the detailed topics resulted in a filtering action. Yes
└─ error object If present, details about an error that prevented content filtering from completing its evaluation. No
└─ code integer (int32) A distinct, machine-readable code associated with the error. Yes
└─ message string A human-readable message associated with the error. Yes
└─ hate AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
└─ indirect_attack AzureContentFilterDetectionResult A labeled content filter result item that indicates whether the content was detected and whether the content was
filtered.		 Yes
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
└─ jailbreak AzureContentFilterDetectionResult A labeled content filter result item that indicates whether the content was detected and whether the content was
filtered.		 Yes
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
└─ profanity AzureContentFilterDetectionResult A labeled content filter result item that indicates whether the content was detected and whether the content was
filtered.		 No
└─ detected boolean Whether the labeled content category was detected in the content. Yes
└─ filtered boolean Whether the content detection resulted in a content filtering action. Yes
└─ self_harm AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
└─ sexual AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
└─ violence AzureContentFilterSeverityResult A labeled content filter result item that indicates whether the content was filtered and what the qualitative
severity level of the content was, as evaluated against content filter configuration for the category.		 No
└─ filtered boolean Whether the content severity resulted in a content filtering action. Yes
└─ severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes
prompt_index integer (int32) The index of the input prompt associated with the accompanying content filter result categories. No

AzureContentFilterSeverityResult

A labeled content filter result item that indicates whether the content was filtered and what the qualitative severity level of the content was, as evaluated against content filter configuration for the category.

Name Type Description Required Default
filtered boolean Whether the content severity resulted in a content filtering action. Yes
severity enum The labeled severity of the content.
Possible values: safe, low, medium, high		 Yes

AzurePiiSubCategoryResult

Result details for individual PIIHarmSubCategory(s).

Name Type Description Required Default
detected boolean Whether the labeled content subcategory was detected in the content. Yes
filtered boolean Whether the content detection resulted in a content filtering action for this subcategory. Yes
redacted boolean Whether the content was redacted for this subcategory. Yes
sub_category string The PIIHarmSubCategory that was evaluated. Yes

OpenAI.ChatCompletionStreamOptions

Options for streaming response. Only set this when you set stream: true.

Name Type Description Required Default
include_obfuscation boolean When true, stream obfuscation will be enabled. Stream obfuscation adds
random characters to an obfuscation field on streaming delta events to
normalize payload sizes as a mitigation to certain side-channel attacks.
These obfuscation fields are included by default, but add a small amount
of overhead to the data stream. You can set include_obfuscation to
false to optimize for bandwidth if you trust the network links between
your application and the OpenAI API.		 No
include_usage boolean If set, an additional chunk will be streamed before the data: [DONE]
message. The usage field on this chunk shows the token usage statistics
for the entire request, and the choices field will always be an empty
array.
All other chunks will also include a usage field, but with a null
value. NOTE: If the stream is interrupted, you may not receive the
final usage chunk which contains the total token usage for the request.		 No

OpenAI.CompletionUsage

Usage statistics for the completion request.

Name Type Description Required Default
completion_tokens integer Number of tokens in the generated completion. Yes
completion_tokens_details OpenAI.CompletionUsageCompletionTokensDetails No
└─ accepted_prediction_tokens integer No
└─ audio_tokens integer No
└─ reasoning_tokens integer No
└─ rejected_prediction_tokens integer No
prompt_tokens integer Number of tokens in the prompt. Yes
prompt_tokens_details OpenAI.CompletionUsagePromptTokensDetails No
└─ audio_tokens integer No
└─ cached_tokens integer No
total_tokens integer Total number of tokens used in the request (prompt + completion). Yes

OpenAI.CompletionUsageCompletionTokensDetails

Name Type Description Required Default
accepted_prediction_tokens integer No
audio_tokens integer No
reasoning_tokens integer No
rejected_prediction_tokens integer No

OpenAI.CompletionUsagePromptTokensDetails

Name Type Description Required Default
audio_tokens integer No
cached_tokens integer No

OpenAI.CreateCompletionResponseChoices

Name Type Description Required Default
content_filter_results AzureContentFilterResultForChoice A content filter result for a single response item produced by a generative AI system. No
finish_reason enum
Possible values: stop, length, content_filter		 Yes
index integer (int32) Yes
logprobs OpenAI.CreateCompletionResponseChoicesLogprobs or null Yes
text string Yes

OpenAI.CreateCompletionResponseChoicesLogprobs

Name Type Description Required Default
text_offset array of integer No
token_logprobs array of number No
tokens array of string No
top_logprobs array of object No

OpenAI.StopConfiguration

Not supported with latest reasoning models o3 and o4-mini. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.

This component can be one of the following:

  • string
  • array
  • Last updated on