图像理解_HTTP协议

# 图像理解_HTTP协议

## 1. 接口说明

协议 ：HTTP
请求方法：POST
默认请求地址如下：

```http
http://maas-api.cn-huabei-1.xf-yun.com/v1
```

部分模型因为部署原因可能略有差异，具体可参考**服务管控** > **模型服务列表**右侧调用信息。技术咨询可直接提交[工单](https://console.xfyun.cn/workorder/commit)

## 2. 接口请求

### 2.1 请求示例

如果想使用 HTTP 请求的 流式输出，请参考如下实例：

```python
from openai import OpenAI

api_key = "<从服务管控页面获取 对应服务的APIKey>"  # 请替换为您的 API Key  
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"

client = OpenAI(api_key=api_key,base_url=api_base)

try:
    response = client.chat.completions.create(
        model="<从服务管控页面获取 对应服务的ModelID>",  # 请根据实际情况替换为您的 Model ID
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "这题的答案是什么"
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."
                        }
                    }
                ]
            }
        ],
        stream=True,
        temperature=0.7,
        max_tokens=8192
    )

full_response = ""
    for chunk in response:
        if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)  # 实时打印每个片段
            full_response += content
    
    print("\n\n ------完整响应：", full_response)    
except Exception as e:
    print(f"Error: {e}")
```

**注意**：在使用demo之前，请务必替换 `api_key` 为您的API Key。

###  2.2 请求参数

| 参数           | 类型    | 是否必填 | 要求                                                 | 说明                                                         |
| -------------- | ------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| model          | string  | 是       |                                                      | 指定要调用的模型ID。请参考 **服务管控** > **模型服务列表** 获取。 |
| messages       | array   | 是       | `[{"role": "user", "content": [...]}]`       | 表示对话上下文的消息列表。其中，`role` 用于标识消息发送方, `content` 则为包含文本和图像信息的数组。 |
| stream         | boolean | 否       | 取值为 `true` 或 `false`，默认值为 `false`           | 指定是否采用流式响应模式。若设置为 `true`，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应 |
| temperature    | float   | 否       | 取值为`[0,1]`,默认值为`0.7`                          | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens     | int     | 否       | 取值为`[1,8192]`，默认值为`2048`                     | 限制生成回复的最大 token 数量 |

####  2.2.1 `messages` 参数说明

messages 参数用于传递对话内容，包括用户输入和 AI 回复

| 字段    | 含义     | 数据类型 | 取值范围              | 默认值 | 说明                                                         |
| ------- | -------- | -------- | --------------------- | ------ | ------------------------------------------------------------ |
| role    | 角色     | string   | user |        | **user表示用户的问题** |
| content | 内容 | array   | --                    |        | 包含文本和图像信息的数组 |

**`content` 数组内对象说明:**

| 类型    | 字段    | 数据类型 | 说明                                                         |
| ------- | -------- | -------- | ------------------------------------------------------------ |
| text    | text | string   | 用户的文本输入 |
| image_url | image_url | object | 图像数据, 包含一个 `url` 字段 |

**`image_url` 对象说明:**

| 字段    | 数据类型 | 说明                                                         |
| ------- | -------- | ------------------------------------------------------------ |
| url | string   | 图像的URL或者Base64编码的图像数据 |

**示例：**
```json
[
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "这题的答案是什么"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."
                }
            }
        ]
    }
]
```

## 3. 接口响应

### 3.1 响应示例

#### 3.1.1 成功响应示例

流式响应会返回一系列的事件（data-only server-sent events），每个事件都是一个JSON对象，称为数据块（chunk）。下面是几个响应数据块的示例：

**数据块 1 (包含内容):**
```json
{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "这张图"
      },
      "finish_reason": null
    }
  ]
}
```

**数据块 2 (继续包含内容):**
```json
{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "标显示的是..."
      },
      "finish_reason": null
    }
  ]
}
```

**结束数据块 (finish_reason 为 stop):**
```json
{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop"
    }
  ],
  "usage": {
      "prompt_tokens": 44,
      "completion_tokens": 42,
      "total_tokens": 86
  }
}
```

#### 3.1.2 异常结果示例

```json
Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型：xqwen2d5s32bvl (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}
```

### 3.2 响应数据参数

在流式响应中，每个数据块（chunk）都包含以下字段：

| 字段名 | 类型 | 字段说明 |
| --- | --- | --- |
| id | string | 唯一标识符，标识本次对话调用的唯一ID。 |
| object | string | 对象类型，对于流式响应，其值为 `chat.completion.chunk`。 |
| created | int | 响应生成时间的Unix时间戳（秒级）。 |
| model | string | 实际调用的模型名称。 |
| choices | array | 包含模型生成回复候选项的数组。 |
| &nbsp;&nbsp;•index | int | 回复候选项在数组中的索引位置，从0开始。 |
| &nbsp;&nbsp;•delta | object | 包含增量消息内容的对象。 |
| &nbsp;&nbsp;&nbsp;&nbsp;◦role | string | 在第一个数据块中出现，值为 `assistant`。 |
| &nbsp;&nbsp;&nbsp;&nbsp;◦content | string | 模型生成的增量回复文本内容。 |
| &nbsp;&nbsp;•finish_reason | string | 在最后一个数据块中出现，指示回复生成结束的原因，如 `"stop"`。 |
| usage | object | 在最后一个数据块中出现（需在请求中加入`stream_options={"include_usage": True}`），包含token使用统计信息。 |
| &nbsp;&nbsp;•completion_tokens | int | 回复文本消耗的token数量。 |
| &nbsp;&nbsp;•prompt_tokens | int | 输入prompt消耗的token数量。 |
| &nbsp;&nbsp;•total_tokens | int | prompt与回复消耗token数量的总和。 |

##  4 . 错误码列表

### 4.1 HTTP状态码

| 错误码                                 | 原因                                      | 解决方案                                                |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| 401-无效的身份验证                     | 身份验证无效。                            | 确保使用正确的API密钥及请求组织。                       |
| 401-提供的API密钥不正确                | 请求的API密钥不正确。                     | 检查所用API密钥是否正确，清除浏览器缓存或生成新的密钥。 |
| 403-不支持的国家、地区或领土           | 您正在从不支持的国家、地区或领土访问API。 | 请参考相关页面获取更多信息。                            |
| 429-请求速率限制已达上限               | 您发送请求过快。                          | 控制请求频率，阅读速率限制指南。                        |
| 429-超出当前配额，请检查计划和计费详情 | 您的额度已用尽或已达到每月最高消费限制。  | 购买更多额度或了解如何提高使用限制。                    |
| 500-服务器处理请求时发生错误           | 服务器内部出现问题。                      | 稍后重试请求；若问题持续，请联系我们查看状态页面。      |
| 503-引擎当前过载，请稍后重试           | 服务器流量过大。                          | 稍候重试您的请求。                                      |

### 4.2 业务逻辑错误码

除了标准的HTTP状态码，服务器在处理请求时也可能返回更详细的业务逻辑错误码。这些错误码通常包含在 `500 Internal Server Error` 等响应的 `error` 对象中。

| 错误码 | 错误信息                                                     |
| ------ | ------------------------------------------------------------ |
| 10000  | 升级为ws出现错误                                             |
| 10001  | 通过ws读取用户的消息 出错                                    |
| 10002  | 通过ws向用户发送消息 出错                                    |
| 10003  | 用户的消息格式有错误                                         |
| 10004  | 用户数据的schema错误                                         |
| 10005  | 用户参数值有错误                                             |
| 10006  | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。     |
| 10007  | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008  | 服务容量不足，联系服务商                                     |
| 10009  | 和引擎建立连接失败                                           |
| 10010  | 接收引擎数据的错误                                           |
| 10011  | 向引擎发送数据的错误                                         |
| 10012  | 引擎内部错误                                                 |
| 10013  | 用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。         |
| 10014  | 回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复） |
| 10015  | appid在黑名单中                                              |
| 10016  | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权等等。（联系我们开通授权或提高限制） |
| 10018  | 用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注 |
| 10019  | 该错误码表示返回结果疑似敏感，建议拒绝用户继续交互           |
| 10110  | 服务忙，请稍后再试。                                         |
| 10163  | 请求引擎的参数异常，引擎的schema检查不通过                   |
| 10222  | 引擎网络异常                                                 |
| 10223  | LB找不到引擎节点                                             |
| 10907  | token数量超过上限。对话历史+问题的字数太多，需要精简输入。   |
| 11200  | 授权错误：该appId没有相关功能的授权或者业务量超过限制（联系我们开通授权或提高限制） |
| 11201  | 授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制） |
| 11202  | 授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制） |
| 11203  | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |

### 5.3 内容审核说明

当返回10013或者10014错误码时，代码内容审核判断当前问题或回复的信息涉及敏感信息。返回错误的同时，在header.message字段中会携带当前的敏感提示语。

-   10013 表示用户的问题涉及敏感信息，服务侧拒绝处理此次请求。
-   10014 表示回复结果中涉及敏感信息，后续结果不可以展示给用户。
-   10019 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回**全部结果**后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们技术支持。

[#](about:blank#%E6%89%B9%E5%A4%84%E7%90%86api%E6%96%87%E6%A1%A3) [#](about:blank#%E6%98%9F%E7%81%AB%E5%A4%A7%E6%A8%A1%E5%9E%8B%E6%89%B9%E5%A4%84%E7%90%86api%E6%96%87%E6%A1%A3) 批处理API文档
=========================================================================================================================================================================================

[#](about:blank#%E4%B8%80%E3%80%81%E6%9C%8D%E5%8A%A1%E4%BB%8B%E7%BB%8D) [#](about:blank#%E4%B8%80%E3%80%81%E6%9C%8D%E5%8A%A1%E4%BB%8B%E7%BB%8D) 一、服务介绍
------------------------------------------------------------------------------------------------------------------------------------------------------

**文件保存时间：** 上传的文件默认保存 30 天；接口返回的文件按照文件生成的时间开始计时，默认保存 30 天。  
**文件要求：**  
格式：只支持 jsonl 文件名后缀  
custom\_id：全文件不能存在重复  
method：只支持 POST  
url：只支持 /v1/chat/completions  
model：支持预置、精调、托管的文本生成类模型，取值为modelId

**注意：每个请求一行，单个文件不超过5万行；body 中 model 全文件保持相同；调用精调大模型时patch_id必传**  
**文件单行示例：**

```
{"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"]}}

```

[#](about:blank#%E4%BA%8C%E3%80%81%E6%8E%A5%E5%8F%A3-demo) [#](about:blank#%E4%BA%8C%E3%80%81%E6%8E%A5%E5%8F%A3-demo) 二、接口 Demo
-------------------------------------------------------------------------------------------------------------------------------

部分开发语言Demo如下，其他开发语言请参照文档进行开发。在使用demo之前，请修改代码中的APIPassword以及patch_id（调用精调大模型时必传）  
[批处理API-Demo-Java (opens new window) (opens new window)](https://openres.xfyun.cn/xfyundoc/2024-10-15/56b6b6b2-547a-4ab6-afb2-c4712df48815/1728991787664/BatchAPI-Java.zip)  
[批处理API-Demo-Python (opens new window) (opens new window)](https://openres.xfyun.cn/xfyundoc/2025-06-16/48915c51-2582-457f-bdeb-8b15e91fd90c/1750067679158/batch_demo.zip)

[#](about:blank#%E4%B8%89%E3%80%81%E6%8E%A5%E5%8F%A3%E5%88%97%E8%A1%A8) [#](about:blank#%E4%B8%89%E3%80%81%E6%8E%A5%E5%8F%A3%E5%88%97%E8%A1%A8) 三、接口列表
------------------------------------------------------------------------------------------------------------------------------------------------------

### [#](about:blank#%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83) [#](about:blank#%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83) 接口鉴权

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

```
Authorization: Bearer 123456

```

### [#](about:blank#_3-1%E3%80%81%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6) [#](about:blank#_3-1%E3%80%81%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6) 3.1、上传文件

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0) 接口描述

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

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80) 接口地址

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

```

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4) 请求头

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

```

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E4%BD%93) [#](about:blank#%E8%AF%B7%E6%B1%82%E4%BD%93) 请求体

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

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E) 响应参数说明

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

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B) 响应参数示例

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

```

### [#](about:blank#_3-2%E3%80%81%E6%9F%A5%E8%AF%A2%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8) [#](about:blank#_3-2%E3%80%81%E6%9F%A5%E8%AF%A2%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8) 3.2、查询文件列表

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-2) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-2) 接口描述

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

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-2) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-2) 接口地址

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

```

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

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-2) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-2) 请求头

```
Authorization: Bearer $APIPassword

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-2) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-2) 响应参数示例

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

```

### [#](about:blank#_3-3%E3%80%81%E6%9F%A5%E8%AF%A2%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6) [#](about:blank#_3-3%E3%80%81%E6%9F%A5%E8%AF%A2%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6) 3.3、查询单个文件

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-3) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-3) 接口描述

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

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-3) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-3) 接口地址

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

