-- ChatGPT开发文档|ChatGPT教程|ChatGPT官方文档|ChatGPT API参考文档

介绍

您可以通过来自任何语言的 HTTP 请求、通过我们的官方 Python 绑定、我们的官方 Node.js 库或社区维护的库与 API 进行交互。

要安装官方 Python 绑定，请运行以下命令：

pip install openai

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

npm install openai

认证

API 密钥

OpenAI API 使用 API 密钥进行身份验证。您可以在用户或服务账户级别创建 API 密钥。服务帐户与“机器人”个人相关联，应该用于为生产系统提供访问权限。每个 API 密钥的范围都可以限定为以下选项之一：

项目密钥 - 提供对单个项目的访问权限（首选选项）;通过选择要为其生成密钥的特定项目来访问项目 API 密钥。
User keys （用户密钥） - 我们的旧密钥。提供对用户已添加到的所有组织和所有项目的访问权;访问 API 密钥以查看您的可用密钥。我们强烈建议您过渡到项目密钥以获得最佳安全实践，尽管目前仍支持通过此方法进行访问。

请记住，您的 API 密钥是秘密！请勿与他人共享或在任何客户端代码（浏览器、应用程序）中公开它。生产请求必须通过您自己的后端服务器进行路由，在该服务器中，您的 API 密钥可以从环境变量或密钥管理服务安全地加载。

所有 API 请求都应在 HTTP 标头中包含您的 API 密钥，如下所示：Authorization

Authorization: Bearer OPENAI_API_KEY

组织和项目（可选）

对于属于多个组织或通过其旧版用户 API 密钥访问其项目的用户，您可以传递标头以指定用于 API 请求的组织和项目。这些 API 请求的使用量将计为指定组织和项目的使用量。

要在组织中访问，请省略标题Default projectOpenAI-Project

curl 命令示例：

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

Python 包的示例：openai

1
2
3
4
5
6
from openai import OpenAI

client = OpenAI(
  organization='YOUR_ORG_ID',
  project='$PROJECT_ID',
)

Node.js 包的示例：openai

1
2
3
4
5
6
import OpenAI from "openai";

const openai = new OpenAI({
    organization: "YOUR_ORG_ID",
    project: "$PROJECT_ID",
});

可以在组织设置页面上找到组织 ID。通过选择特定项目，可以在 General settings （常规设置）页面上找到项目 ID。

提出请求

您可以将以下命令粘贴到您的终端中，以运行您的第一个 API 请求。请确保替换为您的秘密 API 密钥。如果您使用的是旧版用户密钥并且有多个项目，则还需要指定 Project ID。为了提高安全性，我们建议改用基于项目的密钥。$OPENAI_API_KEY

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

此请求查询模型（在后台指向 gpt-4o-mini 模型变体）以完成以提示“Say this is a test”开头的文本。您应该会收到类似于以下内容的响应：gpt-4o-mini

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": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677858242,
    "model": "gpt-4o-mini",
    "usage": {
        "prompt_tokens": 13,
        "completion_tokens": 7,
        "total_tokens": 20,
        "completion_tokens_details": {
            "reasoning_tokens": 0,
            "accepted_prediction_tokens": 0,
            "rejected_prediction_tokens": 0
        }
    },
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "\n\nThis is a test!"
            },
            "logprobs": null,
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

现在，您已经生成了第一个聊天完成，让我们分解响应对象。我们可以看到 is，这意味着 API 返回了模型生成的完整聊天完成，而不会遇到任何限制。在选项列表中，我们只生成了一条消息，但您可以设置参数以生成多个消息选项。finish_reasonstopn

流

OpenAI API 提供了将响应流式传输回客户端的功能，以便允许某些请求获得部分结果。为此，我们遵循 Server-sent events 标准。我们的官方 Node 和 Python 库包含帮助程序，以简化解析这些事件。

聊天完成 API 和 Assistants API 都支持流式处理。本节重点介绍流式处理如何用于 Chat Completions。在此处详细了解 Assistants API 中的流式处理工作原理。

在 Python 中，流式处理请求如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say this is a test"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

在 Node / Typescript 中，流式处理请求如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
    const stream = await openai.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [{ role: "user", content: "Say this is a test" }],
        stream: true,
    });
    for await (const chunk of stream) {
        process.stdout.write(chunk.choices[0]?.delta?.content || "");
    }
}

main();

解析 Server 发送的事件

解析 Server 发送的事件并非易事，应谨慎进行。简单的策略（如按新行拆分）可能会导致解析错误。我们建议尽可能使用现有的客户端库。

调试请求

除了 API 响应返回的错误代码外，有时可能还需要检查 HTTP 响应标头。特别值得一提的是包含特定 API 请求的唯一 ID 的标头，以及应用于请求的速率限制信息。以下是随 API 响应返回的 HTTP 标头的不完整列表：

API 元信息

openai-organization：与请求关联的组织
openai-processing-ms：处理 API 请求所花费的时间
openai-version：用于此请求的 REST API 版本（当前2020-10-01)
x-request-id：此 API 请求的唯一标识符（用于故障排除）

速率限制信息

x-ratelimit-limit-requests
x-ratelimit-limit-tokens
x-ratelimit-remaining-requests
x-ratelimit-remaining-tokens
x-ratelimit-reset-requests
x-ratelimit-reset-tokens

OpenAI 建议在生产部署中记录请求 ID，这将在需要时与我们的支持团队一起更有效地进行故障排除。我们的官方 SDK 在顶级响应对象上提供了一个属性，其中包含 header 的值。x-request-id

Python 中的请求 ID

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    messages=[{
        "role": "user",
        "content": "Say this is a test",
    }],
    model="gpt-4o-mini",
)

print(response._request_id)

JavaScript 中的请求 ID

1
2
3
4
5
6
7
8
9
import OpenAI from 'openai';
const client = new OpenAI();

const response = await client.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-4o-mini'
});

console.log(response._request_id);

在 SDK 中访问原始响应对象

如果您使用的是较低级别的 HTTP 客户端（如 C# 中的 fetch 或 HttpClient），则应该已经可以访问作为 HTTP 接口一部分的响应标头。

如果您使用的是 OpenAI 的官方 SDK 之一（在很大程度上抽象了 HTTP 请求/响应周期），您将需要以略有不同的方式访问原始 HTTP 响应。

以下是使用我们的 Python SDK 访问原始响应对象（和标头）的示例。x-ratelimit-limit-tokens

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.with_raw_response.create(
    messages=[{
        "role": "user",
        "content": "Say this is a test",
    }],
    model="gpt-4o-mini",
)
print(response.headers.get('x-ratelimit-limit-tokens'))

# get the object that `chat.completions.create()` would have returned
completion = response.parse()
print(completion)

以下是使用我们的 JavaScript SDK 访问原始响应（和标头）的方法。x-ratelimit-limit-tokens

1
2
3
4
5
6
7
8
9
10
import OpenAI from 'openai';
const client = new OpenAI();

const response = await client.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-4o-mini'
}).asResponse();

// access the underlying Response object
console.log(response.headers.get('x-ratelimit-limit-tokens'));

向后兼容性

OpenAI 致力于通过尽可能避免主要 API 版本中的中断性变更来为 API 用户提供稳定性。这包括：

REST API（当前v1)
我们的第一方 SDK（已发布的 SDK 将遵循语义版本控制)
模型族（如或gpt-4oo1-mini)

随着时间的推移，将持续提供向后兼容的更改和升级。这些和任何罕见的重大更改都将在更改日志中传达。以下是一些我们认为是向后兼容（非中断性）更改的更改示例。

快照之间模型提示行为的更改

模型输出本质上是变量，因此快照之间的提示和模型行为应该会发生变化。例如，如果从移动到，则相同或消息在版本之间的功能可能不同。确保一致的提示行为和模型输出的最佳方法是使用固定的模型版本，并为您的应用程序实现 eval。gpt-4o-2024-05-13gpt-4o-2024-08-06systemuser

向后兼容的 API 更改

向 REST API 和 SDK 添加新资源（URL）
添加新的可选 API 参数
向 JSON 响应对象或事件数据添加新属性
更改 JSON 响应对象中的属性顺序
更改不透明字符串（如资源标识符和 UUID）的长度或格式
添加新的事件类型（在流式处理或 Realtime API 中）

音频

了解如何将音频转换为文本或将文本转换为音频。

创建语音

帖子 https://api.openai.com/v1/audio/speech

从输入文本生成音频。

请求正文

MODEL

字符串

必填

可用的 TTS 型号之一：或tts-1tts-1-hd

输入

字符串

必填

要为其生成音频的文本。最大长度为 4096 个字符。

声音

字符串

必填

生成音频时使用的语音。支持的语音包括、和。语音预览可在文本到语音转换指南中找到。alloyechofableonyxnovashimmer

response_format

字符串

自选

默认为 mp3

音频格式。支持的格式包括、、、、和。mp3opusaacflacwavpcm

速度

数

自选

默认为 1

生成的音频的速度。从 to 中选择一个值。是默认值。0.254.01.0

音频文件内容。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/audio/speech \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy"
  }' \
  --output speech.mp3

1
2
3
4
5
6
7
8
9
10
from pathlib import Path
import openai

speech_file_path = Path(__file__).parent / "speech.mp3"
response = openai.audio.speech.create(
  model="tts-1",
  voice="alloy",
  input="The quick brown fox jumped over the lazy dog."
)
response.stream_to_file(speech_file_path)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import fs from "fs";
import path from "path";
import OpenAI from "openai";

const openai = new OpenAI();

const speechFile = path.resolve("./speech.mp3");

async function main() {
  const mp3 = await openai.audio.speech.create({
    model: "tts-1",
    voice: "alloy",
    input: "Today is a wonderful day to build something people love!",
  });
  console.log(speechFile);
  const buffer = Buffer.from(await mp3.arrayBuffer());
  await fs.promises.writeFile(speechFile, buffer);
}
main();

创建转录

帖子 https://api.openai.com/v1/audio/transcriptions

将音频转录为输入语言。

请求正文

文件

必填

要转录的音频文件对象（不是文件名），采用以下格式之一：flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。

MODEL

字符串

必填

要使用的模型的 ID。目前仅（由我们的开源 Whisper V2 模型提供支持）可用。whisper-1

语言

字符串

自选

输入音频的语言。以 ISO-639-1 格式提供输入语言将提高准确性和延迟时间。

提示

字符串

自选

一个可选文本，用于引导模型的样式或继续上一个音频片段。提示应与音频语言匹配。

response_format

字符串

自选

默认为 json

输出的格式，位于以下选项之一中：、或。jsontextsrtverbose_jsonvtt

温度

数

自选

默认为 0

采样温度，介于 0 和 1 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。如果设置为 0，则模型将使用对数概率自动增加温度，直到达到某些阈值。

timestamp_granularities

数组

自选

默认为 segment

要为此转录填充的时间戳粒度。必须设置为使用时间戳粒度。支持以下任一或两个选项：、或。注意：段时间戳没有额外的延迟，但生成单词时间戳会产生额外的延迟。response_formatverbose_jsonwordsegment

transcription 对象或详细的 transcription 对象。

示例请求

1
2
3
4
5
curl https://api.openai.com/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
5
6
7
8
from openai import OpenAI
client = OpenAI()

audio_file = open("speech.mp3", "rb")
transcript = client.audio.transcriptions.create(
  model="whisper-1",
  file=audio_file
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const transcription = await openai.audio.transcriptions.create({
    file: fs.createReadStream("audio.mp3"),
    model: "whisper-1",
  });

  console.log(transcription.text);
}
main();

响应

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."
}

创建翻译

帖子 https://api.openai.com/v1/audio/translations

将音频翻译成英文。

请求正文

文件

必填

音频文件对象（不是文件名）将翻译为以下格式之一：flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。

MODEL

字符串

必填

要使用的模型的 ID。目前仅（由我们的开源 Whisper V2 模型提供支持）可用。whisper-1

提示

字符串

自选

一个可选文本，用于引导模型的样式或继续上一个音频片段。提示应为英文。

response_format

字符串

自选

默认为 json

输出的格式，位于以下选项之一中：、或。jsontextsrtverbose_jsonvtt

温度

数

自选

默认为 0

翻译后的文本。

示例请求

1
2
3
4
5
curl https://api.openai.com/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
5
6
7
8
from openai import OpenAI
client = OpenAI()

audio_file = open("speech.mp3", "rb")
transcript = client.audio.translations.create(
  model="whisper-1",
  file=audio_file
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
    const translation = await openai.audio.translations.create({
        file: fs.createReadStream("speech.mp3"),
        model: "whisper-1",
    });

    console.log(translation.text);
}
main();

响应

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

转录对象（JSON）

表示 model 根据提供的输入返回的转录响应。

发短信

字符串

转录的文本。

OBJECT 转录对象（JSON）

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."
}

转录对象（Verbose JSON）

表示模型根据提供的输入返回的详细 json 转录响应。

语言

字符串

输入音频的语言。

期间

字符串

输入音频的持续时间。

发短信

字符串

转录的文本。

的话

数组

提取的单词及其相应的时间戳。

段

数组

转录文本的片段及其相应的详细信息。

OBJECT 转录对象（Verbose JSON）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "task": "transcribe",
  "language": "english",
  "duration": 8.470000267028809,
  "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 3.319999933242798,
      "text": " The beach was a popular spot on a hot summer day.",
      "tokens": [
        50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530
      ],
      "temperature": 0.0,
      "avg_logprob": -0.2860786020755768,
      "compression_ratio": 1.2363636493682861,
      "no_speech_prob": 0.00985979475080967
    },
    ...
  ]
}

聊天

给定一个包含对话的消息列表，该模型将返回一个响应。相关指南：聊天完成

创建聊天完成

帖子 https://api.openai.com/v1/chat/completions

为给定的聊天对话创建模型响应。在文本生成、愿景、和语音导览。

请求正文

消息

数组

必填

到目前为止，包含对话的消息列表。根据你使用的模型，不同的消息类型（模态）是支持，如文本、图像和音频。

MODEL

字符串

必填

要使用的模型的 ID。有关哪些模型可与 Chat API 配合使用的详细信息，请参阅模型端点兼容性表。

商店

boolean 或 null

自选

默认为 false

是否存储此聊天完成请求的输出用于我们的 Model Distillation 或 EVALS 产品。

元数据

object 或 null

自选

用于筛选补全的开发人员定义的标记和值在仪表板中。

frequency_penalty

number 或 null

自选

默认为 0

介于 -2.0 和 2.0 之间的数字。正值会根据新标记到目前为止在文本中的现有频率来惩罚新标记，从而降低模型逐字重复同一行的可能性。

请参阅有关频率和存在处罚的更多信息。

logit_bias

地图

自选

默认为 null

修改指定标记出现在补全中的可能性。

接受一个 JSON 对象，该对象将令牌（由其在 tokenizer 中的令牌 ID 指定）映射到从 -100 到 100 的关联偏差值。从数学上讲，偏差在采样之前被添加到模型生成的 logit 中。确切的效果因模型而异，但 -1 和 1 之间的值应降低或增加选择的可能性;像 -100 或 100 这样的值应该导致禁止或独占选择相关令牌。

对数问题

boolean 或 null

自选

默认为 false

是否返回输出 Token 的对数概率。如果为 true，则返回 of 中返回的每个输出标记的对数概率。contentmessage

top_logprobs

整数或 null

自选

一个介于 0 和 20 之间的整数，指定在每个标记位置最有可能返回的标记数，每个标记都有一个关联的对数概率。如果使用此参数，则必须设置为。logprobstrue

max_tokens

已废弃

整数或 null

自选

聊天补全中可以生成的令牌的最大数量。此值可用于控制通过 API 生成的文本的成本。

此值现已弃用，取而代之的是，并且与 o1 系列模型不兼容。max_completion_tokens

max_completion_tokens

整数或 null

自选

可以为完成生成的标记数的上限，包括可见的输出标记和推理标记。

整数或 null

自选

默认为 1

为每个输入消息生成多少个聊天完成选项。请注意，您将根据所有选项中生成的令牌数量付费。Keep as 以最大限度地降低成本。n1

方式

array 或 null

自选

您希望模型为此请求生成的 Output types。大多数模型都能够生成文本，这是默认设置：

["text"]

该模型还可用于生成音频。自请求此模型同时生成文本和音频响应，您可以用：gpt-4o-audio-preview

["text", "audio"]

预测

对象

自选

预测输出的配置这可以大大缩短模型大部分响应是提前知道的。当您重新生成一个文件，仅对大部分内容进行细微更改。

音频

object 或 null

自选

音频输出参数。使用请求音频输出时是必需的。了解更多。modalities: ["audio"]

presence_penalty

number 或 null

自选

默认为 0

介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止是否出现在文本中来惩罚新标记，从而增加模型讨论新主题的可能性。

请参阅有关频率和存在处罚的更多信息。

response_format

对象

自选

一个对象，用于指定模型必须输出的格式。兼容 GPT-4o、GPT-4o mini、GPT-4 Turbo 和所有比 .gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

重要提示：使用 JSON 模式时，还必须通过系统或用户消息指示模型自行生成 JSON。否则，模型可能会生成无休止的空格流，直到生成达到令牌限制，从而导致长时间运行且似乎“卡住”的请求。另请注意，如果，则消息内容可能会被部分截断，这表示超出生成或对话超过最大上下文长度。finish_reason="length"max_tokens

种子

整数或 null

自选

此功能处于 Beta 阶段。如果指定，我们的系统将尽最大努力确定性地采样，这样具有相同 and 参数的重复请求应该返回相同的结果。无法保证确定性，您应该参考 response 参数来监控后端的变化。seedsystem_fingerprint

service_tier

string 或 null

自选

默认为 auto

指定用于处理请求的延迟层。此参数与订阅了 Scale Tier 服务的客户相关：

如果设置为 'auto'，并且项目启用了 Scale tier，则系统将使用 Scale Tier 积分，直到它们用完。
如果设置为“auto”，并且项目未启用扩展层，则将使用正常运行时间 SLA 较低且无延迟保证的默认服务层级处理请求。
如果设置为“default”，则将使用正常运行时间 SLA 较低且无延迟保证的默认服务层级处理请求。
如果未设置，则默认行为为 'auto'。

设置此参数后，响应正文将包含 used.service_tier

停

字符串 / 数组 / 空

自选

默认为 null

最多 4 个序列，API 将在其中停止生成更多令牌。

流

boolean 或 null

自选

默认为 false

如果设置，将发送部分消息增量，就像在 ChatGPT 中一样。令牌将在可用时作为仅限数据、服务器发送的事件发送，流由消息终止。Python 代码示例。data: [DONE]

stream_options

object 或 null

自选

默认为 null

流式处理响应的选项。仅在设置时设置此项。stream: true

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

我们通常建议更改此项或同时更改两者。top_p

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此项或同时更改两者。temperature

工具

数组

自选

模型可以调用的工具列表。目前，仅支持将函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。最多支持 128 个函数。

tool_choice

字符串或对象

自选

控制模型调用哪个（如果有）工具。表示模型不会调用任何工具，而是生成一条消息。表示模型可以在生成消息或调用一个或多个工具之间进行选择。表示模型必须调用一个或多个工具。指定特定工具的 via 会强制模型调用该工具。noneautorequired{"type": "function", "function": {"name": "my_function"}}

none是不存在工具时的默认值。如果存在工具，则为默认值。auto

parallel_tool_calls

布尔

自选

默认为 true

是否在工具使用过程中启用并行函数调用。

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

function_call

已废弃

字符串或对象

自选

已弃用，取而代之的是 .tool_choice

控制模型调用哪个（如果有）函数。表示模型不会调用函数，而是生成一条消息。表示模型可以在生成消息或调用函数之间进行选择。指定特定函数 via 会强制模型调用该函数。noneauto{"name": "my_function"}

none是不存在函数时的默认值。如果存在函数，则为默认值。auto

功能

已废弃

数组

自选

已弃用，取而代之的是 .tools

模型可以为其生成 JSON 输入的函数列表。

返回聊天完成对象，如果请求是流式的，则返回聊天完成区块对象的流式序列。

示例请求

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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!"
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const completion = await openai.chat.completions.create({
    messages: [{ role: "system", content: "You are a helpful assistant." }],
    model: "gpt-4o",
  });

  console.log(completion.choices[0]);
}

main();

响应

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
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "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,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

聊天完成对象

表示 model 根据提供的输入返回的聊天完成响应。

身份证

字符串

聊天完成的唯一标识符。

选择

数组

聊天完成选项的列表。如果大于 1，则可以多个。n

创建

整数

创建聊天完成时的 Unix 时间戳（以秒为单位）。

MODEL

字符串

用于聊天完成的模型。

service_tier

string 或 null

用于处理请求的服务层。仅当在请求中指定了参数时，才会包含此字段。service_tier

system_fingerprint

字符串

此指纹表示模型运行时使用的后端配置。

可以与 request 参数结合使用，以了解何时进行了可能影响确定性的后端更改。seed

对象

字符串

对象类型，始终为 .chat.completion

用法

对象

完成请求的使用情况统计信息。

OBJECT 聊天完成对象

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
{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1728933352,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi there! How can I assist you today?",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_6b68a8204b"
}

聊天完成区块对象

表示模型根据提供的输入返回的聊天完成响应的流式块。

身份证

字符串

聊天完成的唯一标识符。每个块具有相同的 ID。

选择

数组

聊天完成选项的列表。如果大于 1，则可以包含多个元素。也可以为空，因为 last chunk （如果将 .nstream_options: {"include_usage": true}

创建

整数

创建聊天完成时的 Unix 时间戳（以秒为单位）。每个块具有相同的时间戳。

MODEL

字符串

用于生成完成项的模型。

service_tier

string 或 null

用于处理请求的服务层。仅当在请求中指定了参数时，才会包含此字段。service_tier

system_fingerprint

字符串

此指纹表示模型运行时使用的后端配置。可以与 request 参数结合使用，以了解何时进行了可能影响确定性的后端更改。seed

对象

字符串

对象类型，始终为 .chat.completion.chunk

用法

object 或 null

一个可选字段，仅在您在请求中设置时显示。如果存在，则它包含一个 null 值，但最后一个块除外，该块包含整个请求的令牌使用情况统计信息。stream_options: {"include_usage": true}

OBJECT 聊天完成区块对象

1
2
3
4
5
6
7
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "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-4o-mini", "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-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

Embeddings

获取给定输入的向量表示形式，机器学习模型和算法可以轻松使用该向量表示形式。相关指南：Embeddings

创建嵌入

帖子 https://api.openai.com/v1/embeddings

创建表示输入文本的嵌入向量。

请求正文

输入

字符串或数组

必填

输入要嵌入的文本，编码为字符串或标记数组。若要在单个请求中嵌入多个输入，请传递字符串数组或令牌数组数组。输入不得超过模型的最大输入标记数（8192 个标记），不能为空字符串，并且任何数组的维数不得超过 2048 个。用于对令牌进行计数的 Python 代码示例。text-embedding-ada-002

MODEL

字符串

必填

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。

encoding_format

字符串

自选

默认为 float

要返回嵌入向量的格式。可以是 either 或 base64。float

尺寸

整数

自选

生成的输出嵌入应具有的维度数。仅在及更高版本的型号中受支持。text-embedding-3

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

Embeddings对象的列表。

示例请求

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-ada-002",
    "encoding_format": "float"
  }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

client.embeddings.create(
  model="text-embedding-ada-002",
  input="The food was delicious and the waiter...",
  encoding_format="float"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const embedding = await openai.embeddings.create({
    model: "text-embedding-ada-002",
    input: "The quick brown fox jumped over the lazy dog",
    encoding_format: "float",
  });

  console.log(embedding);
}

main();

响应

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
  }
}

嵌入对象

表示 embedding endpoint 返回的嵌入向量。

指数

整数

嵌入列表中嵌入的索引。

Embeddings

数组

嵌入向量，它是一个浮点数列表。向量的长度取决于嵌入指南中列出的模型。

对象

字符串

对象类型，始终为 “embedding”。

OBJECT 嵌入对象

1
2
3
4
5
6
7
8
9
10
{
  "object": "embedding",
  "embedding": [
    0.0023064255,
    -0.009327292,
    .... (1536 floats total for ada-002)
    -0.0028842222,
  ],
  "index": 0
}

微调

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

创建微调作业

帖子 https://api.openai.com/v1/fine_tuning/jobs

创建一个微调作业，该作业开始从给定数据集创建新模型的过程。

响应包括已排队作业的详细信息，包括作业状态和完成后微调模型的名称。

了解有关微调的更多信息

请求正文

MODEL

字符串

必填

要微调的模型的名称。您可以选择其中一个受支持的模型。

training_file

字符串

必填

包含训练数据的已上传文件的 ID。

有关如何上传文件的信息，请参阅上传文件。

您的数据集必须格式化为 JSONL 文件。此外，您必须上传具有 .fine-tune

文件的内容应有所不同，具体取决于模型是使用 chat 还是 completions 格式。

有关更多详细信息，请参阅微调指南。

超参数

对象

自选

用于微调作业的超参数。

后缀

string 或 null

自选

默认为 null

一个最多 64 个字符的字符串，将添加到您的微调模型名称中。

例如，“custom-model-name” 的 a 将生成类似于的模型名称。suffixft:gpt-4o-mini:openai:custom-model-name:7p4lURel

