Files + Batch 接口使用指南（OpenAI 兼容版）

更新时间：2026-02-02

1、前置准备

获取APikey：调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。
开通BOS：账户需要开通BOS对象存储，如您未开通BOS功能，可提前开通。

2、标准操作流程

整个批推过程分为四个步骤：准备数据 -> 上传文件 -> 创建 Batch 任务 -> 查询结果。

2.1、数据准备

创建一个.jsonl文件（例如batch_input.jsonl），每一行是一个独立的 JSON 对象，格式需严格符合 OpenAI 的 Batch 标准。 JSONL文件内容示例：

                Json
                
                {"custom_id": "request-1", "method": "POST", "url": "/v2/chat/completions", "body": {"model": "ernie-4.5-0.3b", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}],"top_p": 0.5, "temperature": 0.9, "penalty_score": 1.1}}

注意：由于此jsonl文件会用于后续的批量推理任务，因此需要严格符合 OpenAI 的 Batch的文件格式要求
文件内字段说明：

字段	类型	必填	说明
custom_id	String	是	每一行请求的唯一标识。由于批量任务是异步且可能乱序处理的，结果文件将通过此ID与您的原始请求进行关联对应。
method	String	是	HTTP请求方法，仅支持POST.
url	String	是	API关联的URL，需和创建batch任务时的endpoint保持一致。 chat与视觉理解模型为：/v2/chat/completions. 图像生成为：/v2/images/generations. 图像编辑为：/v2/images/edits.
body	Object	是	模型调用的请求体，包含调用模型所需的全部参数，如`model`、`messages`、`enable_thinking`，`thinking_budget`等。请求体中的参数与实时推理接口所支持的参数保持一致。如果需要进一步扩展支持更多参数（如`max_tokens`, `temperature`等），也可以添加到`body`中，参数之间通过英文逗号隔开。
extra_body	Object	否	额外的请求体字段。其内容会与当前请求的默认 body 合并，同名字段以 extra_body 中的值为准。
extra_body.replace	Array	否	在已有请求体的基础上，对指定字段进行覆盖。适用于针对单条请求修改公共 body 中的部分参数。

2.2、利用files接口上传文件

前置条件：账户需要开通BOS服务。
上传files文件校验:

文件格式必须为JSONL，每行一个JSON格式的请求
单个Batch最多包含5000个请求
单个Batch任务的所有请求必须选用同一个模型
- 提示：用户如果要使用openAI SDK，需要保持同一batch任务中model统一，强制异步校验，model不统一会报错。可以在2.3创建批量推理任务中使用"replace":{"model":"deepseek-v3"}指定jsonl文件中的model参数（例：deepseek-v3），用于统一覆盖输入文件中所有请求的模型参数。
单行的请求内容需遵循各模型上下文长度限制
Batch文件最大为1G
每一行的body中必须包含messages对象数组
可以为每一行数据按需设置相同或不同的推理参数，如设定不同的temperature、top_p

请求示例：

                Bash
                
            

                curl --request POST \
  --url https://qianfan.baidubce.com/v2/files \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Authorization: Bearer bce-v3/ALTAK-NPkz8kqLd9wdYUjr3FLho/*****************6477ef23cc8597b' \
  --header 'Connection: keep-alive' \
  --header 'User-Agent: PostmanRuntime-ApipostRuntime/1.1.0' \
  --header 'content-type: multipart/form-data' \
  --form purpose=batch \
  --form 'file=@[object Object]'
            

form（表单）支持参数：

参数名	参数类型	是否必须	参数描述
file	string	是	要上传的文件
purpose	string	是	指定文件用途，支持assistants、batch、fine-tune、vision、user_data、evals

对于批量推理（batch）任务，purpose选择batch即可

返回示例：

                Json
                
            

                {
    "id": "file-uxebkndtfm",
    "object": "file",
    "bytes": 2349,
    "created_at": 1769749720,
    "filename": "test.jsonl",
    "purpose": "batch"
}
            

2.3、创建批量推理任务

2.3.1 请求

请求基本信息：

请求地址：https://qianfan.baidubce.com/v2/batches
请求方式：POST

Header参数：

Content-Type	String	是	HTTP请求内容的类型，固定值：application/json
Authorization	String	是	填写APIkey，APIKey获取方式

Body参数：

