OpenAI 批处理资源与对象

批处理资源

取消批处理

post /batches/{batch_id}/cancel

取消正在进行的批处理。批处理会处于 cancelling 状态，最长持续 10 分钟，然后变为 cancelled；此时可以在输出文件中获得已完成的部分结果（如有）。

路径参数

batch_id: string

要取消的批处理的 ID。

返回值

Batch object { id, completion_window, created_at, 19 more }

id: string

completion_window: string

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

created_at: integer

创建批处理时的 Unix 时间戳，单位为秒。

format: unixtime

endpoint: string

批处理使用的 OpenAI API 端点。

input_file_id: string

批处理输入文件的 ID。

object: "batch"

对象类型，始终为 batch。

"batch"

status: "validating" or "failed" or "in_progress" or 5 more

批处理的当前状态。

"validating"

"failed"

"in_progress"

"finalizing"

"completed"

"expired"

"cancelling"

"cancelled"

cancelled_at: optional integer or null

批处理被取消时的 Unix 时间戳，单位为秒。

format: unixtime

cancelling_at: optional integer or null

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

format: unixtime

completed_at: optional integer or null

批处理完成时的 Unix 时间戳，单位为秒。

format: unixtime

error_file_id: optional string or null

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

errors: optional object { data, object } or null

data: optional array of BatchError

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

object: optional string

对象类型，始终为 list。

expired_at: optional integer or null

批处理过期时的 Unix 时间戳，单位为秒。

format: unixtime

expires_at: optional integer or null

批处理将过期的 Unix 时间戳，单位为秒。

format: unixtime

failed_at: optional integer or null

批处理失败时的 Unix 时间戳，单位为秒。

format: unixtime

finalizing_at: optional integer or null

批处理开始收尾时的 Unix 时间戳，单位为秒。

format: unixtime

in_progress_at: optional integer or null

批处理开始处理时的 Unix 时间戳，单位为秒。

format: unixtime

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

model: optional string

用于处理批处理的模型 ID，例如 gpt-6-astra。OpenAI 提供多种能力、性能特点和价格各异的模型。请参阅模型指南，浏览和比较可用模型。

output_file_id: optional string or null

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

request_counts: optional BatchRequestCounts

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

usage: optional BatchUsage

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches/$BATCH_ID/cancel \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

响应示例

{
  "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": "夜间评测任务"
  }
}

创建批处理

post /batches

根据已上传的请求文件创建并执行批处理。

请求体参数

内容类型：application/json

completion_window: "24h"

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

"24h"

endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more

批处理中所有请求使用的端点。目前支持 /v1/responses、/v1/chat/completions、/v1/embeddings、/v1/completions、/v1/moderations、/v1/images/generations、/v1/images/edits 和 /v1/videos。注意：对于 /v1/embeddings 批处理，所有请求合计最多包含 50,000 个嵌入输入。

"/v1/responses"

"/v1/chat/completions"

"/v1/embeddings"

"/v1/completions"

"/v1/moderations"

"/v1/images/generations"

"/v1/images/edits"

"/v1/videos"

input_file_id: string

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

关于如何上传文件，请参阅上传文件。

输入文件必须采用 JSONL 格式，并以 batch 用途上传。文件最多可包含 50,000 个请求，大小最多为 200 MB。

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

output_expires_after: optional object { anchor, seconds }

为批处理生成的输出文件和／或错误文件的过期策略。

anchor: "created_at"

过期策略生效所依据的基准时间戳。支持的基准为 created_at。注意：这里指文件创建时间，而非批处理创建时间。

"created_at"

seconds: integer

文件在基准时间之后的有效秒数，范围为 3600 秒（1 小时）至 2592000 秒（30 天）。

format: int64, minimum: 3600, maximum: 2592000

返回值

Batch object { id, completion_window, created_at, 19 more }

id: string

completion_window: string

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

created_at: integer

创建批处理时的 Unix 时间戳，单位为秒。

format: unixtime

endpoint: string

批处理使用的 OpenAI API 端点。

input_file_id: string

批处理输入文件的 ID。

object: "batch"

对象类型，始终为 batch。

"batch"

status: "validating" or "failed" or "in_progress" or 5 more

批处理的当前状态。

"validating"

"failed"

"in_progress"

"finalizing"

"completed"

"expired"

"cancelling"

"cancelled"

cancelled_at: optional integer or null

批处理被取消时的 Unix 时间戳，单位为秒。

format: unixtime

cancelling_at: optional integer or null

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

format: unixtime

completed_at: optional integer or null

批处理完成时的 Unix 时间戳，单位为秒。

format: unixtime

error_file_id: optional string or null

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

errors: optional object { data, object } or null

data: optional array of BatchError

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

object: optional string

对象类型，始终为 list。