validation_file

string 或 null

自选

包含验证数据的已上传文件的 ID。

如果您提供此文件，则数据将用于生成验证指标。这些指标可以在微调结果文件。训练文件和验证文件中不应存在相同的数据。

您的数据集必须格式化为 JSONL 文件。您必须上传具有目的的文件。fine-tune

有关更多详细信息，请参阅微调指南。

集成

array 或 null

自选

要为微调作业启用的集成列表。

种子

整数或 null

自选

种子控制作业的可重复性。传入相同的 seed 和 job 参数应该会产生相同的结果，但在极少数情况下可能会有所不同。如果未指定种子，将为您生成一个种子。

一个 fine-tuning.job 对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/fine_tuning/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo",
    "model": "gpt-4o-mini"
  }'

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

client.fine_tuning.jobs.create(
  training_file="file-abc123",
  model="gpt-4o-mini"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const fineTune = await openai.fineTuning.jobs.create({
    training_file: "file-abc123"
  });

  console.log(fineTune);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
{
  "object": "fine_tuning.job",
  "id": "ftjob-abc123",
  "model": "gpt-4o-mini-2024-07-18",
  "created_at": 1721764800,
  "fine_tuned_model": null,
  "organization_id": "org-123",
  "result_files": [],
  "status": "queued",
  "validation_file": null,
  "training_file": "file-abc123",
}

列出微调作业

获取 https://api.openai.com/v1/fine_tuning/jobs

列出组织的微调作业

查询参数

后

字符串

自选

上一个分页请求中最后一个作业的标识符。

限制

整数

自选

默认为 20

要检索的微调作业数。

分页微调作业对象的列表。

示例请求

1
2
curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.fine_tuning.jobs.list()

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.fineTuning.jobs.list();

  for await (const fineTune of list) {
    console.log(fineTune);
  }
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "object": "list",
  "data": [
    {
      "object": "fine_tuning.job.event",
      "id": "ft-event-TjX0lMfOniCZX64t9PUQT5hn",
      "created_at": 1689813489,
      "level": "warn",
      "message": "Fine tuning process stopping due to job cancellation",
      "data": null,
      "type": "message"
    },
    { ... },
    { ... }
  ], "has_more": true
}

列出微调事件

获取 https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/events

获取微调作业的状态更新。

路径参数

fine_tuning_job_id

字符串

必填

要为其获取事件的微调作业的 ID。

查询参数

后

字符串

自选

上一个分页请求中的最后一个事件的标识符。

限制

整数

自选

默认为 20

要检索的事件数。

微调事件对象的列表。

示例请求

1
2
curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

client.fine_tuning.jobs.list_events(
  fine_tuning_job_id="ftjob-abc123",
  limit=2
)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.fineTuning.list_events(id="ftjob-abc123", limit=2);

  for await (const fineTune of list) {
    console.log(fineTune);
  }
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "object": "list",
  "data": [
    {
      "object": "fine_tuning.job.event",
      "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm",
      "created_at": 1721764800,
      "level": "info",
      "message": "Fine tuning job successfully completed",
      "data": null,
      "type": "message"
    },
    {
      "object": "fine_tuning.job.event",
      "id": "ft-event-tyiGuB72evQncpH87xe505Sv",
      "created_at": 1721764800,
      "level": "info",
      "message": "New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel",
      "data": null,
      "type": "message"
    }
  ],
  "has_more": true
}

列出微调检查点

获取 https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints

列出微调作业的检查点。

路径参数

fine_tuning_job_id

字符串

必填

要为其获取检查点的微调作业的 ID。

查询参数

后

字符串

自选

上一个分页请求的最后一个检查点 ID 的标识符。

限制

整数

自选

默认为 10

要检索的检查点数。

用于微调作业的微调检查点对象列表。

示例请求

1
2
curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \
  -H "Authorization: Bearer $OPENAI_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
24
25
26
27
28
29
30
31
32
{
  "object": "list"
  "data": [
    {
      "object": "fine_tuning.job.checkpoint",
      "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
      "created_at": 1721764867,
      "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000",
      "metrics": {
        "full_valid_loss": 0.134,
        "full_valid_mean_token_accuracy": 0.874
      },
      "fine_tuning_job_id": "ftjob-abc123",
      "step_number": 2000,
    },
    {
      "object": "fine_tuning.job.checkpoint",
      "id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy",
      "created_at": 1721764800,
      "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000",
      "metrics": {
        "full_valid_loss": 0.167,
        "full_valid_mean_token_accuracy": 0.781
      },
      "fine_tuning_job_id": "ftjob-abc123",
      "step_number": 1000,
    },
  ],
  "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
  "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy",
  "has_more": true
}

检索微调作业

获取 https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}

获取有关微调作业的信息。

了解有关微调的更多信息

路径参数

fine_tuning_job_id

字符串

必填

微调作业的 ID。

具有给定 ID 的微调对象。

示例请求

1
2
curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.fine_tuning.jobs.retrieve("ftjob-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const fineTune = await openai.fineTuning.jobs.retrieve("ftjob-abc123");

  console.log(fineTune);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "object": "fine_tuning.job",
  "id": "ftjob-abc123",
  "model": "davinci-002",
  "created_at": 1692661014,
  "finished_at": 1692661190,
  "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy",
  "organization_id": "org-123",
  "result_files": [
      "file-abc123"
  ],
  "status": "succeeded",
  "validation_file": null,
  "training_file": "file-abc123",
  "hyperparameters": {
      "n_epochs": 4,
      "batch_size": 1,
      "learning_rate_multiplier": 1.0
  },
  "trained_tokens": 5768,
  "integrations": [],
  "seed": 0,
  "estimated_finish": 0
}

取消微调

post https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/cancel

立即取消微调作业。

路径参数

fine_tuning_job_id

字符串

必填

要取消的微调作业的 ID。

已取消的微调对象。

示例请求

1
2
curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.fine_tuning.jobs.cancel("ftjob-abc123")

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const fineTune = await openai.fineTuning.jobs.cancel("ftjob-abc123");

  console.log(fineTune);
}
main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "object": "fine_tuning.job",
  "id": "ftjob-abc123",
  "model": "gpt-4o-mini-2024-07-18",
  "created_at": 1721764800,
  "fine_tuned_model": null,
  "organization_id": "org-123",
  "result_files": [],
  "hyperparameters": {
    "n_epochs":  "auto"
  },
  "status": "cancelled",
  "validation_file": "file-abc123",
  "training_file": "file-abc123"
}

聊天模型的训练格式

聊天模型的微调输入文件的每行训练示例

消息

数组

工具

数组

模型可以为其生成 JSON 输入的工具列表。

parallel_tool_calls

布尔

是否在工具使用过程中启用并行函数调用。

功能

已废弃

数组

模型可以为其生成 JSON 输入的函数列表。

聊天模型的 OBJECT 训练格式

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
{
  "messages": [
    { "role": "user", "content": "What is the weather in San Francisco?" },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_id",
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}"
          }
        }
      ]
    }
  ],
  "parallel_tool_calls": false,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, eg. San Francisco, USA"
            },
            "format": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location", "format"]
        }
      }
    }
  ]
}

完成模型的训练格式

补全模型的微调输入文件的每行训练示例

提示

字符串

此训练示例的输入提示。

完成

字符串

此训练示例的预期完成。

完成模型的 OBJECT 训练格式

1
2
3
4
{
  "prompt": "What is the answer to 2+2",
  "completion": "4"
}

微调作业对象

该对象表示通过 API 创建的微调作业。fine_tuning.job

身份证

字符串

对象标识符，可在 API 终端节点中引用。

created_at

整数

创建微调作业时的 Unix 时间戳（以秒为单位）。

错误

object 或 null

对于具有的微调作业，这将包含有关失败原因的更多信息。failed

fine_tuned_model

string 或 null

正在创建的微调模型的名称。如果微调作业仍在运行，则该值将为 null。

finished_at

整数或 null

微调作业完成时的 Unix 时间戳（以秒为单位）。如果微调作业仍在运行，则该值将为 null。

超参数

对象

用于微调作业的超参数。有关更多详细信息，请参阅微调指南。

MODEL

字符串

正在微调的基本模型。

对象

字符串

对象类型，始终为 “fine_tuning.job”。

organization_id

字符串

拥有微调作业的组织。

result_files

数组

微调作业的已编译结果文件 ID。您可以使用 Files API 检索结果。

地位

字符串

微调作业的当前状态，可以是、、、、或。validating_filesqueuedrunningsucceededfailedcancelled

trained_tokens

整数或 null

此微调作业处理的可计费 Token 总数。如果微调作业仍在运行，则该值将为 null。

training_file

字符串

用于训练的文件 ID。您可以使用 Files API 检索训练数据。

validation_file

string 或 null

用于验证的文件 ID。您可以使用 Files API 检索验证结果。

集成

array 或 null

要为此微调作业启用的集成列表。

种子

整数

用于微调作业的种子。

estimated_finish

整数或 null

微调作业估计完成时间的 Unix 时间戳（以秒为单位）。如果微调作业未运行，则该值将为 null。

OBJECT 微调作业对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "object": "fine_tuning.job",
  "id": "ftjob-abc123",
  "model": "davinci-002",
  "created_at": 1692661014,
  "finished_at": 1692661190,
  "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy",
  "organization_id": "org-123",
  "result_files": [
      "file-abc123"
  ],
  "status": "succeeded",
  "validation_file": null,
  "training_file": "file-abc123",
  "hyperparameters": {
      "n_epochs": 4,
      "batch_size": 1,
      "learning_rate_multiplier": 1.0
  },
  "trained_tokens": 5768,
  "integrations": [],
  "seed": 0,
  "estimated_finish": 0
}

微调作业事件对象

身份证

字符串

created_at

整数

水平

字符串

消息

字符串

对象

字符串

OBJECT 微调作业事件对象

1
2
3
4
5
6
7
{
  "object": "fine_tuning.job.event",
  "id": "ftevent-abc123"
  "created_at": 1677610602,
  "level": "info",
  "message": "Created fine-tuning job"
}

微调作业检查点对象

该对象表示可供使用的微调作业的模型检查点。fine_tuning.job.checkpoint

身份证

字符串

检查点标识符，可在 API 终端节点中引用。

created_at

整数

创建检查点时的 Unix 时间戳（以秒为单位）。

fine_tuned_model_checkpoint

字符串

创建的微调检查点模型的名称。

step_number

整数

创建检查点的步骤编号。

指标

对象

微调作业期间步骤编号处的指标。

fine_tuning_job_id

字符串

从中创建此检查点的微调作业的名称。

对象

字符串

对象类型，始终为 “fine_tuning.job.checkpoint”。

OBJECT 微调作业检查点对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "object": "fine_tuning.job.checkpoint",
  "id": "ftckpt_qtZ5Gyk4BLq1SfLFWp3RtO3P",
  "created_at": 1712211699,
  "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:9ABel2dg:ckpt-step-88",
  "fine_tuning_job_id": "ftjob-fpbNQ3H1GrMehXRf8cO97xTN",
  "metrics": {
    "step": 88,
    "train_loss": 0.478,
    "train_mean_token_accuracy": 0.924,
    "valid_loss": 10.112,
    "valid_mean_token_accuracy": 0.145,
    "full_valid_loss": 0.567,
    "full_valid_mean_token_accuracy": 0.944
  },
  "step_number": 88
}

Batch

创建大批量 API 请求以进行异步处理。Batch API 在 24 小时内返回完成情况，可享受 50% 的折扣。相关指南： Batch

创建批处理

帖子 https://api.openai.com/v1/batches

从上传的请求文件创建并执行批处理

请求正文

input_file_id

字符串

必填

包含新批处理请求的已上传文件的 ID。

有关如何上传文件的信息，请参阅上传文件。

您的输入文件必须格式化为 JSONL 文件，并且必须使用 purpose .该文件最多可包含 50000 个请求，最大大小可达 200 MB。batch

Endpoint

字符串

必填

用于批处理中所有请求的终端节点。目前支持、和。请注意，批处理还限制为批处理中所有请求中最多 50,000 个嵌入输入。/v1/chat/completions/v1/embeddings/v1/completions/v1/embeddings

completion_window

字符串

必填

应处理批处理的时间范围。目前仅支持。24h

元数据

object 或 null

自选

批处理的可选自定义元数据。

创建的 Batch 对象。

示例请求

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

client.batches.create(
  input_file_id="file-abc123",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const batch = await openai.batches.create({
    input_file_id: "file-abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h"
  });

  console.log(batch);
}

main();

响应

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
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

检索批次

获取 https://api.openai.com/v1/batches/{batch_id}

检索批次。

路径参数

batch_id

字符串

必填

要检索的批处理的 ID。

与指定 ID 匹配的 Batch 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.batches.retrieve("batch_abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const batch = await openai.batches.retrieve("batch_abc123");

  console.log(batch);
}

main();

响应

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
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

取消批处理

发布 https://api.openai.com/v1/batches/{batch_id}/cancel

取消正在进行的批处理。该批次将处于状态长达 10 分钟，然后更改为，此时它将在输出文件中提供部分结果（如果有）。cancellingcancelled

路径参数

batch_id

字符串

必填

要取消的批处理的 ID。

与指定 ID 匹配的 Batch 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.batches.cancel("batch_abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const batch = await openai.batches.cancel("batch_abc123");

  console.log(batch);
}

main();

响应

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
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711475133,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

列出批次

获取 https://api.openai.com/v1/batches

列出组织的批次。

查询参数

后

字符串

自选

用于分页的游标。是定义您在列表中的位置的对象 ID。例如，如果您发出列表请求并收到 100 个对象，以 obj_foo 结尾，则您的后续调用可以包含 after=obj_foo 以便获取列表的下一页。after

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

分页的 Batch 对象列表。

示例请求

1
2
3
curl https://api.openai.com/v1/batches?limit=2 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.batches.list()

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.batches.list();

  for await (const batch of list) {
    console.log(batch);
  }
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job",
      }
    },
    { ... },
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc456",
  "has_more": true
}

batch 对象

身份证

字符串

对象

字符串

对象类型，始终为 .batch

Endpoint

字符串

批处理使用的 OpenAI API 终端节点。

错误

对象

input_file_id

字符串

批处理的输入文件的 ID。

completion_window

字符串

应处理批处理的时间范围。

地位

字符串

批处理的当前状态。

output_file_id

字符串

包含成功执行的请求的输出的文件的 ID。

error_file_id

字符串

包含错误请求输出的文件的 ID。

created_at

整数

创建批处理时的 Unix 时间戳（以秒为单位）。

in_progress_at

整数

批处理开始处理时的 Unix 时间戳（以秒为单位）。

expires_at

整数

批处理过期时间的 Unix 时间戳（以秒为单位）。

finalizing_at

整数

批处理开始完成时的 Unix 时间戳（以秒为单位）。

completed_at

整数

批处理完成时的 Unix 时间戳（以秒为单位）。

failed_at

整数

批处理失败时的 Unix 时间戳（以秒为单位）。

expired_at

整数

批处理过期时的 Unix 时间戳（以秒为单位）。

cancelling_at

整数

批处理开始取消时的 Unix 时间戳（以秒为单位）。

cancelled_at

整数

取消批处理时的 Unix 时间戳（以秒为单位）。

request_counts

对象

请求计数批处理中的不同状态。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

OBJECT 批处理对象

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
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

请求输入对象

批处理输入文件的每行对象

custom_id

字符串

开发人员提供的按请求 ID 将用于将输出与输入匹配。对于批处理中的每个请求，必须是唯一的。

方法

字符串

要用于请求的 HTTP 方法。目前仅支持。POST

网址

字符串

要用于请求的 OpenAI API 相对 URL。目前支持、和。/v1/chat/completions/v1/embeddings/v1/completions

OBJECT 请求输入对象

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}]}}

请求输出对象

批处理输出和错误文件的每行对象

身份证

字符串

custom_id

字符串

开发人员提供的按请求 ID 将用于将输出与输入匹配。

响应

object 或 null

错误

object 或 null

对于因非 HTTP 错误而失败的请求，这将包含有关失败原因的更多信息。

OBJECT 请求输出对象

{"id": "batch_req_wnaDys", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_c187b3", "body": {"id": "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 24, "completion_tokens": 15, "total_tokens": 39}, "system_fingerprint": null}}, "error": null}

文件

Files 用于上传可与 Assistants、Fine-tuning 和 Batch API 等功能一起使用的文档。

上传文件

帖子 https://api.openai.com/v1/files

上传可跨各种终端节点使用的文件。单个文件最大为 512 MB，一个组织上传的所有文件的大小最大为 100 GB。

Assistants API 支持最多 200 万个令牌和特定文件类型的文件。有关详细信息，请参阅 Assistants Tools 指南。

Fine-tuning API 仅支持文件。input 还具有微调聊天或完成模型所需的某些格式。.jsonl

Batch API 仅支持最大 200 MB 的文件。input 还具有特定的 required 格式。.jsonl

如果您需要提高这些仓储限制，请联系我们。

请求正文

文件

必填

要上传的 File 对象（不是文件名）。

目的

字符串

必填

上传文件的预期用途。

使用 “assistants” 表示 Assistants 和 Message 文件，使用 “vision” 表示 Assistants 图像文件输入，使用 “batch” 表示 Batch API，使用 “fine-tune” 进行微调。

上传的 File 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="fine-tune" \
  -F file="@mydata.jsonl"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

client.files.create(
  file=open("mydata.jsonl", "rb"),
  purpose="fine-tune"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.create({
    file: fs.createReadStream("mydata.jsonl"),
    purpose: "fine-tune",
  });

  console.log(file);
}

main();

响应

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

列出文件

获取 https://api.openai.com/v1/files

返回文件列表。

查询参数

目的

字符串

自选

仅返回具有给定目的的文件。

限制

整数

自选

默认为 10000

要返回的对象数量限制。Limit 的范围可以介于 1 到 10,000 之间，默认值为 10,000。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

File 对象的列表。

示例请求

1
2
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.list()

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.files.list();

  for await (const file of list) {
    console.log(file);
  }
}

main();

响应

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

检索文件

获取 https://api.openai.com/v1/files/{file_id}

返回有关特定文件的信息。

路径参数

file_id

字符串

必填

用于此请求的文件的 ID。

与指定 ID 匹配的 File 对象。

示例请求

1
2
curl https://api.openai.com/v1/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.retrieve("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.retrieve("file-abc123");

  console.log(file);
}

main();

响应

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

删除文件

删除 https://api.openai.com/v1/files/{file_id}

删除文件。

路径参数

file_id

字符串

必填

用于此请求的文件的 ID。

删除状态。

示例请求

1
2
3
curl https://api.openai.com/v1/files/file-abc123 \
  -X DELETE \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.delete("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.del("file-abc123");

  console.log(file);
}

main();

响应

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

检索文件内容

获取 https://api.openai.com/v1/files/{file_id}/content

返回指定文件的内容。

路径参数

file_id

字符串

必填

用于此请求的文件的 ID。

文件内容。

示例请求

1
2
curl https://api.openai.com/v1/files/file-abc123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl

1
2
3
4
from openai import OpenAI
client = OpenAI()

content = client.files.content("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.content("file-abc123");

  console.log(file);
}

main();

file 对象

该对象表示已上传到 OpenAI 的文档。File

身份证

字符串

文件标识符，可在 API 终端节点中引用。

字节

整数

文件大小（以字节为单位）。

created_at

整数

创建文件时的 Unix 时间戳（以秒为单位）。

文件名

字符串

文件的名称。

对象

字符串

对象类型，始终为 .file

目的

字符串

文件的预期用途。支持的值为、、、、和。assistantsassistants_outputbatchbatch_outputfine-tunefine-tune-resultsvision

地位

已废弃

字符串

已废弃。文件的当前状态，可以是、或。uploadedprocessederror

status_details

已废弃

字符串

已废弃。有关微调训练文件未通过验证的原因的详细信息，请参阅上的字段。errorfine_tuning.job

OBJECT 文件对象

1
2
3
4
5
6
7
8
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "salesOverview.pdf",
  "purpose": "assistants",
}

上传

允许您分多个部分上传大型文件。

创建上传

帖子 https://api.openai.com/v1/uploads

创建可向其添加段的中间 Upload 对象。目前，Upload 最多可以接受 8 GB 的总容量，并在您创建后一小时后过期。

完成 Upload 后，我们将创建一个 File 对象，其中包含您上传的所有段。此 File 可在我们平台的其余部分作为常规 File 对象使用。

对于某些，必须指定 correct。请参阅文档，了解适用于您的用例的 MIME 类型：purposemime_type

助理

有关每种用途的正确文件扩展名的指导，请遵循有关创建文件的文档。

请求正文

文件名

字符串

必填

要上传的文件的名称。

目的

字符串

必填

上传文件的预期用途。

请参阅有关文件目的的文档。

字节

整数

必填

您正在上传的文件中的字节数。

mime_type

字符串

必填

文件的 MIME 类型。

这必须属于您的文件目的支持的 MIME 类型。请参阅助手和视觉支持的 MIME 类型。

状态为 .pending

示例请求

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/uploads \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "purpose": "fine-tune",
    "filename": "training_examples.jsonl",
    "bytes": 2147483648,
    "mime_type": "text/jsonl"
  }'

响应

1
2
3
4
5
6
7
8
9
10
{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "pending",
  "expires_at": 1719127296
}

添加上传部分

发布 https://api.openai.com/v1/uploads/{upload_id}/parts

将 Part 添加到 Upload 对象。Part 表示您尝试上传的文件中的字节块。

每个段最大为 64 MB，您可以添加段，直到达到 8 GB 的上传最大值。

可以并行添加多个 Part。您可以在完成上传时决定 Part 的预期顺序。

路径参数

upload_id

字符串

必填

上传的 ID。

请求正文

数据

文件

必填

此 Part 的字节块。

upload Part 对象。

示例请求

1
2
curl https://api.openai.com/v1/uploads/upload_abc123/parts
  -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..."

响应

1
2
3
4
5
6
{
  "id": "part_def456",
  "object": "upload.part",
  "created_at": 1719185911,
  "upload_id": "upload_abc123"
}

完成上传

post https://api.openai.com/v1/uploads/{upload_id}/complete

完成上传。

在返回的 Upload 对象中，有一个嵌套的 File 对象，该对象已准备好在平台的其余部分使用。

您可以通过传入 Part ID 的有序列表来指定 Part 的顺序。

完成时上传的字节数必须与创建 Upload 对象时最初指定的字节数匹配。上传完成后，不得添加任何段。

路径参数

upload_id

字符串

必填

上传的 ID。

请求正文

part_ids

数组

必填

部件 ID 的有序列表。

md5

字符串

自选

文件内容的可选 md5 校验和，用于验证上传的字节数是否符合您的预期。

具有 status 的 Upload 对象，其中包含包含已创建的可用 File 对象的附加属性。completedfile

示例请求

1
2
3
4
curl https://api.openai.com/v1/uploads/upload_abc123/complete
  -d '{
    "part_ids": ["part_def456", "part_ghi789"]
  }'

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "completed",
  "expires_at": 1719127296,
  "file": {
    "id": "file-xyz321",
    "object": "file",
    "bytes": 2147483648,
    "created_at": 1719186911,
    "filename": "training_examples.jsonl",
    "purpose": "fine-tune",
  }
}

取消上传

post https://api.openai.com/v1/uploads/{upload_id}/cancel

取消上传。取消上传后，不得添加任何段。

路径参数

upload_id

字符串

必填

上传的 ID。

状态为 .cancelled

示例请求

curl https://api.openai.com/v1/uploads/upload_abc123/cancel

响应

1
2
3
4
5
6
7
8
9
10
{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "cancelled",
  "expires_at": 1719127296
}

upload 对象

Upload 对象可以接受 Part 形式的字节块。

身份证

字符串

的 Upload unique identifier，可在 API 端点中引用。

created_at

整数

创建 Upload 时的 Unix 时间戳（以秒为单位）。

文件名

字符串

要上传的文件的名称。

字节

整数

要上传的预期字节数。

目的

字符串

文件的预期用途。请参阅此处了解可接受的值。

地位

字符串

The status of the Upload.

expires_at

整数

创建 Upload 时的 Unix 时间戳（以秒为单位）。

对象

字符串

对象类型，始终为 “upload”。

文件

该对象表示已上传到 OpenAI 的文档。File

OBJECT 上传对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "completed",
  "expires_at": 1719127296,
  "file": {
    "id": "file-xyz321",
    "object": "file",
    "bytes": 2147483648,
    "created_at": 1719186911,
    "filename": "training_examples.jsonl",
    "purpose": "fine-tune",
  }
}

上传段对象

upload Part 表示我们可以添加到 Upload 对象的字节块。

身份证

字符串

上传 Part 唯一标识符，可在 API 端点中引用。

created_at

整数

创建 Part 时的 Unix 时间戳（以秒为单位）。

upload_id

字符串

此 Part 添加到的 Upload 对象的 ID。

对象

字符串

对象类型，始终为 .upload.part

OBJECT 上传段对象

1
2
3
4
5
6
{
    "id": "part_def456",
    "object": "upload.part",
    "created_at": 1719186911,
    "upload_id": "upload_abc123"
}

图像

给定提示和/或输入图像，模型将生成新图像。相关指南：图像生成

创建镜像

