MaaS 产品文档

1 服务介绍 ​

  • 文件保存时间：

    • 上传的文件默认保存 30 天；

接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

  • 文件要求：

    • 格式：只支持 jsonl 文件名后缀

    • custom_id：全文件不能存在重复

    • method：只支持 POST

    • url：只支持 /v1/chat/completions

    • model：支持预置、精调、托管的文本生成类模型，取值为modelId

注意

每个请求一行，单个文件不超过5万行；body 中 model 全文件保持相同

文件单行示例：

json
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "xop1ef199ca", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "1+1=?"}],"max_tokens":2048,"top_k":4,"temperature":0.5,"patch_id":["0"]}}

2 接口 Demo ​

部分开发语言Demo如下，其他开发语言请参照文档进行开发。
批处理API-Demo-Java
批处理API-Demo-Python

3 接口列表 ​

3.1 接口鉴权 ​

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

http
Authorization: Bearer 123456

4 上传文件 ​

4.1 接口描述 ​

  • 上传jsonl文件，文件格式需要符合要求，参考服务介绍。

  • 上传的文件默认保存 30 天。

4.2 接口地址 ​

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

4.3 请求参数 ​

（1）请求头

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

（2）请求体

字段名类型是否必传描述
purposestring是传 batch，表示上传文件的意图
filefile是文件（最大不超过 100 MB，默认保存30天）

4.4 响应参数 ​

（1）响应参数说明

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

（2）响应参数示例

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

5 查询文件列表 ​

5.1 接口描述 ​

  • 获取 appid 下的文件列表。

  • 上传的文件默认保存 30 天；

接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

5.2 接口地址 ​

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

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

5.3 请求参数 ​

（1）请求头

http
Authorization: Bearer $APIPassword

5.4 响应参数 ​

5.4.1 响应参数示例 ​

json
{
  "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"
}

6 查询单个文件 ​

6.1 接口描述 ​

  • 根据文件的file_id获取该文件信息。

  • 上传的文件默认保存 30 天；

接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

6.2 接口地址 ​

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

注意

请求参数file_id放在路径中！

6.3 请求参数 ​

http
Authorization: Bearer $APIPassword

6.4 响应参数示例 ​

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

7 删除文件 ​

7.1 接口描述 ​

根据文件的file_id删除该文件

7.2 接口地址 ​

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

注意

请求参数file_id放在路径中！

7.3 请求参数 ​

请求头

http
Authorization: Bearer $APIPassword

7.4 响应参数 ​

响应参数示例

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

8 下载文件 ​

8.1 接口描述 ​

  • 根据文件的file_id获取文件的详细内容；

  • 上传的文件默认保存 30 天；

接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。

8.2 接口地址 ​

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

注意

请求参数file_id放在路径中！

8.3 请求参数 ​

请求头

http
Authorization: Bearer $APIPassword

8.4 响应参数 ​

响应参数示例

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

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

9 创建Batch任务 ​

9.1 接口描述 ​

  • 调用该接口前需要先上传jsonl文件，通过上传文件得到的file_id来创建Batch任务。

  • 单个Batch任务最多包含5万个请求（一个请求对应jsonl文件的一行），每个请求的body不超过6KB

9.2 接口地址 ​

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

9.3 请求参数 ​

（1）请求头

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

（2）请求体

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

9.4 响应参数 ​

（1）响应参数说明

id
string可选
批任务唯一标识（全局唯一）。格式为：batch_xxxxx
object
string可选
结构类型，当前仅为 batch
endpoint
string可选
处理批任务的服务的 path 路径，当前仅为 /v1/chat/completions
errors
object可选
错误列表
object
string可选
描述 data 类型 (list)
data
array可选
错误项列表，每项包含：code string、message string、param string or null、line int or null
input_file_id
string可选
文件id（用户入参）
status
string可选
任务状态（枚举值）
枚举值：queuing（排队）/ in_progress（在处理）/ finalizing（上传中）/ completed（处理成功）/ failed（处理失败）/ expired（超时）/ canceled（已取消）
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可选
批任务信息
total
int可选
批任务当前完成总数
completed
int可选
任务当前成功数
failed
int可选
任务当前失败数
metadata
object可选
批任务附加信息（用户入参）

（2）status字段说明

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

（3）响应参数示例

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

10 查询Batch任务 ​

10.1 接口描述 ​

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

10.2 接口地址 ​

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

注意

请求参数batch_id放在路径中！

10.3 请求参数 ​

（1）请求头

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

10.4 响应参数 ​

（2）响应参数示例

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

11 取消Batch任务 ​

11.1 接口描述 ​

根据batch_id取消该Batch任务

11.2 接口地址 ​

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

注意

请求参数batch_id放在路径中！

11.3 请求参数 ​

（1）请求头

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

11.4 响应参数 ​

（1）响应参数示例

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

12 查询Batch列表 ​

12.1 接口描述 ​

获取 appid 下的Batch列表

12.2 接口地址 ​

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

注意

请求参数batch_id放在路径中！

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

12.3 请求参数 ​

（1）请求头

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

12.4 响应参数 ​

（1）响应参数示例

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
}