# 星火大模型批处理API文档

    有奖调研 (opens new window)诚邀您参与我们星火大模型服务有奖调研，参与问卷即有机会获取千万Tokens
    技术咨询可直接提交工单 (opens new window)

    # 一、服务介绍

    以通过文件方式提交批量任务，任务将异步执行，在24小时内返回结果，费用仅为实时调用的30%。
    文件保存时间： 上传的文件默认保存 48h；接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。
    文件要求：
    格式：只支持 jsonl 文件名后缀
    custom_id：全文件不能存在重复
    method：只支持 POST
    url：只支持 /v1/chat/completions
    model：支持 x1、4.0Ultra、generalv3.5。x1指向深度推理Spark X1，generalv3.5指向Spark Max，4.0Ultra指向Spark4.0 Ultra。
    注意：每个请求一行，单个文件不超过5万行；每个请求中body 长度 <= 6KB，body 中 model 全文件保持相同
    文件单行示例：

    {"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "4.0Ultra", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "1+1=?"}],"max_tokens": 1000}}

    # 二、接口 Demo

    部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到讯飞开放平台社区 (opens new window)交流集成经验。
    批处理API-Demo-Java (opens new window)

    批处理API-Demo-Python (opens new window)

    批处理API PYTHON-SDK-DEMO (opens new window)

    批处理API JAVA-SDK-DEMO (opens new window)

    # 三、接口列表

    # 接口鉴权

    请到控制台获取http服务接口认证信息中的APIPassword，假如获取到的值为123456，则请求头如下：

    Authorization: Bearer 123456

    # 3.1、上传文件

    # 接口描述

    上传jsonl文件，文件格式需要符合要求（具体可参考 一、服务介绍），上传的文件默认保存 48h。

    # 接口地址

    POST   https://spark-api-open.xf-yun.com/v1/files

    # 请求头

    Authorization: Bearer $APIPassword
Content-Type: multipart/form-data

    # 请求体

    字段名 类型 是否必传 描述
    purpose string 是 传 batch，表示上传文件的意图
    file file 是 文件（最大不超过 100 MB，默认保存48h）

    # 响应参数说明

    字段名 类型 描述
    id string 文件唯一标识符（全局唯一）
    格式为：file_xxxxx
    object string 上传类型(扩展字段，当前仅为 file)
    bytes int 文件长度(单位：Byte)
    created_at int 文件创建时间
    filename string 文件名
    purpose string 上传文件的意图(请求参数传入值)

    # 响应参数示例

    {
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "mydata.jsonl",
  "purpose": "batch"
}

    # 3.2、查询文件列表

    # 接口描述

    获取 appid 下的文件列表。 上传的文件默认保存 48h；接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

    # 接口地址

    GET   https://spark-api-open.xf-yun.com/v1/files?page=1&size=20

    按创建时间排序，获取 [(page-1) 20 + 1, (page-1) 20 + size] 的数据

    # 请求头

    Authorization: Bearer $APIPassword

    # 响应参数示例

    {
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "filename": "mydata.jsonl",
      "purpose": "batch"
    },
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "filename": "puppy.jsonl",
      "purpose": "batch"
    }
  ],
  "object": "list"
}

    # 3.3、查询单个文件

    # 接口描述

    根据文件的file_id获取该文件信息。 上传的文件默认保存 48h；接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

    # 接口地址

    GET   https://spark-api-open.xf-yun.com/v1/files/{file_id}

    注意：请求参数file_id放在路径中！

    # 请求头

    Authorization: Bearer $APIPassword

    # 响应参数示例

    {
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "mydata.jsonl",
  "purpose": "batch"
}

    # 3.4、删除文件

    # 接口描述

    根据文件的file_id删除该文件

    # 接口地址

    DELETE   https://spark-api-open.xf-yun.com/v1/files/{file_id}

    注意：请求参数file_id放在路径中！

    # 请求头

    Authorization: Bearer $APIPassword

    # 响应参数示例

    {
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

    # 3.5、下载文件

    # 接口描述

    根据文件的file_id获取文件的详细内容。 上传的文件默认保存 48h；接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

    # 接口地址

    GET   https://spark-api-open.xf-yun.com/v1/files/{file_id}/content

    注意：请求参数file_id放在路径中！

    # 请求头

    Authorization: Bearer $APIPassword

    # 响应参数示例

    响应为文件的详细内容，可参考：

    {"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "4.0Ultra", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "1+1=?"}],"max_tokens": 1000}}

    # 3.6、创建Batch任务

    # 接口描述

    调用该接口前需要先上传jsonl文件，通过上传文件得到的file_id来创建Batch任务。 单个Batch任务最多包含5万个请求（一个请求对应jsonl文件的一行），每个请求的body不超过6KB

    # 接口地址

    POST   https://spark-api-open.xf-yun.com/v1/batches

    # 请求头

    Authorization: Bearer $APIPassword
Content-Type: application/json

    # 请求体

    字段名 类型 是否必传 描述
    input_file_id string 是 文件标识符 （上传文件成功时返回的 file_id）
    格式为：file_xxxxx
    endpoint string 是 处理批任务的服务的 path 路径
    当前仅支持 /v1/chat/completions
    completion_window string 是 批处理任务完成的时间窗口
    当前仅支持 24h，在此时间内完成，超时则不再处理，未处理任务视为失败
    metadata Map<String, String> 否 批任务附加信息，例如：
    "customer_id": "user_123456789"
    "batch_description": "Sentiment classification"

    # 响应参数说明

    字段名 类型 描述
    id string 批任务唯一标识（全局唯一）
    格式为：batch_xxxxx
    object string 结构类型，当前仅为 batch
    endpoint string 处理批任务的服务的 path 路径，当前仅为 /v1/chat/completions
    errors object 错误列表
    errors.object string 描述 data 类型 (list)
    errors.data array [{code string, message string, param string or null, line int or null}]
    input_file_id string 文件id（用户入参）
    status string 任务状态（枚举值）
    output_file_id string 结果文件id
    error_file_id string 错误文件id
    created_at int 任务创建时间（unix时间戳，下面的时间也均为unix时间戳）
    in_progress_at int 任务开始处理时间
    expires_at int 任务预期超时时间
    finalizing_at int 任务完成开始时间(写 out_file && error_file 开始)
    completed_at int 任务完成结束时间(写 out_file && error_file 结束)
    failed_at int 任务失败时间(所有任务失败时返回)
    expired_at int 任务实际超时时间
    cancelling_at int 任务取消开始时间 （收到取消请求时间）
    cancelled_at int 任务取消结束时间 （任务实际取消时间）
    request_counts object 批任务信息
    request_counts.total int 批任务当前完成总数
    request_counts.completed int 任务当前成功数
    request_counts.failed int 任务当前失败数
    metadata object 批任务附加信息（用户入参）

    # status字段说明

    枚举值 描述
    queuing 排队
    failed 处理失败
    in_progress 在处理
    finalizing 上传中
    completed 处理成功
    expired 超时
    canceled 已取消

    # 响应参数示例

    {
  "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": "Sentiment classification"
  }
}

    # 3.7、查询Batch任务

    # 接口描述

    根据batch_id获取该Batch任务的详细信息

    # 接口地址

    GET   https://spark-api-open.xf-yun.com/v1/batches/{batch_id}

    注意：请求参数batch_id放在路径中！

    # 请求头

    Authorization: Bearer $APIPassword
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": "Sentiment classification"
  }
}

    # 3.8、取消Batch任务

    # 接口描述

    根据batch_id取消该Batch任务

    # 接口地址

    GET   https://spark-api-open.xf-yun.com/v1/batches/{batch_id}/cancel

    注意：请求参数batch_id放在路径中！

    # 请求头

    Authorization: Bearer $APIPassword
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": "Sentiment classification"
  }
}

    # 3.9、查询Batch列表

    # 接口描述

    获取 appid 下的Batch列表

    # 接口地址

    GET   /v1/batches?limit=10&after={batch_id}

    注意：请求参数batch_id放在路径中！

    字段名 类型 是否必传 描述
    limit int 否，默认为10 响应中列表长度（最大为100）
    after string 否，默认从批任务创建时间正序排序开始查询 从此 batch_id 开始查询（响应中不包括此 batch_id）

    # 请求头

    Authorization: Bearer $APIPassword
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": "Sentiment classification"
      }
    },
    ......
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc456",
  "has_more": true
}
    在这篇文章中：
    在线咨询
    体验中心