帖子 https://api.openai.com/v1/images/generations

在给定提示的情况下创建图像。

请求正文

提示

字符串

必填

所需图像的文本描述。最大长度为 1000 个字符，最大长度为 4000 个字符。dall-e-2dall-e-3

MODEL

字符串

自选

默认为 dall-e-2

用于图像生成的模型。

整数或 null

自选

默认为 1

要生成的图像数。必须介于 1 和 10 之间。对于，仅支持。dall-e-3n=1

质量

字符串

自选

默认为 standard

将生成的图像质量。创建的图像具有更精细的细节和更高的图像一致性。此参数仅支持。hddall-e-3

response_format

string 或 null

自选

默认为 url

返回生成图像的格式。必须是或之一。URL 仅在图像生成后的 60 分钟内有效。urlb64_json

大小

string 或 null

自选

默认为 1024x1024

生成的图像的大小。必须是、或中的之一。必须是、或 for models 之一。256x256512x5121024x1024dall-e-21024x10241792x10241024x1792dall-e-3

风格

string 或 null

自选

默认为 vivid

生成的图像的样式。必须是或之一。Vivid 使模型倾向于生成超真实和戏剧性的图像。自然使模型生成更自然、外观更不真实的图像。此参数仅支持。vividnaturaldall-e-3

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

返回图像对象列表。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "n": 1,
    "size": "1024x1024"
  }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

client.images.generate(
  model="dall-e-3",
  prompt="A cute baby sea otter",
  n=1,
  size="1024x1024"
)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const image = await openai.images.generate({ model: "dall-e-3", prompt: "A cute baby sea otter" });

  console.log(image.data);
}
main();

响应

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

创建图像编辑

帖子 https://api.openai.com/v1/images/edits

在给定原始图像和提示的情况下创建已编辑或扩展的图像。

请求正文

图像

文件

必填

要编辑的图像。必须是有效的 PNG 文件，大小小于 4MB，并且是正方形。如果未提供 mask，则图像必须具有透明度，该透明度将用作 mask。

提示

字符串

必填

所需图像的文本描述。最大长度为 1000 个字符。

遮罩

文件

自选

一个附加图像，其完全透明的区域（例如，alpha 为零的位置）指示应编辑的位置。必须是有效的 PNG 文件，小于 4MB，并且尺寸与 .imageimage

MODEL

字符串

自选

默认为 dall-e-2

用于图像生成的模型。目前仅支持。dall-e-2

整数或 null

自选

默认为 1

要生成的图像数。必须介于 1 和 10 之间。

大小

string 或 null

自选

默认为 1024x1024

生成的图像的大小。必须是、或之一。256x256512x5121024x1024

response_format

string 或 null

自选

默认为 url

返回生成图像的格式。必须是或之一。URL 仅在图像生成后的 60 分钟内有效。urlb64_json

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

返回图像对象列表。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_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
from openai import OpenAI
client = OpenAI()

client.images.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
11
12
13
14
15
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const image = await openai.images.edit({
    image: fs.createReadStream("otter.png"),
    mask: fs.createReadStream("mask.png"),
    prompt: "A cute baby sea otter wearing a beret",
  });

  console.log(image.data);
}
main();

响应

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

创建图像变体

帖子 https://api.openai.com/v1/images/variations

创建给定图像的变体。

请求正文

图像

文件

必填

用作变体基础的图像。必须是有效的 PNG 文件，大小小于 4MB，并且是正方形。

MODEL

字符串

自选

默认为 dall-e-2

用于图像生成的模型。目前仅支持。dall-e-2

整数或 null

自选

默认为 1

要生成的图像数。必须介于 1 和 10 之间。对于，仅支持。dall-e-3n=1

response_format

string 或 null

自选

默认为 url

返回生成图像的格式。必须是或之一。URL 仅在图像生成后的 60 分钟内有效。urlb64_json

大小

string 或 null

自选

默认为 1024x1024

生成的图像的大小。必须是、或之一。256x256512x5121024x1024

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

返回图像对象列表。

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/images/variations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image="@otter.png" \
  -F n=2 \
  -F size="1024x1024"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

response = client.images.create_variation(
  image=open("image_edit_original.png", "rb"),
  n=2,
  size="1024x1024"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const image = await openai.images.createVariation({
    image: fs.createReadStream("otter.png"),
  });

  console.log(image.data);
}
main();

响应

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

图像对象

表示 OpenAI API 生成的图像的 url 或内容。

b64_json

字符串

生成的图像的 base64 编码的 JSON，如果为 .response_formatb64_json

网址

字符串

生成图像的 URL（如果为 is ）（默认）。response_formaturl

revised_prompt

字符串

用于生成图像的提示（如果提示有任何修订）。

OBJECT 图像对象

1
2
3
4
{
  "url": "...",
  "revised_prompt": "..."
}

模型

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

列出模型

获取 https://api.openai.com/v1/models

列出当前可用的模型，并提供有关每个模型的基本信息，例如所有者和可用性。

模型对象的列表。

示例请求

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

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.models.list()

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.models.list();

  for await (const model of list) {
    console.log(model);
  }
}
main();

响应

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

检索模型

获取 https://api.openai.com/v1/models/{model}

检索模型实例，提供有关模型的基本信息，例如所有者和权限。

路径参数

MODEL

字符串

必填

用于此请求的模型的 ID

与指定 ID 匹配的模型对象。

示例请求

1
2
curl https://api.openai.com/v1/models/gpt-4o \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.models.retrieve("gpt-4o")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const model = await openai.models.retrieve("gpt-4o");

  console.log(model);
}

main();

响应

1
2
3
4
5
6
{
  "id": "gpt-4o",
  "object": "model",
  "created": 1686935002,
  "owned_by": "openai"
}

删除微调模型

删除 https://api.openai.com/v1/models/{model}

删除微调的模型。您必须在组织中具有 Owner （所有者）角色才能删除模型。

路径参数

MODEL

字符串

必填

要删除的模型

删除状态。

示例请求

1
2
3
curl https://api.openai.com/v1/models/ft:gpt-4o-mini:acemeco:suffix:abc123 \
  -X DELETE \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.models.delete("ft:gpt-4o-mini:acemeco:suffix:abc123")

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const model = await openai.models.del("ft:gpt-4o-mini:acemeco:suffix:abc123");

  console.log(model);
}
main();

响应

1
2
3
4
5
{
  "id": "ft:gpt-4o-mini:acemeco:suffix:abc123",
  "object": "model",
  "deleted": true
}

模型对象

描述可与 API 一起使用的 OpenAI 模型产品。

身份证

字符串

模型标识符，可在 API 终端节点中引用。

创建

整数

创建模型时的 Unix 时间戳（以秒为单位）。

对象

字符串

对象类型，始终为 “model”。

owned_by

字符串

拥有该模型的组织。

OBJECT 模型对象

1
2
3
4
5
6
{
  "id": "gpt-4o",
  "object": "model",
  "created": 1686935002,
  "owned_by": "openai"
}

审核

给定文本和/或图像输入，对这些输入在多个类别中是否可能有害进行分类。相关指南：审核

创建审核

帖子 https://api.openai.com/v1/moderations

对文本和/或图像输入是否可能有害进行分类。学习更多信息请参阅审核指南。

请求正文

输入

字符串或数组

必填

要分类的 Input（或多个 Inputs）。可以是单个字符串、字符串数组或类似于其他模型的多模态输入对象数组。

MODEL

字符串

自选

默认为 omni-moderation-latest

您要使用的内容审核模型。在审核指南中了解更多信息，并了解可用型号在这里。

审核对象。

示例请求

1
2
3
4
5
6
curl https://api.openai.com/v1/moderations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "input": "I want to kill them."
  }'

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

moderation = client.moderations.create(input="I want to kill them.")
print(moderation)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const moderation = await openai.moderations.create({ input: "I want to kill them." });

  console.log(moderation);
}
main();

响应

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
{
  "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR",
  "model": "text-moderation-007",
  "results": [
    {
      "flagged": true,
      "categories": {
        "sexual": false,
        "hate": false,
        "harassment": true,
        "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": 0.000011726012417057063,
        "hate": 0.22706663608551025,
        "harassment": 0.5215635299682617,
        "self-harm": 2.227119921371923e-6,
        "sexual/minors": 7.107352217872176e-8,
        "hate/threatening": 0.023547329008579254,
        "violence/graphic": 0.00003391829886822961,
        "self-harm/intent": 1.646940972932498e-6,
        "self-harm/instructions": 1.1198755256458526e-9,
        "harassment/threatening": 0.5694745779037476,
        "violence": 0.9971134662628174
      }
    }
  ]
}

moderation 对象

表示给定的文本输入是否可能有害。

身份证

字符串

审核请求的唯一标识符。

MODEL

字符串

用于生成审核结果的模型。

结果

数组

审核对象列表。

OBJECT 审核对象

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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
  "id": "modr-0d9740456c391e43c445bf0f010940c7",
  "model": "omni-moderation-latest",
  "results": [
    {
      "flagged": true,
      "categories": {
        "harassment": true,
        "harassment/threatening": true,
        "sexual": false,
        "hate": false,
        "hate/threatening": false,
        "illicit": false,
        "illicit/violent": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "self-harm": false,
        "sexual/minors": false,
        "violence": true,
        "violence/graphic": true
      },
      "category_scores": {
        "harassment": 0.8189693396524255,
        "harassment/threatening": 0.804985420696006,
        "sexual": 1.573112165348997e-6,
        "hate": 0.007562942636942845,
        "hate/threatening": 0.004208854591835476,
        "illicit": 0.030535955153511665,
        "illicit/violent": 0.008925306722380033,
        "self-harm/intent": 0.00023023930975076432,
        "self-harm/instructions": 0.0002293869201073356,
        "self-harm": 0.012598046106750154,
        "sexual/minors": 2.212566909570261e-8,
        "violence": 0.9999992735124786,
        "violence/graphic": 0.843064871157054
      },
      "category_applied_input_types": {
        "harassment": [
          "text"
        ],
        "harassment/threatening": [
          "text"
        ],
        "sexual": [
          "text",
          "image"
        ],
        "hate": [
          "text"
        ],
        "hate/threatening": [
          "text"
        ],
        "illicit": [
          "text"
        ],
        "illicit/violent": [
          "text"
        ],
        "self-harm/intent": [
          "text",
          "image"
        ],
        "self-harm/instructions": [
          "text",
          "image"
        ],
        "self-harm": [
          "text",
          "image"
        ],
        "sexual/minors": [
          "text"
        ],
        "violence": [
          "text",
          "image"
        ],
        "violence/graphic": [
          "text",
          "image"
        ]
      }
    }
  ]
}

助理
试用版

构建可以调用模型并使用工具执行任务的助手。

开始使用 Assistants API

创建助手
试用版

帖子 https://api.openai.com/v1/assistants

创建包含模型和说明的助手。

请求正文

MODEL

字符串

必填

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。

名字

string 或 null

自选

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

自选

助手的描述。最大长度为 512 个字符。

指示

string 或 null

自选

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

自选

默认为 []

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterfile_searchfunction

tool_resources

object 或 null

自选

助手的工具使用的一组资源。这些资源特定于工具类型。例如，该工具需要文件 ID 列表，而该工具需要矢量存储 ID 列表。code_interpreterfile_search

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

“auto” 或 object

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

辅助对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    "name": "Math Tutor",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o"
  }'

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

my_assistant = client.beta.assistants.create(
    instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    name="Math Tutor",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4o",
)
print(my_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistant = await openai.beta.assistants.create({
    instructions:
      "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    name: "Math Tutor",
    tools: [{ type: "code_interpreter" }],
    model: "gpt-4o",
  });

  console.log(myAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

列出助理
试用版

获取 https://api.openai.com/v1/assistants

返回助手列表。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

用于分页的游标。是定义您在列表中的位置的对象 ID。例如，如果您发出一个列表请求并收到 100 个对象，以 obj_foo 开头，则您的后续调用可以包含 before=obj_foo 以便获取列表的上一页。before

辅助对象列表。

示例请求

1
2
3
4
curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistants = await openai.beta.assistants.list({
    order: "desc",
    limit: "20",
  });

  console.log(myAssistants.data);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123",
      "object": "assistant",
      "created_at": 1698982736,
      "name": "Coding Tutor",
      "description": null,
      "model": "gpt-4o",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc456",
      "object": "assistant",
      "created_at": 1698982718,
      "name": "My Assistant",
      "description": null,
      "model": "gpt-4o",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc789",
      "object": "assistant",
      "created_at": 1698982643,
      "name": null,
      "description": null,
      "model": "gpt-4o",
      "instructions": null,
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    }
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

检索助手
试用版

获取 https://api.openai.com/v1/assistants/{assistant_id}

检索助手。

路径参数

assistant_id

字符串

必填

要检索的助手的 ID。

与指定 ID 匹配的 assistant 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistant = await openai.beta.assistants.retrieve(
    "asst_abc123"
  );

  console.log(myAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

修改助手
试用版

帖子 https://api.openai.com/v1/assistants/{assistant_id}

修改助手。

路径参数

assistant_id

字符串

必填

要修改的助手的 ID。

请求正文

MODEL

自选

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。

名字

string 或 null

自选

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

自选

助手的描述。最大长度为 512 个字符。

指示

string 或 null

自选

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

自选

默认为 []

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterfile_searchfunction

tool_resources

object 或 null

自选

助手的工具使用的一组资源。这些资源特定于工具类型。例如，该工具需要文件 ID 列表，而该工具需要矢量存储 ID 列表。code_interpreterfile_search

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

“auto” 或 object

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

修改后的 assistant 对象。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "file_search"}],
      "model": "gpt-4o"
    }'

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "file_search"}],
  model="gpt-4o"
)

print(my_updated_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myUpdatedAssistant = await openai.beta.assistants.update(
    "asst_abc123",
    {
      instructions:
        "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      name: "HR Helper",
      tools: [{ type: "file_search" }],
      model: "gpt-4o"
    }
  );

  console.log(myUpdatedAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "asst_123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": []
    }
  },
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

删除助手
试用版

删除 https://api.openai.com/v1/assistants/{assistant_id}

删除助手。

路径参数

assistant_id

字符串

必填

要删除的助手的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

response = client.beta.assistants.delete("asst_abc123")
print(response)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const response = await openai.beta.assistants.del("asst_abc123");

  console.log(response);
}
main();

响应

1
2
3
4
5
{
  "id": "asst_abc123",
  "object": "assistant.deleted",
  "deleted": true
}

辅助对象
试用版

表示可以调用模型并使用工具的 an。assistant

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .assistant

created_at

整数

创建 Assistant 时的 Unix 时间戳（以秒为单位）。

名字

string 或 null

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

助手的描述。最大长度为 512 个字符。

MODEL

字符串

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。

指示

string 或 null

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterfile_searchfunction

tool_resources

object 或 null

助手的工具使用的一组资源。这些资源特定于工具类型。例如，该工具需要文件 ID 列表，而该工具需要矢量存储 ID 列表。code_interpreterfile_search

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

温度

number 或 null

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

“auto” 或 object

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

OBJECT 辅助对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

线程
试用版

创建助理可以与之交互的线程。

相关指南：助手

创建线程
试用版

帖子 https://api.openai.com/v1/threads

创建线程。

请求正文

消息

数组

自选

要开始线程的消息列表。

tool_resources

object 或 null

自选

在此线程中可供 Assistant 工具使用的一组资源。这些资源特定于工具类型。例如，该工具需要文件 ID 列表，而该工具需要矢量存储 ID 列表。code_interpreterfile_search

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

线程对象。

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d ''

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

empty_thread = client.beta.threads.create()
print(empty_thread)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const emptyThread = await openai.beta.threads.create();

  console.log(emptyThread);
}

main();

响应

1
2
3
4
5
6
7
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699012949,
  "metadata": {},
  "tool_resources": {}
}

检索线程
试用版

获取 https://api.openai.com/v1/threads/{thread_id}

检索线程。

路径参数

thread_id

字符串

必填

要检索的线程的 ID。

与指定 ID 匹配的 thread 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myThread = await openai.beta.threads.retrieve(
    "thread_abc123"
  );

  console.log(myThread);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699014083,
  "metadata": {},
  "tool_resources": {
    "code_interpreter": {
      "file_ids": []
    }
  }
}

修改线程
试用版

帖子 https://api.openai.com/v1/threads/{thread_id}

修改线程。

路径参数

thread_id

字符串

必填

要修改的线程的 ID。只有可以修改。metadata

请求正文

tool_resources

object 或 null

自选

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

与指定 ID 匹配的修改后的线程对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
from openai import OpenAI
client = OpenAI()

my_updated_thread = client.beta.threads.update(
  "thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123"
  }
)
print(my_updated_thread)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const updatedThread = await openai.beta.threads.update(
    "thread_abc123",
    {
      metadata: { modified: "true", user: "abc123" },
    }
  );

  console.log(updatedThread);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699014083,
  "metadata": {
    "modified": "true",
    "user": "abc123"
  },
  "tool_resources": {}
}

删除线程
试用版

删除 https://api.openai.com/v1/threads/{thread_id}

删除线程。

路径参数

thread_id

字符串

必填

要删除的线程的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

response = client.beta.threads.delete("thread_abc123")
print(response)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const response = await openai.beta.threads.del("thread_abc123");

  console.log(response);
}
main();

响应

1
2
3
4
5
{
  "id": "thread_abc123",
  "object": "thread.deleted",
  "deleted": true
}

thread 对象
试用版

表示包含消息的线程。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread

created_at

整数

创建线程时的 Unix 时间戳（以秒为单位）。

tool_resources

object 或 null

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

OBJECT 线程对象

1
2
3
4
5
6
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1698107661,
  "metadata": {}
}

消息
试用版

在话题中创建消息

相关指南：助手

创建消息
试用版

发布 https://api.openai.com/v1/threads/{thread_id}/messages

创建消息。

路径参数

thread_id

字符串

必填

要为其创建消息的线程的 ID。

请求正文

角色

字符串

必填

创建消息的实体的角色。允许的值包括：

user：表示消息是由实际用户发送的，在大多数情况下应该用于表示用户生成的消息。
assistant：表示消息由助手生成。使用此值可将来自助手的消息插入到对话中。

内容

字符串或数组

必填

附件

array 或 null

自选

附加到邮件的文件列表，以及应将它们添加到的工具。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

消息对象。

示例请求

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.create(
    "thread_abc123",
    { role: "user", content: "How does AI work? Explain it in simple terms." }
  );

  console.log(threadMessages);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1713226573,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

列出消息
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/messages

返回给定线程的消息列表。

路径参数

thread_id

字符串

必填

消息所属线程的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

run_id

字符串

自选

按生成消息的运行 ID 筛选消息。

消息对象列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.list(
    "thread_abc123"
  );

  console.log(threadMessages.data);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "How does AI work? Explain it in simple terms.",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    },
    {
      "id": "msg_abc456",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "Hello, what is AI?",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc456",
  "has_more": false
}

检索消息
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

检索消息。

路径参数

thread_id

字符串

必填

此消息所属的线程的 ID。

message_id

字符串

必填

要检索的消息的 ID。

与指定 ID 匹配的 message 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.retrieve(
    "thread_abc123",
    "msg_abc123"
  );

  console.log(message);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

修改消息
试用版

帖子 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

修改消息。

路径参数

thread_id

字符串

必填

此消息所属的线程的 ID。

message_id

字符串

必填

要修改的消息的 ID。

请求正文

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

修改后的 message 对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.update(
    "thread_abc123",
    "msg_abc123",
    {
      metadata: {
        modified: "true",
        user: "abc123",
      },
    }
  }'

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "metadata": {
    "modified": "true",
    "user": "abc123"
  }
}

删除消息
试用版

删除 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

删除消息。

路径参数

thread_id

字符串

必填

此消息所属的线程的 ID。

message_id

字符串

必填

要删除的消息的 ID。

删除状态

示例请求

1
2
3
4
curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

deleted_message = client.beta.threads.messages.delete(
  message_id="msg_abc12",
  thread_id="thread_abc123",
)
print(deleted_message)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const deletedMessage = await openai.beta.threads.messages.del(
    "thread_abc123",
    "msg_abc123"
  );

  console.log(deletedMessage);
}

响应

1
2
3
4
5
{
  "id": "msg_abc123",
  "object": "thread.message.deleted",
  "deleted": true
}

message 对象
试用版

表示线程中的消息。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.message

created_at

整数

创建消息时的 Unix 时间戳（以秒为单位）。

thread_id

字符串

此消息所属的线程 ID。

地位

字符串

消息的状态，可以是、或。in_progressincompletecompleted

incomplete_details

object 或 null

在未完成的消息中，有关消息未完成原因的详细信息。

completed_at

整数或 null

消息完成时的 Unix 时间戳（以秒为单位）。

incomplete_at

整数或 null

消息标记为未完成时的 Unix 时间戳（以秒为单位）。

角色

字符串

生成消息的实体。或 .userassistant

内容

数组

文本和/或图像数组中的消息内容。

assistant_id

string 或 null

如果适用，则为创作此消息的助手的 ID。

run_id

string 或 null

与创建此消息关联的运行的 ID。Value 是使用 create message 或 create thread 端点手动创建消息时的值。null

附件

array 或 null

附加到消息的文件列表，以及它们被添加到的工具。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

OBJECT 消息对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1698983503,
  "thread_id": "thread_abc123",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Hi! How can I help you today?",
        "annotations": []
      }
    }
  ],
  "assistant_id": "asst_abc123",
  "run_id": "run_abc123",
  "attachments": [],
  "metadata": {}
}

运行
试用版

表示在线程上运行的执行。

相关指南：助手

创建运行
试用版

发布 https://api.openai.com/v1/threads/{thread_id}/runs

创建运行。

路径参数

thread_id

字符串

必填

要运行的线程的 ID。

查询参数

include[]

数组

自选

要包含在响应中的其他字段的列表。目前唯一支持的值是 to fetch the file search result content。step_details.tool_calls[*].file_search.results[*].content

有关更多信息，请参阅文件搜索工具文档。

请求正文

assistant_id

字符串

必填

用于执行此运行的助手的 ID。

MODEL

字符串

自选

用于执行此运行的 Model 的 ID。如果此处提供了值，它将覆盖与助手关联的模型。否则，将使用与助手关联的模型。

指示

string 或 null

自选

覆盖助手的指令。这对于修改每次运行的行为非常有用。

additional_instructions

string 或 null

自选

在运行说明的末尾附加其他说明。这对于在每次运行的基础上修改行为而不覆盖其他指令非常有用。

additional_messages

array 或 null

自选

在创建运行之前向线程添加其他消息。

工具

array 或 null

自选

覆盖助手可用于此运行的工具。这对于修改每次运行的行为非常有用。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

max_prompt_tokens

整数或 null

自选

在运行过程中可以使用的提示令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的提示令牌数。如果运行超过指定的提示令牌数，则运行将以 status 结束。有关更多信息，请参阅。incompleteincomplete_details

max_completion_tokens

整数或 null

自选

在运行过程中可以使用的完成令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的完成令牌数。如果运行超过指定的完成令牌数，则运行将以 status 结束。有关更多信息，请参阅。incompleteincomplete_details

truncation_strategy

对象

自选

控制线程在运行之前如何被截断。使用此选项可控制运行的初始上下文窗口。

tool_choice

字符串或对象

自选

控制模型调用哪个（如果有）工具。表示模型不会调用任何工具，而是生成一条消息。是默认值，这意味着模型可以在生成消息或调用一个或多个工具之间进行选择。表示模型在响应用户之前必须调用一个或多个工具。指定特定工具（如 or ）会强制模型调用该工具。noneautorequired{"type": "file_search"}{"type": "function", "function": {"name": "my_function"}}

parallel_tool_calls

布尔

自选

默认为 true

是否在工具使用过程中启用并行函数调用。

response_format

“auto” 或 object

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