名称	类型	必填	描述	备注
completion_window	string	是	最大运行时间支持1-672h可选值 \dh
endpoint	string	是	可选： chat与视觉理解模型为：/v2/chat/completions 图像生成为：/v2/images/generations 图像编辑为：/v2/images/edits
input_file_id	string	是	已上传文件的ID约束： 1. 使用files接口上传文件 2. 文件格式需要为jsonl 3. purpose需要为batch4. 文件中请求最多5000个，文件最大1G	参考”第二步：利用files接口上传文件“中返回的id示例："id": "file-4u2y7ue9iw"
metadata	map	否	存储附加信息16个key-value对存储
replace	string	否	替换文件中model参数，用于统一覆盖输入文件中所有请求的模型参数。	{"model":"deepseek-v3"} {"model":"amv-bwmjp1ujiuyp"} 如果是预置服务，填写接入点model如果是千帆平台模型可填modelVersionId

2.3.2响应

响应参数：

字段	类型	说明	备注
id	string
object	string	对象类型，返回“batch”
endpoint	string	例：/v2/completions需要与输入文件中的url字段保持一致
model	string	model 入参
errors	object	任务级别错误码	{ "failureCode": 205, "failureReason": "data content not json line"}
input_file_id	string	batch文件的ID
completion_window	string	任务处理时间，只能填“1-672h”
status	string	batch的当前状态	任务运行状态 Running: 运行中 Done: 运行完成 Stopped: 运行中止 Failed: 运行失败 Expired: 运行超时
output_file_id	string	成功处理后的文件ID
error_file_id	string	错误请求的文件ID
created_at	int	batch被创建的时间
in_progress_at	int	batch开始处理的时间
expires_at	int	batch将会过期的时间点
finalizing_at	int	batch开始完成的时间（started finalizing）
completed_at	int	batch完成的时间
failed_at	int	批推处理失败的时间
expired_at	int	batch已过期的时间点
cancelled_at	int	取消完成时间
cancelling_at	int	batch真正开始取消的时间
request_counts	object	示例： { "total": 2, "completed": 2, "failed": 0 }	total：总请求数completed：已完成failed：失败数量
usage 1. input_tokens 2.input_tokens_details 3.output_tokens 4. output_tokens_details 5. total_tokens	object	示例：	input_tokens：输入Tokens数量cached_tokens：命中缓存Tokens数量output_tokens：输出Tokens数量reasoning_tokens：深度思考Tokens数量total_tokens：总Tokens数量
metadata	map	扩展元数据	{ "description": "nightly eval job"}

2.3.3调用示例

请求：

                Bash
                
            

                POST /v2/batches HTTP/1.1
Host: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
    "completion_window": "1h",
    "endpoint": "/v2/chat/completions",
    "input_file_id": "file-****7cz9",
    "metadata":{
        "model": "llama-3-8b", 
        "messages": [
                        {
                            "role": "user", 
                            "content": "Tell me a joke about programming."
                        }
                    ], 
        "temperature": 1.0
                },
    "replace": {"model": "deepseek-v3"}
}
            

                Json
                
            

                {
    "id": "infer-5ghwq9mqh7e9",
    "object": "batch",
    "endpoint": "/v2/chat/completions",
    "model": "deepseek-v3",
    "errors": null,
    "input_file_id": "file-9x3zvgwkex",
    "completion_window": "24h",
    "status": "Done",
    "output_file_id": "file-ynedb6bxju",
    "error_file_id": null,
    "created_at": 1769764375,
    "in_progress_at": 1769764384,
    "expires_at": 1769850775,
    "finalizing_at": 1769764439,
    "completed_at": 1769764439,
    "failed_at": null,
    "expired_at": null,
    "cancelled_at": null,
    "cancelling_at": null,
    "request_counts": {
        "total": 1,
        "completed": 1,
        "failed": 0
    },
    "usage": {
        "input_tokens": 21,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 13,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 34
    },
    "metadata": {
        "messages": [
            {
                "content": "Tell me a joke about programming.",
                "role": "user"
            }
        ],
        "model": "llama-3-8b",
        "temperature": 1
    }
}
            

2.4 获取批量推理任务详情

由于批量推理任务为异步任务，因此可以通过查询接口来获取批量推理任务详情

2.4.1 请求

请求基本信息：

请求地址：https://qianfan.baidubce.com/v2/batches/{batch_id}
请求方式：GET

Header参数：

名称	类型	必填	描述
Content-Type	String	是	HTTP请求内容的类型，固定值：application/json
Authorization	String	是	填写APIkey APIKey获取方式

