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

Batch

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

创建批处理

POST https://api.openai.com/v1/batches

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

请求正文

input_file_id

字符串source

必填

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

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

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

Endpoint

字符串source

必填

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

completion_window

字符串source

必填

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

元数据

object 或 nullsource

可选

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

创建的 Batch 对象。source

示例请求

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}

检索批次。source

路径参数

batch_id

字符串source

必填

要检索的批处理的 ID。source

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

示例请求

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

取消正在进行的批处理。批处理将处于cancelling最多 10 分钟，然后更改为cancelled，其中输出文件中将提供部分结果（如果有）。source

路径参数

batch_id

字符串source

必填

要取消的批处理的 ID。source

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

示例请求

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

列出组织的批次。source

查询参数

后

字符串source

可选

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

限制

整数source

可选

默认为 20

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

分页的 Batch 对象列表。source

示例请求

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 对象

身份证

字符串source

对象

字符串source

对象类型，始终为batch.source

Endpoint

字符串source

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

错误

对象source

input_file_id

字符串source

批处理的输入文件的 ID。source

completion_window

字符串source

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

地位

字符串source

批处理的当前状态。source

output_file_id

字符串source

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

error_file_id

字符串source

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

created_at

整数source

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

in_progress_at

整数source

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

expires_at

整数source

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

finalizing_at

整数source

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

completed_at

整数source

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

failed_at

整数source

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

expired_at

整数source

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

cancelling_at

整数source

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

cancelled_at

整数source

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

request_counts

对象source

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

元数据

地图source

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

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

请求输入对象

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

custom_id

字符串source

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

方法

字符串source

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

网址

字符串source

要用于请求的 OpenAI API 相对 URL。现在/v1/chat/completions,/v1/embeddings和/v1/completions受支持。source

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?"}]}}

请求输出对象

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

身份证

字符串source

custom_id

字符串source

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

响应

object 或 nullsource

错误

object 或 nullsource

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

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}