run 对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/threads/thread_abc123/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "assistant_id": "asst_abc123"
  }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.create(
  thread_id="thread_abc123",
  assistant_id="asst_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.create(
    "thread_abc123",
    { assistant_id: "asst_abc123" }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699063290,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": 1699063290,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699063291,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

创建线程并运行
试用版

帖子 https://api.openai.com/v1/threads/runs

创建一个线程并在一个请求中运行它。

请求正文

assistant_id

字符串

必填

用于执行此运行的助手的 ID。

线程

对象

自选

MODEL

字符串

自选

用于执行此运行的 Model 的 ID。如果此处提供了值，它将覆盖与助手关联的模型。否则，将使用与助手关联的模型。

指示

string 或 null

自选

覆盖助手的默认系统消息。这对于修改每次运行的行为非常有用。

工具

array 或 null

自选

覆盖助手可用于此运行的工具。这对于修改每次运行的行为非常有用。

tool_resources

object 或 null

自选

助手的工具使用的一组资源。这些资源特定于工具类型。例如，该工具需要文件 ID 列表，而该工具需要矢量存储 ID 列表。code_interpreterfile_search

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

max_prompt_tokens

整数或 null

自选

max_completion_tokens

整数或 null

自选

truncation_strategy

对象

自选

控制线程在运行之前如何被截断。使用此选项可控制运行的初始上下文窗口。

tool_choice

字符串或对象

自选

parallel_tool_calls

布尔

自选

默认为 true

是否在工具使用过程中启用并行函数调用。

response_format

“auto” 或 object

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

run 对象。

示例请求

1
2
3
4
5
6
7
8
9
10
11
12
curl https://api.openai.com/v1/threads/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "assistant_id": "asst_abc123",
      "thread": {
        "messages": [
          {"role": "user", "content": "Explain deep learning to a 5 year old."}
        ]
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.create_and_run(
  assistant_id="asst_abc123",
  thread={
    "messages": [
      {"role": "user", "content": "Explain deep learning to a 5 year old."}
    ]
  }
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.createAndRun({
    assistant_id: "asst_abc123",
    thread: {
      messages: [
        { role: "user", content: "Explain deep learning to a 5 year old." },
      ],
    },
  });

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076792,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": null,
  "expires_at": 1699077392,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "required_action": null,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": "You are a helpful assistant.",
  "tools": [],
  "tool_resources": {},
  "metadata": {},
  "temperature": 1.0,
  "top_p": 1.0,
  "max_completion_tokens": null,
  "max_prompt_tokens": null,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "incomplete_details": null,
  "usage": null,
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

列出运行
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/runs

返回属于线程的运行列表。

路径参数

thread_id

字符串

必填

运行所属线程的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

run 对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

runs = client.beta.threads.runs.list(
  "thread_abc123"
)

print(runs)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const runs = await openai.beta.threads.runs.list(
    "thread_abc123"
  );

  console.log(runs);
}

main();

响应

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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
  "object": "list",
  "data": [
    {
      "id": "run_abc123",
      "object": "thread.run",
      "created_at": 1699075072,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699075072,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699075073,
      "last_error": null,
      "model": "gpt-4o",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "tool_resources": {
        "code_interpreter": {
          "file_ids": [
            "file-abc123",
            "file-abc456"
          ]
        }
      },
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto",
      "parallel_tool_calls": true
    },
    {
      "id": "run_abc456",
      "object": "thread.run",
      "created_at": 1699063290,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699063290,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699063291,
      "last_error": null,
      "model": "gpt-4o",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "tool_resources": {
        "code_interpreter": {
          "file_ids": [
            "file-abc123",
            "file-abc456"
          ]
        }
      },
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto",
      "parallel_tool_calls": true
    }
  ],
  "first_id": "run_abc123",
  "last_id": "run_abc456",
  "has_more": false
}

检索运行
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

检索运行。

路径参数

thread_id

字符串

必填

运行的线程的 ID。

run_id

字符串

必填

要检索的运行的 ID。

与指定 ID 匹配的 run 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.retrieve(
    "thread_abc123",
    "run_abc123"
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

修改运行
试用版

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

修改运行。

路径参数

thread_id

字符串

必填

运行的线程的 ID。

run_id

字符串

必填

要修改的运行的 ID。

请求正文

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "metadata": {
      "user_id": "user_abc123"
    }
  }'

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.update(
  thread_id="thread_abc123",
  run_id="run_abc123",
  metadata={"user_id": "user_abc123"},
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.update(
    "thread_abc123",
    "run_abc123",
    {
      metadata: {
        user_id: "user_abc123",
      },
    }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "file-abc123",
        "file-abc456"
      ]
    }
  },
  "metadata": {
    "user_id": "user_abc123"
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

提交工具输出以运行
试用版

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs

当运行具有和 is 时，此终端节点可用于在工具调用全部完成后提交工具调用的输出。所有输出都必须在单个请求中提交。status: "requires_action"required_action.typesubmit_tool_outputs

路径参数

thread_id

字符串

必填

此运行所属的线程的 ID。

run_id

字符串

必填

需要提交工具输出的运行的 ID。

请求正文

tool_outputs

数组

必填

要提交其输出的工具列表。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
5
6
7
8
9
10
11
12
curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_001",
        "output": "70 degrees and sunny."
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id="thread_123",
  run_id="run_123",
  tool_outputs=[
    {
      "tool_call_id": "call_001",
      "output": "70 degrees and sunny."
    }
  ]
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.submitToolOutputs(
    "thread_123",
    "run_123",
    {
      tool_outputs: [
        {
          tool_call_id: "call_001",
          output: "70 degrees and sunny.",
        },
      ],
    }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_123",
  "object": "thread.run",
  "created_at": 1699075592,
  "assistant_id": "asst_123",
  "thread_id": "thread_123",
  "status": "queued",
  "started_at": 1699075592,
  "expires_at": 1699076192,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": null,
  "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"]
        }
      }
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

取消运行
试用版

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/cancel

取消为的运行。in_progress

路径参数

thread_id

字符串

必填

此运行所属的线程的 ID。

run_id

字符串

必填

要取消的运行的 ID。

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -X POST

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.cancel(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.cancel(
    "thread_abc123",
    "run_abc123"
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076126,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "cancelling",
  "started_at": 1699076126,
  "expires_at": 1699076726,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": "You summarize books.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": ["vs_123"]
    }
  },
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

run 对象
试用版

表示在线程上运行的执行。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run

created_at

整数

创建运行时的 Unix 时间戳（以秒为单位）。

thread_id

字符串

作为此运行的一部分执行的线程的 ID。

assistant_id

字符串

用于执行此运行的助手的 ID。

地位

字符串

运行的状态，可以是、queuedin_progressrequires_actioncancellingcancelledfailedcompletedincompleteexpired

required_action

object 或 null

有关继续运行所需操作的详细信息。如果不需要执行任何操作，则为 WILL 。null

last_error

object 或 null

与此运行关联的最后一个错误。如果没有错误，则会是。null

expires_at

整数或 null

运行过期时间的 Unix 时间戳（以秒为单位）。

started_at

整数或 null

运行启动时的 Unix 时间戳（以秒为单位）。

cancelled_at

整数或 null

取消运行时的 Unix 时间戳（以秒为单位）。

failed_at

整数或 null

运行失败时的 Unix 时间戳（以秒为单位）。

completed_at

整数或 null

运行完成时的 Unix 时间戳（以秒为单位）。

incomplete_details

object 或 null

有关运行未完成原因的详细信息。如果运行未完成，则为。null

MODEL

字符串

助手用于此运行的模型。

指示

字符串

助手用于此运行的说明。

工具

数组

助手用于此运行的工具列表。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

用法

object 或 null

与运行相关的使用情况统计信息。如果运行未处于终端状态（即、、等），则此值为该值。nullin_progressqueued

温度

number 或 null

用于此运行的采样温度。如果未设置，则默认为 1。

top_p

number 或 null

用于此运行的 nucleus 采样值。如果未设置，则默认为 1。

max_prompt_tokens

整数或 null

指定为在运行过程中使用的提示令牌的最大数量。

max_completion_tokens

整数或 null

指定为在运行过程中使用的最大完成令牌数。

truncation_strategy

对象

控制线程在运行之前如何被截断。使用此选项可控制运行的初始上下文窗口。

tool_choice

字符串或对象

parallel_tool_calls

布尔

是否在工具使用过程中启用并行函数调用。

response_format

“auto” 或 object

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 Structured Outputs，以确保模型与您提供的 JSON 架构匹配。在结构化输出指南中了解更多信息。{ "type": "json_schema", "json_schema": {...} }

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

OBJECT run 对象

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1698107661,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699073476,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699073498,
  "last_error": null,
  "model": "gpt-4o",
  "instructions": null,
  "tools": [{"type": "file_search"}, {"type": "code_interpreter"}],
  "metadata": {},
  "incomplete_details": null,
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

运行步骤
试用版

表示运行期间执行的步骤（模型和工具调用）。

相关指南：助手

列出运行步骤
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps

返回属于运行的运行步骤列表。

路径参数

thread_id

字符串

必填

run 和 run steps 所属的线程的 ID。

run_id

字符串

必填

运行步骤所属的运行的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

include[]

数组

自选

要包含在响应中的其他字段的列表。目前唯一支持的值是 to fetch the file search result content。step_details.tool_calls[*].file_search.results[*].content

有关更多信息，请参阅文件搜索工具文档。

运行步骤对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run_steps = client.beta.threads.runs.steps.list(
    thread_id="thread_abc123",
    run_id="run_abc123"
)

print(run_steps)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const runStep = await openai.beta.threads.runs.steps.list(
    "thread_abc123",
    "run_abc123"
  );
  console.log(runStep);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "step_abc123",
      "object": "thread.run.step",
      "created_at": 1699063291,
      "run_id": "run_abc123",
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "type": "message_creation",
      "status": "completed",
      "cancelled_at": null,
      "completed_at": 1699063291,
      "expired_at": null,
      "failed_at": null,
      "last_error": null,
      "step_details": {
        "type": "message_creation",
        "message_creation": {
          "message_id": "msg_abc123"
        }
      },
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      }
    }
  ],
  "first_id": "step_abc123",
  "last_id": "step_abc456",
  "has_more": false
}

检索运行步骤
试用版

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps/{step_id}

检索运行步骤。

路径参数

thread_id

字符串

必填

run 和 run step 所属的线程的 ID。

run_id

字符串

必填

运行步骤所属的运行的 ID。

step_id

字符串

必填

要检索的运行步骤的 ID。

查询参数

include[]

数组

自选

要包含在响应中的其他字段的列表。目前唯一支持的值是 to fetch the file search result content。step_details.tool_calls[*].file_search.results[*].content

有关更多信息，请参阅文件搜索工具文档。

与指定 ID 匹配的 run step 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

run_step = client.beta.threads.runs.steps.retrieve(
    thread_id="thread_abc123",
    run_id="run_abc123",
    step_id="step_abc123"
)

print(run_step)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const runStep = await openai.beta.threads.runs.steps.retrieve(
    "thread_abc123",
    "run_abc123",
    "step_abc123"
  );
  console.log(runStep);
}

main();

响应

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
{
  "id": "step_abc123",
  "object": "thread.run.step",
  "created_at": 1699063291,
  "run_id": "run_abc123",
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "type": "message_creation",
  "status": "completed",
  "cancelled_at": null,
  "completed_at": 1699063291,
  "expired_at": null,
  "failed_at": null,
  "last_error": null,
  "step_details": {
    "type": "message_creation",
    "message_creation": {
      "message_id": "msg_abc123"
    }
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

run step 对象
试用版

表示执行运行的步骤。

身份证

字符串

运行步骤的标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run.step

created_at

整数

创建运行步骤时的 Unix 时间戳（以秒为单位）。

assistant_id

字符串

与运行步骤关联的助手的 ID。

thread_id

字符串

运行的线程的 ID。

run_id

字符串

此运行步骤所属的运行的 ID。

类型

字符串

运行步骤的类型，可以是或。message_creationtool_calls

地位

字符串

运行步骤的状态，可以是、或。in_progresscancelledfailedcompletedexpired

step_details

对象

run 步骤的详细信息。

last_error

object 或 null

与此运行步骤关联的最后一个错误。如果没有错误，则会是。null

expired_at

整数或 null

运行步骤过期时的 Unix 时间戳（以秒为单位）。如果父运行已过期，则认为步骤已过期。

cancelled_at

整数或 null

取消运行步骤时的 Unix 时间戳（以秒为单位）。

failed_at

整数或 null

运行步骤失败时的 Unix 时间戳（以秒为单位）。

completed_at

整数或 null

运行步骤完成时的 Unix 时间戳（以秒为单位）。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

用法

object 或 null

与 run 步骤相关的使用情况统计信息。当运行步骤的状态为时，此值将为。nullin_progress

OBJECT 运行步骤对象

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
{
  "id": "step_abc123",
  "object": "thread.run.step",
  "created_at": 1699063291,
  "run_id": "run_abc123",
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "type": "message_creation",
  "status": "completed",
  "cancelled_at": null,
  "completed_at": 1699063291,
  "expired_at": null,
  "failed_at": null,
  "last_error": null,
  "step_details": {
    "type": "message_creation",
    "message_creation": {
      "message_id": "msg_abc123"
    }
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

矢量存储
试用版

矢量存储用于存储供工具使用的文件。file_search

创建矢量存储
试用版

帖子 https://api.openai.com/v1/vector_stores

创建 vector store。

请求正文

file_ids

数组

自选

矢量存储应使用的文件 ID 列表。对于可以访问文件的工具很有用。file_search

名字

字符串

自选

向量存储的名称。

expires_after

对象

自选

向量存储的过期策略。

chunking_strategy

对象

自选

用于对文件进行分块的分块策略。如果未设置，将使用该策略。仅当非空时适用。autofile_ids

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

矢量存储对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"
  -d '{
    "name": "Support FAQ"
  }'

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

vector_store = client.beta.vector_stores.create(
  name="Support FAQ"
)
print(vector_store)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStore = await openai.beta.vectorStores.create({
    name: "Support FAQ"
  });
  console.log(vectorStore);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

列出向量存储
试用版

获取 https://api.openai.com/v1/vector_stores

返回向量存储的列表。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

矢量存储对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

vector_stores = client.beta.vector_stores.list()
print(vector_stores)

1
2
3
4
5
6
7
8
9
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStores = await openai.beta.vectorStores.list();
  console.log(vectorStores);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "vs_abc123",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    },
    {
      "id": "vs_abc456",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ v2",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    }
  ],
  "first_id": "vs_abc123",
  "last_id": "vs_abc456",
  "has_more": false
}

检索向量存储
试用版

获取 https://api.openai.com/v1/vector_stores/{vector_store_id}

检索 vector store。

路径参数

vector_store_id

字符串

必填

要检索的向量存储的 ID。

与指定 ID 匹配的 vector store 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

vector_store = client.beta.vector_stores.retrieve(
  vector_store_id="vs_abc123"
)
print(vector_store)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStore = await openai.beta.vectorStores.retrieve(
    "vs_abc123"
  );
  console.log(vectorStore);
}

main();

响应

1
2
3
4
5
{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776
}

修改向量存储
试用版

帖子 https://api.openai.com/v1/vector_stores/{vector_store_id}

修改向量存储。

路径参数

vector_store_id

字符串

必填

要修改的向量存储的 ID。

请求正文

名字

string 或 null

自选

向量存储的名称。

expires_after

对象

自选

向量存储的过期策略。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

修改后的 vector store 对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"
  -d '{
    "name": "Support FAQ"
  }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store = client.beta.vector_stores.update(
  vector_store_id="vs_abc123",
  name="Support FAQ"
)
print(vector_store)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStore = await openai.beta.vectorStores.update(
    "vs_abc123",
    {
      name: "Support FAQ"
    }
  );
  console.log(vectorStore);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

删除 vector store
试用版

删除 https://api.openai.com/v1/vector_stores/{vector_store_id}

删除 vector store。

路径参数

vector_store_id

字符串

必填

要删除的向量存储的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

deleted_vector_store = client.beta.vector_stores.delete(
  vector_store_id="vs_abc123"
)
print(deleted_vector_store)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const deletedVectorStore = await openai.beta.vectorStores.del(
    "vs_abc123"
  );
  console.log(deletedVectorStore);
}

main();

响应

1
2
3
4
5
{
  id: "vs_abc123",
  object: "vector_store.deleted",
  deleted: true
}

向量存储对象
试用版

矢量存储是该工具可以使用的已处理文件的集合。file_search

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .vector_store

created_at

整数

创建向量存储时的 Unix 时间戳（以秒为单位）。

名字

字符串

向量存储的名称。

usage_bytes

整数

矢量存储中文件使用的总字节数。

file_counts

对象

地位

字符串

向量存储的状态，可以是、或。状态 of 表示向量存储已准备就绪，可供使用。expiredin_progresscompletedcompleted

expires_after

对象

向量存储的过期策略。

expires_at

整数或 null

向量存储过期的 Unix 时间戳（以秒为单位）。

last_active_at

整数或 null

向量存储上次处于活动状态时的 Unix 时间戳（以秒为单位）。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的长度最大为 64 个字符，值的长度最大为 512 个字符。

OBJECT 向量存储对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "vs_123",
  "object": "vector_store",
  "created_at": 1698107661,
  "usage_bytes": 123456,
  "last_active_at": 1698107661,
  "name": "my_vector_store",
  "status": "completed",
  "file_counts": {
    "in_progress": 0,
    "completed": 100,
    "cancelled": 0,
    "failed": 0,
    "total": 100
  },
  "metadata": {},
  "last_used_at": 1698107661
}

矢量存储文件
试用版

矢量存储文件表示矢量存储中的文件。

创建矢量存储文件
试用版

发布 https://api.openai.com/v1/vector_stores/{vector_store_id}/files

通过将 File 附加到矢量存储来创建矢量存储文件。

路径参数

vector_store_id

字符串

必填

要为其创建 File 的向量存储的 ID。

请求正文

file_id

字符串

必填

矢量存储应使用的文件 ID。对于可以访问文件的工具很有用。file_search

chunking_strategy

对象

自选

用于对文件进行分块的分块策略。如果未设置，将使用该策略。auto

矢量存储文件对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/vector_stores/vs_abc123/files \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -H "OpenAI-Beta: assistants=v2" \
    -d '{
      "file_id": "file-abc123"
    }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store_file = client.beta.vector_stores.files.create(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)
print(vector_store_file)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const myVectorStoreFile = await openai.beta.vectorStores.files.create(
    "vs_abc123",
    {
      file_id: "file-abc123"
    }
  );
  console.log(myVectorStoreFile);
}

main();

响应

1
2
3
4
5
6
7
8
9
{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "usage_bytes": 1234,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

列出向量存储文件
试用版

获取 https://api.openai.com/v1/vector_stores/{vector_store_id}/files

返回矢量存储文件的列表。

路径参数

vector_store_id

字符串

必填

文件所属的矢量存储的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

滤波器

字符串

自选

按文件状态筛选。、、、、中的一个。in_progresscompletedfailedcancelled

矢量存储文件对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores/vs_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

vector_store_files = client.beta.vector_stores.files.list(
  vector_store_id="vs_abc123"
)
print(vector_store_files)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStoreFiles = await openai.beta.vectorStores.files.list(
    "vs_abc123"
  );
  console.log(vectorStoreFiles);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    },
    {
      "id": "file-abc456",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

检索向量存储文件
试用版

获取 https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id}

检索向量存储文件。

路径参数

vector_store_id

字符串

必填

文件所属的向量存储的 ID。

file_id

字符串

必填

正在检索的文件的 ID。

矢量存储文件对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store_file = client.beta.vector_stores.files.retrieve(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)
print(vector_store_file)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStoreFile = await openai.beta.vectorStores.files.retrieve(
    "vs_abc123",
    "file-abc123"
  );
  console.log(vectorStoreFile);
}

main();

响应

1
2
3
4
5
6
7
8
{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

删除 vector store 文件
试用版

删除 https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id}

删除 vector store 文件。这将从矢量存储中删除文件，但不会删除文件本身。要删除文件，请使用 delete file 端点。

路径参数

vector_store_id

字符串

必填

文件所属的向量存储的 ID。

file_id

字符串

必填

要删除的文件的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

deleted_vector_store_file = client.beta.vector_stores.files.delete(
    vector_store_id="vs_abc123",
    file_id="file-abc123"
)
print(deleted_vector_store_file)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const deletedVectorStoreFile = await openai.beta.vectorStores.files.del(
    "vs_abc123",
    "file-abc123"
  );
  console.log(deletedVectorStoreFile);
}

main();

响应

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

矢量存储文件对象
试用版

附加到矢量存储的文件列表。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .vector_store.file

usage_bytes

整数

矢量存储总使用量（以字节为单位）。请注意，这可能与原始文件大小不同。

created_at

整数

创建向量存储文件时的 Unix 时间戳（以秒为单位）。

vector_store_id

字符串

File 附加到的向量存储的 ID。

地位

字符串

矢量存储文件的状态，可以是、、或。状态指示矢量存储文件已准备就绪，可供使用。in_progresscompletedcancelledfailedcompleted

last_error

object 或 null

与此 vector store 文件关联的最后一个错误。如果没有错误，则会是。null

chunking_strategy

对象

用于对文件进行分块的策略。

OBJECT 向量存储文件对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "id": "file-abc123",
  "object": "vector_store.file",
  "usage_bytes": 1234,
  "created_at": 1698107661,
  "vector_store_id": "vs_abc123",
  "status": "completed",
  "last_error": null,
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 800,
      "chunk_overlap_tokens": 400
    }
  }
}

矢量存储文件批处理
试用版

向量存储文件批次表示将多个文件添加到向量存储的操作。相关指南：文件搜索

创建矢量存储文件批处理
试用版

帖子 https://api.openai.com/v1/vector_stores/{vector_store_id}/file_batches

创建向量存储文件批处理。

路径参数

vector_store_id

字符串

必填

要为其创建 File Batch 的向量存储的 ID。

请求正文

file_ids

数组

必填

矢量存储应使用的文件 ID 列表。对于可以访问文件的工具很有用。file_search

chunking_strategy

对象

自选

用于对文件进行分块的分块策略。如果未设置，将使用该策略。auto

矢量存储文件批处理对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json \
    -H "OpenAI-Beta: assistants=v2" \
    -d '{
      "file_ids": ["file-abc123", "file-abc456"]
    }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store_file_batch = client.beta.vector_stores.file_batches.create(
  vector_store_id="vs_abc123",
  file_ids=["file-abc123", "file-abc456"]
)
print(vector_store_file_batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const myVectorStoreFileBatch = await openai.beta.vectorStores.fileBatches.create(
    "vs_abc123",
    {
      file_ids: ["file-abc123", "file-abc456"]
    }
  );
  console.log(myVectorStoreFileBatch);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}

检索向量存储文件批处理
试用版

获取 https://api.openai.com/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}

检索向量存储文件批次。

路径参数

vector_store_id

字符串

必填

文件批次所属的向量存储的 ID。

batch_id

字符串

必填

正在检索的文件批处理的 ID。

矢量存储文件批处理对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store_file_batch = client.beta.vector_stores.file_batches.retrieve(
  vector_store_id="vs_abc123",
  batch_id="vsfb_abc123"
)
print(vector_store_file_batch)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStoreFileBatch = await openai.beta.vectorStores.fileBatches.retrieve(
    "vs_abc123",
    "vsfb_abc123"
  );
  console.log(vectorStoreFileBatch);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}

取消向量存储文件批处理
试用版

post https://api.openai.com/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

取消矢量存储文件批处理。这将尝试尽快取消此批处理中的文件的处理。

路径参数

vector_store_id

字符串

必填

文件批次所属的向量存储的 ID。

batch_id

字符串

必填

要取消的文件批次的 ID。

修改后的 vector store file 批处理对象。

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X POST

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

deleted_vector_store_file_batch = client.beta.vector_stores.file_batches.cancel(
    vector_store_id="vs_abc123",
    file_batch_id="vsfb_abc123"
)
print(deleted_vector_store_file_batch)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const deletedVectorStoreFileBatch = await openai.vector_stores.fileBatches.cancel(
    "vs_abc123",
    "vsfb_abc123"
  );
  console.log(deletedVectorStoreFileBatch);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "cancelling",
  "file_counts": {
    "in_progress": 12,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 15,
  }
}

批量列出向量存储文件
试用版

获取 https://api.openai.com/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files

返回批量向量存储文件的列表。

路径参数

vector_store_id

字符串

必填

文件所属的矢量存储的 ID。

batch_id

字符串

必填

文件所属的文件批次的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

滤波器

字符串

自选

按文件状态筛选。、、、、中的一个。in_progresscompletedfailedcancelled

矢量存储文件对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

vector_store_files = client.beta.vector_stores.file_batches.list_files(
  vector_store_id="vs_abc123",
  batch_id="vsfb_abc123"
)
print(vector_store_files)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const vectorStoreFiles = await openai.beta.vectorStores.fileBatches.listFiles(
    "vs_abc123",
    "vsfb_abc123"
  );
  console.log(vectorStoreFiles);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    },
    {
      "id": "file-abc456",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

向量存储文件批处理对象
试用版

附加到向量存储的一批文件。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .vector_store.file_batch

created_at

整数

创建向量存储文件批处理时的 Unix 时间戳（以秒为单位）。

vector_store_id

字符串

File 附加到的向量存储的 ID。

地位

字符串

向量存储文件批处理的状态，可以是、或。in_progresscompletedcancelledfailed

file_counts

对象

OBJECT 向量存储文件批处理对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "vsfb_123",
  "object": "vector_store.files_batch",
  "created_at": 1698107661,
  "vector_store_id": "vs_abc123",
  "status": "completed",
  "file_counts": {
    "in_progress": 0,
    "completed": 100,
    "failed": 0,
    "cancelled": 0,
    "total": 100
  }
}

流
试用版

流式传输执行 Run 的结果或在提交工具输出后恢复 Run。您可以通过传递 .响应将是 Server-Sent 事件流。我们的 Node 和 Python SDK 提供了有用的实用程序，使流式传输变得容易。请参阅 Assistants API 快速入门以了解更多信息。"stream": true

消息 delta 对象
试用版

表示消息增量，即流式处理期间消息上的任何更改字段。

身份证

字符串

消息的标识符，可在 API 端点中引用。

对象

字符串

对象类型，始终为 .thread.message.delta

三角洲

对象

包含 Message 上已更改的字段的增量。

OBJECT 消息 delta 对象

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "msg_123",
  "object": "thread.message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": { "value": "Hello", "annotations": [] }
      }
    ]
  }
}

run step delta 对象
试用版

表示运行步骤增量，即流式处理期间运行步骤上任何更改的字段。

身份证

