BatchImport - 批量导入数据--全域AI搜索-火山引擎

文档中心

导航

BatchImport - 批量导入数据

最近更新时间：2025.12.17 00:05:00首次发布时间：2025.12.17 00:05:00

在调用创建批式导入任务后（见：CreateBatchImport - 创建批量导入任务），使用返回的batch_id逐次导入批量数据。
使用同一个batch_id多次调用本接口，上传的所有数据将攒批进入同一个导入批次，上传完成后您可以调用完成上传接口完成该批次的导入操作，系统将自动开始后续的数据入库和处理流程。
当前批式导入数据仅支持物品数据集，支持以下数据操作：

批量导入新数据：适用于创建数据集后，批量导入全量候选数据。物品数据使用JSON Object列表形式上传。上传的数据 schema 必须遵循您在控制台创建数据集时定义的 schema。
批量更新数据：通过重复上传物品数据（传入的数据唯一标识已存在于数据集中）则触发数据更新，最新上传的数据将覆盖已有的数据。如果您只需要更新一批数据中的某几个字段，则每条数据仅需要上传物品数据的id和待更新字段。

注意事项

任务有效期: 每个批量导入任务的有效生命周期为24小时，您需要在创建任务的24小时内完成数据导入并通过调用导入任务完成接口提交这批数据。过期后任务将自动失效。
接口请求体上限：您可以连续调用批量导入接口上传同一批内的数据，首接口的请求体大小限制，您每次接口调用的请求体不能超过10MB。
批量导入接口限流：批量导入接口限制请求频度 50QPS 。若您有更高的请求频率需求，请与我们去的联系。

请求说明

请求方式: POST
请求 URL: https://aisearch.cn-beijing.volces.com/api/v1/dataset/{dataset_id}/batch_import

请求参数

图文数据集请求体

参数

类型

是否必选

示例值

描述

batch_id

String

是

"a8fd2b826203421bb977"

创建批式导入任务时返回的batch_id

fields

Array of Object

是

图文数据：

［
    {
        "item_id": "WSHOE001",
         "title": "舒适通勤 尖头浅口高跟鞋 - 黑色",
         "category": "女士高跟鞋",
         "status": 1,
         "images": [
         {
             "image_url": "https://example.com/images/womens_pump_black.jpg"
          }
         ]
     }
］

需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

上传图片文件

上传数据时，请根据您已经在数据集中定义的字段类型来上传图片文件数据。您必须上传符合以下说明中格式和限制的图片文件，AI 搜索引擎才可以对图片进行处理并索引：

说明

支持格式：jpeg、png、 webp、bmp、tiff、ico、dib、icns、sgi、jpeg2000。其中，tiff、sgi、icns、jpeg2000 格式图片，需要保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败。
宽高比（宽/高）：在范围[1/100, 100] 。
边长： [10, 6000] px，即短边像素需大于 10 px，长边像素需小于6000 px。

您可以按照您在数据集配置中的属性定义，上传可公开访问的URL链接或使用Base64编码直接上传图片文件：

使用URL链接上传：请确保您的URL链接保持公开可访问，如果您的链接有访问限制，请对 aisearch.cn-beijing.volces.com 域名开放访问的白名单。
使用Base64编码的图片文件上传：请确保Base64编码符合标准格式，包含数据头（Data URI Scheme）与 Base64 编码正文两部分：

格式

JPEG 图片

PNG 图片

WebP 图片

data:<MIME类型>;base64,<Base64编码字符串>

视频数据集请求体

参数	类型	是否必选	示例值	描述
batch_id	String	是	`"a8fd2b826203421bb977"`	创建批式导入任务时返回的batch_id
fields	Array of Object	是	`[ { "content_id": "video_900026", "content_type": "video", "parent_content_id": "collection_342534", "sequence_index": 26, "video_url": [ "http://xxxx.mp4" ], "my_title": "三体第二十六集" } ]`	需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

上传视频文件

上传数据时，请根据您已经在数据集中定义的字段类型来上传视频数据。在视频数据集中需要使用video_url（Array）上传单个视频的url列表（支持多个视频片段拼接为1个视频）。视频的上传格式和要求如下：

说明

在导入视频下载链接前，请确保这些视频的下载 URL 能够被火山引擎的官方接口域名访问。不支持通过上传任意网页链接来爬取网页上的视频。
在上传前，请确保列表内所有视频文件的总大小不超过 10GB，总时长不超过 3 小时。
支持上传以下格式的视频文件：
mp4、flv、asf、rm、rmvb、mpeg、mov、avi、mpegts、m4s、m3u8、matroska、wmv、3gp、ts、mpg、webm、mkv、wm、asx、ram、mpe、vob、dat、mp4v、m4v、f4v、mxf、qt

响应参数

请求响应

参数	类型	示例	描述
`batch_id`	String	`6c0001b0-f696-4bfc-acda-a2ee05170485`	批式导入任务的唯一标识符。
`accepted_count`	Integer	`1000`	本次请求成功接收的数据条数。
`total_received`	Integer	`5000`	任务累计已接收的数据总条数。
`status`	String	`processing`	任务的当前状态。
`expired_time`	String	`2025-11-19T14:23:45Z`	任务的过期时间。

请求示例

图文数据集

视频数据集

图文数据集批量上传示例：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/batch_import'   -H 'Content-Type: application/json'   -H 'Authorization: Bearer <API Key>'   -d '{
    "batch_id":"a8fd2b826203421bb977",
    "fields": [
                {
                    "item_id": "WSHOE001",
                    "title": "舒适通勤 尖头浅口高跟鞋 - 黑色",
                    "category": "女士高跟鞋",
                    "status": 1,
                    "images": [
                        {
                            "image_url": "https://example.com/images/womens_pump_black.jpg"
                        }
                    ]
                },
                {
                    "item_id": "WSHOE002",
                    "title": "轻便网面 跑步运动鞋 - 粉色拼灰色",
                    "category": "女士运动鞋",
                    "status": 1,
                    "images": [
                        {
                            "image_url": "https://example.com/images/womens_sneaker_pink.jpg"
                        }
                    ]
                }
            ]
}'

视频数据集批量上传示例：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/batch_import'   -H 'Content-Type: application/json'   -H 'Authorization: <火山鉴权的一系列相关header>'   -d '{
    "fields": [
                {
                    "content_id": "video_900026",
                    "content_type": "video",
                    "parent_content_id": "collection_342534",
                    "sequence_index": 26,
                    "video_url": [
                        "http://xxxx.mp4"
                    ],
                    "my_title": "三体第二十六集"
                },
                {
                    "content_id": "video_900027",
                    "content_type": "video",
                    "parent_content_id": "collection_342534",
                    "sequence_index": 27,
                    "video_url": [
                        "http://xxxx.mp4"
                    ],
                    "my_title": "三体第二十七集"
                }
    ]
}'

返回示例

{
    "request_id": "41feb961-6b21-94e0-ba4e-c063aaff0784",
    "result": {
        "batch_id": "a8fd2b826203421bb977",
        "accepted_count": 2,
        "total_received": 2,
        "status": "processing",
        "expired_time": "2025-12-17T21:15:59+08:00"
    }
}

错误码

请查看公共错误码