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

运行（v1）
Legacy

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

创建运行（v1）
Legacy

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

创建运行。source

路径参数

thread_id

字符串source

必填

要运行的线程的 ID。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 结束complete.看incomplete_details了解更多信息。source

max_completion_tokens

整数或 nullsource

可选

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

truncation_strategy

对象source

可选

tool_choice

字符串或对象source

可选

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

response_format

字符串或对象source

可选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号gpt-3.5-turbo-1106.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=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

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

元数据

地图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 结束complete.看incomplete_details了解更多信息。source

max_completion_tokens

整数或 nullsource

可选

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

truncation_strategy

对象source

可选

tool_choice

字符串或对象source

可选

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

response_format

字符串或对象source

可选

指定模型必须输出的格式。兼容 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 型号gpt-3.5-turbo-1106.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=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

返回属于线程的运行列表。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=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

返回属于运行的运行步骤列表。source

路径参数

thread_id

字符串source

必填

run 和 run steps 所属的线程的 ID。source

run_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

返回

运行步骤对象的列表。source

示例请求

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}

检索运行。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=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}

检索运行步骤。source

路径参数

thread_id

字符串source

必填

run 和 run step 所属的线程的 ID。source

run_id

字符串source

必填

运行步骤所属的运行的 ID。source

step_id

字符串source

必填

要检索的运行步骤的 ID。source

返回

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

示例请求

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}

修改运行。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=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

当运行具有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=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.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=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

表示在线程上运行的执行。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或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

file_ids

数组source

助手用于此运行的文件 ID 列表。source

元数据

地图source

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

tool_choice

字符串或对象source

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

response_format

字符串或对象source

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

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

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

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

表示执行运行的步骤。source

身份证

字符串source

运行步骤的标识符，可在 API 终端节点中引用。source

对象

字符串source

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

created_at

整数source

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

assistant_id

字符串source

与运行步骤关联的助手的 ID。source

thread_id

字符串source

运行的线程的 ID。source

run_id

字符串source

此运行步骤所属的运行的 ID。source

类型

字符串source

运行步骤的类型，可以是message_creation或tool_calls.source

地位

字符串source

运行步骤的状态，可以是in_progress,cancelled,failed,completed或expired.source

step_details

对象source

run 步骤的详细信息。source

last_error

object 或 nullsource

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

expired_at

整数或 nullsource

运行步骤过期时的 Unix 时间戳（以秒为单位）。如果父运行已过期，则认为步骤已过期。source

cancelled_at

整数或 nullsource

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

failed_at

整数或 nullsource

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

completed_at

整数或 nullsource

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

元数据

地图source

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

用法

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

创建运行 （v1）Legacy

路径参数

请求正文

返回

创建线程并运行 （v1）Legacy

请求正文

返回

列出运行 （v1）Legacy

路径参数

查询参数

返回

列出运行步骤 （v1）Legacy

路径参数

查询参数

返回

检索运行 （v1）Legacy

路径参数

返回

检索运行步骤 （v1）Legacy

路径参数

返回

修改运行 （v1）Legacy

路径参数

请求正文

返回

提交工具输出以运行 （v1）Legacy

路径参数

请求正文

返回

取消运行 （v1）Legacy

路径参数

返回

run 对象 （v1）Legacy

run step 对象 （v1）Legacy

运行（v1）
Legacy

创建运行（v1）
Legacy

创建线程并运行（v1）
Legacy

列出运行（v1）
Legacy

列出运行步骤（v1）
Legacy

检索运行（v1）
Legacy

检索运行步骤（v1）
Legacy

修改运行（v1）
Legacy

提交工具输出以运行（v1）
Legacy

取消运行（v1）
Legacy

run 对象（v1）
Legacy

run step 对象（v1）
Legacy