字符串

运行步骤的标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run.step.delta

三角洲

对象

包含在 run 步骤中已更改的字段的 delta。

OBJECT 运行步骤 delta 对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "id": "step_123",
  "object": "thread.run.step.delta",
  "delta": {
    "step_details": {
      "type": "tool_calls",
      "tool_calls": [
        {
          "index": 0,
          "id": "call_123",
          "type": "code_interpreter",
          "code_interpreter": { "input": "", "outputs": [] }
        }
      ]
    }
  }
}

Google 助理直播活动
试用版

表示流式传输 Run 时发出的事件。

服务器发送的事件流中的每个事件都有一个 and 属性：eventdata

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

每当创建新对象、转换到新状态或正在分部分流式传输（delta）。例如，当新运行、运行完成时创建，依此类推。当 Assistant 选择为了在运行期间创建消息，我们发出 A、A Event、Many Events，最后发出 Event。thread.run.createdthread.run.completedthread.message.created eventthread.message.in_progressthread.message.deltathread.message.completed

随着时间的推移，我们可能会添加其他事件，因此我们建议妥善处理未知事件在你的代码中。请参阅 Assistants API 快速入门，了解如何将 Assistants API 与流式处理集成。

thread.created 文件

data是一个线程

在创建新线程时发生。

thread.run.created

data是一次运行

在创建新运行时发生。

thread.run.queued

data是一次运行

当运行移动到某种状态时发生。queued

thread.run.in_progress

data是一次运行

当运行移动到某种状态时发生。in_progress

thread.run.requires_action

data是一次运行

当运行移动到某种状态时发生。requires_action

thread.run.completed

data是一次运行

在运行完成时发生。

thread.run.incomplete

data是一次运行

当运行以 status 结束时发生。incomplete

thread.run.failed

data是一次运行

在运行失败时发生。

thread.run.cancelling

data是一次运行

当运行移动到某种状态时发生。cancelling

thread.run.cancelled 的

data是一次运行

在取消运行时发生。

thread.run.expired 的

data是一次运行

在运行过期时发生。

thread.run.step.created

data是运行步骤

在创建运行步骤时发生。

thread.run.step.in_progress

data是运行步骤

当运行步骤移动到某种状态时发生。in_progress

thread.run.step.delta

data是运行步骤增量

在流式传输运行步骤的某些部分时发生。

thread.run.step.completed

data是运行步骤

在运行步骤完成时发生。

thread.run.step.failed

data是运行步骤

当运行步骤失败时发生。

thread.run.step.cancelled 的

data是运行步骤

在取消运行步骤时发生。

thread.run.step.expired

data是运行步骤

当运行步骤过期时发生。

thread.message.created

data是一条消息

在创建消息时发生。

thread.message.in_progress

data是一条消息

当消息移动到某种状态时发生。in_progress

线程消息.delta

data是消息增量

在流式传输 Message 的某些部分时发生。

thread.message.completed

data是一条消息

在消息完成时发生。

thread.message.incomplete

data是一条消息

当消息在完成之前结束时出现。

错误

data是错误

发生错误时回调。这可能是由于内部服务器错误或超时而发生的。

做

data是[DONE]

在流结束时发生。

管理

以编程方式管理您的组织。的 Audit Logs 端点提供组织中出于安全和监控目的而采取的所有操作的日志。要访问这些终端节点，请通过 API 平台组织概述生成管理员 API 密钥。Admin API 密钥不能用于非管理终端节点。有关设置组织的最佳实践，请参阅本指南

邀请

邀请和管理组织的邀请。受邀用户将自动添加到 Default 项目中。

列出邀请

获取 https://api.openai.com/v1/organization/invites

返回组织中的邀请列表。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

Invite 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
  "object": "list",
  "data": [
    {
      "object": "organization.invite",
      "id": "invite-abc",
      "email": "user@example.com",
      "role": "owner",
      "status": "accepted",
      "invited_at": 1711471533,
      "expires_at": 1711471533,
      "accepted_at": 1711471533
    }
  ],
  "first_id": "invite-abc",
  "last_id": "invite-abc",
  "has_more": false
}

创建邀请

帖子 https://api.openai.com/v1/organization/invites

为用户创建组织邀请。用户必须先接受邀请，然后才能访问组织。

请求正文

电子邮件

字符串

必填

向此地址发送电子邮件

角色

字符串

必填

owner或reader

创建的 Invite 对象。

示例请求

1
2
3
4
5
6
7
curl -X POST https://api.openai.com/v1/organization/invites \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "email": "user@example.com",
      "role": "owner"
  }'

响应

{
    "object": "organization.invite",
    "id": "invite-abc",
    "email": "user@example.com",
    "role": "owner",
    "invited_at": 1711471533,
    "expires_at": 1711471533,
    "accepted_at": null
}

检索邀请

获取 https://api.openai.com/v1/organization/invites/{invite_id}

检索邀请。

路径参数

invite_id

字符串

必填

要检索的邀请的 ID。

与指定 ID 匹配的 Invite 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/invites/invite-abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.invite",
    "id": "invite-abc",
    "email": "user@example.com",
    "role": "owner",
    "status": "accepted",
    "invited_at": 1711471533,
    "expires_at": 1711471533,
    "accepted_at": 1711471533
}

删除邀请

删除 https://api.openai.com/v1/organization/invites/{invite_id}

删除邀请。如果邀请已被接受，则无法删除。

路径参数

invite_id

字符串

必填

要删除的邀请的 ID。

确认邀请已被删除

示例请求

1
2
3
curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.invite.deleted",
    "id": "invite-abc",
    "deleted": true
}

invite 对象

在组织中代表个人。invite

对象

字符串

对象类型，始终为organization.invite

身份证

字符串

标识符，可在 API 端点中引用

电子邮件

字符串

接收邀请的个人的电子邮件地址

角色

字符串

owner或reader

地位

字符串

accepted或expiredpending

invited_at

整数

发送邀请时的 Unix 时间戳（以秒为单位）。

expires_at

整数

邀请过期的 Unix 时间戳（以秒为单位）。

accepted_at

整数

接受邀请时的 Unix 时间戳（以秒为单位）。

OBJECT 邀请对象

1
2
3
4
5
6
7
8
9
10
{
  "object": "organization.invite",
  "id": "invite-abc",
  "email": "user@example.com",
  "role": "owner",
  "status": "accepted",
  "invited_at": 1711471533,
  "expires_at": 1711471533,
  "accepted_at": 1711471533
}

用户

管理用户及其在组织中的角色。用户将自动添加到 Default 项目。

列出用户

获取 https://api.openai.com/v1/organization/users

列出组织中的所有用户。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

User 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "list",
    "data": [
        {
            "object": "organization.user",
            "id": "user_abc",
            "name": "First Last",
            "email": "user@example.com",
            "role": "owner",
            "added_at": 1711471533
        }
    ],
    "first_id": "user-abc",
    "last_id": "user-xyz",
    "has_more": false
}

修改用户

帖子 https://api.openai.com/v1/organization/users/{user_id}

修改用户在组织中的角色。

路径参数

user_id

字符串

必填

用户的 ID。

请求正文

角色

字符串

必填

owner或reader

更新的 User 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "owner"
  }'

响应

{
    "object": "organization.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

检索用户

获取 https://api.openai.com/v1/organization/users/{user_id}

按用户的标识符检索用户。

路径参数

user_id

字符串

必填

用户的 ID。

与指定 ID 匹配的 User 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

删除用户

删除 https://api.openai.com/v1/organization/users/{user_id}

从组织中删除用户。

路径参数

user_id

字符串

必填

用户的 ID。

确认已删除的用户

示例请求

1
2
3
curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.user.deleted",
    "id": "user_abc",
    "deleted": true
}

用户对象

表示组织内的个人。user

对象

字符串

对象类型，始终为organization.user

身份证

字符串

标识符，可在 API 端点中引用

名字

字符串

用户的名称

电子邮件

字符串

用户的电子邮件地址

角色

字符串

owner或reader

added_at

整数

添加用户时的 Unix 时间戳（以秒为单位）。

OBJECT 用户对象

1
2
3
4
5
6
7
8
{
    "object": "organization.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

项目

管理组织内的项目包括创建、更新和存档或项目。 Default 项目无法修改或存档。

列出项目

获取 https://api.openai.com/v1/organization/projects

返回项目列表。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

include_archived

布尔

自选

默认为 false

If 返回所有项目，包括那些已经 .默认情况下，不包括已存档的项目。truearchived

Project 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "list",
    "data": [
        {
            "id": "proj_abc",
            "object": "organization.project",
            "name": "Project example",
            "created_at": 1711471533,
            "archived_at": null,
            "status": "active"
        }
    ],
    "first_id": "proj-abc",
    "last_id": "proj-xyz",
    "has_more": false
}

创建项目

帖子 https://api.openai.com/v1/organization/projects

在组织中创建新项目。可以创建和存档项目，但不能删除项目。

请求正文

名字

字符串

必填

项目的友好名称，此名称显示在报表中。

创建的 Project 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/projects \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Project ABC"
  }'

响应

{
    "id": "proj_abc",
    "object": "organization.project",
    "name": "Project ABC",
    "created_at": 1711471533,
    "archived_at": null,
    "status": "active"
}

检索项目

获取 https://api.openai.com/v1/organization/projects/{project_id}

检索项目。

路径参数

project_id

字符串

必填

项目的 ID。

与指定 ID 匹配的 Project 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "id": "proj_abc",
    "object": "organization.project",
    "name": "Project example",
    "created_at": 1711471533,
    "archived_at": null,
    "status": "active"
}

修改项目

帖子 https://api.openai.com/v1/organization/projects/{project_id}

修改组织中的项目。

路径参数

project_id

字符串

必填

项目的 ID。

请求正文

名字

字符串

必填

项目的更新名称，此名称显示在报表中。

更新的 Project 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Project DEF"
  }'

存档项目

post https://api.openai.com/v1/organization/projects/{project_id}/archive

存档组织中的项目。存档的项目不能使用或更新。

路径参数

project_id

字符串

必填

项目的 ID。

存档的 Project 对象。

示例请求

1
2
3
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "id": "proj_abc",
    "object": "organization.project",
    "name": "Project DEF",
    "created_at": 1711471533,
    "archived_at": 1711471533,
    "status": "archived"
}

项目对象

表示单个项目。

身份证

字符串

标识符，可在 API 端点中引用

对象

字符串

对象类型，始终为organization.project

名字

字符串

项目的名称。这将显示在报表中。

created_at

整数

创建项目时的 Unix 时间戳（以秒为单位）。

archived_at

整数或 null

项目存档时的 Unix 时间戳（以秒为单位）或 .null

地位

字符串

active或archived

OBJECT 项目对象

1
2
3
4
5
6
7
8
{
    "id": "proj_abc",
    "object": "organization.project",
    "name": "Project example",
    "created_at": 1711471533,
    "archived_at": null,
    "status": "active"
}

项目用户

管理项目中的用户，包括添加、更新角色和删除用户。除非将用户从组织中删除，否则无法从 Default 项目中删除用户。

列出项目用户

获取 https://api.openai.com/v1/organization/projects/{project_id}/users

返回项目中的用户列表。

路径参数

project_id

字符串

必填

项目的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

ProjectUser 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "list",
    "data": [
        {
            "object": "organization.project.user",
            "id": "user_abc",
            "name": "First Last",
            "email": "user@example.com",
            "role": "owner",
            "added_at": 1711471533
        }
    ],
    "first_id": "user-abc",
    "last_id": "user-xyz",
    "has_more": false
}

创建项目用户

post https://api.openai.com/v1/organization/projects/{project_id}/users

将用户添加到项目中。用户必须已经是要添加到工程中的组织的成员。

路径参数

project_id

字符串

必填

项目的 ID。

请求正文

user_id

字符串

必填

用户的 ID。

角色

字符串

必填

owner或member

创建的 ProjectUser 对象。

示例请求

1
2
3
4
5
6
7
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "user_id": "user_abc",
      "role": "member"
  }'

响应

{
    "object": "organization.project.user",
    "id": "user_abc",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

检索项目用户

获取 https://api.openai.com/v1/organization/projects/{project_id}/users/{user_id}

检索项目中的用户。

路径参数

project_id

字符串

必填

项目的 ID。

user_id

字符串

必填

用户的 ID。

与指定 ID 匹配的 ProjectUser 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

修改项目用户

帖子 https://api.openai.com/v1/organization/projects/{project_id}/users/{user_id}

修改用户在项目中的角色。

路径参数

project_id

字符串

必填

项目的 ID。

user_id

字符串

必填

用户的 ID。

请求正文

角色

字符串

必填

owner或member

更新的 ProjectUser 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "owner"
  }'

响应

{
    "object": "organization.project.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

删除项目用户

删除 https://api.openai.com/v1/organization/projects/{project_id}/users/{user_id}

从项目中删除用户。

路径参数

project_id

字符串

必填

项目的 ID。

user_id

字符串

必填

用户的 ID。

确认项目已被删除或已存档项目（没有用户）出错

示例请求

1
2
3
curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.user.deleted",
    "id": "user_abc",
    "deleted": true
}

项目用户对象

表示项目中的单个用户。

对象

字符串

对象类型，始终为organization.project.user

身份证

字符串

标识符，可在 API 端点中引用

名字

字符串

用户的名称

电子邮件

字符串

用户的电子邮件地址

角色

字符串

owner或member

added_at

整数

添加项目时的 Unix 时间戳（以秒为单位）。

OBJECT 项目用户对象

1
2
3
4
5
6
7
8
{
    "object": "organization.project.user",
    "id": "user_abc",
    "name": "First Last",
    "email": "user@example.com",
    "role": "owner",
    "added_at": 1711471533
}

Project 服务帐户

管理项目中的服务帐户。服务帐户是未与用户关联的机器人用户。如果用户离开组织，他们在项目中的密钥和成员资格将不再有效。服务账户没有此限制。但是，也可以从项目中删除服务帐户。

列出项目服务帐户

获取 https://api.openai.com/v1/organization/projects/{project_id}/service_accounts

返回项目中的服务账户列表。

路径参数

project_id

字符串

必填

项目的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

ProjectServiceAccount 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "list",
    "data": [
        {
            "object": "organization.project.service_account",
            "id": "svc_acct_abc",
            "name": "Service Account",
            "role": "owner",
            "created_at": 1711471533
        }
    ],
    "first_id": "svc_acct_abc",
    "last_id": "svc_acct_xyz",
    "has_more": false
}

创建 Project Service 帐户

帖子 https://api.openai.com/v1/organization/projects/{project_id}/service_accounts

在项目中创建新的服务账户。这还会返回服务账户的未编辑 API 密钥。

路径参数

project_id

字符串

必填

项目的 ID。

请求正文

名字

字符串

必填

正在创建的服务帐户的名称。

创建的 ProjectServiceAccount 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Production App"
  }'

响应

{
    "object": "organization.project.service_account",
    "id": "svc_acct_abc",
    "name": "Production App",
    "role": "member",
    "created_at": 1711471533,
    "api_key": {
        "object": "organization.project.service_account.api_key",
        "value": "sk-abcdefghijklmnop123",
        "name": "Secret Key",
        "created_at": 1711471533,
        "id": "key_abc"
    }
}

检索 Project Service 帐户

获取 https://api.openai.com/v1/organization/projects/{project_id}/service_accounts/{service_account_id}

检索项目中的服务帐户。

路径参数

project_id

字符串

必填

项目的 ID。

service_account_id

字符串

必填

服务帐户的 ID。

与指定 ID 匹配的 ProjectServiceAccount 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.service_account",
    "id": "svc_acct_abc",
    "name": "Service Account",
    "role": "owner",
    "created_at": 1711471533
}

删除 Project Service 帐户

删除 https://api.openai.com/v1/organization/projects/{project_id}/service_accounts/{service_account_id}

从项目中删除服务帐户。

路径参数

project_id

字符串

必填

项目的 ID。

service_account_id

字符串

必填

服务帐户的 ID。

确认服务帐户被删除，或者确认没有服务帐户的存档项目时出现错误

示例请求

1
2
3
curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.service_account.deleted",
    "id": "svc_acct_abc",
    "deleted": true
}

Project Service 帐户对象

表示项目中的单个服务账户。

对象

字符串

对象类型，始终为organization.project.service_account

身份证

字符串

标识符，可在 API 端点中引用

名字

字符串

服务帐户的名称

角色

字符串

owner或member

created_at

整数

创建服务账户时的 Unix 时间戳（以秒为单位）

OBJECT 项目服务帐户对象

1
2
3
4
5
6
7
{
    "object": "organization.project.service_account",
    "id": "svc_acct_abc",
    "name": "Service Account",
    "role": "owner",
    "created_at": 1711471533
}

项目 API 密钥

管理给定项目的 API 密钥。支持为用户列出和删除密钥。该接口不允许为用户发放密钥，因为用户需要自行授权才能生成密钥。

列出项目 API 密钥

获取 https://api.openai.com/v1/organization/projects/{project_id}/api_keys

返回项目中的 API 密钥列表。

路径参数

project_id

字符串

必填

项目的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

ProjectApiKey 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "list",
    "data": [
        {
            "object": "organization.project.api_key",
            "redacted_value": "sk-abc...def",
            "name": "My API Key",
            "created_at": 1711471533,
            "id": "key_abc",
            "owner": {
                "type": "user",
                "user": {
                    "object": "organization.project.user",
                    "id": "user_abc",
                    "name": "First Last",
                    "email": "user@example.com",
                    "role": "owner",
                    "added_at": 1711471533
                }
            }
        }
    ],
    "first_id": "key_abc",
    "last_id": "key_xyz",
    "has_more": false
}

检索项目 API 密钥

获取 https://api.openai.com/v1/organization/projects/{project_id}/api_keys/{key_id}

检索项目中的 API 密钥。

路径参数

project_id

字符串

必填

项目的 ID。

key_id

字符串

必填

API 密钥的 ID。

与指定 ID 匹配的 ProjectApiKey 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.api_key",
    "redacted_value": "sk-abc...def",
    "name": "My API Key",
    "created_at": 1711471533,
    "id": "key_abc",
    "owner": {
        "type": "user",
        "user": {
            "object": "organization.project.user",
            "id": "user_abc",
            "name": "First Last",
            "email": "user@example.com",
            "role": "owner",
            "added_at": 1711471533
        }
    }
}

删除项目 API 密钥

删除 https://api.openai.com/v1/organization/projects/{project_id}/api_keys/{key_id}

从项目中删除 API 密钥。

路径参数

project_id

字符串

必填

项目的 ID。

key_id

字符串

必填

API 密钥的 ID。

确认密钥已删除，如果密钥属于服务账户，则显示错误

示例请求

1
2
3
curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

{
    "object": "organization.project.api_key.deleted",
    "id": "key_abc",
    "deleted": true
}

项目 API 密钥对象

表示项目中的单个 API 密钥。

对象

字符串

对象类型，始终为organization.project.api_key

redacted_value

字符串

API 密钥的隐去值

名字

字符串

API 密钥的名称

created_at

整数

创建 API 密钥时的 Unix 时间戳（以秒为单位）

身份证

字符串

标识符，可在 API 端点中引用

所有者

对象

OBJECT 项目 API 密钥对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "object": "organization.project.api_key",
    "redacted_value": "sk-abc...def",
    "name": "My API Key",
    "created_at": 1711471533,
    "id": "key_abc",
    "owner": {
        "type": "user",
        "user": {
            "object": "organization.project.user",
            "id": "user_abc",
            "name": "First Last",
            "email": "user@example.com",
            "role": "owner",
            "created_at": 1711471533
        }
    }
}

项目速率限制

管理项目的每个模型的速率限制。速率限制可以配置为等于或低于组织的速率限制。

列出项目速率限制

获取 https://api.openai.com/v1/organization/projects/{project_id}/rate_limits

返回项目的每个模型的速率限制。

路径参数

project_id

字符串

必填

项目的 ID。

查询参数

限制

整数

自选

默认为 100

要返回的对象数量限制。默认值为 100。

后

字符串

自选

以前

字符串

自选

用于分页的游标。是定义您在列表中的位置的对象 ID。例如，如果您发出列表请求并收到 100 个对象（以 obj_foo 开头），则后续调用可以包含 before=obj_foo 以便获取列表的上一页。before

ProjectRateLimit 对象的列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "object": "list",
    "data": [
        {
          "object": "project.rate_limit",
          "id": "rl-ada",
          "model": "ada",
          "max_requests_per_1_minute": 600,
          "max_tokens_per_1_minute": 150000,
          "max_images_per_1_minute": 10
        }
    ],
    "first_id": "rl-ada",
    "last_id": "rl-ada",
    "has_more": false
}

修改项目速率限制

帖子 https://api.openai.com/v1/organization/projects/{project_id}/rate_limits/{rate_limit_id}

更新项目速率限制。

路径参数

project_id

字符串

必填

项目的 ID。

rate_limit_id

字符串

必填

速率限制的 ID。

请求正文

max_requests_per_1_minute

整数

自选

每分钟的最大请求数。

max_tokens_per_1_minute

整数

自选

每分钟的最大令牌数。

max_images_per_1_minute

整数

自选

每分钟的最大图像数。仅与某些模型相关。

max_audio_megabytes_per_1_minute

整数

自选

每分钟的最大音频兆字节数。仅与某些模型相关。

max_requests_per_1_day

整数

自选

每天的最大请求数。仅与某些模型相关。

batch_1_day_max_input_tokens

整数

自选

每天的最大批量输入令牌数。仅与某些模型相关。

更新的 ProjectRateLimit 对象。

示例请求

1
2
3
4
5
6
curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "max_requests_per_1_minute": 500
  }'

响应

1
2
3
4
5
6
7
8
{
    "object": "project.rate_limit",
    "id": "rl-ada",
    "model": "ada",
    "max_requests_per_1_minute": 600,
    "max_tokens_per_1_minute": 150000,
    "max_images_per_1_minute": 10
  }

项目速率限制对象

表示项目速率限制配置。

对象

字符串

对象类型，始终为project.rate_limit

身份证

字符串

标识符，可在 API 终端节点中引用。

MODEL

字符串

此速率限制适用的模型。

max_requests_per_1_minute

整数

每分钟的最大请求数。

max_tokens_per_1_minute

整数

每分钟的最大令牌数。

max_images_per_1_minute

整数

每分钟的最大图像数。仅对相关模型显示。

max_audio_megabytes_per_1_minute

整数

每分钟的最大音频兆字节数。仅对相关模型显示。

max_requests_per_1_day

整数

每天的最大请求数。仅对相关模型显示。

batch_1_day_max_input_tokens

整数

每天的最大批量输入令牌数。仅对相关模型显示。

OBJECT 项目速率限制对象

1
2
3
4
5
6
7
8
{
    "object": "project.rate_limit",
    "id": "rl_ada",
    "model": "ada",
    "max_requests_per_1_minute": 600,
    "max_tokens_per_1_minute": 150000,
    "max_images_per_1_minute": 10
}

审核日志

此组织内的用户操作和配置更改的日志。要记录事件，您必须在 Organization Settings （组织设置）中激活日志记录。激活后，出于安全原因，无法停用日志记录。

列出审核日志

获取 https://api.openai.com/v1/organization/audit_logs

列出此组织内的用户操作和配置更改。

查询参数

effective_at

对象

自选

仅返回（Unix 秒）在此范围内的事件。effective_at

project_ids

数组

自选

仅返回这些项目的事件。

event_types

数组

自选

仅返回其中一个值中具有 a 的事件。例如。有关所有选项，请参阅审核日志对象的文档。typeproject.created

actor_ids

数组

自选

仅返回这些 actor 执行的事件。可以是用户 ID、服务账户 ID 或 API 密钥跟踪 ID。

actor_emails

数组

自选

仅返回用户使用这些电子邮件执行的事件。

resource_ids

数组

自选

仅返回对这些目标执行的事件。例如，更新了项目 ID。

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

后

字符串

自选

以前

字符串

自选

分页的 Audit Log 对象列表。

示例请求

1
2
3
curl https://api.openai.com/v1/organization/audit_logs \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

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
{
    "object": "list",
    "data": [
        {
            "id": "audit_log-xxx_yyyymmdd",
            "type": "project.archived",
            "effective_at": 1722461446,
            "actor": {
                "type": "api_key",
                "api_key": {
                    "type": "user",
                    "user": {
                        "id": "user-xxx",
                        "email": "user@example.com"
                    }
                }
            },
            "project.archived": {
                "id": "proj_abc"
            },
        },
        {
            "id": "audit_log-yyy__20240101",
            "type": "api_key.updated",
            "effective_at": 1720804190,
            "actor": {
                "type": "session",
                "session": {
                    "user": {
                        "id": "user-xxx",
                        "email": "user@example.com"
                    },
                    "ip_address": "127.0.0.1",
                    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
                }
            },
            "api_key.updated": {
                "id": "key_xxxx",
                "data": {
                    "scopes": ["resource_2.operation_2"]
                }
            },
        }
    ],
    "first_id": "audit_log-xxx__20240101",
    "last_id": "audit_log_yyy__20240101",
    "has_more": true
}

审核日志对象

此组织内的用户操作或配置更改的日志。

身份证

字符串

此日志的 ID。

类型

字符串

事件类型。

effective_at

整数

事件的 Unix 时间戳（以秒为单位）。

