:::tip \*说明 **Viking AI Search** is an enterprise\-level AI search product based on generative AI. It leverages the multi\-modal semantic representation and understanding of large models, combined with ByteDance's best practices in information retrieval, to provide an out\-of\-the\-box AI search platform. This platform helps customers easily build and integrate end\-to\-end multi\-modal search and recommendation capabilities for images and text. * To experience more Viking AI Search capabilities, visit: [Viking AI Search Engine, an integrated intelligent engine for enterprise search, recommendation, and Q&A](https://www.volcengine.com/product/AI-Search-Rec) ::: --- Gets the list of imported items for a specified dataset. Pagination is supported. :::tip \*Description Only list queries for item datasets are supported. Queries for behavior datasets are not currently supported. ::: ## Notes * **Usage Limits:** * The body of a single request cannot exceed 10 MB. ## Request Description * Request Method: POST * API Name: ListItems * Request URL: * North China: https://aisearch.cn\-beijing.volces.com/api/v1/dataset/`{dataset_id}`/list_items * Johor: https://aisearch.ap\-southeast\-1.volces.com/api/v1/dataset/`{dataset_id}`/list_items --- *{dataset_id}: The unique ID for a dataset, assigned by the system after you create it in the console. You can view and copy it from the dataset details page.* ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/b9a634b3f3eb4fdb926fe562f4c92fa6 =2544x) ## Request Parameters ### Request Body |**Parameter Name** |**Type** |**Required** |**Example Value** |**Description** | |---|---|---|---|---| |`filter` |Filter structure |No | |Filtering conditions for querying batch records | |`max_results`|Int|No|10 |The number of results to get per page. The default value is used if not specified. Values: \- Minimum: 1 \- Maximum: 100 \- Default: 10 |\ | | | | | | |`output_fields`|Array |No |["title", "price", "category"]|Specifies the fields of item data to return for the queried dataset. When return fields are specified, the `raw_data` field in the API response includes only those fields.|\ | | | | |> If the dataset contains nested objects, only top\-level field names are supported.|\ | | | | |> Non\-existent fields or fields within a nested object will be ignored. | |`next_token` |String |No |MHwxMDY4MzAzMDNfOTM4Njk4NDM4NTAyMzEwNDkx |String used to retrieve the next page of content. | `Filter` |**Parameter Name** |**Type** |**Required** |**Example Value** |**Description** | |---|---|---|---|---| |`_id` |String |No |"test_id" |The primary key of the data entry. Filter criteria. No filter is applied by default.|\ | | | | ||\ | | | | |* Image\-text dataset: the field that corresponds to the item ID attribute you specified.|\ | | | | |* Video dataset: the ID corresponding to the `content_id` field. | |`process_status`|Array<**String**\>|No|["success", "processing", "failed"] |Processing status of data entries: "success" means the data is valid, "processing" means it is being processed, and "failed" means there is an error. Returns all statuses by default. |\ | | | | | | ### Response Body |**Parameter name** |**Parameter type** |**Example** |**Description** | |---|---|---|---| |`next_token` |String |MHwxMDY4MzAzMDNfOTM4Njk4NDM4NTAyMzEwNDkx |A string used to retrieve the next page of content. An empty value indicates the last data entry. | |`items` |Array structure | |A list of retrieved data items, where each item contains the data fields corresponding to the item ID and the processing details. | `DataItem` |**Parameter Name** |**Parameter Type** |**Example** |**Description** | |---|---|---|---| |`_id` |String |"test_itemid" |The primary key of the data record, which is unique within the dataset. | |`raw_data` |String | |The content of all fields in the imported raw data. | |`meta` |DataItemMeta structure | |For video datasets, this returns the data's processing and status information. | |`process_status` |String |"success" |Data processing status: success, processing, or failed | |`check_status` |String |"normal" |Data check status: normal, warning, or error | |`data_status_details` |Array | |A list of data quality check and processing statuses, including status descriptions for the initial import and latest update. | |`create_time` |String |"2025\-03\-12T15:01:07+08:00" |Creation time, in RFC3339 format | |`update_time` |String |"2025\-03\-12T15:01:07+08:00" |Update time, in RFC3339 format | **DataItem response for video datasets:** `DataItemMeta` |**Parameter name** |**Parameter type** |**Example** |**Description** | |---|---|---|---| |`video_meta` |VideoMeta | |Video data processing and status information | `VideoMeta` |**Parameter name** |**Parameter type** |**Example** |**Description** | |---|---|---|---| |`content_type` |String |video |Content type: video, collection | |`video_urls` |Array |["https://domain.com/file_path.format"] |Video URL list | |`parent_content_id` |String | |Parent content ID | |`sequence_index` |Int | |Sequence index | |`video_content` |VideoContent | |Video processing and understanding content | |`collection_content` |CollectionContent | |Video collection processing and understanding content | |`duration` |Int | |Video duration in seconds, rounded up to the nearest whole number. | `VideoContent` |**Parameter Name** |**Parameter Type** |**Example** |**Description** | |---|---|---|---| |`Title` |String |"Video title" |The generated video title. | |`Summary` |String |"Content summary" |Generated video summary | |`Insight` |String | |All content returned by the video storyline analysis, with the JSON marshaled into a string. | `CollectionContent` |**Parameter name** |**Parameter type** |**Example** |**Description** | |---|---|---|---| |`summary` |String | |A video summary generated by summarizing the entire collection after processing each video in the series. | `DataStatusDetail` |**Parameter name** |**Parameter type** |**Example** |**Description** | |---|---|---|---| |`update_type` |String |FIRST_UPDATE_SUCCESS |Update type:|\ | | | ||\ | | | |* FIRST_UPDATE_SUCCESS: first import and processing succeeded|\ | | | |* LATEST_UPDATE_SUCCESS: latest update and processing succeeded|\ | | | |* UPDATE_FAILED: an error occurred during the latest data update | |`timestamp` |String |2025\-03\-12T15:01:07+08:00 |Update time in RFC3339 format | |`warning_info` |Map[String]String | |Data quality exception details in the format "Status Code": "Exception Details"|\ | | | |Data quality exceptions do not affect data processing or indexing, but fixing them is recommended to improve search performance. | |`error_info` |Map[String]String | |Data validation and processing exception details in the format "Status Code": "Exception Details"|\ | | | |Validation and processing exceptions indicate that data was blocked during the validation stage and could not be processed or indexed. Review the exception details and re\-upload the corrected data. | ### Data Status Description After data is imported, it undergoes quality checks and processing. Data statuses are generated during this process and affect data indexing and usage. The following sections describe the process and status definitions. #### Data Processing Status The data processing status is returned in `DataItem` and includes 2 statuses: * `process_status`: The processing status of the data, which includes the following: * "success": Indicates that the data has been processed and stored successfully, corresponding to "Data normal" displayed on the console. * "failed": Indicates a blocking exception that caused the data import to fail. The console displays "Data exception". * "processing": Indicates that the data is being processed. This status usually applies to video files, which have longer processing times, and is less common for image and text data that are processed quickly. The console displays "Data processing". * `check_status`: The quality validation status of the data, which includes: * "normal": The data has passed all validation checks, and there are no format, type, or file exceptions in any fields. * "warning": Indicates a data quality issue, such as a type exception in a non\-preset field or an invalid image link. This issue does not affect the data import process, but we recommend you fix and resubmit the data upon receiving this status. * "error": Indicates a serious data quality issue, such as a type exception in a preset field or an invalid video file link. This issue affects the data import process, and we recommend that you fix and resubmit the data upon receiving this status. #### Status Details The `DataStatusDetail` structure returns the status code and detailed status information for the initial import and the most recent update: |**Status Code** |**Description** | |---|---| |`Finished` |Data processing complete | |`Running` |Processing data | |`InternalError` |Failed to handle internal error | |`InvalidJsonLineError` |Invalid JSON data format | |`DataPrimaryKeyNotFoundError` |A primary key field with a value is required. | |`InvalidImageUrlError` |The image link is inaccessible | |`ImageDownloadTimeout` |Image download timed out | |`ImageUnsupportedFileFormat` |Unsupported image file format | |`ImageSizeTooSmall` |The image is too small to be processed | |`ExtremeImageProportion` |The image aspect ratio exceeds 100:1 and cannot be processed | |`ImageFileTooLarge` |The image file is too large. | |`ImageBase64UriInvalid` |Invalid image Base64 encoding format. | |`DataContentTypeNotFoundError` |The content_type field is required for video data and must have a value. | |`UnsupportedContentTypeError` |Unsupported content_type value. Only "video" and "collection" are supported. | |`DuplicateMediaSequenceIndexError` |Duplicate media sequence index. | |`MediaCannotBeSetAsParentError` |Media content cannot be set as a parent | |`ParentContentMustBeCollectionError` |Parent content must be a collection | |`ParentContentNotUploadedError` |The parent content has not been uploaded | |`InvalidVideoUrlError` |The video URL cannot be accessed | |`InvalidImageUrlError` |The image URL cannot be accessed | |`VideoUrlNotUploadedError` |(Video data) Video URL not uploaded | |`InvalidMediaSequenceIndexError` |(Video data) Invalid media sequence number. Duplicate sequence numbers exist. | |`InvalidMediaCoverUrlError` |(Video data) The media cover URL is inaccessible. | |`RequiredFieldTypeMismatchError` |(Video data) Incorrect preset field type. | |`NonRequiredFieldTypeMismatchError` |Incorrect custom field type. | |`ContentTypeNotModifiableError` |(Video data) The content_type cannot be modified. | |`VideoProcessError` |(Video data) Video processing error. | |`VideoDurationExceedsLimitError` |(Video data) The video duration exceeds the 3.5\-hour limit. | |`VideoSizeExceedsLimitError` |(Video data) The video size exceeds the 10 GB limit. | ### Error Code |**Error code** |**HTTP status code** |**Error message** |**Description** | |---|---|---|---| |DatasetNotFound |404 |The dataset not found %s |The dataset does not exist. | |InvalidParameter |400 |A parameter in the request is not valid: %s |The parameter format is invalid. | |ErrCodeInvalidRequestBody|400 |The request cannot be parsed in JSON format: %s |Request deserialization failed. |\ | | | | | |ErrCodeInternalServiceError|500 |Service has some internal Error. Pls Contact With Admin. |A reliability\-related unknown error occurred during request processing, such as a backend service timeout or network fluctuations. |\ | | | | | ## Request Example ## Request Sample Code ```mixin-react return ( ' \\ -d '{ "max_results": 2 }' \`\`\` `}> params) throws Exception { try { // 1. Build the request body String requestBody = params != null ? client.getGson().toJson(params) : ""; // 2. Prepare the signed request SignableRequest signableRequest = prepareRequest( client.getHost(), path, method, new ArrayList<>(), requestBody, client.accessKey, client.secretKey ); // 3. Build the final HTTP request URI uri = signableRequest.getUriBuilder().build(); HttpPost httpPost = new HttpPost(uri); // 4. Set the request headers httpPost.setHeader("Content-Type", "application/json"); httpPost.setHeader("Accept", "application/json"); httpPost.setHeader("Host", client.getHost()); // 5. Copy the authentication request headers if (signableRequest.getFirstHeader("Authorization") != null) { httpPost.setHeader("Authorization", signableRequest.getFirstHeader("Authorization").getValue()); } if (signableRequest.getFirstHeader("X-Date") != null) { httpPost.setHeader("X-Date", signableRequest.getFirstHeader("X-Date").getValue()); } if (signableRequest.getFirstHeader("X-Content-Sha256") != null) { httpPost.setHeader("X-Content-Sha256", signableRequest.getFirstHeader("X-Content-Sha256").getValue()); } // 6. Set the request body httpPost.setEntity(new StringEntity(requestBody, StandardCharsets.UTF_8)); httpPost.setConfig(signableRequest.getConfig()); // 8. Send the request HttpResponse response = client.httpClient.execute(httpPost); // 9. Handle the response int statusCode = response.getStatusLine().getStatusCode(); HttpEntity responseEntity = response.getEntity(); if (responseEntity != null) { String responseBody = EntityUtils.toString(responseEntity, StandardCharsets.UTF_8); if (statusCode >= 200 && statusCode < 300) { System.out.println("API调用成功 (状态码: " + statusCode + ")"); return responseBody; } else { System.err.println("API调用失败: " + statusCode); System.err.println("错误详情: " + responseBody); return null; } } return null; } catch (Exception e) { System.err.println("调用异常: " + e.getMessage()); e.printStackTrace(); return null; } } public String listItems(String datasetId, int maxResults) throws Exception { String path = "/api/v1/dataset/" + datasetId + "/list_items"; Map params = new HashMap<>(); params.put("max_results", maxResults); return callApi("POST", path, params); } public String getItem(String datasetId, String itemId) throws Exception { String path = "/api/v1/dataset/" + datasetId + "/get_item"; Map params = new HashMap<>(); params.put("_id", itemId); return callApi("POST", path, params); } } public static void main(String[] args) { // Configuration information (replace with actual values) String DATASET_ID = ""; int MAX_RESULTS = 3; try { // Create a generic client ApiClient client = new ApiClient(AK, SK, REGION, HOST, SERVICE); AISearchService service = new AISearchService(client); System.out.println("=== 列出数据集项目 ==="); String listResult = service.listItems(DATASET_ID, MAX_RESULTS); if (listResult != null) { // Format and save the results JsonElement jsonElement = JsonParser.parseString(listResult); String formattedJson = client.getGson().toJson(jsonElement); Files.write(Paths.get("list_items.json"), formattedJson.getBytes(StandardCharsets.UTF_8)); System.out.println("列表结果已保存到 list_items.json"); } } catch (Exception e) { System.err.println("程序执行异常: " + e.getMessage()); e.printStackTrace(); } } public static SignableRequest prepareRequest(String host, String path, String method, List params, String body, String ak, String sk) throws Exception { SignableRequest request = new SignableRequest(); request.setMethod(method); request.setHeader("Accept", "application/json"); request.setHeader("Content-Type", "application/json"); request.setHeader("Host", HOST); request.setEntity(new StringEntity(body, "utf-8")); URIBuilder builder = request.getUriBuilder(); builder.setScheme(SCHEMA); builder.setHost(host); builder.setPath(path); if (params != null) { builder.setParameters(params); } RequestConfig requestConfig = RequestConfig.custom().setSocketTimeout(5000).setConnectTimeout(2000).build(); request.setConfig(requestConfig); Credentials credentials = new Credentials(REGION, SERVICE); credentials.setAccessKeyID(ak); credentials.setSecretAccessKey(sk); // Signature ISignerV4 ISigner = new SignerV4Impl(); ISigner.sign(request, credentials); return request; } } \`\`\` `}>); ``` ## Response Sample ```JSON { "request_id": "0cbab6b2-b17e-4ef6-885b-ed9b9099569a", "result": { "next_token": "MTc1NDQ4MTQ0MTkyM3wxMDcxNTEwNDdfNTc3MzE4NDA0NDcwNTQ5NjIzfDEwNzE1MTA0Nw\u003d\u003d", "items": [ { "_id": "30", "raw_data": "{\"duration\":\"\",\"video_url\":[\"http://domain.com/path\"],\"language\":\"汉语普通话\",\"content_id\":\"30\",\"sequence_index\":30,\"title\":\"三体\",\"media_link\":\"https://example.com/tv_series/67890/episode_1/\",\"parent_content_id\":\"三体\",\"release_date\":\"\",\"image\":\"https://domain.com/filename.jpg\",\"content_type\":\"video\",\"genres\":\"剧情/科幻\"}", "meta": { "video_meta": { "content_type": "video", "video_urls": [ "http://domain.com/path" ], "parent_content_id": "三体", "sequence_index": 30, "video_content": { "title": "智子封锁下的科技困局：微观粒子操控与文明存亡博弈", "summary": "三体文明通过智子工程展开质子维度操控，将二维平面包裹星球进行集成电路蚀刻，制造出能干扰地球高能加速器的超能计算机。地球科学家发现基础物理停滞源于智子对撞击实验的破坏，科技发展被彻底锁死。三体世界为此承受极寒黑夜，全民脱水贮存以应对漫长工程。人类科学家在绝望中探讨文明对抗本质，以虫子的生存韧性类比人类与三体文明的科技差距，寻找突破封锁的可能性。", "insight": "{\"Summaries\":[\"三体文明通过智子工程展开质子维度操控，将二维平面包裹星球进行集成电路蚀刻，制造出能干扰地球高能加速器的超能计算机。地球科学家发现基础物理停滞源于智子对撞击实验的破坏，科技发展被彻底锁死。三体世界为此承受极寒黑夜，全民脱水贮存以应对漫长工程。人类科学家在绝望中探讨文明对抗本质，以虫子的生存韧性类比人类与三体文明的科技差距，寻找突破封锁的可能性。\"],\"Titles\":[\"智子封锁下的科技困局：微观粒子操控与文明存亡博弈\"],\"Clips\":[{\"Title\":\"《三体》开场，宇宙探秘之旅开启\",\"Summary\":\"视频开场展示了出品人、总制片人等信息，随后画面切换到一艘在迷雾中航行的船，标注着林奇、孙忠怀等名字。接着，画面呈现出神秘的宇宙景象，包括悬浮的星球和复杂的机械装置，显示出科幻氛围。最后，镜头转到户外，有几个人在草地上活动，似乎在进行某种探索或讨论，为后续剧情埋下伏笔。\",\"Score\":3.5,\"Dialogue\":\"沪剧审字2023第001号。林奇、孙忠怀，出品人何嵩、白一骢、卢歧、马延琨、中积军、纪敬、胡进、黄杰、夏晓辉、王寒英。李尔云、白一骢、杨星阳、伊简梅、朱智涵、纪毅、朱绍超、黄橙、王宁、刘焱、田咏力、胡海波、徐丹、桑俊、康歆、李潇、闫豪利、吴洋、刘羽丹、章炜、尹秀杰、刘浮、海霞程、王涛、蔡天君、陈正纲、陈晨、刘勇奇、刘屹、周炜强、姜涛、刘屹、灯伟、周炜强、姜涛、男津语、路迪、音乐总监陈雪燃。\",\"Start\":0,\"End\":66.5}... ...]}" }, "collection_content": {}, "duration": 3288 } }, "process_status": "success", "check_status": "warning", "data_status_details": [ { "update_type": "FIRST_UPDATE_SUCCESS", "timestamp": "2025-08-06T19:57:23+08:00", "warning_info": { "ParentContentNotUploadedError": "" } } ], "update_time": "2025-08-06T19:57:22+08:00" }, { "_id": "29", "raw_data": "{\"image\":\"https://domain.com/filename.jpg\",\"title\":\"三体\",\"director\":\"杨磊\",\"video_url\":[\"http://domain.com/filename.mp4\"],\"content_type\":\"video\",\"sequence_index\":29,\"language\":\"汉语普通话\",\"release_date\":\"\",\"content_id\":\"29\",\"parent_content_id\":\"三体\",\"screenwriter\":[\"田良良\",\"陈晨\"],\"alias\":\"三体/Three-Body\",\"genres\":\"剧情/科幻\",\"douban_rating\":\"7.0\",\"first_air_date\":\"2023-01-15(中国大陆)\",\"media_link\":\"https://example.com/tv_series/67890/episode_1/\"}", "meta": { "video_meta": { "content_type": "video", "video_urls": [ "http://domain.com/filename.mp4\" ], "parent_content_id": "三体", "sequence_index": 29, "video_content": { "title": "纳米丝弦锁运河，星际谍影现杀机", "summary": "多国部队联合执行古筝行动，在巴拿马运河布设纳米丝切割网。审判日号载着穷凶极恶的船员驶入死亡之网，船体被精密切割解体。行动同时揭示三体监听站秘密，监听员冒死向地球发出警告，暴露三体文明占领太阳系的阴谋。全球战区协同完成信息截获，废墟中展开三体数据搜索，人类首次直面星际威胁。", "insight": "{\"Summaries\":[\"多国部队联合执行古筝行动，在巴拿马运河布设纳米丝切割网。审判日号载着穷凶极恶的船员驶入死亡之网，船体被精密切割解体。行动同时揭示三体监听站秘密，监听员冒死向地球发出警告，暴露三体文明占领太阳系的阴谋。全球战区协同完成信息截获，废墟中展开三体数据搜索，人类首次直面星际威胁。\"],\"Titles\":[\"纳米丝弦锁运河，星际谍影现杀机\"],\"Clips\":[{\"Title\":\"《三体》开场，宇宙探秘之旅开启\",\"Summary\":\"视频开场展示了国产电视剧发行许可证，随后是出品人、制片人等众多主创人员名单。画面中出现了神秘的宇宙景象，包括星空、星球以及一些高科技装置，营造出神秘而宏大的氛围。最后，镜头切换到户外，几个人在草地上似乎在进行某种活动，为故事的展开埋下伏笔。\",\"Score\":3.5,\"Dialogue\":\"沪剧审字2023第001号。林奇、孙忠怀，出品人何嵩、白一、卢歧、马延琨、中积军、纪敬、胡进、黄杰、夏晓辉、王寒英、李尔云、白一骢、杨星阳、伊简梅、A李尔云白，制A人黄星、汪悍贤、马骏、赵小波、朱智涵、纪毅、朱绍超、黄橙、王宁、刘田、水力胡、彭好、李盐、赵菁菁、事李、闫豪利、吴洋、刘羽丹、章炜、尹秀杰、王禹、齐昱、杨舒童、尹铁钢、刘淳、孙宏志、张曙光、陈晨、国剧陈晨、刘勇奇、刘屹、\",\"Start\":0,\"End\":67.5},{\"Title\":\"众人商讨过运河计划\",\"Summary\":\"在一间高科技感十足的会议室里，众人围坐在长桌旁，正在紧张地讨论着。其中一位戴眼镜的男子提出，船必须在白天过运河，其他人则认真倾听并思考着这一计划的可行性，整个场景充满了紧张和严肃的氛围。\",\"Score\":3,\"Dialogue\":\"也就是说，这船，得在白天过运河。\",\"Start\":67.5,\"End\":126},{\"Title\":\"众人商讨纳米丝布置方案\",\"Summary\":\"在一个指挥室内，众人正在讨论纳米丝的布置方案。有人提出，考虑到夜间船上人员的睡觉姿势，五十厘米的空档太大，而白天则足够。另一人提出疑问，如何确保其他船只的通行安全。随后，有人建议每根纳米丝在岸上连接一段普通钢丝，每根柱子一端连接活动绞机，通过坠在上面的重物使纳米丝沉入河底。\",\"Score\":3.5,\"Dialogue\":\"为什么？夜里船上的人得睡觉啊，他躺下或者趴下，那五十厘米空档太大了。白天不管他是站着，还是蹲着还是坐着，也都够了吧。你真是个魔鬼。我有一个问题，五十根一百六十米的、超强度纳米丝，按五十公分的间距，连接在两根钢柱上，可我们如何确保，其它船只的通行安全？所以我建议，每一根纳米丝，在岸上连接一段普通的钢丝，每一根柱子的一端，和活动的绞机连接，这样，纳米丝可以通过坠在上面的重物，沉入到河底。\",\"Start\":126,\"End\":179}... ....]}" }, "collection_content": {}, "duration": 2991 } }, "process_status": "success", "check_status": "warning", "data_status_details": [ { "update_type": "FIRST_UPDATE_SUCCESS", "timestamp": "2025-08-06T19:57:22+08:00", "warning_info": { "ParentContentNotUploadedError": "" } } ], "update_time": "2025-08-06T19:57:22+08:00" } } ``` :::tip \*说明 To experience more of Viking AI's search capabilities, visit [Viking AI Search, an all-in-one intelligent engine for enterprise search, recommendation, and Q&A](https://www.volcengine.com/product/AI-Search-Rec). :::