ChatGPT API教程
- ChatGPT API教程

创建Chat Completions

Chat Completion对象

请求 URL

bash
POST https://api.openai.com/v1/chat/completions

功能

为给定的聊天对话生成模型的响应。

请求体

`messages` (数组)

必填

一个包含对话内容的消息列表。

示例 Python 代码

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
)

print(completion.choices[0].message)

curl：

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

响应：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0125",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nHello there, how may I assist you today?",
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

消息类型

系统消息

属性

属性名	类型	是否必填	描述
content	string	必填	系统消息的内容。
role	string	必填	消息作者的角色（此处为 `system`）。
name	string	可选	用于区分相同角色的参与者。

用户消息

属性

属性名	类型	是否必填	描述
content	string 或 array	必填	用户消息的内容。
role	string	必填	消息作者的角色（此处为 `user`）。
name	string	可选	用于区分相同角色的参与者。

助手消息

属性

属性名	类型	是否必填	描述
content	string 或 null	可选	助手消息的内容（若未指定 `tool_calls` 或 `function_call` 则必填）。
role	string	必填	消息作者的角色（此处为 `assistant`）。
name	string	可选	用于区分相同角色的参与者。
tool_calls	array	可选	模型生成的工具调用，例如函数调用。

工具消息

属性

属性名	类型	是否必填	描述
role	string	必填	消息作者的角色（此处为 `tool`）。
content	string	必填	工具消息的内容。
tool_call_id	string	必填	工具调用的响应。

函数消息（已弃用）

属性

属性名	类型	是否必填	描述
role	string	必填	消息作者的角色（此处为 `function`）。
content	string 或 null	必填	函数消息的内容。
name	string	必填	要调用的函数名称。

其他参数

`model` (string)

必填

使用的模型的 ID，也就是模型名。例如：gpt-4o

`frequency_penalty` (number 或 null)

可选

默认值：0

用于控制模型重复现有文本的概率，值的范围为 -2.0 到 2.0。正值会减少模型逐字重复的可能性。

`logit_bias` (map)

可选

默认值：null

修改特定标记出现的可能性。接受一个 JSON 对象，将标记（由标记器中的标记 ID 指定）映射到与之关联的偏差值，范围为 -100 到 100。负值减少选择的可能性，正值增加选择的可能性。

`logprobs` (boolean 或 null)

可选

默认值：false

是否返回输出标记的日志概率。若为 true，将返回内容中每个输出标记的日志概率。

`top_logprobs` (integer 或 null)

可选

一个介于 0 到 20 之间的整数，指定在每个标记位置返回的最可能标记的数量，每个标记都有一个关联的日志概率。需设置 logprobs 为 true 才能使用此参数。

`max_tokens` (integer 或 null)

可选

最大生成标记数。

输入标记和生成标记的总长度受模型的上下文长度限制。计数标记的示例 Python 代码。

`n` (integer 或 null)

可选

默认值：1

为每条输入消息生成的聊天完成选项数量。注意，你将按生成的标记数收费。将 n 设置为 1 以最小化成本。

`presence_penalty` (number 或 null)

可选

默认值：0

用于控制模型谈论新主题的可能性，值的范围为 -2.0 到 2.0。正值会增加模型谈论新主题的可能性。

`response_format` (object)

可选

指定模型必须输出的格式。兼容 GPT-4 Turbo 和所有更新版本的 GPT-3.5 Turbo 模型。

设置 { "type": "json_object" } 启用 JSON 模式，确保模型生成有效的 JSON。

重要：使用 JSON 模式时，必须通过系统或用户消息指示模型生成 JSON。否则，模型可能会生成大量空白，直到达到令牌限制，导致请求长时间运行。还要注意，如果 finish_reason="length" 表示生成超过 max_tokens 或对话超过最大上下文长度，消息内容可能会部分被截断。

`seed` (integer 或 null)

可选

此功能为 Beta 版。如果指定了 seed，系统将尽力确定性采样，使得相同参数和种子下的请求返回相同的结果。确定性不保证，你应监控 system_fingerprint 响应参数以检测后端更改。

`service_tier` (string 或 null)

可选

默认值：null

指定用于处理请求的延迟级别。适用于订阅规模服务的客户：

auto：系统将使用规模服务积分，直到耗尽。
default：请求将使用默认服务级别处理，无高 SLA 和无延迟保证。设置此参数时，响应主体将包含所用的服务级别。

`stop` (string / array / null)

可选

默认值：null