项目

对象

操作范围限定到的项目。对于范围不限定为项目的操作，不存在。

演员

对象

执行 audit logged 操作的操作者。

api_key.created

对象

具有此 .type

api_key.updated

对象

具有此 .type

api_key.deleted

对象

具有此 .type

邀请.sent

对象

具有此 .type

invite.accepted

对象

具有此 .type

invite.deleted

对象

具有此 .type

对象

具有此 .type

logout.failed

对象

具有此 .type

组织 .updated

对象

具有此 .type

项目创建文件

对象

具有此 .type

project.updated

对象

具有此 .type

project.archived 文件

对象

具有此 .type

rate_limit.updated

对象

具有此 .type

rate_limit.deleted

对象

具有此 .type

service_account.created

对象

具有此 .type

service_account.updated

对象

具有此 .type

service_account.deleted

对象

具有此 .type

已添加 user.added

对象

具有此 .type

user.updated

对象

具有此 .type

用户.deleted

对象

具有此 .type

OBJECT 审核日志对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "id": "req_xxx_20240101",
    "type": "api_key.created",
    "effective_at": 1720804090,
    "actor": {
        "type": "session",
        "session": {
            "user": {
                "id": "user-xxx",
                "email": "user@example.com"
            },
            "ip_address": "127.0.0.1",
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
        }
    },
    "api_key.created": {
        "id": "key_xxxx",
        "data": {
            "scopes": ["resource.operation"]
        }
    }
}

用法

使用情况 API 提供了有关您在 OpenAI API 中的活动的详细见解。它还包括一个单独的成本终端节点，可让您了解支出，按发票行项目和项目 ID 细分消费。

虽然 Usage API 提供了精细的使用情况数据，但由于使用情况和支出的记录方式存在细微差异，它可能并不总是与 Costs 完全一致。出于财务目的，我们建议使用 Costs 端点或 Usage Dashboard 中的 Costs 选项卡，这将核对回您的账单发票。

完成

获取 https://api.openai.com/v1/organization/usage/completions

获取组织的完成项使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

Batch

布尔

自选

如果，则仅返回批处理作业。如果，则仅返回非批处理作业。默认情况下，同时返回两者。truefalse

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、、或它们的任意组合。project_iduser_idapi_key_idmodelbatch

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Completions 使用对象的列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

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
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.completions.result",
                    "input_tokens": 1000,
                    "output_tokens": 500,
                    "input_cached_tokens": 800,
                    "num_model_requests": 5,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null,
                    "batch": null
                }
            ]
        }
    ],
    "has_more": true,
    "next_page": "AAAAAGdGxdEiJdKOAAAAAGcqsYA="
}

Completions 使用对象

特定时间存储桶的聚合完成使用情况详细信息。

对象

字符串

input_tokens

整数

使用的输入令牌的聚合数量。对于订阅 Scale Tier 的客户，这包括 Scale Tier 令牌。

input_cached_tokens

整数

从以前的请求中缓存的输入令牌的聚合数。对于订阅 Scale Tier 的客户，这包括 Scale Tier 令牌。

output_tokens

整数

使用的输出令牌的聚合数量。对于订阅 Scale Tier 的客户，这包括 Scale Tier 令牌。

num_model_requests

整数

对模型发出的请求计数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

Batch

boolean 或 null

When ，此字段指示分组的使用结果是否为 batch。group_by=batch

OBJECT Completions 使用对象

1
2
3
4
5
6
7
8
9
10
11
12
{
    "object": "organization.usage.completions.result",
    "input_tokens": 5000,
    "output_tokens": 1000,
    "input_cached_tokens": 4000,
    "num_model_requests": 5,
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "gpt-4o-mini-2024-07-18",
    "batch": false
}

Embeddings

获取 https://api.openai.com/v1/organization/usage/embeddings

获取组织的嵌入使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、或它们的任意组合。project_iduser_idapi_key_idmodel

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Embeddings 使用对象的列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.embeddings.result",
                    "input_tokens": 16,
                    "num_model_requests": 2,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Embeddings 使用对象

聚合的嵌入使用时间 Bucket 的使用情况详细信息。

对象

字符串

input_tokens

整数

使用的输入令牌的聚合数量。

num_model_requests

整数

对模型发出的请求计数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

OBJECT 嵌入使用对象

1
2
3
4
5
6
7
8
9
{
    "object": "organization.usage.embeddings.result",
    "input_tokens": 20,
    "num_model_requests": 2,
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "text-embedding-ada-002-v2"
}

审核

获取 https://api.openai.com/v1/organization/usage/moderations

获取组织的审核使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、或它们的任意组合。project_iduser_idapi_key_idmodel

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Moderations 使用对象列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.moderations.result",
                    "input_tokens": 16,
                    "num_model_requests": 2,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Moderations usage 对象

特定时间存储桶的聚合审核使用情况详细信息。

对象

字符串

input_tokens

整数

使用的输入令牌的聚合数量。

num_model_requests

整数

对模型发出的请求计数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

OBJECT Moderations 使用对象

1
2
3
4
5
6
7
8
9
{
    "object": "organization.usage.moderations.result",
    "input_tokens": 20,
    "num_model_requests": 2,
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "text-moderation"
}

图像

获取 https://api.openai.com/v1/organization/usage/images

获取组织的映像使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

来源

数组

自选

仅返回这些源的用法。可能的值为、或它们的任意组合。image.generationimage.editimage.variation

大小

数组

自选

仅返回这些图像大小的用法。可能的值为、、、或它们的任意组合。256x256512x5121024x10241792x17921024x1792

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、、、或它们的任意组合。project_iduser_idapi_key_idmodelsizesource

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Images 使用对象列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

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
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.images.result",
                    "images": 2,
                    "num_model_requests": 2,
                    "size": null,
                    "source": null,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Images usage 对象

特定时间桶的聚合图像使用详情。

对象

字符串

图像

整数

处理的图像数量。

num_model_requests

整数

对模型发出的请求计数。

源

string 或 null

当时，此字段提供分组使用结果的来源，可能的值为、、。group_by=sourceimage.generationimage.editimage.variation

大小

string 或 null

当时，此字段提供分组使用结果的图像大小。group_by=size

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

OBJECT 图像使用对象

1
2
3
4
5
6
7
8
9
10
11
{
    "object": "organization.usage.images.result",
    "images": 2,
    "num_model_requests": 2,
    "size": "1024x1024",
    "source": "image.generation",
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "dall-e-3"
}

音频演讲

获取 https://api.openai.com/v1/organization/usage/audio_speeches

获取组织的音频语音使用详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、或它们的任意组合。project_iduser_idapi_key_idmodel

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Audio speeches 使用对象列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.audio_speeches.result",
                    "characters": 45,
                    "num_model_requests": 1,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Audio speeches 使用对象

特定时间桶的聚合音频语音使用详细信息。

对象

字符串

字符

整数

处理的字符数。

num_model_requests

整数

对模型发出的请求计数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

OBJECT Audio speeches usage 对象

1
2
3
4
5
6
7
8
9
{
    "object": "organization.usage.audio_speeches.result",
    "characters": 45,
    "num_model_requests": 1,
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "tts-1"
}

音频转录

获取 https://api.openai.com/v1/organization/usage/audio_transcriptions

获取组织的音频转录使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

user_ids

数组

自选

仅返回这些用户的使用情况。

api_key_ids

数组

自选

仅返回这些 API 密钥的用法。

模型

数组

自选

仅返回这些模型的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括、、或它们的任意组合。project_iduser_idapi_key_idmodel

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的音频转录使用对象列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.audio_transcriptions.result",
                    "seconds": 20,
                    "num_model_requests": 1,
                    "project_id": null,
                    "user_id": null,
                    "api_key_id": null,
                    "model": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Audio transcriptions usage 对象

特定时间存储桶的聚合音频转录使用情况详细信息。

对象

字符串

秒

整数

处理的秒数。

num_model_requests

整数

对模型发出的请求计数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

user_id

string 或 null

当时，此字段提供分组使用结果的用户 ID。group_by=user_id

api_key_id

string 或 null

当时，此字段提供分组使用结果的 API 密钥 ID。group_by=api_key_id

MODEL

string 或 null

当时，此字段提供分组使用结果的模型名称。group_by=model

OBJECT 音频转录使用对象

1
2
3
4
5
6
7
8
9
{
    "object": "organization.usage.audio_transcriptions.result",
    "seconds": 10,
    "num_model_requests": 1,
    "project_id": "proj_abc",
    "user_id": "user-abc",
    "api_key_id": "key_abc",
    "model": "tts-1"
}

矢量存储

获取 https://api.openai.com/v1/organization/usage/vector_stores

获取 vector 存储组织的使用情况详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括 .project_id

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Vector 列表存储使用对象。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.vector_stores.result",
                    "usage_bytes": 1024,
                    "project_id": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Vector 存储使用对象

聚合向量存储特定时间桶的使用情况详细信息。

对象

字符串

usage_bytes

整数

向量以字节为单位存储使用情况。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

OBJECT Vector 存储使用对象

1
2
3
4
5
{
    "object": "organization.usage.vector_stores.result",
    "usage_bytes": 1024,
    "project_id": "proj_abc"
}

代码解释器会话

获取 https://api.openai.com/v1/organization/usage/code_interpreter_sessions

获取组织的 Code Interpreter 会话使用详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。当前和受支持，默认为。1m1h1d1d

project_ids

数组

自选

仅返回这些项目的使用情况。

group_by

数组

自选

按指定字段对使用情况数据进行分组。支持字段包括 .project_id

限制

整数

自选

指定要返回的存储桶数。

bucket_width=1d：默认： 7，最大： 31
bucket_width=1h：默认： 24，最大： 168
bucket_width=1m：默认值： 60，最大值： 1440

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Code 解释器会话使用对象的列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.usage.code_interpreter_sessions.result",
                    "sessions": 1,
                    "project_id": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

代码解释器会话使用对象

特定时间存储桶的聚合代码解释器会话使用情况详细信息。

对象

字符串

会话

整数

代码解释器会话数。

project_id

string 或 null

当时，此字段提供分组使用结果的项目 ID。group_by=project_id

OBJECT 代码解释器会话使用对象

1
2
3
4
5
{
    "object": "organization.usage.code_interpreter_sessions.result",
    "sessions": 1,
    "project_id": "proj_abc"
}

成本

获取 https://api.openai.com/v1/organization/costs

获取组织的成本详细信息。

查询参数

start_time

整数

必填

查询时间范围（含）的开始时间（Unix 秒）。

end_time

整数

自选

查询时间范围的结束时间（Unix 秒），不包括。

bucket_width

字符串

自选

默认为 1d

响应中每个时间桶的宽度。目前仅支持，默认为。1d1d

project_ids

数组

自选

仅返回这些项目的成本。

group_by

数组

自选

按指定字段对成本进行分组。支持字段包括以及它们的任意组合。project_idline_item

限制

整数

自选

默认为 7

要返回的存储桶数量限制。Limit 的范围可以介于 1 和 180 之间，默认值为 7。

页

字符串

自选

用于分页的游标。对应于上一个响应中的字段。next_page

分页、时间分段的 Costs 对象列表。

示例请求

1
2
3
curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.costs.result",
                    "amount": {
                        "value": 0.06,
                        "currency": "usd"
                    },
                    "line_item": null,
                    "project_id": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

costs 对象

特定时间桶的聚合成本详细信息。

对象

字符串

量

对象

以关联货币表示的货币价值。

line_item

string 或 null

When ，此字段提供分组成本结果的行项目。group_by=line_item

project_id

string 或 null

当时，此字段提供分组成本结果的项目 ID。group_by=project_id

OBJECT Costs 对象

1
2
3
4
5
6
7
8
9
{
    "object": "organization.costs.result",
    "amount": {
      "value": 0.06,
      "currency": "usd"
    },
    "line_item": "Image models",
    "project_id": "proj_abc"
}

实时
试用版

通过 WebSocket 与 GPT-4o 类模型实时通信。生成音频和文本转录。详细了解 Realtime API。

客户端事件

这些是 OpenAI Realtime WebSocket 服务器将从客户端接受的事件。

会话更新

发送此事件以更新会话的默认配置。客户可以随时发送此事件以更新会话配置，以及任何字段可能随时更新，但 “voice” 除外。服务器将响应替换为一个显示完整有效配置的事件。只有存在的字段才会更新，因此清除字段（如 “instructions” ）用于传递空字符串。session.updated

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。session.update

会期

对象

实时会话对象配置。

对象 session.update

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
{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "modalities": ["text", "audio"],
        "instructions": "You are a helpful assistant.",
        "voice": "sage",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "input_audio_transcription": {
            "model": "whisper-1"
        },
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "prefix_padding_ms": 300,
            "silence_duration_ms": 500
        },
        "tools": [
            {
                "type": "function",
                "name": "get_weather",
                "description": "Get the current weather...",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": { "type": "string" }
                    },
                    "required": ["location"]
                }
            }
        ],
        "tool_choice": "auto",
        "temperature": 0.8,
        "max_response_output_tokens": "inf"
    }
}

input_audio_buffer.append

发送此事件以将音频字节追加到输入音频缓冲区。音频 buffer 是您可以写入并在以后提交的临时存储。在服务器 VAD 中模式下，音频缓冲区用于检测语音，服务器将决定何时提交。禁用服务器 VAD 后，必须提交音频缓冲区手动地。

客户端可以选择在每个事件中放置多少音频，但最多可以放置多少音频的 15 MiB 中，例如，从客户端流式传输较小的数据块可能允许 VAD 的响应速度更快。与创建的其他客户端事件不同，服务器将不发送对此事件的确认响应。

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。input_audio_buffer.append

音频

字符串

Base64 编码的音频字节。这必须采用会话配置中字段指定的格式。input_audio_format

对象 input_audio_buffer.append

1
2
3
4
5
{
    "event_id": "event_456",
    "type": "input_audio_buffer.append",
    "audio": "Base64EncodedAudioData"
}

input_audio_buffer.commit

发送此事件以提交用户输入音频缓冲区，这将创建一个对话中的 New User Message 项。此事件将产生错误如果 Input Audio buffer 为空。当处于 Server VAD 模式时，客户端执行不需要发送此事件，服务器将提交音频缓冲区自然而然。

提交输入音频缓冲区将触发输入音频转录（如果在会话配置中启用），但它不会创建响应从模型中。服务器将以事件进行响应。input_audio_buffer.committed

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。input_audio_buffer.commit

对象 input_audio_buffer.commit

1
2
3
4
{
    "event_id": "event_789",
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

发送此事件以清除缓冲区中的音频字节。服务器将使用事件进行响应。input_audio_buffer.cleared

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。input_audio_buffer.clear

对象 input_audio_buffer.clear

1
2
3
4
{
    "event_id": "event_012",
    "type": "input_audio_buffer.clear"
}

conversation.item.create

向 Conversation 的上下文添加新 Item，包括 messages， function calls 和函数调用响应。此事件可用于填充 “history” 并添加新项目，但具有当前限制，它无法填充 Assistant 音频消息。

如果成功，服务器将以事件响应，否则将发送事件。conversation.item.createderror

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。conversation.item.create

previous_item_id

字符串

前一项的 ID，新项将在其后插入。如果未设置，则新项目将附加到对话的末尾。如果设置，则允许在对话中插入项目。如果 ID 找不到，则将返回错误，并且不会添加该项目。

项目

对象

要添加到对话中的项。

对象 conversation.item.create

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "event_id": "event_345",
    "type": "conversation.item.create",
    "previous_item_id": null,
    "item": {
        "id": "msg_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Hello, how are you?"
            }
        ]
    }
}

conversation.item.truncate

发送此事件可截断上一个助理消息的音频。服务器将比 RealTime 更快地生成音频，因此当用户 interrupts 截断已发送到客户端但未发送到客户端的音频但玩了。这将使服务器对音频的理解与客户端的播放。

截断音频将删除服务器端文本转录，以确保存在不是用户未听到的上下文中的文本。

如果成功，服务器将响应事件。conversation.item.truncated

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。conversation.item.truncate

item_id

字符串

需要截断的助手消息项的 ID。仅助手消息项可以截断。

content_index

整数

要截断的内容部分的索引。将此项设置为 0。

audio_end_ms

整数

非独占持续时间，最长为音频被截断的持续时间（以毫秒为单位）。如果 audio_end_ms大于实际音频持续时间，则服务器将响应错误。

对象 conversation.item.truncate

1
2
3
4
5
6
7
{
    "event_id": "event_678",
    "type": "conversation.item.truncate",
    "item_id": "msg_002",
    "content_index": 0,
    "audio_end_ms": 1500
}

conversation.item.delete

当您想从对话中删除任何项目时发送此事件历史。服务器将以事件除非该项目在对话历史记录中不存在，在这种情况下，服务器将响应错误。conversation.item.deleted

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。conversation.item.delete

item_id

字符串

要删除的项目的 ID。

对象 conversation.item.delete

1
2
3
4
5
{
    "event_id": "event_901",
    "type": "conversation.item.delete",
    "item_id": "msg_003"
}

response.create

此事件指示服务器创建一个 Response，这意味着触发模型推理。当处于 Server VAD 模式时，服务器将创建 Responses 自然而然。

响应将至少包含一个 Item，并且可能包含两个，在这种情况下第二个将是函数调用。这些 Item 将被附加到对话历史。

服务器将响应一个事件，即 Items 的事件和内容创建，最后是一个事件来指示响应已完成。response.createdresponse.done

该事件包括推理配置，如、和。这些字段将覆盖 Session 的配置。response.createinstructionstemperature

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。response.create

响应

对象

实时会话对象配置。

OBJECT response.create

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
{
    "event_id": "event_234",
    "type": "response.create",
    "response": {
        "modalities": ["text", "audio"],
        "instructions": "Please assist the user.",
        "voice": "sage",
        "output_audio_format": "pcm16",
        "tools": [
            {
                "type": "function",
                "name": "calculate_sum",
                "description": "Calculates the sum of two numbers.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "a": { "type": "number" },
                        "b": { "type": "number" }
                    },
                    "required": ["a", "b"]
                }
            }
        ],
        "tool_choice": "auto",
        "temperature": 0.7,
        "max_output_tokens": 150
    }
}

response.cancel

发送此事件可取消正在进行的响应。服务器将响应替换为事件或错误（如果没有对取消。response.cancelled

event_id

字符串

用于标识此事件的可选客户端生成的 ID。

类型

字符串

事件类型必须为。response.cancel

OBJECT 响应.cancel

1
2
3
4
{
    "event_id": "event_567",
    "type": "response.cancel"
}

服务器事件

这些是从 OpenAI Realtime WebSocket 服务器发送到客户端的事件。

错误

发生错误时返回，这可能是客户端问题或服务器问题。大多数错误都是可恢复的，并且会话将保持打开状态，因此建议实现者默认监控和记录错误消息。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。error

错误

对象

错误的详细信息。

OBJECT 错误

1
2
3
4
5
6
7
8
9
10
11
{
    "event_id": "event_890",
    "type": "error",
    "error": {
        "type": "invalid_request_error",
        "code": "invalid_event",
        "message": "The 'type' field is missing.",
        "param": null,
        "event_id": "event_567"
    }
}

会话创建文件

创建 Session 时返回。当新的 Connection 作为第一个 Server 事件建立。此事件将包含默认的 Session 配置。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。session.created

会期

对象

实时会话对象配置。

OBJECT session.created

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
{
    "event_id": "event_1234",
    "type": "session.created",
    "session": {
        "id": "sess_001",
        "object": "realtime.session",
        "model": "gpt-4o-realtime-preview-2024-10-01",
        "modalities": ["text", "audio"],
        "instructions": "...model instructions here...",
        "voice": "sage",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "input_audio_transcription": null,
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "prefix_padding_ms": 300,
            "silence_duration_ms": 200
        },
        "tools": [],
        "tool_choice": "auto",
        "temperature": 0.8,
        "max_response_output_tokens": "inf"
    }
}

session.updated

当使用事件更新会话时返回，除非出现错误。session.update

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。session.updated

会期

对象

实时会话对象配置。

OBJECT session.updated

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "event_id": "event_5678",
    "type": "session.updated",
    "session": {
        "id": "sess_001",
        "object": "realtime.session",
        "model": "gpt-4o-realtime-preview-2024-10-01",
        "modalities": ["text"],
        "instructions": "New instructions",
        "voice": "sage",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "input_audio_transcription": {
            "model": "whisper-1"
        },
        "turn_detection": null,
        "tools": [],
        "tool_choice": "none",
        "temperature": 0.7,
        "max_response_output_tokens": 200
    }
}

对话创建（conversation.created）

创建对话时返回。在会话创建后立即发出。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.created

谈话

对象

对话资源。

对象 conversation.created

1
2
3
4
5
6
7
8
{
    "event_id": "event_9101",
    "type": "conversation.created",
    "conversation": {
        "id": "conv_001",
        "object": "realtime.conversation"
    }
}

conversation.item.created

创建对话项时返回。有几种情况生成此事件：

服务器正在生成一个 Response，如果成功，将生成 Response 一个或两个 Items，其类型为（role ）或 type 。messageassistantfunction_call
输入音频缓冲区已由客户端或服务器（处于模式中）。服务器将获取 input audio buffer 并将其添加到新用户消息 Item 中。server_vad
客户端已发送事件以添加新 Item 到 Conversation。conversation.item.create

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.item.created

previous_item_id

字符串

Conversation 上下文中前一项的 ID 允许 client 来了解会话的顺序。

项目

对象

要添加到对话中的项。

对象 conversation.item.created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "event_id": "event_1920",
    "type": "conversation.item.created",
    "previous_item_id": "msg_002",
    "item": {
        "id": "msg_003",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "user",
        "content": [
            {
                "type": "input_audio",
                "transcript": "hello how are you",
                "audio": "base64encodedaudio=="
            }
        ]
    }
}

conversation.item.input_audio_transcription.已完成

此事件是写入用户音频缓冲区。当输入音频缓冲区为由客户端或服务器提交（in 模式）。听录运行与 Response creation 异步，因此此事件可能出现在 Response 之前或之后响应事件。server_vad

实时 API 模型原生接受音频，因此输入转录是一种在单独的 ASR（自动语音识别）模型上运行的单独进程，当前始终 .因此，转录本可能与模型的解释，应被视为粗略的指南。whisper-1

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.item.input_audio_transcription.completed

item_id

字符串

包含音频的用户消息项的 ID。

content_index

整数

包含音频的内容部分的索引。

抄本

字符串

转录的文本。

对象 conversation.item.input_audio_transcription.completed

1
2
3
4
5
6
7
{
    "event_id": "event_2122",
    "type": "conversation.item.input_audio_transcription.completed",
    "item_id": "msg_003",
    "content_index": 0,
    "transcript": "Hello, how are you?"
}

conversation.item.input_audio_transcription.failed

配置输入音频转录时返回，并且转录请求用户消息失败。这些事件与其他事件分开，以便客户端可以识别相关 Item。error

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.item.input_audio_transcription.failed

item_id

字符串

用户消息项的 ID。

content_index

整数

包含音频的内容部分的索引。

错误

对象

转录错误的详细信息。

对象 conversation.item.input_audio_transcription.failed

1
2
3
4
5
6
7
8
9
10
11
12
{
    "event_id": "event_2324",
    "type": "conversation.item.input_audio_transcription.failed",
    "item_id": "msg_003",
    "content_index": 0,
    "error": {
        "type": "transcription_error",
        "code": "audio_unintelligible",
        "message": "The audio could not be transcribed.",
        "param": null
    }
}

conversation.item.truncated

当较早的 Assistant 音频消息项被 client 与事件一起。此事件用于将服务器对音频的理解与客户端的播放同步。conversation.item.truncate

此操作将截断音频并删除服务器端文本转录以确保上下文中没有用户未听到的文本。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.item.truncated

item_id

字符串

被截断的助手消息项的 ID。

content_index

整数

被截断的内容部分的索引。

audio_end_ms

整数

音频被截断的持续时间，以毫秒为单位。

对象 conversation.item.truncated

1
2
3
4
5
6
7
{
    "event_id": "event_2526",
    "type": "conversation.item.truncated",
    "item_id": "msg_004",
    "content_index": 0,
    "audio_end_ms": 1500
}

conversation.item.deleted

当客户端使用事件删除会话中的项目时返回。此事件用于同步服务器对 Client 端视图的会话历史记录的理解。conversation.item.delete

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。conversation.item.deleted

item_id

字符串

已删除项目的 ID。

对象 conversation.item.deleted

1
2
3
4
5
{
    "event_id": "event_2728",
    "type": "conversation.item.deleted",
    "item_id": "msg_005"
}

input_audio_buffer.committed

当客户端或在服务器 VAD 模式下自动运行。该属性是用户的 ID message 项，因此会生成一个事件也将发送给客户端。item_idconversation.item.created

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。input_audio_buffer.committed

previous_item_id

字符串

前一项的 ID，新项将在其后插入。

item_id

字符串

将创建的用户消息项的 ID。

对象 input_audio_buffer.committed

1
2
3
4
5
6
{
    "event_id": "event_1121",
    "type": "input_audio_buffer.committed",
    "previous_item_id": "msg_001",
    "item_id": "msg_002"
}

input_audio_buffer.清除