```

**注意：请求参数file\_id放在路径中！**

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-3) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-3) 请求头

```
Authorization: Bearer $APIPassword

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-3) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-3) 响应参数示例

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

```

### [#](about:blank#_3-4%E3%80%81%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6) [#](about:blank#_3-4%E3%80%81%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6) 3.4、删除文件

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-4) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-4) 接口描述

根据文件的file\_id删除该文件

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-4) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-4) 接口地址

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

```

**注意：请求参数file\_id放在路径中！**

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-4) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-4) 请求头

```
Authorization: Bearer $APIPassword

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-4) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-4) 响应参数示例

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

```

### [#](about:blank#_3-5%E3%80%81%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6) [#](about:blank#_3-5%E3%80%81%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6) 3.5、下载文件

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-5) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-5) 接口描述

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

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-5) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-5) 接口地址

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

```

**注意：请求参数file\_id放在路径中！**

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-5) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-5) 请求头

```
Authorization: Bearer $APIPassword

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-5) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-5) 响应参数示例

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

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

```

### [#](about:blank#_3-6%E3%80%81%E5%88%9B%E5%BB%BAbatch%E4%BB%BB%E5%8A%A1) [#](about:blank#_3-6%E3%80%81%E5%88%9B%E5%BB%BAbatch%E4%BB%BB%E5%8A%A1) 3.6、创建Batch任务

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-6) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-6) 接口描述

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

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-6) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-6) 接口地址

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

```

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-6) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-6) 请求头

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

