OpenAI API使用用户API keys来鉴权。联系管理员获取API Keys。
请注意保护API keys！ 不要分享或暴露在任何客户端（浏览器， apps)。 业务访问的时候一定在服务器端进行，不要直接通过客户端使用API keys访问接口。
所有的接口访问都需要在HTTP头加入Authorization进行鉴权。例如：
Authorization: Bearer API_KEY联系我们获取API Endpoint。
在终端使用如下代码可以发起你的第一次API请求。确保使用你的API key替换了 $API_KEY 。
1
2
3
4
5
6
7
8
curl https://API_ENDPOINT/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Say this is a test!"}],
"temperature": 0.7
}'这个请求使用 gpt-3.5-turbo model 针对
"Say this is a test"进行回复。收到的返回如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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
}
]
}你已完成首次对话。反馈中的 finish_reason 是 stop ，
这表示 API 返回了model生成的完整内容。如下的请求中，我们只生成唯一的结果，但是可以通过
设定参数 n 来生成多种结果。另外下列示例中使用 gpt-3.5-turbo model，
此model多用在 text completion task。
同时也多用于 chat applications 。
1
2
curl https://API_ENDPOINT/v1/models \
-H "Authorization: Bearer $API_KEY"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"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"
}get https://API_ENDPOINT/v1/models/{model}
查询某个model的基本信息，例如 owner 和 permissioning.
1
2
curl https://API_ENDPOINT/v1/models/text-davinci-003 \
-H "Authorization: Bearer $API_KEY"1
2
3
4
5
6
{
"id": "text-davinci-003",
"object": "model",
"owned_by": "openai",
"permission": [...]
}根据给定的prompt（引导语）, model 将给出一个或多个completions（预言结果）， 并将给出每个结果的相关属性。
post https://API_ENDPOINT/v1/completions
根据给定的 prompt （引导语）和参数创建文本处理任务。
Request body
prompt(s) 引导语，用于生成 completions。 类型：string， string数组，token数组，token数组组成的数组。 使用数组方式可以使得我们更加方便地将一个文本片段分成多个段落或句子， 这样可以更好地控制生成的文本的结构和内容。 同时，使用数组方式还可以使得我们更加灵活地在prompt中添加或删除特定的句子，以便进行实验和测试。 因此，在实际应用中，使用数组方式可能更加方便和实用。
Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
完成生成文本后的后缀字符串，默认为空。 参数suffix用于在模型生成的文本之后添加一段固定的后缀。 这可以用来添加一些额外的文本或标记，例如表示文本结束的符号。
生成内容的最大 tokens 数。
prompt的token数加上max_tokens不能超过model的内容长度。
大部分模型的长度为2048个tokens（最新的模型可以达到4096）。
通过控制max_tokens参数，我们可以控制模型生成的文本长度，以便生成符合我们需求的文本结果。 需要注意的是，生成的文本长度过长可能会影响API的响应时间和计费。
temperature，0 到 2之间，用于调整模型生成文本时的创造性程度。 0.8较大，输出的文本更加随机， 0.2较小，输出的文本更加专注、确定。
推荐使用 参数temperature 或者 top_p，但不同时使用。
top_p 参数和temperature类似，用于控制模型生成文本时，选择下一个单词的概率分布的范围。
当使用top_p参数时，模型将考虑累积概率分布中概率之和最大的最小集合中的所有单词，并在其中选择下一个单词。 这个参数控制着OpenAI生成文本的多样性，具体来说， 它表示从概率分布中选取的概率质量值之和达到 top_p 时停止，生成的文本就是这个分布下的采样结果。 与之类似的另一个参数是temperature，它也可以控制生成文本的多样性。 不同的是，temperature是一个正实数，它用来缩放模型生成的原始概率分布。 当temperature较低时，生成的文本更加保守、可预测，当temperature较高时，生成的文本更加随机、多样。
推荐使用 参数temperature 或者 top_p，但不同时使用。
比较参数 temperature 和 top_p。
| 参数 | top_p | temperature |
|---|---|---|
| 作用 | 控制生成文本的多样性，选择概率质量值之和达到top_p的概率分布采样结果 | 缩放模型生成的原始概率分布，控制生成文本的多样性 |
| 适用场景 | - 当需要生成较为可控、可预测的文本时 - 当需要生成语法正确、含义明确的文本时 - 当需要保留模型生成文本的局部结构时 |
- 当需要生成多样、创新的文本时 - 当需要避免生成重复或过度拟合的文本时 - 当需要让模型在新领域的表现更加灵活、泛化能力更强时 |
n这个参数控制了API返回的候选文本的数量，即API会生成多少个可能的文本选项供用户选择。
注意: 由于此参数会生成许多，
因此它会快速消耗token配额，请谨慎使用。
可以使用参数
max_tokens and stop
控制使用量 。
默认false,是否流式传输回部分进度。 参数stream可以在请求生成文本时控制文本是否以流的形式返回。
使用stream参数的好处在于，它允许我们按需生成文本，而不需要等到整个文本都生成完毕。 这对于处理大型文本生成任务来说非常有用，因为它可以降低内存占用和网络带宽使用，并且可以更快地获得部分结果。
logprobs参数用于返回每个生成token的概率值（log-softmax）和其对应的token。
设置5，表示成器返回生成文本中，前5个概率值对应的token。 通过使用logprobs参数，可以更加细致地控制文本生成过程， 例如可以根据每个token的概率值来选择生成文本的下一个token，或者对生成文本的可解释性进行分析等。
默认最大值5.
echo参数用于将输入的prompt文本作为生成结果的一部分返回， 这可以用于将输入的上下文与生成的文本结果组合在一起，增强文本的可读性和可解释性。
例如，当生成的文本用于回答问题时，将输入的问题作为生成结果的一部分返回， 可以让用户更加清楚地理解回答的内容与输入问题之间的关系。
用于指定在生成文本时停止生成的条件，当生成文本中包含指定的字符串或达到指定的最大生成长度时，生成过程会自动停止。
当stop参数包含多个值时，只要满足其中任意一个条件，生成器就会停止生成。
除了字符串之外，stop参数还可以接受一个整数，表示生成文本的最大长度。
取值 -2.0 到 2.0。生成文本的内容是否使用频繁出现的词汇。
和frequency_penalty的区别：
| frequency_penalty | presence_penalty | |
|---|---|---|
| 适用范围 | 表示惩罚那些在训练数据中出现频率较高的单词或短语。 | 表示惩罚那些在生成文本中频繁出现的单词或短语。 |
| 设置高的值时 | 当frequency_penalty设置为较高的值时，生成文本会更加多样化，避免出现过于常见的单词或短语。 | 当presence_penalty设置为较高的值时，生成文本会更加多样化，避免出现重复的内容。 |
| 设置低的值时 | 当frequency_penalty设置为较低的值时，生成文本可能会出现更多的常见单词或短语。 | 而当presence_penalty设置为较低的值时，生成文本可能会出现更多的重复内容。 |
取值 -2.0 到 2.0。生成文本时模型是否应该使用高频词汇。 这里指的是model训练过程中定义的的高频词汇。
例如：
参数被设置为0， 表示完全忽略单词的出现频率。这将导致模型更有可能生成一些常见的单词。
参数被设置为0.5，表示模型更有可能避免生成常见的单词。
参数被设置为1，表示模型完全避免生成常见的单词。
用于指定多个生成器对同一个prompt文本进行生成，并从中选择最好的结果返回。
无法使用 stream.
使用 n, best_of 生成文本。
生成 n 个结果，返回 best_of 个得分最靠前的。
给出偏好设置，用于对生成器的输出结果进行修正， 以使生成的文本更加符合特定的条件或偏好。 具体来说，该参数将文本生成器的输出偏向于某些给定的单词或短语， 从而使生成文本更加贴合这些条件。
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 (which works for both GPT-2 and GPT-3) 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.
1
2
3
4
5
6
7
8
9
curl https://API_ENDPOINT/v1/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "text-davinci-003",
"prompt": "Say this is a test",
"max_tokens": 7,
"temperature": 0
}'1
2
3
4
5
6
7
8
9
10
11
{
"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
12
13
14
15
16
17
18
19
{
"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
}
}对话交谈场景。
OpenAI的ChatCompletion和Completion都是自然语言生成模型的接口，但它们的用途和应用场景略有不同。
| ChatCompletion | Completion | |
|---|---|---|
| 区别 | 专为生成对话和聊天场景而设计。 | 是一个通用的自然语言生成接口，支持生成各种类型的文本，包括段落、摘要、建议、答案等等。 |
| 适用场景 | ChatCompletion接口生成的文本通常会更具有人类对话的风格和语调，可以用于智能客服、聊天机器人等场景，以及在日常聊天中帮助用户自动生成回复。 | Completion接口的输出更为多样化，可能会更加严谨和专业，适用于各种文本生成场景，例如文章创作、信息提取、机器翻译、自然语言问题回答等等。 |
post https://API_ENDPOINT/v1/chat/completions
根据消息获取对话
Request body
messages必须是消息对象的数组，其中每个对象都有一个角色（“system”、“user”、“assistant”）和内容（消息的内容）。 对话可以短至 1 条消息或填满许多页面。
通常，对话的格式首先是system消息，然后是交替的user和assistant消息。
system消息有助于设置聊天AI助手的行为。在上面的例子中，被指示“你是一个乐于助人的助手”。
user消息有助于指示助手。它们可以由应用程序的最终用户生成，也可以由开发人员设置为指令。
assistant消息有助于存储先前的响应。它们也可以由开发人员编写，以帮助提供所需行为的示例。
因为请求是无状态的（模型没有过去请求的记忆），引用以前的消息(对话历史记录)会帮助AI理解上下文。 比如在上面的例子中，用户的最后一个问题“在哪里开的？”，只有在之前关于2020年世界大赛的消息的上下文中才有意义。
temperature，0 到 2之间，用于调整模型生成文本时的创造性程度。 0.8较大，输出的文本更加随机， 0.2较小，输出的文本更加专注、确定。
推荐使用 参数temperature 或者 top_p，但不同时使用。
top_p 参数和temperature类似，用于控制模型生成文本时，选择下一个单词的概率分布的范围。
当使用top_p参数时，模型将考虑累积概率分布中概率之和最大的最小集合中的所有单词，并在其中选择下一个单词。 这个参数控制着OpenAI生成文本的多样性，具体来说， 它表示从概率分布中选取的概率质量值之和达到 top_p 时停止，生成的文本就是这个分布下的采样结果。 与之类似的另一个参数是temperature，它也可以控制生成文本的多样性。 不同的是，temperature是一个正实数，它用来缩放模型生成的原始概率分布。 当temperature较低时，生成的文本更加保守、可预测，当temperature较高时，生成的文本更加随机、多样。
推荐使用 参数temperature 或者 top_p，但不同时使用。
n这个参数控制了API返回的候选文本的数量，即API会生成多少个可能的文本选项供用户选择。
注意: 由于此参数会生成许多，
因此它会快速消耗token配额，请谨慎使用。
可以使用参数
max_tokens and stop
控制使用量 。
默认false,是否流式传输回部分进度。 参数stream可以在请求生成文本时控制文本是否以流的形式返回。
使用stream参数的好处在于，它允许我们按需生成文本，而不需要等到整个文本都生成完毕。 这对于处理大型文本生成任务来说非常有用，因为它可以降低内存占用和网络带宽使用，并且可以更快地获得部分结果。
用于指定在生成文本时停止生成的条件，当生成文本中包含指定的字符串或达到指定的最大生成长度时，生成过程会自动停止。
当stop参数包含多个值时，只要满足其中任意一个条件，生成器就会停止生成。
除了字符串之外，stop参数还可以接受一个整数，表示生成文本的最大长度。
生成内容的最大 tokens 数。
prompt的token数加上max_tokens不能超过model的内容长度。
大部分模型的长度为2048个tokens（最新的模型可以达到4096）。
取值 -2.0 到 2.0。生成文本的内容是否使用频繁出现的词汇。
和frequency_penalty的区别：
取值 -2.0 到 2.0。生成文本时模型是否应该使用高频词汇。 这里指的是model训练过程中定义的的高频词汇。
给出偏好设置，用于对生成器的输出结果进行修正， 以使生成的文本更加符合特定的条件或偏好。 具体来说，该参数将文本生成器的输出偏向于某些给定的单词或短语， 从而使生成文本更加贴合这些条件。
Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. 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.
1
2
3
4
5
6
7
curl https://API_ENDPOINT/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Hello!"}]
}'1
2
3
4
{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Hello!"}]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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
}
}根据指示 instruction 对 导引语 prompt进行修改。
post https://API_ENDPOINT/v1/edits
根据输入 input 、指示 instruction 和参数 parameters，创建一个新的文本修改。
Request body
temperature，0 到 2之间，用于调整模型生成文本时的创造性程度。 0.8较大，输出的文本更加随机， 0.2较小，输出的文本更加专注、确定。
推荐使用 参数temperature 或者 top_p，但不同时使用。
1
2
3
4
5
6
7
8
curl https://API_ENDPOINT/v1/edits \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "text-davinci-edit-001",
"input": "What day of the wek is it?",
"instruction": "Fix the spelling mistakes"
}'1
2
3
4
5
{
"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
9
10
11
12
13
14
15
{
"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
}
}根据导引词 prompt 生成图片，可以输入图像作为参考。
post https://API_ENDPOINT/v1/images/generations
根据给定的 prompt，创建图片。
Request body
1
2
3
4
5
6
7
8
curl https://API_ENDPOINT/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"prompt": "A cute baby sea otter",
"n": 2,
"size": "1024x1024"
}'1
2
3
4
5
{
"prompt": "A cute baby sea otter",
"n": 2,
"size": "1024x1024"
}1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}post https://API_ENDPOINT/v1/images/edits
根据引导词对给定的图像进行扩展和修正。
Request body
可选的参数，在这张图上，标记原图image的哪些区域用于编辑扩展。
可以使用透明 (e.g. where alpha is zero) 进行标识。
必须是PNG，小于4MB，和原图等大。
1
2
3
4
5
6
7
curl https://API_ENDPOINT/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F image="@otter.png" \
-F mask="@mask.png" \
-F prompt="A cute baby sea otter wearing a beret" \
-F n=2 \
-F size="1024x1024"1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}post https://API_ENDPOINT/v1/images/variations
异化一张图？
Request body
1
2
3
4
5
curl https://API_ENDPOINT/v1/images/variations \
-H "Authorization: Bearer $API_KEY" \
-F image="@otter.png" \
-F n=2 \
-F size="1024x1024"1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}获取输入文本的自然语言向量 vector
post https://API_ENDPOINT/v1/embeddings
获取代表输入字符串的自然语言向量。
1
2
3
4
5
6
7
curl https://API_ENDPOINT/v1/embeddings \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "The food was delicious and the waiter...",
"model": "text-embedding-ada-002"
}'1
2
3
4
{
"model": "text-embedding-ada-002",
"input": "The food was delicious and the waiter..."
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"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
}
}给定输入文本，如果模型将其分类为违反 OpenAI 的内容策略，则输出。
Related guide: Moderations
post https://API_ENDPOINT/v1/moderations
分类文本是否违反 OpenAI 的内容政策
Request body
1
2
3
4
5
6
curl https://API_ENDPOINT/v1/moderations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"input": "I want to kill them."
}'1
2
3
{
"input": "I want to kill them."
}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
{
"id": "modr-5MWoLO",
"model": "text-moderation-001",
"results": [
{
"categories": {
"hate": false,
"hate/threatening": true,
"self-harm": false,
"sexual": false,
"sexual/minors": false,
"violence": true,
"violence/graphic": false
},
"category_scores": {
"hate": 0.22714105248451233,
"hate/threatening": 0.4132447838783264,
"self-harm": 0.005232391878962517,
"sexual": 0.01407341007143259,
"sexual/minors": 0.0038522258400917053,
"violence": 0.9223177433013916,
"violence/graphic": 0.036865197122097015
},
"flagged": true
}
]
}将音频转化为文本
post https://API_ENDPOINT/v1/audio/transcriptions
转换语音成文本，以输入语音的语言为准
Request body
需要转换的音频，支持如下格式: mp3, mp4, mpeg, mpga, m4a, wav, or webm.
模型ID。只支持 whisper-1 。
导引词，需要和原语音相同语种。可以对输出内容细调，比如简体，繁体。
返回格式: json, text, srt, verbose_json, or vtt.
采样 temperature，介于 0 和 1 之间。 较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使输出更加集中和确定。 如果设置为 0，模型将使用对数概率自动升高 temperature，直到达到特定阈值。
输入音频的语言。以 ISO-639-1 格式提供输入语言将提高准确性。
1
2
3
4
5
curl https://API_ENDPOINT/v1/audio/transcriptions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/audio.mp3" \
-F model="whisper-1"1
2
3
4
{
"file": "audio.mp3",
"model": "whisper-1"
}1
2
3
{
"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."
}post https://API_ENDPOINT/v1/audio/translations
语音转换为英语
Request body
支持格式: mp3, mp4, mpeg, mpga, m4a, wav, or webm.
模型ID。只支持 whisper-1 .
导模型的风格或继续之前的音频片段。提示应为英文，英语。
返回格式: json, text, srt, verbose_json, or vtt.
采样 temperature，介于 0 和 1 之间。 较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使输出更加集中和确定。 如果设置为 0，模型将使用对数概率自动升高 temperature，直到达到特定阈值。
1
2
3
4
5
curl https://API_ENDPOINT/v1/audio/translations \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/german.m4a" \
-F model="whisper-1"1
2
3
4
{
"file": "german.m4a",
"model": "whisper-1"
}1
2
3
{
"text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}