OpenAI API参考文档_opeanai api 请求格式

介绍

您可以通过来自任何语言的 HTTP 请求、我们的官方 Python 绑定、我们的官方 Node.js 库或社区维护的库与 API 进行交互。
若要安装官方 Python 绑定，请运行以下命令：

pip install openai
1

要安装官方的 Node.js 库，请在 Node.js 项目目录中运行以下命令：

npm install openai
1

身份认证

OpenAI API 使用 API 密钥进行身份验证。访问您的 API 密钥页面，检索您将在请求中使用的 API 密钥。
请记住，您的API密钥是一个秘密！不要与他人共享或在任何客户端代码（浏览器、应用程序）中公开它。生产请求必须通过您自己的后端服务器进行路由，在该服务器上，可以从环境变量或密钥管理服务安全地加载 API 密钥。
所有 API 请求都应在 Authorization HTTP 标头中包含您的 API 密钥，如下所示：

Authorization: Bearer YOUR_API_KEY
1

请求组织

对于属于多个组织的用户，您可以传递标头以指定用于 API 请求的组织。这些 API 请求的使用量将计入指定组织的订阅配额。
示例 curl 命令：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Organization: YOUR_ORG_ID"
1
2
3

Python 包的openai示例：

import os
import openai
openai.organization = "YOUR_ORG_ID"
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.list()
Node.js 包的openai示例：
import { Configuration, OpenAIApi } from "openai";
const configuration = new Configuration({
    organization: "YOUR_ORG_ID",
    apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.listEngines();
1
2
3
4
5
6
7
8
9
10
11
12
13

可以在组织设置页面上找到组织 ID。

提出请求

您可以将以下命令粘贴到终端中以运行您的第一个 API 请求。请确保将 $OPENAI_API_KEY 替换为您的密钥。

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
     "model": "gpt-3.5-turbo",
     "messages": [{"role": "user", "content": "Say this is a test!"}],
     "temperature": 0.7
   }'
1
2
3
4
5
6
7
8

此请求使用 “gpt-3.5-turbo” 模型来完成以 “Say this is a test” 为提示的文本。您将收到一个类似以下的响应：

{
   "id":"chatcmpl-abc123",
   "object":"chat.completion",
   "created":1677858242,
   "model":"gpt-3.5-turbo-0301",
   "usage":{
      "prompt_tokens":13,
      "completion_tokens":7,
      "total_tokens":20
   },
   "choices":[
      {
         "message":{
            "role":"assistant",
            "content":"\n\nThis is a test!"
         },
         "finish_reason":"stop",
         "index":0
      }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

现在您已经生成了第一个聊天完成。我们可以看到 finish_reason 是 stop，这意味着 API 返回了模型生成的完整完成结果。在上述请求中，我们只生成了一条消息，但您可以通过设置 n 参数来生成多个消息选择。

模型

列出并描述 API 中可用的各种模型。您可以参考模型文档以了解可用的模型以及它们之间的差异。

API 中可用的各种模型及其描述：
text-davinci-003: 这是一个基于文本的模型，适用于广泛的自然语言处理任务。它可以生成高质量的文本，但需要更长的推理时间。
text-davinci-002: 这也是一个基于文本的模型，适用于各种自然语言处理任务。它在速度和质量之间取得了平衡。
text-davinci-001: 这是一个基于文本的模型，适用于常见的自然语言处理任务。它在速度方面更快，但可能牺牲一些质量。
gpt-3.5-turbo: 这是一个强大的模型，适用于生成文本、回答问题、完成任务等多种任务。它是最先进的模型之一，具有出色的质量和速度。
每个模型都有不同的特点和用途，具体选择取决于您的需求和偏好。您可以参考「Models」文档以了解可用模型之间的区别和适用场景。

列出模型

GET https://api.openai.com/v1/models

示例请求

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.list()
1
2
3
4

响应

{
  "data": [
    {
      "id": "model-id-0",
      "object": "model",
      "owned_by": "organization-owner",
      "permission": [...]
    },
    {
      "id": "model-id-1",
      "object": "model",
      "owned_by": "organization-owner",
      "permission": [...]
    },
    {
      "id": "model-id-2",
      "object": "model",
      "owned_by": "openai",
      "permission": [...]
    },
  ],
  "object": "list"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

模型获取

GET https://api.openai.com/v1/models/{model}
获取模型实例，提供有关模型的基本信息，例如所有者和权限。

路径参数 model string Required
用于此请求的模型 ID
示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.retrieve("text-davinci-003")
1
2
3
4

响应

{
  "id": "text-davinci-003",
  "object": "model",
  "owned_by": "openai",
  "permission": [...]
}
1
2
3
4
5
6

Chat（聊天）：

给定一个包含对话的消息列表，模型将返回一个响应

创建完成

POST https://api.openai.com/v1/completions
创建给定聊天对话的模型响应：

请求 body

model string Required
要使用的模型的ID。有关哪些模型适用于 Chat API 的详细信息，请参阅模型端点兼容性表。

messages array Required
以下是一个示例的 Python 代码，其中包含一个消息列表，表示到目前为止的对话：
role string Required
消息作者的角色。可以是以下之一：system（系统）、user（用户）、assistant（助手）或function（函数）。
content string Optional
消息的内容。除了助手消息中的函数调用外，所有消息都需要提供内容（content）。
name string Optional
消息作者的名称。如果角色（role）是 function，则需要提供名称（name），它应该是内容（content）中响应的函数的名称。名称可以包含 a-z、A-Z、0-9 和下划线，最大长度为 64 个字符。
function_call object Optional
由模型生成的应调用的函数的名称和参数。

functions array Optional
模型可能为其生成 JSON 输入的函数列表。
name string Required
要调用的函数的名称。名称必须由 a-z、A-Z、0-9 组成，可以包含下划线和破折号，最大长度为 64。
description string Optional
函数的描述，即函数的功能说明。
parameters object Optional
函数接受的参数，以 JSON Schema 对象的形式进行描述。请参阅指南中的示例，以及 JSON Schema 参考文档，了解有关格式的详细信息。

function_call string or object Optional
控制模型对函数调用的响应方式。“none” 表示模型不调用函数，而是直接响应给最终用户。“auto” 表示模型可以在最终用户和调用函数之间进行选择。通过 {“name”: “my_function”} 指定特定函数会强制模型调用该函数。当没有函数存在时，默认值为 “none”。当存在函数时，默认值为 “auto”。

temperature number Optional Defaults to 1
要使用的采样温度，取值范围为 0 到 2 之间。较高的值（例如 0.8）会使输出更加随机，而较低的值（例如 0.2）会使其更加集中和确定性。通常建议只修改其中一个参数，而不是同时修改两个参数（sampling temperature 和 top_p）。
top_p number Optional Defaults to 1
一种替代采用温度进行采样的方法是使用核心采样（nucleus sampling），其中模型考虑具有 top_p 概率质量的令牌的结果。因此，0.1 表示仅考虑组成前 10% 概率质量的令牌。通常建议只修改其中一个参数，而不是同时修改两个参数（核心采样和温度）。
n integer Optional Defaults to 1
为每个输入消息生成的聊天完成选项的数量。

Strea（流式传输） 布尔值 可选项，默认为 false
如果设置为 true，将发送部分消息增量，就像在 ChatGPT 中一样。令牌将作为数据的服务器推送事件在可用时发送，流式传输以 data: [DONE] 消息终止。stream 被设置为 True，表示启用了流式传输。
stop（停止标记） 字符串或数组 可选项，默认为 null
最多可以指定 4 个序列，当 API 生成这些序列后，将停止继续生成更多的令牌

max_tokens（最大令牌数） 整数 可选项，默认为 inf（无限）
聊天完成中要生成的最大令牌数。输入令牌和生成的令牌的总长度受模型上下文长度的限制。max_tokens 被设置为 100，表示在聊天完成中最多生成 100 个令牌。

presence_penalty 数字 可选项，默认为 0
取值范围为 -2.0 到 2.0 之间的数字。正值会根据新令牌是否在已生成的文本中出现来对其进行惩罚，增加模型谈论新话题的可能性。
frequency_penalty 数字 可选项，默认为 0
取值范围为 -2.0 到 2.0 之间的数字。正值会根据新令牌在已生成的文本中的频率对其进行惩罚，降低模型直接重复相同文本的可能性。
logit_bias 映射 可选项，默认为 null
修改特定令牌在生成结果中出现的可能性。接受一个 JSON 对象，将令牌（由其在分词器中的令牌 ID 指定）映射到 -100 到 100 之间的相关偏差值。在数学上，在采样之前，将偏差添加到模型生成的 logits 中。具体效果因模型而异，但 -1 到 1 之间的值应该会减少或增加选择的可能性；-100 或 100 这样的值应该会导致相关令牌的禁止或独占选择。
user 字符串 可选项
表示您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。

请求示例：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")

completion = openai.ChatCompletion.create(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
)

print(completion.choices[0].message)
1
2
3
4
5
6
7
8
9
10
11
12
13

参数：

{
  "model": "gpt-3.5-turbo",
  "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}]
}
1
2
3
4

响应：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nHello there, how may I assist you today?",
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Completions（完成）

给定一个提示（prompt），模型将返回一个或多个预测的完成（completion），并且还可以返回每个位置上备选令牌的概率。这意味着模型可以给出多个可能的完成，并且可以提供每个令牌的概率分布，以指示其在生成结果中的可能性。这样可以帮助用户了解模型对不同选项的置信度，并根据需要进行进一步的处理或选择。

创建完成（Completion）请求

POST https://api.openai.com/v1/completions
使用提供的提示和参数创建一个完成请求。通过向上述 API 端点发送 POST 请求，可以向 OpenAI 服务提交一个完成请求，以生成模型的响应或补全文本。在请求中，您需要提供适当的提示和其他参数，以控制生成的完成内容。

请求体（Request Body）

model 字符串 必填 要使用的模型的ID。
您可以使用"列出模型"API来查看所有可用的模型，或者查看我们的模型概述以获取它们的描述。

prompt 字符串或者数组 可选 Defaults to <|endoftext|>
用于生成完成、编码为字符串、字符串数组、标记数组或标记数组数组的提示。
请注意，<|endoftext|> 是模型在训练期间看到的文档分隔符，因此如果未指定提示，模型将生成，就像从新文档的开头一样。

suffix 字符串 可选 默认为null
插入文本完成后的后缀。

max_tokens 整型 可选 默认16
完成时要生成的最大令牌数。
提示加号的令牌计数不能超过模型的上下文长度 max_tokens。大多数模型的上下文长度为 2048 个令牌（最新模型除外，它支持 4096）。

温度 数字 可选项 默认为1
采样温度的设定范围在0到2之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议只修改其中一个参数，要么是温度，要么是top_p。
top_p 数字 可选项 默认为1
这是一种与温度采样相对的方法，称为nucleus采样，模型会考虑具有top_p概率质量的标记的结果。因此，0.1表示只考虑组成前10%概率质量的标记。我们通常建议只修改其中一个参数，要么是top_p，要么是温度。
n 整数 可选项 默认为1
每个提示生成的完成数量。 注意：由于此参数会生成许多完成结果，它可能会快速消耗您的令牌配额。请谨慎使用，并确保您对max_tokens和stop设置了合理的值。

stream 布尔值 可选项 默认为false
是否以流式返回部分进度。如果设置为true，令牌将作为数据的服务器推送事件随着其可用性而发送，流式传输将以数据：[DONE]消息终止。
logprobs 整数 可选项 默认为null
在最有可能的logprobs个标记中包括对数概率，以及所选择的标记。例如，如果logprobs为5，API将返回最有可能的5个标记的列表。API将始终返回所采样标记的对数概率，因此响应中可能有logprobs+1个元素。 logprobs的最大值为5。
echo 布尔值 可选项 默认为false
除了完成结果之外，是否将提示内容回显。

stop 字符串或数组 可选项 默认为null
最多4个序列，API将停止生成进一步的标记。返回的文本将不包含停止序列。
presence_penalty 数字 可选项 默认为0
取值范围在-2.0到2.0之间。正值根据新标记在文本中的出现情况对其进行惩罚，增加模型谈论新话题的可能性。 有关频率和存在惩罚的更多信息，请参阅相关文档。
frequency_penalty 数字 可选项 默认为0
取值范围在-2.0到2.0之间。正值根据标记在文本中的现有频率对其进行惩罚，降低模型重复相同行的可能性。 有关频率和存在惩罚的更多信息，请参阅相关文档。

best_of 整数 可选项 默认为1
在服务器端生成best_of个完成结果，并返回“最佳”（每个标记具有最高对数概率的结果）。结果无法进行流式传输。 当与n一起使用时，best_of控制候选完成结果的数量，而n指定要返回的数量 - best_of必须大于n。 注意：由于此参数会生成许多完成结果，它可能会快速消耗您的令牌配额。请谨慎使用，并确保您对max_tokens和stop设置了合理的值。
logit_bias（逻辑偏置） map（映射） 可选项 默认为null
修改指定标记在完成中出现的可能性。接受一个JSON对象，将标记（通过GPT分词器中的标记ID指定）映射到-100到100之间的相关偏置值。您可以使用此分词器工具（适用于GPT-2和GPT-3）将文本转换为标记ID。从数学上讲，在采样之前，模型生成的逻辑值会受到偏置的影响。具体效果因模型而异，但在-1到1之间的值应该会减少或增加选择的可能性；像-100或100这样的值应该会导致相关标记的禁止或独占选择。
例如，您可以传递{“50256”: -100}以防止生成 <|endoftext|> 令牌。
user string Optional
代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Completion.create(
  model="text-davinci-003",
  prompt="Say this is a test",
  max_tokens=7,
  temperature=0
)
1
2
3
4
5
6
7
8
9

参数：

{
  "model": "text-davinci-003",
  "prompt": "Say this is a test",
  "max_tokens": 7,
  "temperature": 0,
  "top_p": 1,
  "n": 1,
  "stream": false,
  "logprobs": null,
  "stop": "\n"
}
1
2
3
4
5
6
7
8
9
10
11

响应：

{
  "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
  "object": "text_completion",
  "created": 1589478378,
  "model": "text-davinci-003",
  "choices": [
    {
      "text": "\n\nThis is indeed a test",
      "index": 0,
      "logprobs": null,
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 7,
    "total_tokens": 12
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

编辑

给定提示和指令，模型将返回提示的编辑版本。

创建编辑

POST https://api.openai.com/v1/edits
为提供的输入、指令和参数创建新的编辑。

请求 body

model string Required
要使用的模型的 ID。可以将 text-davinci-edit-001 或 code-davinci-edit-001 模型用于此终结点。

input string Optional Defaults to ‘’
要用作编辑起点的输入文本。

instruction string Required
告知模型如何编辑提示的说明。

n integer Optional Defaults to 1
要为输入和指令生成的编辑次数。

temperature number Optional Defaults to 1
使用什么采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。
我们通常建议更改此设置，但不要同时更改 top_p 两者。

top_p number Optional Defaults to 1
使用温度采样的替代方法称为核心采样，其中模型考虑具有top_p概率质量的令牌的结果。因此，0.1 意味着只考虑包含前 10% 概率质量的代币。
我们通常建议更改此设置，但不要同时更改 temperature 两者。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Edit.create(
  model="text-davinci-edit-001",
  input="What day of the wek is it?",
  instruction="Fix the spelling mistakes"
)
1
2
3
4
5
6
7
8

参数：

{
  "model": "text-davinci-edit-001",
  "input": "What day of the wek is it?",
  "instruction": "Fix the spelling mistakes"
}
1
2
3
4
5

响应：

{
  "object": "edit",
  "created": 1589478378,
  "choices": [
    {
      "text": "What day of the week is it?",
      "index": 0,
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

图像

给定提示和/或输入图像，模型将生成一个新图像。

图像生成

POST https://api.openai.com/v1/images/generations
创建给定提示的图像。

请求 Body

prompt string Required
所需图像的文本描述。最大长度为 1000 个字符。
n integer Optional Defaults to 1
要生成的图像数。必须介于 1 和 10 之间。
size string Optional Defaults to 1024x1024
生成的图像的大小。必须是 256x256、 512x512 或 1024x1024 之一。
response_format string Optional Defaults to url
返回生成的图像的格式。必须是 url 或 b64_json 之一。
user string Optional
代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create(
  prompt="A cute baby sea otter",
  n=2,
  size="1024x1024"
)
1
2
3
4
5
6
7
8

参数：

{
  "prompt": "A cute baby sea otter",
  "n": 2,
  "size": "1024x1024"
}
1
2
3
4
5

响应：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

创建图像编辑

POST https://api.openai.com/v1/images/edits
在给定原始图像和提示的情况下创建编辑或扩展的图像。

请求 Body

image string Required
需要编辑的图片。必须是有效的PNG文件，大小不超过4MB，并且是正方形的。如果没有提供遮罩（mask），图片必须具有透明度，透明度将被用作遮罩。
mask string Optional
一个附加图像，其完全透明的区域（例如，alpha为零）指示 image 应编辑的位置。必须是有效的 PNG 文件，小于 4MB，并且尺寸与 image 相同。
prompt string Required
所需图像的文本描述。最大长度为 1000 个字符。
n integer Optional Defaults to 1
要生成的图像数。必须介于 1 和 10 之间。
size string Optional Defaults to 1024x1024
生成的图像的大小。必须是 256x256 、 512x512 或 1024x1024 之一。
response_format string Optional Defaults to url
返回生成的图像的格式。必须是 url 或 b64_json 之一。
user string Optional
代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create_edit(
  image=open("otter.png", "rb"),
  mask=open("mask.png", "rb"),
  prompt="A cute baby sea otter wearing a beret",
  n=2,
  size="1024x1024"
)
1
2
3
4
5
6
7
8
9
10

响应：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

创建图像变体

POST https://api.openai.com/v1/images/variations
创建给定图像的变体。

请求 Body

image string Required
用作变体基础的图像。必须是有效的 PNG 文件，小于 4MB，并且是正方形。
n integer Optional Defaults to 1
要生成的图像数。必须介于 1 和 10 之间。
size string Optional Defaults to 1024x1024
生成的图像的大小。必须是 256x256 、 512x512 或 1024x1024 之一。
response_format string Optional Defaults to url
返回生成的图像的格式。必须是 url 或 b64_json 之一。b64_json
user string Optional
代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create_variation(
  image=open("otter.png", "rb"),
  n=2,
  size="1024x1024"
)
1
2
3
4
5
6
7
8

响应：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

嵌入（Embeddings）

获取给定输入的向量表示，该表示可以被机器学习模型和算法轻松使用。

创建嵌入

POST https://api.openai.com/v1/embeddings
创建表示输入文本的嵌入向量。

请求 Body

model string Required
要使用的模型的 ID。可以使用列表模型 API 查看所有可用模型，或参阅模型概述了解它们的描述。
input string or array Required
要为其嵌入的输入文本，编码为字符串或标记数组。若要在单个请求中获取多个输入的嵌入，请传递字符串数组或令牌数组数组。每个输入的长度不得超过 8192 个令牌。
user string Optional
代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Embedding.create(
  model="text-embedding-ada-002",
  input="The food was delicious and the waiter..."
)
1
2
3
4
5
6
7

参数：
{
“model”: “text-embedding-ada-002”,
“input”: “The food was delicious and the waiter…”
}
响应：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... (1536 floats total for ada-002)
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

音频Audio

学习如何将音频转换为文本。

创建转录（测试版）

POST https://api.openai.com/v1/audio/transcriptions
将音频转录为输入语言。

请求主体

file file 必填项
要转录的音频文件对象（不是文件名），格式可以是以下之一：mp3、mp4、mpeg、mpga、m4a、wav 或 webm。

model 字符串 必填项
要使用的模型的ID。目前只有whisper-1可用。
prompt 字符串 可选项
一个可选的文本，用于指导模型的风格或继续之前的音频片段。提示文本应与音频语言相匹配。

response_format 字符串 可选项 默认为json
转录输出的格式，可以是以下选项之一：json、text、srt、verbose_json 或 vtt。
temperature 数字 可选项 默认为0 采样温度，
介于0和1之间。较高的值（如0.8）会使输出更随机，而较低的值（如0.2）会使其更加集中和确定性。如果设置为0，模型将使用对数概率自动增加温度，直到达到一定的阈值。

language 字符串 可选项 输入音频的语言。以 ISO-639-1 格式提供输入语言将提高准确性和延迟。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
audio_file = open("audio.mp3", "rb")
transcript = openai.Audio.transcribe("whisper-1", audio_file)
1
2
3
4
5

参数：

{
  "file": "audio.mp3",
  "model": "whisper-1"
}
1
2
3
4

响应：

{
  "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that."
}
1
2
3

创建翻译（测试版）

POST https://api.openai.com/v1/audio/translations
将音频翻译为英语

请求主体

file file 必填项
要翻译的音频文件对象（不是文件名），格式可以是以下之一：mp3、mp4、mpeg、mpga、m4a、wav 或 webm。
model 字符串 必填项
要使用的模型的ID。目前只有whisper-1可用。
prompt 字符串 可选项
一个可选的文本，用于指导模型的风格或继续之前的音频片段。提示文本应为英文

response_format 字符串 可选项 默认为json
转录输出的格式，可以是以下选项之一：json、text、srt、verbose_json 或 vtt。
temperature 数字 可选项 默认为0
采样温度，介于0和1之间。较高的值（如0.8）会使输出更随机，而较低的值（如0.2）会使其更加集中和确定性。如果设置为0，模型将使用对数概率自动增加温度，直到达到一定的阈值

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
audio_file = open("german.m4a", "rb")
transcript = openai.Audio.translate("whisper-1", audio_file)
1
2
3
4
5

参数：

{
  "file": "german.m4a",
  "model": "whisper-1"
}
1
2
3
4

响应：

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

文件

文件用于上传可以与微调等功能一起使用的文档。

列出文件

GET https://api.openai.com/v1/files
返回属于用户组织的文件列表

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.list()
1
2
3
4

响应：

{
  "data": [
    {
      "id": "file-ccdDZrC3iZVNiQVeEA6Z66wf",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "filename": "train.jsonl",
      "purpose": "search"
    },
    {
      "id": "file-XjGxS3KTG0uNmNOK362iJua3",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "filename": "puppy.jsonl",
      "purpose": "search"
    }
  ],
  "object": "list"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

上传文件

POST https://api.openai.com/v1/files
上传包含要在各个端点/功能中使用的文档的文件。目前，一个组织上传的所有文件的大小总和最多可以达到1 GB。如果您需要增加存储限制，请与我们联系。

请求主体

file 字符串 必填项
要上传的 JSON Lines 文件的名称。如果目的设置为 “fine-tune”，每行都是一个 JSON 记录，其中包含 “prompt” 和 “completion” 字段，表示您的训练示例。
purpose 字符串 必填项
上传文档的预期用途。对于 Fine-tuning，请使用 “fine-tune”。这样可以验证上传文件的格式。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.create(
  file=open("mydata.jsonl", "rb"),
  purpose='fine-tune'
)
1
2
3
4
5
6
7

响应：

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779121,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune"
}
1
2
3
4
5
6
7
8

删除文件

DELETE https://api.openai.com/v1/files/{file_id}
删除文件
路径参数
file_id 字符串 必填项
要在此请求中使用的文件的ID。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.delete("file-XjGxS3KTG0uNmNOK362iJua3")
1
2
3
4

响应：

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "deleted": true
}
1
2
3
4
5

检索文件

GET https://api.openai.com/v1/files/{file_id}
返回有关特定文件的信息。
路径参数 file_id 字符串 必填项
请求file的id

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.retrieve("file-XjGxS3KTG0uNmNOK362iJua3")
1
2
3
4

响应

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779657,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune"
}
1
2
3
4
5
6
7
8

检索文件内容

GET https://api.openai.com/v1/files/{file_id}/content
返回指定文件的内容
路径参数 file_id 字符串 必填项 要在此请求中使用的文件的ID。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
content = openai.File.download("file-XjGxS3KTG0uNmNOK362iJua3")
1
2
3
4

微调

管理微调作业，以根据您的特定训练数据定制模型。

创建微调

POST https://api.openai.com/v1/fine-tunes
创建一个作业，对给定的数据集微调指定的模型。响应包括已入队作业的详细信息，包括作业状态和完成后的微调模型的名称。

请求主体

training_file 字符串 必填项
包含训练数据的已上传文件的ID。 有关如何上传文件，请参阅上传文件。 您的数据集必须格式化为一个 JSONL 文件，其中每个训练示例都是一个带有键 “prompt” 和 “completion” 的 JSON 对象。此外，您必须使用 fine-tune 的目的上传文件
validation_file 字符串 可选项
包含验证数据的已上传文件的ID。如果提供此文件，数据将在微调过程中定期生成验证指标。这些指标可以在微调结果文件中查看。您的训练和验证数据应该是互斥的。您的数据集必须格式化为一个 JSONL 文件，其中每个验证示例都是一个带有键 “prompt” 和 “completion” 的 JSON 对象。此外，您必须使用 fine-tune 的目的上传文件。
model 字符串 可选项 默认为curie
要微调的基础模型的名称。您可以选择 “ada”、“babbage”、“curie”、“davinci” 中的一个，或者选择2022-04-21之后创建的经过微调的模型。要了解有关这些模型的更多信息，请参阅模型文档。
n_epochs 整数 可选项 默认为4
训练模型的时期数。一个时期指的是对训练数据集进行一次完整循环
batch_size 整数 可选项 默认为null
用于训练的批次大小。批次大小是用于训练单个前向和后向传递的训练示例的数量。默认情况下，批次大小将动态配置为训练集中示例数量的约0.2%，上限为256 - 通常情况下，我们发现较大的批次大小对于较大的数据集效果更好
learning_rate_multiplier 数字 可选项 默认为null
用于训练的学习率乘数。微调学习率是预训练时使用的原始学习率乘以该值。 默认情况下，学习率乘数为0.05、0.1或0.2，取决于最终的批次大小（较大的学习率在较大的批次大小下通常表现更好）。我们建议在0.02到0.2的范围内尝试不同的值，以找到产生最佳结果的值
prompt_loss_weight 数字 可选项 默认为0.01
用于提示令牌损失的权重。这控制了模型尝试学习生成提示的程度（与始终具有1.0权重的完成进行比较），并且可以在完成较短时对训练产生稳定效果。如果提示非常长（相对于完成），可能有必要减小此权重，以避免过度优先学习提示。
compute_classification_metrics 布尔值 可选项 默认为false
如果设置为true，我们将在每个时期结束时使用验证集计算特定于分类的指标，如准确率和F-1分数。这些指标可以在结果文件中查看。 为了计算分类指标，您必须提供一个验证文件。此外，您必须指定classification_n_classes（用于多类分类）或classification_positive_class（用于二分类）。
classification_n_classes 整数 可选项 默认为null
分类任务中的类别数量。 对于多类分类，此参数是必需的。
classification_positive_class 字符串 可选项 默认为null
二分类中的正类别。 在进行二分类时，需要此参数来生成精确度、召回率和F1指标。

classification_betas 数组 可选项 默认为null
如果提供了此参数，我们将在指定的beta值上计算F-beta分数。F-beta分数是F-1分数的一般化。这仅用于二分类。 对于beta为1（即F-1分数），精确度和召回率被赋予相同的权重。较大的beta分数对召回率的权重更大，对精确度的权重较小。较小的beta分数对精确度的权重更大，对召回率的权重较小。
suffix 字符串 可选项 默认为null
最多40个字符的字符串，将添加到您的微调模型名称中。 例如，后缀为"custom-model-name"将生成一个类似ada:ft-your-org:custom-model-name-2022-02-15-04-21-04的模型名称

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.create(training_file="file-XGinujblHPwGLSztz8cPS8XY")
1
2
3
4

响应：

{
  "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807352,
  "events": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    }
  ],
  "fine_tuned_model": null,
  "hyperparams": {
    "batch_size": 4,
    "learning_rate_multiplier": 0.1,
    "n_epochs": 4,
    "prompt_loss_weight": 0.1,
  },
  "organization_id": "org-...",
  "result_files": [],
  "status": "pending",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807352,
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

列出微调任务

GET https://api.openai.com/v1/fine-tunes
列出您组织的微调任务

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list()
1
2
3
4

响应：

{
  "object": "list",
  "data": [
    {
      "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
      "object": "fine-tune",
      "model": "curie",
      "created_at": 1614807352,
      "fine_tuned_model": null,
      "hyperparams": { ... },
      "organization_id": "org-...",
      "result_files": [],
      "status": "pending",
      "validation_files": [],
      "training_files": [ { ... } ],
      "updated_at": 1614807352,
    },
    { ... },
    { ... }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

获取微调任务

GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}
获取有关微调作业的信息。
路径参数 fine_tune_id 字符串 必需 微调作业的ID

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.retrieve(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
1
2
3
4

响应：

{
  "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807352,
  "events": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807356,
      "level": "info",
      "message": "Job started."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807861,
      "level": "info",
      "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Job succeeded."
    }
  ],
  "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20",
  "hyperparams": {
    "batch_size": 4,
    "learning_rate_multiplier": 0.1,
    "n_epochs": 4,
    "prompt_loss_weight": 0.1,
  },
  "organization_id": "org-...",
  "result_files": [
    {
      "id": "file-QQm6ZpqdNwAaVC3aSz5sWwLT",
      "object": "file",
      "bytes": 81509,
      "created_at": 1614807863,
      "filename": "compiled_results.csv",
      "purpose": "fine-tune-results"
    }
  ],
  "status": "succeeded",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807865,
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

取消微调任务

POST https://api.openai.com/v1/fine-tunes/{fine_tune_id}/cancel
立即取消微调作业。
路径参数 fine_tune_id 字符串 必需 要取消的微调作业的ID

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.cancel(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
1
2
3
4

响应：

{
  "id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807770,
  "events": [ { ... } ],
  "fine_tuned_model": null,
  "hyperparams": { ... },
  "organization_id": "org-...",
  "result_files": [],
  "status": "cancelled",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807789,
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

列出微调事件

GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events
获取微调作业的详细状态更新。
路径参数 fine_tune_id 字符串 必需 要获取事件的微调作业的ID。

查询参数 stream 布尔值 可选项 默认为false
是否为微调作业流式传输事件。如果设置为true，事件将作为数据服务器推送事件在可用时发送。当作业完成（成功、取消或失败）时，流将以数据：[DONE] 消息终止。 如果设置为false，只返回到目前为止

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list_events(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
1
2
3
4

响应：

{
  "object": "list",
  "data": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807356,
      "level": "info",
      "message": "Job started."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807861,
      "level": "info",
      "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Job succeeded."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

删除微调模型

DELETE https://api.openai.com/v1/models/{model}
删除一个微调模型。您必须在您的组织中拥有所有者角色。
路径参数 model 字符串 必需

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.delete("curie:ft-acmeco-2021-03-03-21-44-20")
1
2
3
4

响应：

{
  "id": "curie:ft-acmeco-2021-03-03-21-44-20",
  "object": "model",
  "deleted": true
}
1
2
3
4
5

Moderations 内容审核

给定一个输入文本，输出模型是否将其分类为违反OpenAI内容政策的

创建内容审核

POST https://api.openai.com/v1/moderations
对文本进行分类，判断是否违反OpenAI的内容政策。

请求体 Request body

input 字符串或数组 必需 要分类的输入文本
model 字符串 可选项 默认为text-moderation-latest 有两个内容审核模型可用：text-moderation-stable和text-moderation-latest。
默认为text-moderation-latest，它会随着时间的推移自动升级。这确保您始终使用我们最准确的模型。如果使用text-moderation-stable，我们将在更新模型之前提前通知您。text-moderation-stable的准确性可能略低于text-moderation-latest。

示例请求：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Moderation.create(
  input="I want to kill them.",
)
1
2
3
4
5
6

参数：

{
  "input": "I want to kill them."
}
1
2
3

响应：

{
  "id": "modr-XXXXX",
  "model": "text-moderation-005",
  "results": [
    {
      "flagged": true,
      "categories": {
        "sexual": false,
        "hate": false,
        "harassment": false,
        "self-harm": false,
        "sexual/minors": false,
        "hate/threatening": false,
        "violence/graphic": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "harassment/threatening": true,
        "violence": true,
      },
      "category_scores": {
        "sexual": 1.2282071e-06,
        "hate": 0.010696256,
        "harassment": 0.29842457,
        "self-harm": 1.5236925e-08,
        "sexual/minors": 5.7246268e-08,
        "hate/threatening": 0.0060676364,
        "violence/graphic": 4.435014e-06,
        "self-harm/intent": 8.098441e-10,
        "self-harm/instructions": 2.8498655e-11,
        "harassment/threatening": 0.63055265,
        "violence": 0.99011886,
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

参数详细信息

频率和存在惩罚

在Completions API中找到的频率和存在惩罚可以用于减少采样重复的令牌序列的可能性。它们通过直接对logits（未归一化的对数概率）进行加性调整来实现

mu[j] -> mu[j] - c[j] * alpha_frequency - float(c[j] > 0) * alpha_presence
1

其中：

mu[j] 是第 j 个令牌的 logits 
c[j] 是在当前位置之前采样该令牌的次数 
float(c[j] > 0) 如果 c[j] > 0 则为 1，否则为 0 
alpha_frequency 是频率惩罚系数 
alpha_presence 是存在惩罚
1
2
3
4
5

正如我们所看到的，存在惩罚是一次性的加性贡献，适用于所有已经被采样至少一次的令牌，而频率惩罚是与特定令牌已经被采样的次数成比例的贡献。
如果目标只是稍微减少重复样本，那么惩罚系数的合理值大约在0.1到1之间。如果目标是强烈抑制重复，那么可以将系数增加到2，但这可能会明显降低样本的质量。可以使用负值来增加重复的可能性。