expired_at: optional integer or null

批处理过期时的 Unix 时间戳，单位为秒。

format: unixtime

expires_at: optional integer or null

批处理将过期的 Unix 时间戳，单位为秒。

format: unixtime

failed_at: optional integer or null

批处理失败时的 Unix 时间戳，单位为秒。

format: unixtime

finalizing_at: optional integer or null

批处理开始收尾时的 Unix 时间戳，单位为秒。

format: unixtime

in_progress_at: optional integer or null

批处理开始处理时的 Unix 时间戳，单位为秒。

format: unixtime

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

model: optional string

用于处理批处理的模型 ID，例如 gpt-6-astra。OpenAI 提供多种能力、性能特点和价格各异的模型。请参阅模型指南，浏览和比较可用模型。

output_file_id: optional string or null

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

request_counts: optional BatchRequestCounts

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

usage: optional BatchUsage

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "completion_window": "24h",
          "endpoint": "/v1/responses",
          "input_file_id": "input_file_id"
        }'

200 响应示例

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
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"
  }'

响应示例

{
  "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": "夜间评测任务"
  }
}

列出批处理

get /batches

列出组织的批处理。

查询参数

after: optional string

分页游标。after 使用对象 ID 表示列表中的位置。例如，本次返回 100 个对象，最后一个为 obj_foo，则下次可传入 after=obj_foo 获取下一页。

limit: optional integer (default: 20)

返回对象数量上限，范围为 1–100，默认为 20。

返回值

data: array of Batch

id: string

completion_window: string

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

created_at: integer

创建批处理时的 Unix 时间戳，单位为秒。

format: unixtime

endpoint: string

批处理使用的 OpenAI API 端点。

input_file_id: string

批处理输入文件的 ID。

object: "batch"

对象类型，始终为 batch。

"batch"

status: "validating" or "failed" or "in_progress" or 5 more

批处理的当前状态。

"validating"

"failed"

"in_progress"

"finalizing"

"completed"

"expired"

"cancelling"

"cancelled"

cancelled_at: optional integer or null

批处理被取消时的 Unix 时间戳，单位为秒。

format: unixtime

cancelling_at: optional integer or null

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

format: unixtime

completed_at: optional integer or null

批处理完成时的 Unix 时间戳，单位为秒。

format: unixtime

error_file_id: optional string or null

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

errors: optional object { data, object } or null

data: optional array of BatchError

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

object: optional string

对象类型，始终为 list。

expired_at: optional integer or null

批处理过期时的 Unix 时间戳，单位为秒。

format: unixtime

expires_at: optional integer or null

批处理将过期的 Unix 时间戳，单位为秒。

format: unixtime

failed_at: optional integer or null

批处理失败时的 Unix 时间戳，单位为秒。

format: unixtime

finalizing_at: optional integer or null

批处理开始收尾时的 Unix 时间戳，单位为秒。

format: unixtime

in_progress_at: optional integer or null

批处理开始处理时的 Unix 时间戳，单位为秒。

format: unixtime

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

model: optional string

用于处理批处理的模型 ID，例如 gpt-6-astra。OpenAI 提供多种能力、性能特点和价格各异的模型。请参阅模型指南，浏览和比较可用模型。

output_file_id: optional string or null

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

request_counts: optional BatchRequestCounts

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

usage: optional BatchUsage

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。

has_more: boolean

object: "list"

"list"

first_id: optional string

last_id: optional string

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "data": [
    {
      "id": "id",
      "completion_window": "completion_window",
      "created_at": 0,
      "endpoint": "endpoint",
      "input_file_id": "input_file_id",
      "object": "batch",
      "status": "validating",
      "cancelled_at": 0,
      "cancelling_at": 0,
      "completed_at": 0,
      "error_file_id": "error_file_id",
      "errors": {
        "data": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ],
        "object": "object"
      },
      "expired_at": 0,
      "expires_at": 0,
      "failed_at": 0,
      "finalizing_at": 0,
      "in_progress_at": 0,
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "output_file_id": "output_file_id",
      "request_counts": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "first_id": "batch_abc123",
  "last_id": "batch_abc456"
}

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches?limit=2 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

响应示例

{
  "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": "夜间任务"
      }
    }
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc123",
  "has_more": false
}

检索批处理

get /batches/{batch_id}

检索一个批处理。

路径参数

batch_id: string

要检索的批处理的 ID。

返回值

Batch object { id, completion_window, created_at, 19 more }

id: string

completion_window: string

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

created_at: integer

创建批处理时的 Unix 时间戳，单位为秒。

format: unixtime

endpoint: string

批处理使用的 OpenAI API 端点。

input_file_id: string

批处理输入文件的 ID。

object: "batch"

对象类型，始终为 batch。

"batch"