最多 4 个序列，API 在生成这些序列时将停止生成更多标记。

`stream` (boolean 或 null)

可选

默认值：false

流式输出开关。如果设置，部分消息增量将作为数据发送，类似于 ChatGPT。标记将作为数据事件发送，直到终止标记 data: [DONE] 消息。例如 Python 代码。

`stream_options` (object 或 null)

可选

默认值：null

用于流响应的选项，仅在设置 stream: true 时设置。

`include_usage` (boolean)

可选

如果设置，在 data: [DONE] 消息前将发送一个额外的数据块。使用字段将显示整个请求的标记使用情况，并且 choices 字段始终为空数组。所有其他块也将包含使用字段，但值为 null。

`temperature` (number 或 null)

可选

默认值：1

用于控制生成内容的随机性，范围为 0 到 2。较高的值（如 0.8）生成更随机的内容，较低的值（如 0.2）生成更聚焦的内容。

通常建议调整 temperature 或 top_p，但不要同时调整两者。

`top_p` (number 或 null)

可选

默认值：1

使用核采样作为 temperature 的替代方法，模型考虑概率质量最高的标记结果。例如 0.1 表示仅考虑概率质量最高的前 10% 标记。

通常建议调整 temperature 或 top_p，但不要同时调整两者。

`tools` (array)

可选

模型可以调用的工具列表。目前只支持函数作为工具。最多支持 128 个函数。

属性

属性名	类型	是否必填	描述
type	string	必填	工具的类型。目前只支持 `function`。
function	object	必填	工具调用的函数。

`function_call` (已弃用) (string 或 object)

可选

已弃用，改用 tools。

控制是否调用函数。none 表示模型不会调用任何函数，而是生成消息。auto 表示模型可以在生成消息和调用函数之间进行选择。通过 {"name": "my_function"} 指定特定函数可强制模型调用该函数。

`functions` (已弃用) (array)

可选

已弃用，改用 tools。

模型可能生成 JSON 输入的函数列表。

属性

属性名	类型	是否必填	描述
description	string	可选	函数的描述，用于模型选择何时和如何调用函数。
name	string	必填	要调用的函数名称。必须是 a-z, A-Z, 0-9 或包含下划线和短划线，长度最大为 `64`。
parameters	object	可选	函数接受的参数，描述为 JSON Schema 对象。

返回值

返回聊天完成对象，或如果请求流式传输，则返回流式聊天完成块对象序列。

更多示例：

1、输入图片：

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
                },
            ],
        }
    ],
    max_tokens=300,
)

print(response.choices[0])

响应：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0125",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nThis image shows a wooden boardwalk extending through a lush green marshland.",
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

2、流式输出（Streaming）：

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  stream=True
)

for chunk in completion:
  print(chunk.choices[0].delta)

响应：

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0125", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0125", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]}

....

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0125", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

3、函数调用（Functions）:

from openai import OpenAI
client = OpenAI()

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA",
          },
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
      },
    }
  }
]
messages = [{"role": "user", "content": "What's the weather like in Boston today?"}]
completion = client.chat.completions.create(
  model="gpt-4o",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

print(completion)

响应：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-3.5-turbo-0125",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n\"location\": \"Boston, MA\"\n}"
            }
          }
        ]
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99
  }
}

4、Logprobs（日志概率）

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "user", "content": "Hello!"}
  ],
  logprobs=True,
  top_logprobs=2
)

print(completion.choices[0].message)
print(completion.choices[0].logprobs)