当客户端使用事件清除输入音频缓冲区时返回。input_audio_buffer.clear

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。input_audio_buffer.cleared

对象 input_audio_buffer.cleared

1
2
3
4
{
    "event_id": "event_1314",
    "type": "input_audio_buffer.cleared"
}

input_audio_buffer.speech_started

在处于模式时由服务器发送，以指示语音已在音频缓冲区中检测到。每当将音频添加到缓冲区（除非已检测到语音）。客户端可能希望使用此事件中断音频播放或向用户提供视觉反馈。server_vad

客户端应该会收到一个事件当言语停止时。该属性是用户消息项的 ID 这将在语音停止时创建，并且也将包含在事件中（除非客户端手动提交 VAD 激活期间的音频缓冲区）。input_audio_buffer.speech_stoppeditem_idinput_audio_buffer.speech_stopped

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。input_audio_buffer.speech_started

audio_start_ms

整数

在首次检测到语音时的会话。这将对应于音频的开头，因此包括 Session 中配置的。prefix_padding_ms

item_id

字符串

语音停止时将创建的用户消息项的 ID。

对象 input_audio_buffer.speech_started

1
2
3
4
5
6
{
    "event_id": "event_1516",
    "type": "input_audio_buffer.speech_started",
    "audio_start_ms": 1000,
    "item_id": "msg_003"
}

input_audio_buffer.speech_stopped

当服务器在音频缓冲区。服务器还将发送一个事件，其中包含从音频缓冲区创建的用户消息项。server_vadconversation.item.created

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。input_audio_buffer.speech_stopped

audio_end_ms

整数

语音停止时自会话开始以来的毫秒数。这将对应于发送到模型的音频的结尾，因此包括 Session 中配置的音频。min_silence_duration_ms

item_id

字符串

将创建的用户消息项的 ID。

对象 input_audio_buffer.speech_stopped

1
2
3
4
5
6
{
    "event_id": "event_1718",
    "type": "input_audio_buffer.speech_stopped",
    "audio_end_ms": 2000,
    "item_id": "msg_003"
}

response.created

创建新 Response 时返回。响应创建的第一个事件其中响应处于初始状态。in_progress

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.created

响应

对象

响应资源。

OBJECT response.created

1
2
3
4
5
6
7
8
9
10
11
12
{
    "event_id": "event_2930",
    "type": "response.created",
    "response": {
        "id": "resp_001",
        "object": "realtime.response",
        "status": "in_progress",
        "status_details": null,
        "output": [],
        "usage": null
    }
}

响应.done

当 Response 完成流式处理时返回。始终发出，无论 final 状态。事件中包含的 Response 对象将在 Response 中包含所有输出 Item，但会省略原始音频数据。response.done

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.done

响应

对象

响应资源。

OBJECT response.done

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
{
    "event_id": "event_3132",
    "type": "response.done",
    "response": {
        "id": "resp_001",
        "object": "realtime.response",
        "status": "completed",
        "status_details": null,
        "output": [
            {
                "id": "msg_006",
                "object": "realtime.item",
                "type": "message",
                "status": "completed",
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Sure, how can I assist you today?"
                    }
                ]
            }
        ],
        "usage": {
            "total_tokens":275,
            "input_tokens":127,
            "output_tokens":148,
            "input_token_details": {
                "cached_tokens":384,
                "text_tokens":119,
                "audio_tokens":8,
                "cached_tokens_details": {
                    "text_tokens": 128,
                    "audio_tokens": 256
                }
            },
            "output_token_details": {
              "text_tokens":36,
              "audio_tokens":112
            }
        }
    }
}

response.output_item.added

在生成 Response 期间创建新 Item 时返回。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.output_item.added

response_id

字符串

项目所属的 Response 的 ID。

output_index

整数

响应中输出项的索引。

项目

对象

要添加到对话中的项。

对象 response.output_item.added

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "event_id": "event_3334",
    "type": "response.output_item.added",
    "response_id": "resp_001",
    "output_index": 0,
    "item": {
        "id": "msg_007",
        "object": "realtime.item",
        "type": "message",
        "status": "in_progress",
        "role": "assistant",
        "content": []
    }
}

response.output_item.done

当 Item 完成流式处理时返回。当 Response 为已中断、不完整或已取消。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.output_item.done

response_id

字符串

项目所属的 Response 的 ID。

output_index

整数

响应中输出项的索引。

项目

对象

要添加到对话中的项。

对象 response.output_item.done

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "event_id": "event_3536",
    "type": "response.output_item.done",
    "response_id": "resp_001",
    "output_index": 0,
    "item": {
        "id": "msg_007",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Sure, I can help with that."
            }
        ]
    }
}

response.content_part.added

在响应生成。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.content_part.added

response_id

字符串

响应的 ID。

item_id

字符串

内容部分添加到的项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

部分

对象

添加的内容部分。

对象 response.content_part.added

1
2
3
4
5
6
7
8
9
10
11
12
{
    "event_id": "event_3738",
    "type": "response.content_part.added",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "part": {
        "type": "text",
        "text": ""
    }
}

response.content_part.done

当内容部分在 Assistant 消息项中完成流式处理时返回。当 Response 中断、不完整或取消时也会发出。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.content_part.done

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

部分

对象

完成的内容部分。

对象 response.content_part.done

1
2
3
4
5
6
7
8
9
10
11
12
{
    "event_id": "event_3940",
    "type": "response.content_part.done",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "part": {
        "type": "text",
        "text": "Sure, I can help with that."
    }
}

response.text.delta 的

当 “text” 内容部分的 text 值更新时返回。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.text.delta

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

三角洲

字符串

文本增量。

对象 response.text.delta

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_4142",
    "type": "response.text.delta",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "delta": "Sure, I can h"
}

response.text.done

当 “text” 内容部分的 text 值完成流式处理时返回。也当 Response 中断、不完整或取消时发出。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.text.done

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

发短信

字符串

最终的文本内容。

对象 response.text.done

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_4344",
    "type": "response.text.done",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "text": "Sure, I can help with that."
}

response.audio_transcript.delta

更新模型生成的音频输出转录时返回。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.audio_transcript.delta

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

三角洲

字符串

转录本增量。

对象 response.audio_transcript.delta

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_4546",
    "type": "response.audio_transcript.delta",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0,
    "delta": "Hello, how can I a"
}

response.audio_transcript.done

在完成模型生成的音频输出转录时返回流。当 Response 中断、不完整或取消。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.audio_transcript.done

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

抄本

字符串

音频的最终转录。

对象 response.audio_transcript.done

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_4748",
    "type": "response.audio_transcript.done",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0,
    "transcript": "Hello, how can I assist you today?"
}

response.audio.delta 的

更新模型生成的音频时返回。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.audio.delta

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

三角洲

字符串

Base64 编码的音频数据增量。

对象 response.audio.delta

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_4950",
    "type": "response.audio.delta",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0,
    "delta": "Base64EncodedAudioDelta"
}

response.audio.done

在模型生成的音频完成时返回。当 Response 已中断、不完整或已取消。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.audio.done

response_id

字符串

响应的 ID。

item_id

字符串

项目的 ID。

output_index

整数

响应中输出项的索引。

content_index

整数

内容部分在项的 content 数组中的索引。

对象 response.audio.done

1
2
3
4
5
6
7
8
{
    "event_id": "event_5152",
    "type": "response.audio.done",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0
}

response.function_call_arguments.delta

更新模型生成的函数调用参数时返回。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.function_call_arguments.delta

response_id

字符串

响应的 ID。

item_id

字符串

函数调用项的 ID。

output_index

整数

响应中输出项的索引。

call_id

字符串

函数调用的 ID。

三角洲

字符串

参数 delta 为 JSON 字符串。

对象 response.function_call_arguments.delta

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_5354",
    "type": "response.function_call_arguments.delta",
    "response_id": "resp_002",
    "item_id": "fc_001",
    "output_index": 0,
    "call_id": "call_001",
    "delta": "{\"location\": \"San\""
}

response.function_call_arguments.done

当模型生成的函数调用参数完成流式处理时返回。当 Response 中断、不完整或取消时也会发出。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。response.function_call_arguments.done

response_id

字符串

响应的 ID。

item_id

字符串

函数调用项的 ID。

output_index

整数

响应中输出项的索引。

call_id

字符串

函数调用的 ID。

参数

字符串

最终参数为 JSON 字符串。

对象 response.function_call_arguments.done

1
2
3
4
5
6
7
8
9
{
    "event_id": "event_5556",
    "type": "response.function_call_arguments.done",
    "response_id": "resp_002",
    "item_id": "fc_001",
    "output_index": 0,
    "call_id": "call_001",
    "arguments": "{\"location\": \"San Francisco\"}"
}

rate_limits.updated

在 Response 的开头发出，以指示更新的速率限制。创建 Response 时，将为输出 “保留” 一些令牌令牌，则此处显示的速率限制会反映该预留，即响应完成后进行相应调整。

event_id

字符串

服务器事件的唯一 ID。

类型

字符串

事件类型必须为。rate_limits.updated

rate_limits

数组

速率限制信息列表。

对象 rate_limits.updated

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "event_id": "event_5758",
    "type": "rate_limits.updated",
    "rate_limits": [
        {
            "name": "requests",
            "limit": 1000,
            "remaining": 999,
            "reset_seconds": 60
        },
        {
            "name": "tokens",
            "limit": 50000,
            "remaining": 49950,
            "reset_seconds": 60
        }
    ]
}

完成
Legacy

给定提示，模型将返回一个或多个预测的完成次数以及每个位置上替代标记的概率。大多数开发人员应该使用我们的 Chat Completions API 来利用我们最好和最新的模型。

创建补全
Legacy

帖子 https://api.openai.com/v1/completions

为提供的提示和参数创建补全。

请求正文

MODEL

字符串

必填

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。

提示

字符串或数组

必填

生成补全的提示，编码为字符串、字符串数组、标记数组或标记数组数组。

请注意，<|endoftext|> 是模型在训练过程中看到的文档分隔符，因此如果未指定提示，模型将生成，就像从新文档的开头开始一样。

best_of

整数或 null

自选

默认为 1

在服务器端生成完成并返回 “best” （每个令牌具有最高对数概率的那个）。无法流式传输结果。best_of

与一起使用时，控制候选完成的数量，并指定要返回的候选完成数 – 必须大于。nbest_ofnbest_ofn

注意：由于此参数会生成许多完成，因此它会快速消耗您的令牌配额。请谨慎使用，并确保和的设置合理。max_tokensstop

回波

boolean 或 null

自选

默认为 false

除了完成之外，还回显提示

frequency_penalty

number 或 null

自选

默认为 0

介于 -2.0 和 2.0 之间的数字。正值会根据新标记到目前为止在文本中的现有频率来惩罚新标记，从而降低模型逐字重复同一行的可能性。

请参阅有关频率和存在处罚的更多信息。

logit_bias

地图

自选

默认为 null

修改指定标记出现在补全中的可能性。

接受一个 JSON 对象，该对象将令牌（由 GPT 分词器中的令牌 ID 指定）映射到从 -100 到 100 的关联偏差值。您可以使用此分词器工具将文本转换为分词 ID。从数学上讲，偏差在采样之前被添加到模型生成的 logit 中。确切的效果因模型而异，但 -1 和 1 之间的值应降低或增加选择的可能性;像 -100 或 100 这样的值应该导致禁止或独占选择相关令牌。

例如，你可以传递以防止生成 <|endoftext|> 标记。{"50256": -100}

对数问题

整数或 null

自选

默认为 null

包括最可能的输出 Token（输出）的对数概率，以及所选的 Token。例如，如果为 5，则 API 将返回 5 个最可能的令牌的列表。API 将始终返回采样令牌的，因此响应中可能最多有元素。logprobslogprobslogproblogprobs+1

的最大值为 5。logprobs

max_tokens

整数或 null

自选

默认为 16

补全中可以生成的最大令牌数。

提示加的标记计数不能超过模型的上下文长度。用于对令牌进行计数的 Python 代码示例。max_tokens

整数或 null

自选

默认为 1

要为每个提示生成的完成次数。

注意：由于此参数会生成许多完成，因此它会快速消耗您的令牌配额。请谨慎使用，并确保和的设置合理。max_tokensstop

presence_penalty

number 或 null

自选

默认为 0

介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止是否出现在文本中来惩罚新标记，从而增加模型讨论新主题的可能性。

请参阅有关频率和存在处罚的更多信息。

种子

整数或 null

自选

如果指定，我们的系统将尽最大努力确定性地采样，这样具有相同 and 参数的重复请求应该返回相同的结果。seed

无法保证确定性，您应该参考 response 参数来监控后端的变化。system_fingerprint

停

字符串 / 数组 / 空

自选

默认为 null

最多 4 个序列，API 将在其中停止生成更多令牌。返回的文本将不包含停止序列。

流

boolean 或 null

自选

默认为 false

是否流回部分进度。如果设置，令牌将在可用时作为仅限数据、服务器发送的事件发送，流由消息终止。Python 代码示例。data: [DONE]

stream_options

object 或 null

自选

默认为 null

流式处理响应的选项。仅在设置时设置此项。stream: true

后缀

string 或 null

自选

默认为 null

插入文本完成后的后缀。

此参数仅支持。gpt-3.5-turbo-instruct

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

我们通常建议更改此项或同时更改两者。top_p

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此项或同时更改两者。temperature

用户

字符串

自选

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

返回一个完成对象，如果请求是流式的，则返回一系列完成对象。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo-instruct",
    "prompt": "Say this is a test",
    "max_tokens": 7,
    "temperature": 0
  }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

client.completions.create(
  model="gpt-3.5-turbo-instruct",
  prompt="Say this is a test",
  max_tokens=7,
  temperature=0
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const completion = await openai.completions.create({
    model: "gpt-3.5-turbo-instruct",
    prompt: "Say this is a test.",
    max_tokens: 7,
    temperature: 0,
  });

  console.log(completion);
}
main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
  "object": "text_completion",
  "created": 1589478378,
  "model": "gpt-3.5-turbo-instruct",
  "system_fingerprint": "fp_44709d6fcb",
  "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
  }
}

完成对象
Legacy

表示来自 API 的完成响应。注意：流式和非流式响应对象共享相同的形状（与聊天端点不同）。

身份证

字符串

完成的唯一标识符。

选择

数组

模型为输入提示生成的完成选项列表。

创建

整数

创建完成时的 Unix 时间戳（以秒为单位）。

MODEL

字符串

用于完成（completion）的模型。

system_fingerprint

字符串

此指纹表示模型运行时使用的后端配置。

可以与 request 参数结合使用，以了解何时进行了可能影响确定性的后端更改。seed

对象

字符串

对象类型，始终为 “text_completion”

用法

对象

完成请求的使用情况统计信息。

OBJECT 完成对象

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": "gpt-4-turbo",
  "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
  }
}

助手（v1）
Legacy

构建可以调用模型并使用工具执行任务的助手。

开始使用 Assistants API

创建助手（v1）
Legacy

帖子 https://api.openai.com/v1/assistants

创建包含模型和说明的助手。

请求正文

MODEL

字符串

必填

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。type：字符串

名字

string 或 null

自选

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

自选

助手的描述。最大长度为 512 个字符。

指示

string 或 null

自选

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

自选

默认为 []

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterretrievalfunction

file_ids

数组

自选

默认为 []

附加到此助手的文件 ID 列表。最多可以有 20 个文件附加到助手。文件按其创建日期升序排序。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

字符串或对象

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

辅助对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    "name": "Math Tutor",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo"
  }'

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

my_assistant = client.beta.assistants.create(
    instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    name="Math Tutor",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-turbo",
)
print(my_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistant = await openai.beta.assistants.create({
    instructions:
      "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    name: "Math Tutor",
    tools: [{ type: "code_interpreter" }],
    model: "gpt-4-turbo",
  });

  console.log(myAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

创建辅助文件（v1）
Legacy

发布 https://api.openai.com/v1/assistants/{assistant_id}/files

通过将 File 附加到 Assistant 来创建 Assistant 文件。

路径参数

assistant_id

字符串

必填

要为其创建 File 的助手的 ID。

请求正文

file_id

字符串

必填

助手应使用的文件 ID（带）。对于可以访问文件的工具（如和）很有用。purpose="assistants"retrievalcode_interpreter

辅助文件对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/assistants/asst_abc123/files \
    -H 'Authorization: Bearer $OPENAI_API_KEY"' \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v1' \
    -d '{
      "file_id": "file-abc123"
    }'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="file-abc123"
)
print(assistant_file)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const myAssistantFile = await openai.beta.assistants.files.create(
    "asst_abc123",
    {
      file_id: "file-abc123"
    }
  );
  console.log(myAssistantFile);
}

main();

响应

1
2
3
4
5
6
{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

列表助手（v1）
Legacy

获取 https://api.openai.com/v1/assistants

返回助手列表。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

用于分页的游标。是定义您在列表中的位置的对象 ID。例如，如果您发出一个列表请求并收到 100 个对象，以 obj_foo 结尾，则您的后续调用可以包含 before=obj_foo 以便获取列表的上一页。before

辅助对象列表。

示例请求

1
2
3
4
curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistants = await openai.beta.assistants.list({
    order: "desc",
    limit: "20",
  });

  console.log(myAssistants.data);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123",
      "object": "assistant",
      "created_at": 1698982736,
      "name": "Coding Tutor",
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "file_ids": [],
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc456",
      "object": "assistant",
      "created_at": 1698982718,
      "name": "My Assistant",
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "file_ids": [],
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc789",
      "object": "assistant",
      "created_at": 1698982643,
      "name": null,
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "tools": [],
      "file_ids": [],
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    }
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

列出助手文件（v1）
Legacy

获取 https://api.openai.com/v1/assistants/{assistant_id}/files

返回 Assistant 文件的列表。

路径参数

assistant_id

字符串

必填

文件所属的助手的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

辅助文件对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/assistants/asst_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const assistantFiles = await openai.beta.assistants.files.list(
    "asst_abc123"
  );
  console.log(assistantFiles);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "assistant.file",
      "created_at": 1699060412,
      "assistant_id": "asst_abc123"
    },
    {
      "id": "file-abc456",
      "object": "assistant.file",
      "created_at": 1699060412,
      "assistant_id": "asst_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

检索助手（v1）
Legacy

获取 https://api.openai.com/v1/assistants/{assistant_id}

检索助手。

路径参数

assistant_id

字符串

必填

要检索的助手的 ID。

与指定 ID 匹配的 assistant 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myAssistant = await openai.beta.assistants.retrieve(
    "asst_abc123"
  );

  console.log(myAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
  "tools": [
    {
      "type": "retrieval"
    }
  ],
  "file_ids": [
    "file-abc123"
  ],
  "metadata": {}
}

检索助手文件（v1）
Legacy

获取 https://api.openai.com/v1/assistants/{assistant_id}/files/{file_id}

检索 AssistantFile。

路径参数

assistant_id

字符串

必填

文件所属的助手的 ID。

file_id

字符串

必填

我们获取的文件的 ID。

与指定 ID 匹配的 assistant 文件对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \
  -H 'Authorization: Bearer $OPENAI_API_KEY"' \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1'

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="file-abc123"
)
print(assistant_file)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const myAssistantFile = await openai.beta.assistants.files.retrieve(
    "asst_abc123",
    "file-abc123"
  );
  console.log(myAssistantFile);
}

main();

响应

1
2
3
4
5
6
{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

修改助手（v1）
Legacy

帖子 https://api.openai.com/v1/assistants/{assistant_id}

修改助手。

路径参数

assistant_id

字符串

必填

要修改的助手的 ID。

请求正文

MODEL

自选

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。type：字符串

名字

string 或 null

自选

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

自选

助手的描述。最大长度为 512 个字符。

指示

string 或 null

自选

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

自选

默认为 []

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterretrievalfunction

file_ids

数组

自选

默认为 []

附加到此助手的文件 ID 列表。最多可以有 20 个文件附加到助手。文件按其创建日期升序排序。如果文件之前已附加到列表中，但未显示在列表中，则会将其从 Assistant 中删除。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

字符串或对象

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

修改后的 assistant 对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "retrieval"}],
      "model": "gpt-4-turbo",
      "file_ids": ["file-abc123", "file-abc456"]
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI
client = OpenAI()

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "retrieval"}],
  model="gpt-4-turbo",
  file_ids=["file-abc123", "file-abc456"],
)

print(my_updated_assistant)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myUpdatedAssistant = await openai.beta.assistants.update(
    "asst_abc123",
    {
      instructions:
        "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      name: "HR Helper",
      tools: [{ type: "retrieval" }],
      model: "gpt-4-turbo",
      file_ids: [
        "file-abc123",
        "file-abc456",
      ],
    }
  );

  console.log(myUpdatedAssistant);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
  "tools": [
    {
      "type": "retrieval"
    }
  ],
  "file_ids": [
    "file-abc123",
    "file-abc456"
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

删除助手（v1）
Legacy

删除 https://api.openai.com/v1/assistants/{assistant_id}

删除助手。

路径参数

assistant_id

字符串

必填

要删除的助手的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -X DELETE

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

response = client.beta.assistants.delete("asst_abc123")
print(response)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const response = await openai.beta.assistants.del("asst_abc123");

  console.log(response);
}
main();

响应

1
2
3
4
5
{
  "id": "asst_abc123",
  "object": "assistant.deleted",
  "deleted": true
}

删除助手文件（v1）
Legacy

删除 https://api.openai.com/v1/assistants/{assistant_id}/files/{file_id}

删除 Assistant 文件。

路径参数

assistant_id

字符串

必填

文件所属的助手的 ID。

file_id

字符串

必填

要删除的文件的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -X DELETE

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="file-abc123"
)
print(deleted_assistant_file)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const deletedAssistantFile = await openai.beta.assistants.files.del(
    "asst_abc123",
    "file-abc123"
  );
  console.log(deletedAssistantFile);
}

main();

响应

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

助手对象（v1）
Legacy

表示可以调用模型并使用工具的 an。assistant

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .assistant

created_at

整数

创建 Assistant 时的 Unix 时间戳（以秒为单位）。

名字

string 或 null

助手的姓名。最大长度为 256 个字符。

描述

string 或 null

助手的描述。最大长度为 512 个字符。

MODEL

要使用的模型的 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 了解它们的描述。type：字符串

指示

string 或 null

助手使用的系统指令。最大长度为 256,000 个字符。

工具

数组

在 Assistant 上启用的工具列表。每个助手最多可以有 128 个工具。工具可以是、或类型的。code_interpreterretrievalfunction

file_ids

数组

附加到此助手的文件 ID 列表。最多可以有 20 个文件附加到助手。文件按其创建日期升序排序。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

温度

number 或 null

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

response_format

字符串或对象

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

OBJECT 辅助对象（v1）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

辅助文件对象（v1）
Legacy

附加到的文件列表。assistant

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .assistant.file

created_at

整数

创建 assistant 文件时的 Unix 时间戳（以秒为单位）。

assistant_id

字符串

文件附加到的助手 ID。

OBJECT 辅助文件对象（v1）

1
2
3
4
5
6
{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

线程（v1）
Legacy

创建助理可以与之交互的线程。

相关指南：助手

创建线程（v1）
Legacy

帖子 https://api.openai.com/v1/threads

创建线程。

请求正文

消息

数组

自选

要开始线程的消息列表。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

线程对象。

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

empty_thread = client.beta.threads.create()
print(empty_thread)

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const emptyThread = await openai.beta.threads.create();

  console.log(emptyThread);
}

main();

响应

1
2
3
4
5
6
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699012949,
  "metadata": {}
}

检索线程（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}

检索线程。

路径参数

thread_id

字符串

必填

要检索的线程的 ID。

与指定 ID 匹配的 thread 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const myThread = await openai.beta.threads.retrieve(
    "thread_abc123"
  );

  console.log(myThread);
}

main();

响应

1
2
3
4
5
6
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699014083,
  "metadata": {}
}

修改线程（v1）
Legacy

帖子 https://api.openai.com/v1/threads/{thread_id}

修改线程。

路径参数

thread_id

字符串

必填

要修改的线程的 ID。只有可以修改。metadata

请求正文

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

与指定 ID 匹配的修改后的线程对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
from openai import OpenAI
client = OpenAI()

my_updated_thread = client.beta.threads.update(
  "thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123"
  }
)
print(my_updated_thread)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const updatedThread = await openai.beta.threads.update(
    "thread_abc123",
    {
      metadata: { modified: "true", user: "abc123" },
    }
  );

  console.log(updatedThread);
}

main();

响应

1
2
3
4
5
6
7
8
9
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699014083,
  "metadata": {
    "modified": "true",
    "user": "abc123"
  }
}

删除线程（v1）
Legacy

删除 https://api.openai.com/v1/threads/{thread_id}

删除线程。

路径参数

thread_id

字符串

必填

要删除的线程的 ID。

删除状态

示例请求

1
2
3
4
5
curl https://api.openai.com/v1/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -X DELETE

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

response = client.beta.threads.delete("thread_abc123")
print(response)

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const response = await openai.beta.threads.del("thread_abc123");

  console.log(response);
}
main();

响应

1
2
3
4
5
{
  "id": "thread_abc123",
  "object": "thread.deleted",
  "deleted": true
}

thread 对象（v1）
Legacy

表示包含消息的线程。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread

created_at

整数

创建线程时的 Unix 时间戳（以秒为单位）。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