status: "validating" or "failed" or "in_progress" or 5 more

批处理的当前状态。

"validating"

"failed"

"in_progress"

"finalizing"

"completed"

"expired"

"cancelling"

"cancelled"

cancelled_at: optional integer or null

批处理被取消时的 Unix 时间戳，单位为秒。

format: unixtime

cancelling_at: optional integer or null

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

format: unixtime

completed_at: optional integer or null

批处理完成时的 Unix 时间戳，单位为秒。

format: unixtime

error_file_id: optional string or null

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

errors: optional object { data, object } or null

data: optional array of BatchError

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

object: optional string

对象类型，始终为 list。

expired_at: optional integer or null

批处理过期时的 Unix 时间戳，单位为秒。

format: unixtime

expires_at: optional integer or null

批处理将过期的 Unix 时间戳，单位为秒。

format: unixtime

failed_at: optional integer or null

批处理失败时的 Unix 时间戳，单位为秒。

format: unixtime

finalizing_at: optional integer or null

批处理开始收尾时的 Unix 时间戳，单位为秒。

format: unixtime

in_progress_at: optional integer or null

批处理开始处理时的 Unix 时间戳，单位为秒。

format: unixtime

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

model: optional string

用于处理批处理的模型 ID，例如 gpt-6-astra。OpenAI 提供多种能力、性能特点和价格各异的模型。请参阅模型指南，浏览和比较可用模型。

output_file_id: optional string or null

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

request_counts: optional BatchRequestCounts

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

usage: optional BatchUsage

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches/$BATCH_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

示例

## 先设置 OPENAI_API_KEY；按当前接口需要替换示例 ID 和参数。
curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \

响应示例

{
  "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": "夜间评测任务"
  }
}

资源类型

批处理对象

Batch object { id, completion_window, created_at, 19 more }

id: string

completion_window: string

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

created_at: integer

创建批处理时的 Unix 时间戳，单位为秒。

format: unixtime

endpoint: string

批处理使用的 OpenAI API 端点。

input_file_id: string

批处理输入文件的 ID。

object: "batch"

对象类型，始终为 batch。

"batch"

status: "validating" or "failed" or "in_progress" or 5 more

批处理的当前状态。

"validating"

"failed"

"in_progress"

"finalizing"

"completed"

"expired"

"cancelling"

"cancelled"

cancelled_at: optional integer or null

批处理被取消时的 Unix 时间戳，单位为秒。

format: unixtime

cancelling_at: optional integer or null

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

format: unixtime

completed_at: optional integer or null

批处理完成时的 Unix 时间戳，单位为秒。

format: unixtime

error_file_id: optional string or null

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

errors: optional object { data, object } or null

data: optional array of BatchError

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

object: optional string

对象类型，始终为 list。

expired_at: optional integer or null

批处理过期时的 Unix 时间戳，单位为秒。

format: unixtime

expires_at: optional integer or null

批处理将过期的 Unix 时间戳，单位为秒。

format: unixtime

failed_at: optional integer or null

批处理失败时的 Unix 时间戳，单位为秒。

format: unixtime

finalizing_at: optional integer or null

批处理开始收尾时的 Unix 时间戳，单位为秒。

format: unixtime

in_progress_at: optional integer or null

批处理开始处理时的 Unix 时间戳，单位为秒。

format: unixtime

metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可以结构化方式存储对象的额外信息，并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为最多 512 个字符的字符串。

model: optional string

用于处理批处理的模型 ID，例如 gpt-6-astra。OpenAI 提供多种能力、性能特点和价格各异的模型。请参阅模型指南，浏览和比较可用模型。

output_file_id: optional string or null

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

request_counts: optional BatchRequestCounts

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

usage: optional BatchUsage

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。

批处理错误

BatchError object { code, line, message, param }

code: optional string

标识错误类型的错误代码。

line: optional integer or null

输入文件中发生错误的行号（如适用）。

message: optional string

便于人阅读、包含更多错误详情的消息。

param: optional string or null

导致错误的参数名称（如适用）。

批处理请求计数

BatchRequestCounts object { completed, failed, total }

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

completed: integer

成功完成的请求数量。

failed: integer

失败的请求数量。

total: integer

批处理中的请求总数。

批处理用量

BatchUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }

词元用量详情，包括输入词元、输出词元、输出词元明细和词元总数。仅在 2025 年 9 月 7 日之后创建的批处理中填充。

input_tokens: integer

输入词元数量。

input_tokens_details: object { cached_tokens }

输入词元的详细分类统计。

cached_tokens: integer

从缓存中读取的词元数量。了解提示词缓存。

output_tokens: integer

输出词元数量。

output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

reasoning_tokens: integer

推理词元数量。

total_tokens: integer

使用的总词元数。