响应：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1702685778,
  "model": "gpt-3.5-turbo-0125",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?"
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              },
              {
                "token": "Hi",
                "logprob": -1.3190403,
                "bytes": [72, 105]
              }
            ]
          },
          {
            "token": "!",
            "logprob": -0.02380986,
            "bytes": [
              33
            ],
            "top_logprobs": [
              {
                "token": "!",
                "logprob": -0.02380986,
                "bytes": [33]
              },
              {
                "token": " there",
                "logprob": -3.787621,
                "bytes": [32, 116, 104, 101, 114, 101]
              }
            ]
          },
          {
            "token": " How",
            "logprob": -0.000054669687,
            "bytes": [32, 72, 111, 119],
            "top_logprobs": [
              {
                "token": " How",
                "logprob": -0.000054669687,
                "bytes": [32, 72, 111, 119]
              },
              {
                "token": "<|end|>",
                "logprob": -10.953937,
                "bytes": null
              }
            ]
          },
          {
            "token": " can",
            "logprob": -0.015801601,
            "bytes": [32, 99, 97, 110],
            "top_logprobs": [
              {
                "token": " can",
                "logprob": -0.015801601,
                "bytes": [32, 99, 97, 110]
              },
              {
                "token": " may",
                "logprob": -4.161023,
                "bytes": [32, 109, 97, 121]
              }
            ]
          },
          {
            "token": " I",
            "logprob": -3.7697225e-6,
            "bytes": [
              32,
              73
            ],
            "top_logprobs": [
              {
                "token": " I",
                "logprob": -3.7697225e-6,
                "bytes": [32, 73]
              },
              {
                "token": " assist",
                "logprob": -13.596657,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              }
            ]
          },
          {
            "token": " assist",
            "logprob": -0.04571125,
            "bytes": [32, 97, 115, 115, 105, 115, 116],
            "top_logprobs": [
              {
                "token": " assist",
                "logprob": -0.04571125,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              },
              {
                "token": " help",
                "logprob": -3.1089056,
                "bytes": [32, 104, 101, 108, 112]
              }
            ]
          },
          {
            "token": " you",
            "logprob": -5.4385737e-6,
            "bytes": [32, 121, 111, 117],
            "top_logprobs": [
              {
                "token": " you",
                "logprob": -5.4385737e-6,
                "bytes": [32, 121, 111, 117]
              },
              {
                "token": " today",
                "logprob": -12.807695,
                "bytes": [32, 116, 111, 100, 97, 121]
              }
            ]
          },
          {
            "token": " today",
            "logprob": -0.0040071653,
            "bytes": [32, 116, 111, 100, 97, 121],
            "top_logprobs": [
              {
                "token": " today",
                "logprob": -0.0040071653,
                "bytes": [32, 116, 111, 100, 97, 121]
              },
              {
                "token": "?",
                "logprob": -5.5247097,
                "bytes": [63]
              }
            ]
          },
          {
            "token": "?",
            "logprob": -0.0008108172,
            "bytes": [63],
            "top_logprobs": [
              {
                "token": "?",
                "logprob": -0.0008108172,
                "bytes": [63]
              },
              {
                "token": "?\n",
                "logprob": -7.184561,
                "bytes": [63, 10]
              }
            ]
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 9,
    "total_tokens": 18
  },
  "system_fingerprint": null
}

Chat Completion对象

ChatGPT API教程 Chat API参考 端点 --Chat 创建Chat Completions Chat Completion对象 Chat Completion块对象

创建Chat Completions

请求 URL

功能

请求体

messages (数组)

必填

示例 Python 代码

消息类型

系统消息

属性

用户消息

属性

助手消息

属性

工具消息

属性

函数消息（已弃用）

属性

其他参数

model (string)

必填

frequency_penalty (number 或 null)

可选

logit_bias (map)

可选

logprobs (boolean 或 null)

可选

top_logprobs (integer 或 null)

可选

max_tokens (integer 或 null)

可选

n (integer 或 null)

可选

presence_penalty (number 或 null)

可选

response_format (object)

可选

seed (integer 或 null)

可选

service_tier (string 或 null)

可选

stop (string / array / null)

可选

stream (boolean 或 null)

可选

stream_options (object 或 null)

可选

include_usage (boolean)

可选

temperature (number 或 null)

可选

top_p (number 或 null)

可选

tools (array)

可选

属性

function_call (已弃用) (string 或 object)

可选

functions (已弃用) (array)

可选

属性

返回值

ChatGPT API教程 Chat API参考 端点 --Chat 创建Chat Completions Chat Completion对象 Chat Completion块对象

ChatGPT API教程

API参考

端点

--Chat

创建Chat Completions

Chat Completion对象

Chat Completion块对象

`messages` (数组)

`model` (string)

`frequency_penalty` (number 或 null)

`logit_bias` (map)

`logprobs` (boolean 或 null)

`top_logprobs` (integer 或 null)

`max_tokens` (integer 或 null)

`n` (integer 或 null)

`presence_penalty` (number 或 null)

`response_format` (object)

`seed` (integer 或 null)

`service_tier` (string 或 null)

`stop` (string / array / null)

`stream` (boolean 或 null)

`stream_options` (object 或 null)

`include_usage` (boolean)

`temperature` (number 或 null)

`top_p` (number 或 null)

`tools` (array)

`function_call` (已弃用) (string 或 object)

`functions` (已弃用) (array)

ChatGPT API教程

API参考

端点

--Chat

创建Chat Completions

Chat Completion对象

Chat Completion块对象