OBJECT 线程对象（v1）

1
2
3
4
5
6
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1698107661,
  "metadata": {}
}

消息（v1）
Legacy

在话题中创建消息

相关指南：助手

创建消息（v1）
Legacy

发布 https://api.openai.com/v1/threads/{thread_id}/messages

创建消息。

路径参数

thread_id

字符串

必填

要为其创建消息的线程的 ID。

请求正文

角色

字符串

必填

创建消息的实体的角色。允许的值包括：

user：表示消息是由实际用户发送的，在大多数情况下应该用于表示用户生成的消息。
assistant：表示消息由助手生成。使用此值可将来自助手的消息插入到对话中。

内容

字符串

必填

消息的内容。

file_ids

数组

自选

默认为 []

消息应使用的文件 ID 列表。一条消息最多可以附加 10 个文件。对于可以访问和使用文件的工具很有用。retrievalcode_interpreter

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

消息对象。

示例请求

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.create(
    "thread_abc123",
    { role: "user", content: "How does AI work? Explain it in simple terms." }
  );

  console.log(threadMessages);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "assistant_id": null,
  "run_id": null,
  "metadata": {}
}

列出消息（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/messages

返回给定线程的消息列表。

路径参数

thread_id

字符串

必填

消息所属线程的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

run_id

字符串

自选

按生成消息的运行 ID 筛选消息。

消息对象列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.list(
    "thread_abc123"
  );

  console.log(threadMessages.data);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "object": "thread.message",
      "created_at": 1699016383,
      "thread_id": "thread_abc123",
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "How does AI work? Explain it in simple terms.",
            "annotations": []
          }
        }
      ],
      "file_ids": [],
      "assistant_id": null,
      "run_id": null,
      "metadata": {}
    },
    {
      "id": "msg_abc456",
      "object": "thread.message",
      "created_at": 1699016383,
      "thread_id": "thread_abc123",
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "Hello, what is AI?",
            "annotations": []
          }
        }
      ],
      "file_ids": [
        "file-abc123"
      ],
      "assistant_id": null,
      "run_id": null,
      "metadata": {}
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc456",
  "has_more": false
}

列出消息文件（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files

返回消息文件列表。

路径参数

thread_id

字符串

必填

消息和文件所属的线程的 ID。

message_id

字符串

必填

文件所属消息的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

消息文件对象列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

message_files = client.beta.threads.messages.files.list(
  thread_id="thread_abc123",
  message_id="msg_abc123"
)
print(message_files)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const messageFiles = await openai.beta.threads.messages.files.list(
    "thread_abc123",
    "msg_abc123"
  );
  console.log(messageFiles);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "thread.message.file",
      "created_at": 1699061776,
      "message_id": "msg_abc123"
    },
    {
      "id": "file-abc123",
      "object": "thread.message.file",
      "created_at": 1699061776,
      "message_id": "msg_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc123",
  "has_more": false
}

检索消息（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

检索消息。

路径参数

thread_id

字符串

必填

此消息所属的线程的 ID。

message_id

字符串

必填

要检索的消息的 ID。

与指定 ID 匹配的 message 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.retrieve(
    "thread_abc123",
    "msg_abc123"
  );

  console.log(message);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "assistant_id": null,
  "run_id": null,
  "metadata": {}
}

检索消息文件（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}

检索消息文件。

路径参数

thread_id

字符串

必填

消息和 File 所属的线程的 ID。

message_id

字符串

必填

文件所属消息的 ID。

file_id

字符串

必填

正在检索的文件的 ID。

消息文件对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

message_files = client.beta.threads.messages.files.retrieve(
    thread_id="thread_abc123",
    message_id="msg_abc123",
    file_id="file-abc123"
)
print(message_files)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const messageFile = await openai.beta.threads.messages.files.retrieve(
    "thread_abc123",
    "msg_abc123",
    "file-abc123"
  );
  console.log(messageFile);
}

main();

响应

1
2
3
4
5
6
{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1699061776,
  "message_id": "msg_abc123"
}

修改消息（v1）
Legacy

帖子 https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

修改消息。

路径参数

thread_id

字符串

必填

此消息所属的线程的 ID。

message_id

字符串

必填

要修改的消息的 ID。

请求正文

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

修改后的 message 对象。

示例请求

1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.update(
    "thread_abc123",
    "msg_abc123",
    {
      metadata: {
        modified: "true",
        user: "abc123",
      },
    }
  }'

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "assistant_id": null,
  "run_id": null,
  "metadata": {
    "modified": "true",
    "user": "abc123"
  }
}

消息对象（v1）
Legacy

表示线程中的消息。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.message

created_at

整数

创建消息时的 Unix 时间戳（以秒为单位）。

thread_id

字符串

此消息所属的线程 ID。

地位

字符串

消息的状态，可以是、或。in_progressincompletecompleted

incomplete_details

object 或 null

在未完成的消息中，有关消息未完成原因的详细信息。

completed_at

整数或 null

消息完成时的 Unix 时间戳（以秒为单位）。

incomplete_at

整数或 null

消息标记为未完成时的 Unix 时间戳（以秒为单位）。

角色

字符串

生成消息的实体。或 .userassistant

内容

数组

文本和/或图像数组中的消息内容。

assistant_id

string 或 null

如果适用，则为创作此消息的助手的 ID。

run_id

string 或 null

与创建此消息关联的运行的 ID。Value 是使用 create message 或 create thread 端点手动创建消息时的值。null

file_ids

数组

助理应使用的文件 ID 列表。对于检索和code_interpreter等可以访问文件的工具很有用。一条消息最多可以附加 10 个文件。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

OBJECT 消息对象（v1）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1698983503,
  "thread_id": "thread_abc123",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Hi! How can I help you today?",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "assistant_id": "asst_abc123",
  "run_id": "run_abc123",
  "metadata": {}
}

消息文件对象（v1）
Legacy

附加到的文件列表。message

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.message.file

created_at

整数

创建消息文件时的 Unix 时间戳（以秒为单位）。

message_id

字符串

File 附加到的消息的 ID。

OBJECT 消息文件对象（v1）

1
2
3
4
5
6
7
{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1698107661,
  "message_id": "message_QLoItBbqwyAJEzlTy4y9kOMM",
  "file_id": "file-abc123"
}

运行（v1）
Legacy

表示在线程上运行的执行。

相关指南：助手

创建运行（v1）
Legacy

发布 https://api.openai.com/v1/threads/{thread_id}/runs

创建运行。

路径参数

thread_id

字符串

必填

要运行的线程的 ID。

请求正文

assistant_id

字符串

必填

用于执行此运行的助手的 ID。

MODEL

字符串

自选

用于执行此运行的 Model 的 ID。如果此处提供了值，它将覆盖与助手关联的模型。否则，将使用与助手关联的模型。

指示

string 或 null

自选

覆盖助手的指令。这对于修改每次运行的行为非常有用。

additional_instructions

string 或 null

自选

在运行说明的末尾附加其他说明。这对于在每次运行的基础上修改行为而不覆盖其他指令非常有用。

additional_messages

array 或 null

自选

在创建运行之前向线程添加其他消息。

工具

array 或 null

自选

覆盖助手可用于此运行的工具。这对于修改每次运行的行为非常有用。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

max_prompt_tokens

整数或 null

自选

在运行过程中可以使用的提示令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的提示令牌数。如果运行超过指定的提示令牌数，则运行将以 status 结束。有关更多信息，请参阅。completeincomplete_details

max_completion_tokens

整数或 null

自选

在运行过程中可以使用的完成令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的完成令牌数。如果运行超过指定的完成令牌数，则运行将以 status 结束。有关更多信息，请参阅。completeincomplete_details

truncation_strategy

对象

自选

tool_choice

字符串或对象

自选

控制模型调用哪个（如果有）工具。表示模型不会调用任何工具，而是生成一条消息。是默认值，表示模型可以在生成消息或调用工具之间进行选择。指定特定工具（如 or ）会强制模型调用该工具。noneauto{"type": "TOOL_TYPE"}{"type": "function", "function": {"name": "my_function"}}

response_format

字符串或对象

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

run 对象。

示例请求

1
2
3
4
5
6
7
curl https://api.openai.com/v1/threads/thread_abc123/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "asst_abc123"
  }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.create(
  thread_id="thread_abc123",
  assistant_id="asst_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.create(
    "thread_abc123",
    { assistant_id: "asst_abc123" }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699063290,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": 1699063290,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699063291,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [
    "file-abc123",
    "file-abc456"
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

创建线程并运行（v1）
Legacy

帖子 https://api.openai.com/v1/threads/runs

创建一个线程并在一个请求中运行它。

请求正文

assistant_id

字符串

必填

用于执行此运行的助手的 ID。

线程

对象

自选

MODEL

字符串

自选

用于执行此运行的 Model 的 ID。如果此处提供了值，它将覆盖与助手关联的模型。否则，将使用与助手关联的模型。

指示

string 或 null

自选

覆盖助手的默认系统消息。这对于修改每次运行的行为非常有用。

工具

array 或 null

自选

覆盖助手可用于此运行的工具。这对于修改每次运行的行为非常有用。

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

温度

number 或 null

自选

默认为 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定。

top_p

number 或 null

自选

默认为 1

使用温度进行采样的替代方法，称为核抽样，其中模型考虑具有top_p概率质量的标记的结果。所以 0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此温度或温度，但不能同时更改两者。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

max_prompt_tokens

整数或 null

自选

max_completion_tokens

整数或 null

自选

truncation_strategy

对象

自选

tool_choice

字符串或对象

自选

response_format

字符串或对象

自选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

run 对象。

示例请求

1
2
3
4
5
6
7
8
9
10
11
12
curl https://api.openai.com/v1/threads/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "assistant_id": "asst_abc123",
      "thread": {
        "messages": [
          {"role": "user", "content": "Explain deep learning to a 5 year old."}
        ]
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.create_and_run(
  assistant_id="asst_abc123",
  thread={
    "messages": [
      {"role": "user", "content": "Explain deep learning to a 5 year old."}
    ]
  }
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.createAndRun({
    assistant_id: "asst_abc123",
    thread: {
      messages: [
        { role: "user", content: "Explain deep learning to a 5 year old." },
      ],
    },
  });

  console.log(run);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076792,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": null,
  "expires_at": 1699077392,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a helpful assistant.",
  "tools": [],
  "file_ids": [],
  "metadata": {},
  "usage": null,
  "temperature": 1
}

列出运行（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/runs

返回属于线程的运行列表。

路径参数

thread_id

字符串

必填

运行所属线程的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

run 对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

runs = client.beta.threads.runs.list(
  "thread_abc123"
)

print(runs)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const runs = await openai.beta.threads.runs.list(
    "thread_abc123"
  );

  console.log(runs);
}

main();

响应

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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
{
  "object": "list",
  "data": [
    {
      "id": "run_abc123",
      "object": "thread.run",
      "created_at": 1699075072,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699075072,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699075073,
      "last_error": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "file_ids": [
        "file-abc123",
        "file-abc456"
      ],
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto"
    },
    {
      "id": "run_abc456",
      "object": "thread.run",
      "created_at": 1699063290,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699063290,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699063291,
      "last_error": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "file_ids": [
        "file-abc123",
        "file-abc456"
      ],
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto"
    }
  ],
  "first_id": "run_abc123",
  "last_id": "run_abc456",
  "has_more": false
}

列出运行步骤（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps

返回属于运行的运行步骤列表。

路径参数

thread_id

字符串

必填

run 和 run steps 所属的线程的 ID。

run_id

字符串

必填

运行步骤所属的运行的 ID。

查询参数

限制

整数

自选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。

次序

字符串

自选

默认为 desc

按对象的时间戳排序。用于升序和降序。created_atascdesc

后

字符串

自选

以前

字符串

自选

运行步骤对象的列表。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run_steps = client.beta.threads.runs.steps.list(
    thread_id="thread_abc123",
    run_id="run_abc123"
)

print(run_steps)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const runStep = await openai.beta.threads.runs.steps.list(
    "thread_abc123",
    "run_abc123"
  );
  console.log(runStep);
}

main();

响应

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
{
  "object": "list",
  "data": [
    {
      "id": "step_abc123",
      "object": "thread.run.step",
      "created_at": 1699063291,
      "run_id": "run_abc123",
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "type": "message_creation",
      "status": "completed",
      "cancelled_at": null,
      "completed_at": 1699063291,
      "expired_at": null,
      "failed_at": null,
      "last_error": null,
      "step_details": {
        "type": "message_creation",
        "message_creation": {
          "message_id": "msg_abc123"
        }
      },
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      }
    }
  ],
  "first_id": "step_abc123",
  "last_id": "step_abc456",
  "has_more": false
}

检索运行（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

检索运行。

路径参数

thread_id

字符串

必填

运行的线程的 ID。

run_id

字符串

必填

要检索的运行的 ID。

与指定 ID 匹配的 run 对象。

示例请求

1
2
3
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.retrieve(
    "thread_abc123",
    "run_abc123"
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [
    "file-abc123",
    "file-abc456"
  ],
  "metadata": {},
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

检索运行步骤（v1）
Legacy

获取 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps/{step_id}

检索运行步骤。

路径参数

thread_id

字符串

必填

run 和 run step 所属的线程的 ID。

run_id

字符串

必填

运行步骤所属的运行的 ID。

step_id

字符串

必填

要检索的运行步骤的 ID。

与指定 ID 匹配的 run step 对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

run_step = client.beta.threads.runs.steps.retrieve(
    thread_id="thread_abc123",
    run_id="run_abc123",
    step_id="step_abc123"
)

print(run_step)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const runStep = await openai.beta.threads.runs.steps.retrieve(
    "thread_abc123",
    "run_abc123",
    "step_abc123"
  );
  console.log(runStep);
}

main();

响应

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
{
  "id": "step_abc123",
  "object": "thread.run.step",
  "created_at": 1699063291,
  "run_id": "run_abc123",
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "type": "message_creation",
  "status": "completed",
  "cancelled_at": null,
  "completed_at": 1699063291,
  "expired_at": null,
  "failed_at": null,
  "last_error": null,
  "step_details": {
    "type": "message_creation",
    "message_creation": {
      "message_id": "msg_abc123"
    }
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

修改运行（v1）
Legacy

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

修改运行。

路径参数

thread_id

字符串

必填

运行的线程的 ID。

run_id

字符串

必填

要修改的运行的 ID。

请求正文

元数据

地图

自选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
5
6
7
8
9
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "metadata": {
      "user_id": "user_abc123"
    }
  }'

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.update(
  thread_id="thread_abc123",
  run_id="run_abc123",
  metadata={"user_id": "user_abc123"},
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.update(
    "thread_abc123",
    "run_abc123",
    {
      metadata: {
        user_id: "user_abc123",
      },
    }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [
    "file-abc123",
    "file-abc456"
  ],
  "metadata": {
    "user_id": "user_abc123"
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

提交工具输出以运行（v1）
Legacy

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs

路径参数

thread_id

字符串

必填

此运行所属的线程的 ID。

run_id

字符串

必填

需要提交工具输出的运行的 ID。

请求正文

tool_outputs

数组

必填

要提交其输出的工具列表。

流

boolean 或 null

自选

如果，则返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有消息的终端状态时终止。truedata: [DONE]

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
5
6
7
8
9
10
11
12
curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_001",
        "output": "70 degrees and sunny."
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id="thread_123",
  run_id="run_123",
  tool_outputs=[
    {
      "tool_call_id": "call_001",
      "output": "70 degrees and sunny."
    }
  ]
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.submitToolOutputs(
    "thread_123",
    "run_123",
    {
      tool_outputs: [
        {
          tool_call_id: "call_001",
          output: "70 degrees and sunny.",
        },
      ],
    }
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_123",
  "object": "thread.run",
  "created_at": 1699075592,
  "assistant_id": "asst_123",
  "thread_id": "thread_123",
  "status": "queued",
  "started_at": 1699075592,
  "expires_at": 1699076192,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "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"]
        }
      }
    }
  ],
  "file_ids": [],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

取消运行（v1）
Legacy

发布 https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/cancel

取消为的运行。in_progress

路径参数

thread_id

字符串

必填

此运行所属的线程的 ID。

run_id

字符串

必填

要取消的运行的 ID。

与指定 ID 匹配的修改后的运行对象。

示例请求

1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -X POST

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.cancel(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const run = await openai.beta.threads.runs.cancel(
    "thread_abc123",
    "run_abc123"
  );

  console.log(run);
}

main();

响应

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076126,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "cancelling",
  "started_at": 1699076126,
  "expires_at": 1699076726,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": "You summarize books.",
  "tools": [
    {
      "type": "retrieval"
    }
  ],
  "file_ids": [],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
}

run 对象（v1）
Legacy

表示在线程上运行的执行。

身份证

字符串

标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run

created_at

整数

创建运行时的 Unix 时间戳（以秒为单位）。

thread_id

字符串

作为此运行的一部分执行的线程的 ID。

assistant_id

字符串

用于执行此运行的助手的 ID。

地位

字符串

运行的状态，可以是、或。queuedin_progressrequires_actioncancellingcancelledfailedcompletedexpired

required_action

object 或 null

有关继续运行所需操作的详细信息。如果不需要执行任何操作，则为 WILL 。null

last_error

object 或 null

与此运行关联的最后一个错误。如果没有错误，则会是。null

expires_at

整数或 null

运行过期时间的 Unix 时间戳（以秒为单位）。

started_at

整数或 null

运行启动时的 Unix 时间戳（以秒为单位）。

cancelled_at

整数或 null

取消运行时的 Unix 时间戳（以秒为单位）。

failed_at

整数或 null

运行失败时的 Unix 时间戳（以秒为单位）。

completed_at

整数或 null

运行完成时的 Unix 时间戳（以秒为单位）。

incomplete_details

object 或 null

有关运行未完成原因的详细信息。如果运行未完成，则为。null

MODEL

字符串

助手用于此运行的模型。

指示

字符串

助手用于此运行的说明。

工具

数组

助手用于此运行的工具列表。

file_ids

数组

助手用于此运行的文件 ID 列表。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

用法

温度

number 或 null

用于此运行的采样温度。如果未设置，则默认为 1。

top_p

number 或 null

用于此运行的 nucleus 采样值。如果未设置，则默认为 1。

max_prompt_tokens

整数或 null

指定为在运行过程中使用的提示令牌的最大数量。

max_completion_tokens

整数或 null

指定为在运行过程中使用的最大完成令牌数。

truncation_strategy

对象

tool_choice

字符串或对象

response_format

字符串或对象

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号。gpt-3.5-turbo-1106

设置为启用 JSON 模式，这保证模型生成的消息是有效的 JSON。{ "type": "json_object" }

OBJECT 运行对象（v1）

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
{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1698107661,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699073476,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699073498,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "tools": [{"type": "retrieval"}, {"type": "code_interpreter"}],
  "file_ids": [],
  "metadata": {},
  "incomplete_details": null,
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

run step 对象（v1）
Legacy

表示执行运行的步骤。

身份证

字符串

运行步骤的标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run.step

created_at

整数

创建运行步骤时的 Unix 时间戳（以秒为单位）。

assistant_id

字符串

与运行步骤关联的助手的 ID。

thread_id

字符串

运行的线程的 ID。

run_id

字符串

此运行步骤所属的运行的 ID。

类型

字符串

运行步骤的类型，可以是或。message_creationtool_calls

地位

字符串

运行步骤的状态，可以是、或。in_progresscancelledfailedcompletedexpired

step_details

对象

run 步骤的详细信息。

last_error

object 或 null

与此运行步骤关联的最后一个错误。如果没有错误，则会是。null

expired_at

整数或 null

运行步骤过期时的 Unix 时间戳（以秒为单位）。如果父运行已过期，则认为步骤已过期。

cancelled_at

整数或 null

取消运行步骤时的 Unix 时间戳（以秒为单位）。

failed_at

整数或 null

运行步骤失败时的 Unix 时间戳（以秒为单位）。

completed_at

整数或 null

运行步骤完成时的 Unix 时间戳（以秒为单位）。

元数据

地图

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

用法

OBJECT 运行步骤对象（v1）

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
{
  "id": "step_abc123",
  "object": "thread.run.step",
  "created_at": 1699063291,
  "run_id": "run_abc123",
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "type": "message_creation",
  "status": "completed",
  "cancelled_at": null,
  "completed_at": 1699063291,
  "expired_at": null,
  "failed_at": null,
  "last_error": null,
  "step_details": {
    "type": "message_creation",
    "message_creation": {
      "message_id": "msg_abc123"
    }
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

流式处理（v1）
Legacy

流式传输执行 Run 的结果或在提交工具输出后恢复 Run。

您可以通过传递 .响应将是 Server-Sent 事件流。"stream": true

我们的 Node 和 Python SDK 提供了有用的实用程序，使流式传输变得容易。请参阅 Assistants API 快速入门以了解更多信息。

消息 delta 对象（v1）
Legacy

表示消息增量，即流式处理期间消息上的任何更改字段。

身份证

字符串

消息的标识符，可在 API 端点中引用。

对象

字符串

对象类型，始终为 .thread.message.delta

三角洲

对象

包含 Message 上已更改的字段的增量。

OBJECT 消息 delta 对象（v1）

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "msg_123",
  "object": "thread.message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": { "value": "Hello", "annotations": [] }
      }
    ]
  }
}

运行步骤 delta 对象（v1）
Legacy

表示运行步骤增量，即流式处理期间运行步骤上任何更改的字段。

身份证

字符串

运行步骤的标识符，可在 API 终端节点中引用。

对象

字符串

对象类型，始终为 .thread.run.step.delta

三角洲

对象

包含在 run 步骤中已更改的字段的 delta。

OBJECT 运行步骤 delta 对象（v1）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "id": "step_123",
  "object": "thread.run.step.delta",
  "delta": {
    "step_details": {
      "type": "tool_calls",
      "tool_calls": [
        {
          "index": 0,
          "id": "call_123",
          "type": "code_interpreter",
          "code_interpreter": { "input": "", "outputs": [] }
        }
      ]
    }
  }
}

Assistant 流事件（v1）
Legacy

表示流式传输 Run 时发出的事件。

服务器发送的事件流中的每个事件都有一个 and 属性：eventdata

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

thread.created 文件

data是一个线程

在创建新线程时发生。

thread.run.created

data是一次运行

在创建新运行时发生。

thread.run.queued

data是一次运行

当运行移动到某种状态时发生。queued

thread.run.in_progress

data是一次运行

当运行移动到某种状态时发生。in_progress

thread.run.requires_action

data是一次运行

当运行移动到某种状态时发生。requires_action

thread.run.completed

data是一次运行

在运行完成时发生。

thread.run.failed

data是一次运行

在运行失败时发生。

thread.run.cancelling

data是一次运行

当运行移动到某种状态时发生。cancelling

thread.run.cancelled 的

data是一次运行

在取消运行时发生。

thread.run.expired 的

data是一次运行

在运行过期时发生。

thread.run.step.created

data是运行步骤

在创建运行步骤时发生。

thread.run.step.in_progress

data是运行步骤

当运行步骤移动到某种状态时发生。in_progress

thread.run.step.delta

data是运行步骤增量

在流式传输运行步骤的某些部分时发生。

thread.run.step.completed

data是运行步骤

在运行步骤完成时发生。

thread.run.step.failed

data是运行步骤

当运行步骤失败时发生。

thread.run.step.cancelled 的

data是运行步骤

在取消运行步骤时发生。

thread.run.step.expired

data是运行步骤

当运行步骤过期时发生。

thread.message.created

data是一条消息

在创建消息时发生。

thread.message.in_progress

data是一条消息

当消息移动到某种状态时发生。in_progress

线程消息.delta

data是消息增量

在流式传输 Message 的某些部分时发生。

thread.message.completed

data是一条消息

在消息完成时发生。

thread.message.incomplete

data是一条消息

当消息在完成之前结束时出现。

错误

data是错误

发生错误时回调。这可能是由于内部服务器错误或超时而发生的。

做

data是[DONE]

在流结束时发生。

介绍

认证

API 密钥

组织和项目 （可选）

提出请求

流

解析 Server 发送的事件

调试请求

在 SDK 中访问原始响应对象

向后兼容性

音频

创建语音

请求正文

返回

创建转录

请求正文

返回

创建翻译

请求正文

返回

转录对象 （JSON）

转录对象 （Verbose JSON）

聊天

创建聊天完成

请求正文

返回

聊天完成对象

聊天完成区块对象

Embeddings

创建嵌入

请求正文

返回

嵌入对象

微调

创建微调作业

请求正文

返回

列出微调作业

查询参数

返回

列出微调事件

路径参数

查询参数

返回

列出微调检查点

路径参数

查询参数

返回

检索微调作业

路径参数

返回

取消微调

路径参数

返回

聊天模型的训练格式

完成模型的训练格式

微调作业对象

微调作业事件对象

微调作业检查点对象

Batch

创建批处理

请求正文

返回

检索批次

路径参数

返回

取消批处理

路径参数

返回

列出批次

查询参数

返回

batch 对象

请求输入对象

请求输出对象

文件

上传文件

请求正文

返回

列出文件

组织和项目（可选）

转录对象（JSON）

转录对象（Verbose JSON）

助理
试用版

创建助手
试用版

列出助理
试用版

检索助手
试用版

修改助手
试用版

删除助手
试用版