OpenAI API参考文档 | OpenAI开发文档|OpenAI中文官方文档|ChatGPT中文版|ChatGPT教程

运行
试用版

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

创建运行
试用版

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

创建运行。source

路径参数

thread_id

字符串source

必填

要运行的线程的 ID。source

查询参数

include[]

数组source

可选

要包含在响应中的其他字段的列表。目前唯一支持的值是step_details.tool_calls[*].file_search.results[*].content以获取文件搜索结果内容。source

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

请求正文

assistant_id

字符串source

必填

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

MODEL

字符串source

可选

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

指示

string 或 nullsource

可选

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

additional_instructions

string 或 nullsource

可选

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

additional_messages

array 或 nullsource

可选

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

工具

array 或 nullsource

可选

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

元数据

地图source

可选

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

温度

number 或 nullsource

可选

默认为 1

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

top_p

number 或 nullsource

可选

默认为 1

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

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

流

boolean 或 nullsource

可选

如果true返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有data: [DONE]消息。source

max_prompt_tokens

整数或 nullsource

可选

在运行过程中可以使用的提示令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的提示令牌数。如果运行超过指定的提示令牌数，则运行将以 status 结束incomplete.看incomplete_details了解更多信息。source

max_completion_tokens

整数或 nullsource

可选

在运行过程中可以使用的完成令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的完成令牌数。如果运行超过指定的完成令牌数，则运行将以 status 结束incomplete.看incomplete_details了解更多信息。source

truncation_strategy

对象source

可选

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

tool_choice

字符串或对象source

可选

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

parallel_tool_calls

布尔source

可选

默认为 true

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

response_format

“auto” 或 objectsource

可选

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

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

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

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

返回

run 对象。source

示例请求

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
}

创建线程并运行
试用版

POST https://api.openai.com/v1/threads/runs

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

请求正文

assistant_id

字符串source

必填

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

线程

对象source

可选

MODEL

字符串source

可选

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

指示

string 或 nullsource

可选

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

工具

array 或 nullsource

可选

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

tool_resources

object 或 nullsource

可选

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

元数据

地图source

可选

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

温度

number 或 nullsource

可选

默认为 1

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

top_p

number 或 nullsource

可选

默认为 1

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

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

流

boolean 或 nullsource

可选

如果true返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有data: [DONE]消息。source

max_prompt_tokens

整数或 nullsource

可选

在运行过程中可以使用的提示令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的提示令牌数。如果运行超过指定的提示令牌数，则运行将以 status 结束incomplete.看incomplete_details了解更多信息。source

max_completion_tokens

整数或 nullsource

可选

在运行过程中可以使用的完成令牌的最大数量。运行将尽最大努力在运行的多个轮次中仅使用指定的完成令牌数。如果运行超过指定的完成令牌数，则运行将以 status 结束incomplete.看incomplete_details了解更多信息。source

truncation_strategy

对象source

可选

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

tool_choice

字符串或对象source

可选

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

parallel_tool_calls

布尔source

可选

默认为 true

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

response_format

“auto” 或 objectsource

可选

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

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

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

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

返回

run 对象。source

示例请求

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

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

路径参数

thread_id

字符串source

必填

运行所属线程的 ID。source

查询参数

限制

整数source

可选

默认为 20

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

次序

字符串source

可选

默认为 desc

按created_at对象的时间戳。asc对于升序和desc以降序排列。source

后

字符串source

可选

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

以前

字符串source

可选

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

返回

run 对象的列表。source

示例请求

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}

检索运行。source

路径参数

thread_id

字符串source

必填

运行的线程的 ID。source

run_id

字符串source

必填

要检索的运行的 ID。source

返回

与指定 ID 匹配的 run 对象。source

示例请求

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}

修改运行。source

路径参数

thread_id

字符串source

必填

运行的线程的 ID。source

run_id

字符串source

必填

要修改的运行的 ID。source

请求正文

元数据

地图source

可选

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

返回

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

示例请求

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

当运行具有status: "requires_action"和required_action.type是submit_tool_outputs，则此终端节点可用于在工具调用全部完成后提交其输出。所有输出都必须在单个请求中提交。source

路径参数

thread_id

字符串source

必填

此运行所属的线程的 ID。source

run_id

字符串source

必填

需要提交工具输出的运行的 ID。source

请求正文

tool_outputs

数组source

必填

要提交其输出的工具列表。source

流

boolean 或 nullsource

可选

如果true返回在 Run as server-sent 事件期间发生的事件流，当 Run 进入带有data: [DONE]消息。source

返回

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

示例请求

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.source

路径参数

thread_id

字符串source

必填

此运行所属的线程的 ID。source

run_id

字符串source

必填

要取消的运行的 ID。source

返回

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

示例请求

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 对象
试用版

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

身份证

字符串source

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

对象

字符串source

对象类型，始终为thread.run.source

created_at

整数source

创建运行时的 Unix 时间戳（以秒为单位）。source

thread_id

字符串source

作为此运行的一部分执行的线程的 ID。source

assistant_id

字符串source

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

地位

字符串source

运行的状态，可以是queued,in_progress,requires_action,cancelling,cancelled,failed,completed,incomplete或expired.source

required_action

object 或 nullsource

有关继续运行所需作的详细信息。将是null如果不需要执行任何作。source

last_error

object 或 nullsource

与此运行关联的最后一个错误。将是null如果没有错误。source

expires_at

整数或 nullsource

运行过期时间的 Unix 时间戳（以秒为单位）。source

started_at

整数或 nullsource

运行启动时的 Unix 时间戳（以秒为单位）。source

cancelled_at

整数或 nullsource

取消运行时的 Unix 时间戳（以秒为单位）。source

failed_at

整数或 nullsource

运行失败时的 Unix 时间戳（以秒为单位）。source

completed_at

整数或 nullsource

运行完成时的 Unix 时间戳（以秒为单位）。source

incomplete_details

object 或 nullsource

有关运行未完成原因的详细信息。将是null如果运行不是未完成的。source

MODEL

字符串source

助手用于此运行的模型。source

指示

字符串source

助手用于此运行的说明。source

工具

数组source

助手用于此运行的工具列表。source

元数据

地图source

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

用法

object 或 nullsource

与运行相关的使用情况统计信息。该值将为null如果运行未处于 TERMINAL 状态（即in_progress,queued等）。source

温度

number 或 nullsource

用于此运行的采样温度。如果未设置，则默认为 1。source

top_p

number 或 nullsource

用于此运行的 nucleus 采样值。如果未设置，则默认为 1。source

max_prompt_tokens

整数或 nullsource

指定为在运行过程中使用的提示令牌的最大数量。source

max_completion_tokens

整数或 nullsource

指定为在运行过程中使用的最大完成令牌数。source

truncation_strategy

对象source

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

tool_choice

字符串或对象source

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

parallel_tool_calls

布尔source

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

response_format

“auto” 或 objectsource

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

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

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

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

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
}

运行试用版

创建运行试用版

路径参数

查询参数

请求正文

返回

创建线程并运行试用版

请求正文

返回

列出运行试用版

路径参数

查询参数

返回

检索运行试用版

路径参数

返回

修改运行试用版

路径参数

请求正文

返回

提交工具输出以运行试用版

路径参数

请求正文

返回

取消运行试用版

路径参数

返回

run 对象试用版

运行
试用版

创建运行
试用版

创建线程并运行
试用版

列出运行
试用版

检索运行
试用版

修改运行
试用版

提交工具输出以运行
试用版

取消运行
试用版

run 对象
试用版