```

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E4%BD%93-2) [#](about:blank#%E8%AF%B7%E6%B1%82%E4%BD%93-2) 请求体

| 字段名 | 类型 | 是否必传 | 描述 |
| --- | --- | --- | --- |
| 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" |

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E-2) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E-2) 响应参数说明

| 字段名 | 类型 | 描述 |
| --- | --- | --- |
| 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 | 批任务附加信息（用户入参） |

#### [#](about:blank#status%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E) [#](about:blank#status%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E) status字段说明

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

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-6) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-6) 响应参数示例

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

```

### [#](about:blank#_3-7%E3%80%81%E6%9F%A5%E8%AF%A2batch%E4%BB%BB%E5%8A%A1) [#](about:blank#_3-7%E3%80%81%E6%9F%A5%E8%AF%A2batch%E4%BB%BB%E5%8A%A1) 3.7、查询Batch任务

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-7) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-7) 接口描述

根据batch\_id获取该Batch任务的详细信息

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-7) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-7) 接口地址

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

```

**注意：请求参数batch\_id放在路径中！**

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-7) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-7) 请求头

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

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-7) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-7) 响应参数示例

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

```

### [#](about:blank#_3-8%E3%80%81%E5%8F%96%E6%B6%88batch%E4%BB%BB%E5%8A%A1) [#](about:blank#_3-8%E3%80%81%E5%8F%96%E6%B6%88batch%E4%BB%BB%E5%8A%A1) 3.8、取消Batch任务

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-8) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-8) 接口描述

根据batch\_id取消该Batch任务

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-8) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-8) 接口地址

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

```

**注意：请求参数batch\_id放在路径中！**

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-8) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-8) 请求头

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

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-8) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-8) 响应参数示例

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

```

### [#](about:blank#_3-9%E3%80%81%E6%9F%A5%E8%AF%A2batch%E5%88%97%E8%A1%A8) [#](about:blank#_3-9%E3%80%81%E6%9F%A5%E8%AF%A2batch%E5%88%97%E8%A1%A8) 3.9、查询Batch列表

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-9) [#](about:blank#%E6%8E%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0-9) 接口描述

获取 appid 下的Batch列表

#### [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-9) [#](about:blank#%E6%8E%A5%E5%8F%A3%E5%9C%B0%E5%9D%80-9) 接口地址

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

```

**注意：请求参数batch\_id放在路径中！**

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

#### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-9) [#](about:blank#%E8%AF%B7%E6%B1%82%E5%A4%B4-9) 请求头

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

```

#### [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-9) [#](about:blank#%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0%E7%A4%BA%E4%BE%8B-9) 响应参数示例

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

```