query参数：

名称	类型	必填	描述
{batch_id}	string	是	批量推理ID，格式 infer-xxxx

2.4.2 响应

响应参数：

字段	类型	说明	备注
id	string
object	string	对象类型，返回“batch”
endpoint	string	例：/v2/completions需要与输入文件中的url字段保持一致
model	string	model 入参
errors	object	任务级别错误码	{ "failureCode": 205, "failureReason": "data content not json line"}
input_file_id	string	batch文件的ID
completion_window	string	任务处理时间，只能填“1-672h”
status	string	batch的当前状态	任务运行状态 Running: 运行中 Done: 运行完成 Stopped: 运行中止 Failed: 运行失败 Expired: 运行超时
output_file_id	string	成功处理后的文件ID
error_file_id	string	错误请求的文件ID
created_at	int	batch被创建的时间
in_progress_at	int	batch开始处理的时间
expires_at	int	batch将会过期的时间点
finalizing_at	int	batch开始完成的时间（started finalizing）
completed_at	int	batch完成的时间
failed_at	int	批推处理失败的时间
expired_at	int	batch已过期的时间点
cancelled_at	int	取消完成时间
cancelling_at	int	batch真正开始取消的时间
request_counts	object	示例：{ "total": 2, "completed": 2, "failed": 0 }	total：总请求数completed：已完成failed：失败数量
usage 1.input_tokens 2.input_tokens_details 3.output_tokens 4.output_tokens_details 5.total_tokens	object	示例：	input_tokens：输入Tokens数量 cached_tokens：命中缓存Tokens数量 output_tokens：输出Tokens数量 reasoning_tokens：深度思考Tokens数量 total_tokens：总Tokens数量
metadata	map	扩展元数据	{ "description": "nightly eval job"}

2.4.3调用示例

请求：

                Bash
                
            

                curl --request GET \
  --url 'http://qianfan.baidubce.com/v2/batches?{batch_id}=infer-48fhgga8v8zh' \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Authorization: Bearer bce-v3/ALTAK-NPkz8kqLd9wdYUjr3FLho/3c9c0dee76f5**************************' \
  --header 'Connection: keep-alive' \
  --header 'User-Agent: PostmanRuntime-ApipostRuntime/1.1.0'
            

                Json
                
            

                {
    "id": "infer-48fhgga8v8zh",
    "object": "batch",
    "endpoint": "/v2/chat/completions",
    "model": "deepseek-v3",
    "errors": null,
    "input_file_id": "file-uxebkndtfm",
    "completion_window": "1h",
    "status": "Queuing",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1769750116,
    "in_progress_at": null,
    "expires_at": 1769753716,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelled_at": null,
    "cancelling_at": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    },
    "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 0
    },
    "metadata": {
        "messages": [
            {
                "content": "Tell me a joke about programming.",
                "role": "user"
            }
        ],
        "model": "llama-3-8b",
        "temperature": 1
    }
}
            

2.5 利用files接口获取任务执行结果

通过files的retrieve content接口获取任务的执行结果，其中file.id为查询批量推理任务中返回的output_file_id。
调用示例：

                Bash
                
            

                curl --request GET \
  --url https://qianfan.baidubce.com/v2/files/{file.id}/content \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Authorization: Bearer bce-v3/ALTAK-NPkz8kqLd9wdYUjr3FLho/3c9c0d8888888*******86477ef23cc8597b' \
  --header 'Connection: keep-alive' \
  --header 'User-Agent: PostmanRuntime-ApipostRuntime/1.1.0'
            

返回结果：

                Json
                
            

                {
    "response": {
        "status_code": 200,
        "body": {
            "choices": [
                {
                    "finish_reason": "stop",
                    "flag": 0,
                    "index": 0,
                    "message": {
                        "content": "The sum of 2 and 2 is **4**.",
                        "role": "assistant"
                    }
                }
            ],
            "created": 1769764430,
            "id": "as-tb7zbgvp8s",
            "model": "deepseek-v3",
            "object": "chat.completion",
            "usage": {
                "completion_tokens": 13,
                "prompt_tokens": 21,
                "total_tokens": 34
            }
        },
        "request_id": "as-tb7zbgvp8s"
    },
    "custom_id": "request-1",
    "id": "as-tb7zbgvp8s"
}
            

通过服务网卡私网访问千帆模型服务

应用开发

百度智能云

百度千帆·大模型服务及Agent开发平台