你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Azure OpenAI 服务 REST API 参考
本文详细介绍了 Azure OpenAI 的推理 REST API 端点。
身份验证
Azure OpenAI 提供两种身份验证方法。 可以使用 API 密钥或 Microsoft Entra ID。
API 密钥身份验证:对于这种类型的身份验证,所有 API 请求都必须在
api-key
HTTP 标头中包含 API 密钥。 本快速入门提供有关如何通过此类身份验证进行调用的指南。Microsoft Entra ID 身份验证:可以使用 Microsoft Entra 令牌对 API 调用进行身份验证。 身份验证令牌作为
Authorization
标头包含在请求中。 提供的令牌必须以Bearer
开头,例如Bearer YOUR_AUTH_TOKEN
。 可以阅读有关如何使用 Microsoft Entra ID 进行身份验证的操作指南。
REST API 版本控制
服务 API 使用 api-version
查询参数进行版本控制。 所有版本都遵循 YYYY-MM-DD 日期结构。 例如:
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01
完成
通过完成操作,模型将根据提供的提示生成一个或多个预测完成。 该服务还可以返回每个位置的替代令牌的概率。
创建完成
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必需 | 部署模型时选择的部署名称。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。 |
支持的版本
2022-12-01
Swagger spec2023-03-15-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-05-15
Swagger spec2023-06-01-preview
Swagger spec2023-07-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-08-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-09-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-10-01-preview
Swagger spec2023-12-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
prompt |
字符串或数组 | 可选 | <\|endoftext\|> |
生成一个或多个完成的提示,其编码为字符串或字符串数组。 <\|endoftext\|> 是模型在训练期间看到的文档分隔符,因此如果未指定提示,模型就会像从新文档的开头一样生成。 |
max_tokens |
integer | 可选 | 16 | 在完成中生成的最大令牌数。 提示加上 max_tokens 的令牌计数不能超过模型的上下文长度。 除最新模型(它支持 4096 个令牌)外,大多数模型的上下文长度为 2048 个令牌。 |
temperature |
数字 | 可选 | 1 | 要使用的采样温度,介于 0 和 2 之间。 较高的值意味着模型将承担更多风险。 对于更具创意的应用程序,请尝试将值设为 0.9,对于具有明确定义答案的应用程序,将值设为 0 (argmax sampling ) 。 我们通常建议更改此设置或 top_p,但不要同时更改这两者。 |
top_p |
数字 | 可选 | 1 | 温度采样的替代方法,称为核采样,其中模型考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度,但不要同时更改这两者。 |
logit_bias |
map | 可选 | Null | 修改指定令牌在完成中出现的可能性。 接受 json 对象,该对象将令牌(由其在 GPT tokenizer 中的令牌 ID 指定)映射到从 -100 到 100 的关联偏差。 可以使用此 tokenizer 工具(适用于 GPT-2 和 GPT-3)将文本转换为令牌 ID。 在数学上,采样之前会将偏差添加到由模型生成的 logit 中。 具体效果因模型而异,但 -1 和 1 之间的值会减少或增加选择的可能性;-100 或 100 等值会导致相关令牌的禁止或独占选择。 例如,可以传递 {"50256": -100} 以防止生成 <|endoftext|> 令牌。 |
user |
字符串 | 可选 | 表示最终用户的唯一标识符,可帮助监视和检测滥用行为 | |
n |
integer | 可选 | 1 | 要为每个提示生成的完成数。 注意:由于此参数会生成许多完成,因此可能会快速消耗你的令牌配额。 谨慎使用并确保对 max_tokens 和 stop 进行了合理的设置。 |
stream |
boolean | 可选 | False | 是否流式传输回部分进度。 如果设置,令牌将在可用时作为仅数据服务器发送的事件发送,流由 data:[DONE] 消息终止。 |
logprobs |
integer | 可选 | Null | 包含有关 logprobs 最有可能的令牌和已选择的令牌的日志概率。 例如,如果 logprobs 为 10,则 API 将返回包含 10 个最有可能的令牌的列表。 API 将始终返回采样令牌的 logprob,因此响应中可能最多有 logprobs+1 个元素。 此参数不能与 gpt-35-turbo 一起使用。 |
suffix |
string | 可选 | Null | 插入的文本完成后的后缀。 |
echo |
boolean | 可选 | False | 除了完成之外,还要回显提示。 此参数不能与 gpt-35-turbo 一起使用。 |
stop |
字符串或数组 | 可选 | Null | 最多四个序列,其中 API 将停止生成进一步的令牌。 返回的文本不包含停止序列。 对于 GPT-4 Turbo with Vision,最多支持两个序列。 |
presence_penalty |
数字 | 可选 | 0 | 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止是否在文本中出现来惩罚新令牌,从而增加模型谈论新话题的可能性。 |
frequency_penalty |
数字 | 可选 | 0 | 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止在文本中的现有频率来惩罚新令牌,从而降低模型逐字重复同一行的可能性。 |
best_of |
integer | 可选 | 1 | 在服务器端生成 best_of 完成并返回“最佳”(每个令牌的日志概率最低的参数)。 无法流式传输结果。 与 n 一起使用时,best_of 控制候选完成数,n 指定返回的完成数,best_of 的值必须大于 n 的值。 注意:由于此参数会生成许多完成,因此可能会快速消耗你的令牌配额。 谨慎使用并确保对 max_tokens 和 stop 进行了合理的设置。 此参数不能与 gpt-35-turbo 一起使用。 |
示例请求
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
}"
示例响应
{
"id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
"object": "text_completion",
"created": 1646932609,
"model": "ada",
"choices": [
{
"text": ", a dark line crossed",
"index": 0,
"logprobs": null,
"finish_reason": "length"
}
]
}
在示例响应中,finish_reason
等于 stop
。 如果 finish_reason
等于 content_filter
,请参阅我们的内容筛选指南,了解发生此情况的原因。
嵌入
获取给定输入的向量表示形式,该输入可由机器学习模型和其他算法轻松使用。
注意
OpenAI 目前允许使用 text-embedding-ada-002
输入更多的数组。 对于 text-embedding-ada-002 (Version 2)
,Azure OpenAI 目前支持最多 16 个输入数组。 两者都要求此模型的每个 API 请求的最大输入令牌限制保持在 8191 之下。
创建嵌入
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必需 | 模型部署的名称。 必须先部署模型,然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。 |
支持的版本
2023-03-15-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-05-15
Swagger spec2023-06-01-preview
Swagger spec2023-07-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-08-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-09-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-10-01-preview
Swagger spec2023-12-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
input |
字符串或数组 | 是 | 空值 | 获取嵌入的输入文本,编码为数组或字符串。 输入令牌的数量因所使用的模型而异。 仅 text-embedding-ada-002 (Version 2) 支持数组输入。 |
user |
string | 否 | Null | 表示最终用户的唯一标识符。 这将帮助 Azure OpenAI 监视和检测滥用行为。 不要传递 PII 标识符,而是使用伪名化值,例如 GUID |
encoding_format |
string | 否 | float |
嵌入的返回格式。 可以为 float 或 base64 。 默认为 float 。 [在 2024-03-01-preview 中添加]。 |
dimensions |
integer | 否 | 生成的输出嵌入应有的维度数。 仅在 text-embedding-3 及更高版本中受支持。 [在 2024-03-01-preview 中添加] |
示例请求
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...\"}"
示例响应
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.018990106880664825,
-0.0073809814639389515,
.... (1024 floats total for ada)
0.021276434883475304,
],
"index": 0
}
],
"model": "text-similarity-babbage:001"
}
聊天完成
使用 GPT-35-Turbo 和 GPT-4 模型创建聊天消息补全内容。
创建聊天完成
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必需 | 模型部署的名称。 必须先部署模型,然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 这遵循 YYYY-MM-DD 或 YYYY-MM-DD-preview 格式。 |
支持的版本
2023-03-15-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-05-15
Swagger spec2023-06-01-preview
Swagger spec2023-07-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-08-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-09-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-10-01-preview
Swagger spec2023-12-01-preview
(即将于 2024 年 7 月 1 日停用)(视觉方案需要此版本或更高版本)Swagger 规范2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
重要
随着 API 的 2023-12-01-preview
版本的发布,functions
和 function_call
参数已被弃用。 functions
的替代项是 tools
参数。 function_call
的替代项是 tool_choice
参数。 仅 gpt-35-turbo
(1106) 和 gpt-4
(1106-preview)(也称为 GPT-4 Turbo 预览版)支持在 2023-12-01-preview
中引入的并行函数调用。
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
messages |
array | 必须 | 与此聊天补全请求关联的上下文消息的集合。 典型的用法从系统角色的聊天消息开始,该消息提供有关助手行为的说明,然后是“用户”和“助手”角色之间的交替消息。 | |
temperature |
数字 | 可选 | 1 | 要使用的采样温度,介于 0 和 2 之间。 较高的值(如 0.8)将使输出更随机,而较小的值(如 0.2)将使输出更集中且更具确定性 我们通常建议更改此设置或 top_p ,但不要同时更改两者。 |
role |
string | 是 | 空值 | 指示谁正在提供当前消息。 可以是 system 、user 、assistant 、tool 或 function 。 |
content |
字符串或数组 | 是 | 空值 | 消息的内容。 它必须是字符串,除非在启用了视觉的方案中。 如果它是 user 消息的一部分,使用 GPT-4 Turbo with Vision 模型以及最新的 API 版本,则 content 必须是一个结构数组,其中每个项代表文本或图像:
|
contentPart |
object | 否 | 空值 | 用户的多模式消息的一部分。 它可以是文本类型或图像类型。 如果为文本,则为文本字符串。 如果为图像,它将是一个 contentPartImage 对象。 |
contentPartImage |
object | 否 | 空值 | 表示用户上传的图像。 它具有一个 url 属性,是图像的 URL 或 base 64 编码的图像数据。 它还具有一个 detail 属性,可以是 auto 、low 或 high 。 |
enhancements |
object | 否 | 空值 | 表示为聊天请求的视觉增强功能。 它具有 grounding 和 ocr 属性,每个属性都具有布尔 enabled 属性。 使用这些内容请求 OCR 服务和/或对象检测/定位服务[此预览版参数在 2024-02-01 GA API 中不可用,并且在 2024-03-01-preview 后在预览版 API 中不再可用]。 |
dataSources |
object | 否 | 空值 | 表示其他资源数据。 视觉增强需要计算机视觉资源数据。 它有一个应为 "AzureComputerVision" 的 type 属性,具有 endpoint 的 parameters 属性,以及 key 属性。 这些字符串应设置为计算机视觉资源的终结点 URL 和访问密钥。 |
n |
integer | 可选 | 1 | 要为每个输入消息生成的聊天完成选项数。 |
stream |
boolean | 可选 | false | 如果设置此选项,将发送部分消息增量,如在 ChatGPT 中一样。 令牌将在可用时作为仅数据服务器发送的事件发送,流由 data: [DONE] 消息终止。 |
stop |
字符串或数组 | 可选 | Null | 最多四个序列,其中 API 将停止生成更多令牌。 |
max_tokens |
integer | 可选 | inf | 生成的答案允许的最大令牌数。 默认情况下,模型可返回的标记数将为(4096 - 提示标记)。 |
presence_penalty |
数字 | 可选 | 0 | 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止是否在文本中出现来惩罚新令牌,从而增加模型谈论新话题的可能性。 |
frequency_penalty |
数字 | 可选 | 0 | 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止在文本中的现有频率来惩罚新令牌,从而降低模型逐字重复同一行的可能性。 |
logit_bias |
对象 (object) | 可选 | Null | 修改指定令牌在完成中出现的可能性。 接受 json 对象,该对象将标记(由 tokenizer 中的标记 ID 指定)映射到从 -100 到 100 的相关偏差值。 在数学上,采样之前会将偏差添加到由模型生成的 logit 中。 具体效果因模型而异,但 -1 和 1 之间的值会减少或增加选择的可能性;-100 或 100 等值会导致相关令牌的禁止或独占选择。 |
user |
string | 可选 | 表示最终用户的唯一标识符,可帮助 Azure OpenAI 监视和检测滥用行为。 | |
function_call |
可选 | [Deprecated in 2023-12-01-preview replacement parameter is tools_choice] 控制模型如何响应函数调用。 “none”表示模型不调用函数,并对最终用户做出响应。 auto 表示模型可以在最终用户或调用函数之间进行选择。 通过 {"name": "my_function"} 指定特定函数会强制模型调用该函数。 当不存在任何函数时,“none”是默认值。 如果存在函数,则 auto 是默认值。 此参数需要 API 版本 2023-07-01-preview |
||
functions |
FunctionDefinition[] |
可选 | [Deprecated in 2023-12-01-preview replacement paremeter is tools] 模型可为其生成 JSON 输入的函数列表。 此参数需要 API 版本 2023-07-01-preview |
|
tools |
字符串(工具的类型。仅支持 function 。) |
可选 | 模型可调用的工具列表。 目前,仅支持函数作为工具。 使用它可以提供函数列表,模型可能为其生成 JSON 输入。 此参数需要 API 版本 2023-12-01-preview |
|
tool_choice |
字符串或对象 | 可选 | 当不存在任何函数时,none 是默认值。 如果存在函数,则 auto 是默认值。 |
控制模型调用的函数(如有)。 None 表示模型不会调用函数,而是生成消息。 auto 表示模型可以在生成消息和调用函数之间进行选择。 通过 {"type: "function", "function": {"name": "my_function"}} 指定特定函数会强制模型调用该函数。 此参数需要 API 2023-12-01-preview 或更高版本。 |
top_p |
数字 | 否 | 默认值:1 最小值:0 最大值:1 |
温度采样的替代方法,称为核采样,其中模型考虑具有 top_p 概率质量的令牌的结果。 因此,0.1 表示只考虑包含前 10% 概率质量的标记。\n我们通常建议更改此值或 temperature ,但不建议同时更改两者。” |
log_probs |
boolean | 否 | 是否返回输出令牌的对数概率。 如果为 true,则返回在 message 的 content 中返回的每个输出令牌的对数概率。 此选项当前在 gpt-4-vision-preview 模型上不可用。 |
|
top_logprobs |
integer | 否 | 最小值:0 最大值:5 |
一个介于 0 和 5 之间的整数,指定在每个标记位置最有可能返回的的标记数,每个都有关联的对数概率。 如果使用此参数,则必须将 logprobs 设置为 true 。 |
response_format |
object | 否 | 一个对象,指定模型必须输出的格式。 用于启用 JSON 模式。 | |
seed |
integer | 否 | 0 | 指定后,我们的系统将尽最大努力以确定性方式采样,使具有相同 seed 和参数的重复请求返回相同的结果。但是无法保证确定性,应该引用 system_fingerprint 响应参数来监视后端中的更改。 |
并非所有参数都在每个 API 版本使用。
示例请求
纯文本聊天
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?"}]}'
通过视觉聊天
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" } }]}]}'
带有视觉的增强聊天
- GPT-4 Turbo GA 模型
gpt-4
版本:turbo-2024-04-09
不支持 2024-02-01
和2024-04-01-preview
及更新 API 版本不支持。
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"}]}]}'
示例响应
{
"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
}
]
}
已为易读性调整输出格式,实际输出是一个没有换行符的单个文本块。
在示例响应中,finish_reason
等于 stop
。 如果 finish_reason
等于 content_filter
,请参阅我们的内容筛选指南,了解发生此情况的原因。
ChatMessage
聊天补全交互中的单个角色属性化消息。
名称 | Type | 描述 |
---|---|---|
内容 | string | 与此消息有效负载关联的文本。 |
function_call | FunctionCall | 应调用的函数的名称和参数,由模型生成。 |
name | string | 此消息的作者的 name 。 如果角色为 function ,则 name 为必填项,并且它应该是其响应在 content 中的函数的名称。 可能包含 a-z、A-Z、0-9 和下划线,最大长度为 64 个字符。 |
role | ChatRole | 与此消息有效负载关联的角色 |
ChatRole
聊天补全交互中消息的预期用途的说明。
名称 | Type | 描述 |
---|---|---|
assistant | string | 对系统指示的用户提示输入做出响应的角色。 |
函数 | string | 为聊天补全提供函数结果的角色。 |
system | string | 指示或设置助手行为的角色。 |
user | string | 为聊天补全提供输入的角色。 |
函数
这与 API 版本 2023-12-01-preview
中添加的 tools
参数一起使用。
名称 | Type | 说明 |
---|---|---|
description | string | 函数作用的描述,由模型用于选择何时以及如何调用函数 |
name | string | 要调用的函数的名称。 必须是 a-z、A-z、0-9,或包含下划线和短划线,最大长度为 64 |
parameters | object | 函数接受的参数,被描述为 JSON 架构对象。 有关格式的文档,请参阅 JSON 模式引用。” |
FunctionCall-Deprecated
应调用的函数的名称和参数,由模型生成。 这需要 API 版本 2023-07-01-preview
名称 | Type | 描述 |
---|---|---|
参数 | string | 用于调用函数的参数,由模型以 JSON 格式生成。 该模型并非始终生成有效的 JSON,并且可能会构造函数架构未定义的参数。 在调用函数之前验证代码中的参数。 |
name | string | 要调用的函数名称。 |
FunctionDefinition-Deprecated
调用方指定的函数的定义,聊天补全可能会调用该函数以响应匹配的用户输入。 这需要 API 版本 2023-07-01-preview
名称 | Type | 说明 |
---|---|---|
description | string | 函数操作的说明。 当选择函数并解释其参数时,模型将使用此说明。 |
name | string | 要调用的函数的名称。 |
parameters | 函数接受的参数,被描述为 JSON 架构对象。 |
完成扩展
本部分的文档已移动。 请改为参阅基于自有数据的 Azure OpenAI 参考文档。
图像生成
请求生成的映像 (DALL-E 3)
通过文本标题生成和检索一批图像。
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必须 | DALL-E 3 模型部署的名称,例如 MyDalle3。 必须先部署 DALL-E 3 模型,然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。 |
支持的版本
2023-12-01-preview (retiring July 1, 2024)
Swagger spec2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
prompt |
字符串 | 必须 | 所需图像的文本说明。 最大长度为 4000 个字符。 | |
n |
integer | 可选 | 1 | 要生成的图像数。 DALL-E 3 仅支持 n=1 。 |
size |
string | 可选 | 1024x1024 |
生成的图像的大小。 必须是 1792x1024 、1024x1024 或 1024x1792 。 |
quality |
string | 可选 | standard |
生成的图像的质量。 必须是 hd 或 standard 。 |
response_format |
string | 可选 | url |
生成的图像的返回格式必须是 url (指向图像的 URL)或 b64_json (JSON 格式的 base64 字节代码)。 |
style |
string | 可选 | vivid |
生成的图像的样式。 必须是 natural 或 vivid (对于超现实/戏剧性图像)。 |
user |
string | 可选 | 表示最终用户的唯一标识符,可帮助监视和检测滥用行为。 |
Dalle-2 现在在 2024-05-01-preview
中受支持。
示例请求
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"
}'
示例响应
操作返回 202
状态代码和 GenerateImagesResponse
JSON 对象,其中包含操作的 ID 和状态。
{
"created": 1698116662,
"data": [
{
"url": "url to the image",
"revised_prompt": "the actual prompt that was used"
},
{
"url": "url to the image"
},
...
]
}
请求生成的图像 (DALL-E 2 预览版)
从文本描述文字生成一批图像。
POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
api-version |
字符串 | 必需 | 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。 |
支持的版本
2023-06-01-preview
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
prompt |
字符串 | 必须 | 所需图像的文本说明。 最大长度为 1000 个字符。 | |
n |
integer | 可选 | 1 | 要生成的图像数。 必须介于 1 和 5 之间。 |
size |
字符串 | 可选 | 1024x1024 | 生成的图像的大小。 必须是 256x256 、512x512 或 1024x1024 。 |
示例请求
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
}'
示例响应
操作返回 202
状态代码和 GenerateImagesResponse
JSON 对象,其中包含操作的 ID 和状态。
{
"id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
"status": "notRunning"
}
获取生成的图像结果 (DALL-E 2 预览版)
使用此 API 检索图像生成操作的结果。 映像生成目前仅适用于 api-version=2023-06-01-preview
。
GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
operation-id |
字符串 | 必须 | 标识原始图像生成请求的 GUID。 |
支持的版本
2023-06-01-preview
Swagger spec
示例请求
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}"
示例响应
成功后,操作将返回 200
状态代码和 OperationResponse
JSON 对象。 status
字段可以是 "notRunning"
(任务已排队但尚未启动)、"running"
、"succeeded"
、"canceled"
(任务已超时)、"failed"
或 "deleted"
。 succeeded
状态表示生成的图像可在给定 URL 处下载。 如果生成了多个图像,则它们的 URL 全部在 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"
}
从服务器中删除生成的图像 (DALL-E 2 预览版)
可以使用请求返回的操作 ID 从 Azure 服务器中删除相应的图像。 默认情况下,生成的图像会在 24 小时后自动删除,但如果需要,可以提前触发删除操作。
DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
operation-id |
字符串 | 必须 | 标识原始图像生成请求的 GUID。 |
支持的版本
2023-06-01-preview
Swagger spec
示例请求
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}"
响应
如果成功,操作将返回 204
状态代码。 仅当操作处于结束状态(不是 running
)时,此 API 才会成功。
语音转文本
可以在 Azure OpenAI 服务中使用 Whisper 模型进行语音转文本听录或语音翻译。 有关使用 Whisper 模型的详细信息,请参阅快速入门和 Whisper 模型概述。
请求语音转文本听录
转录音频文件。
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必须 | Whisper 模型部署的名称,例如 MyWhisperDeployment。 必须先部署 Whisper 模型,然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。 |
支持的版本
2023-09-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-10-01-preview
Swagger spec2023-12-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
file |
文件 | 是 | 空值 | 音频文件对象(非文件名)采用以下格式之一进行转录:flac 、mp3 、mp4 、mpeg 、mpga 、m4a 、ogg 、wav 或 webm 。Azure OpenAI 服务中的 Whisper 模型的文件大小限制为 25 MB。 如果需要转录大于 25 MB 的文件,请将其拆分成区块。 或者,可以使用 Azure AI 语音批处理听录 API。 可以从 GitHub 上的 Azure AI 语音 SDK 存储库获取示例音频文件。 |
language |
string | 否 | Null | 输入音频的语言,例如 fr 。 以 ISO-639-1 格式提供输入语言可以提高准确性并减少延迟。有关受支持语言的列表,请参阅 OpenAI 文档。 |
prompt |
string | 否 | Null | 用于指导模型风格或继续之前的音频片段的可选文本。 提示应与音频语言匹配。 有关提示(包括示例用例)的详细信息,请参阅 OpenAI 文档。 |
response_format |
string | 否 | json | 脚本输出的格式,采用以下选项之一:json、text、srt、verbose_json 或 vtt。 默认值为 json。 |
temperature |
数字 | 否 | 0 | 采样温度,介于 0 和 1 之间。 较大的值(如 0.8)使输出更随机,而较小的值(如 0.2)使输出更集中且更具确定性。 如果设置为 0,则模型使用对数概率自动升高温度,直到达到特定阈值。 默认值为 0。 |
timestamp_granularities |
array | 可选 | 段 | 要为此听录填充的时间戳粒度。 response_format 必须设为 verbose_json 以使用时间戳粒度。 支持以下任一选项或两个选项:word 或 segment 。 注意:段时间戳没有额外的延迟,但生成单词时间戳会产生额外的延迟。 [已在 2024-04-01-prevew 中添加] |
示例请求
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"
示例响应
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.
请求语音到文本的转换
将音频文件从其他语言翻译成英语。 有关受支持语言的列表,请参阅 OpenAI 文档。
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必须 | Whisper 模型部署的名称,例如 MyWhisperDeployment。 必须先部署 Whisper 模型,然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。 |
支持的版本
2023-09-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2023-10-01-preview
Swagger spec2023-12-01-preview
(即将于 2024 年 7 月 1 日停用)Swagger 规范2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec2024-02-01
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
file |
文件 | 是 | 空值 | 音频文件对象(非文件名)采用以下格式之一进行转录:flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。 Azure OpenAI Whisper 模型的文件大小限制为 25 MB。 如果需要转录大于 25 MB 的文件,请将其拆分成区块。 可以从 GitHub 上的 Azure AI 语音 SDK 存储库下载示例音频文件。 |
prompt |
string | 否 | Null | 用于指导模型风格或继续之前的音频片段的可选文本。 提示应与音频语言匹配。 有关提示(包括示例用例)的详细信息,请参阅 OpenAI 文档。 |
response_format |
string | 否 | json | 脚本输出的格式,采用以下选项之一:json、text、srt、verbose_json 或 vtt。 默认值为 json。 |
temperature |
数字 | 否 | 0 | 采样温度,介于 0 和 1 之间。 较大的值(如 0.8)使输出更随机,而较小的值(如 0.2)使输出更集中且更具确定性。 如果设置为 0,则模型使用对数概率自动升高温度,直到达到特定阈值。 默认值为 0。 |
示例请求
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"
示例响应
{
"text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}
文本到语音转换
将文本合成为语音。
POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}
路径参数
参数 | 类型 | 必需? | 说明 |
---|---|---|---|
your-resource-name |
字符串 | 必需 | Azure OpenAI 资源的名称。 |
deployment-id |
字符串 | 必须 | 文本转语音模型部署的名称,例如 MyTextToSpeechDeployment。 必须先部署文本转语音模型(例如 tts-1 或 tts-1-hd ),然后才能进行调用。 |
api-version |
string | 必需 | 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。 |
支持的版本
2024-02-15-preview
Swagger spec2024-03-01-preview
Swagger spec2024-04-01-preview
Swagger spec2024-05-01-preview
Swagger spec
请求正文
参数 | 类型 | 必需? | 默认 | 说明 |
---|---|---|---|---|
model |
字符串 | 是 | 空值 | 可用的 TTS 模型之一:tts-1 或 tts-1-hd |
input |
string | 是 | 空值 | 要为其生成音频的文本。 最大长度为 4096 个字符。 使用所选语言指定输入文本。1 |
voice |
string | 是 | 空值 | 生成音频时要使用的语音。 支持的语音为 alloy 、echo 、fable 、onyx 、nova 和 shimmer 。 OpenAI 文本转语音指南中提供了语音预览。 |
1 文本转语音模型通常与 Whisper 模型支持相同的语言。 有关受支持语言的列表,请参阅 OpenAI 文档。
示例请求
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
示例响应
语音作为上一请求中的音频文件返回。
管理 API
Azure OpenAI 作为 Azure AI 服务的一部分进行部署。 所有 Azure AI 服务都依赖于同一组管理 API 来执行创建、更新和删除操作。 管理 API 还用于在 Azure OpenAI 资源中部署模型。
后续步骤
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