指定数据集和物品ID,获取物品的所有导入字段和处理详情
说明
仅支持对物品数据集查询,暂不支持行为数据集的查询
注意事项
- 使用限制:
- 受到HTTP Body大小限制,单次请求的包体大小最大不超过10MB。
请求说明
{dataset_id}:在控制台创建数据集后,系统指定的数据集唯一标识,可在控制台数据集详情中查看并复制

请求参数
请求体
参数 | 类型 | 是否必选 | 示例值 | 描述 |
|---|
_id
| String | 是 | "test_id" | 数据条目主键 - 图文数据集:您指定的物品ID属性对应的字段
- 视频数据集:content_id字段对应的ID
|
output_fields
| Array | 否 | ["title", "price", "category"] | 对查询的目标数据集,指定返回物品数据的字段。指定返回字段后,接口返回的raw_data字段中仅出现指定的字段。 如果数据集中存在嵌套的对象(Object),则只支持传入上层的字段名。
传入不存在的字段或Object内层的字段会被忽略。
|
响应体
参数名 | 参数类型 | 举例 | 说明 |
|---|
item
| DataItem
| | 查询到的数据条目列表,每条数据条目中包含物品ID对应的数据字段和处理详情。 |
DataItem
参数名 | 参数类型 | 举例 | 说明 |
|---|
_id
| String | "test_itemid" | 数据记录主键,数据集内唯一 |
raw_data
| String | | 导入的原始数据所有字段内容 |
meta
| DataItemMeta
| | 对于**视频数据集**,返回数据的处理和状态信息 |
process_status
| String | "success" | 数据处理状态,success, processing, failed |
check_status
| String | "normal" | 数据检查状态,normal, warning, error |
data_status_details
| Array<DataStatusDetail> | | 数据质量校验和处理状态列表,包含数据首次导入、最近更新的状态说明。 |
create_time
| String | "2025-03-12T15:01:07+08:00" | 创建时间,RFC3339格式 |
update_time
| String | "2025-03-12T15:01:07+08:00" | 更新时间,RFC3339格式 |
DataItem中视频数据集返回:
DataItemMeta
参数名 | 参数类型 | 举例 | 说明 |
|---|
video_meta
| VideoMeta | | 视频数据的处理和状态信息 |
VideoMeta
参数名 | 参数类型 | 举例 | 说明 |
|---|
content_type
| String | video | 内容类型: video, collection |
video_urls
| Array | ["https://domain.com/file_path.format"] | 视频URL列表 |
parent_content_id
| String | | 父内容ID |
sequence_index
| Int | | 序列索引 |
video_content
| VideoContent
| | 视频处理和理解的内容 |
collection_content
| CollectionContent
| | 视频系列的处理和理解内容 |
duration
| Int | | 视频时长(秒),不足 1 秒向上取整 |
VideoContent
参数名 | 参数类型 | 举例 | 说明 |
|---|
Title
| String | "视频标题" | 生成的视频标题 |
Summary
| String | "内容总结" | 生成的视频总结 |
Insight
| String | | 视频故事线理解返回的全部内容,将json marshal 为string格式。 |
CollectionContent
参数名 | 参数类型 | 举例 | 说明 |
|---|
summary
| String | | 对系列合集下的每个视频处理完成后,将合集整体内容进行总结得到的视频摘要 |
DataStatusDetail
参数名 | 参数类型 | 举例 | 说明 |
|---|
update_type
| String | "FIRST_UPDATE_SUCCESS" | 更新类型: - "FIRST_UPDATE_SUCCESS":首次导入和处理成功
- "LATEST_UPDATE_SUCCESS":最新一次更新和处理成功
- "UPDATE_FAILED":最近一次更新数据遭遇异常
|
timestamp
| String | "2025-03-12T15:01:07+08:00" | 更新时间,RFC3339格式 |
warning_info
| Map[String]String | | 数据质量异常信息,格式为"状态码": "异常详情"
出现数据质量异常不影响数据的处理和入库索引,但建议后续修复以提升检索效果 |
error_info
| Map[String]String | | 数据校验和处理异常信息,格式为"状态码": "异常详情"
出现校验和处理异常表示数据被阻断在校验阶段,无法正常处理入库索引,建议查看异常信息并重传修复。 |
数据状态说明
数据导入后会进行数据的质量校验和处理,校验和处理过程中会产生数据状态,数据状态会影响数据的索引和使用,以下介绍数据的过程定义和状态定义。
数据过程状态
数据过程状态在DataItem中返回,分为2个状态:
process_status:数据的处理状态,包含
- "success":表示数据正常处理入库完成,对应控制台展示“数据正常”
- "failed":表示数据有阻断性的异常,导致入库失败,对应控制台展示“数据异常”
- "processing":表示数据正在处理中,图文数据因处理较快一般不会出现处理中状态,视频文件处理时间较长,会出现处理中状态,对应控制台展示“数据处理中”。
check_status:数据的质量验证状态,包含:
- "normal":数据校验一切正常,各字段没有格式、类型、文件的异常
- "warning":数据存在质量问题,如非预置字段的类型异常,或图片的链接异常,不影响整条数据的入库处理,但建议收到质量问题状态时修复和重新传输数据
- "error":数据存在严重质量问题,如预置字段的类型异常,视频文件链接异常,影响整条数据的入库处理,建议收到质量问题状态时修复和重新传输数据
状态详情
在DataStatusDetail 结构中返回状态码和状态信息详情,分别展示首次导入、最近一次更新的处理状态详情:
状态码 | 说明 |
|---|
Finished
| 数据处理完成 |
Running
| 数据正常处理中 |
InternalError
| 内部错误处理失败 |
InvalidJsonLineError
| 数据异常 |
DataPrimaryKeyNotFoundError
| 必须包含主键字段,且有值 |
DataContentTypeNotFoundError
| (视频数据)必须包含content_type字段,且有值 |
UnsupportedContentTypeError
| (视频数据)不支持的content_type枚举值,仅支持“video”和“collection” |
DuplicateMediaSequenceIndexError
| (视频数据)媒体序号重复 |
MediaCannotBeSetAsParentError
| (视频数据)媒体内容不支持设置为父层级 |
ParentContentMustBeCollectionError
| (视频数据)父内容只能为系列 |
ParentContentNotUploadedError
| (视频数据)父内容未上传 |
InvalidVideoUrlError
| (视频数据)视频链接无法访问 |
InvalidImageUrlError
| (视频数据)图片链接无法访问 |
VideoUrlNotUploadedError
| (视频数据)视频url没有上传 |
InvalidMediaSequenceIndexError
| (视频数据)媒体序号值无效,存在重复序号 |
InvalidMediaCoverUrlError
| (视频数据)媒体封面链接无法访问 |
RequiredFieldTypeMismatchError
| (视频数据)预置字段类型错误 |
NonRequiredFieldTypeMismatchError
| 自定义字段类型错误 |
ContentTypeNotModifiableError
| (视频数据)content_type不允许修改 |
VideoProcessError
| (视频数据)视频处理异常 |
VideoDurationExceedsLimitError
| (视频数据)视频时长超过限制,最长3.5小时 |
VideoSizeExceedsLimitError
| (视频数据)视频大小超过限制,最大10GB |
错误码
错误码 | HTTP 状态码 | 错误信息 | 说明 |
|---|
DatasetNotFound | 404 | The dataset not found %s | 数据集不存在 |
InvalidParameter | 400 | A parameter in the request is not valid: %s | 参数不符合格式要求 |
ErrCodeInvalidRequestBody | 400 | The request cannot be parsed in JSON format: %s | 请求反序列化失败 |
ErrCodeInternalServiceError | 500 | Service has some internal Error. Pls Contact With Admin. | 请求处理过程中出现了未知错误,例如后端服务超时、出现网络波动等,与可靠性相关 |
请求示例
curl -X POST https://aisearch.cn-beijing.volces.com/api/v1/dataset/{dataset_id}/get_item -H 'Content-Type: application/json' -H 'Authorization: <火山鉴权的一系列相关header>' -d '{
"_id": "2"
}'
import json
from volcenginesdkcore.rest import ApiException
from volcenginesdkcore import ApiClient, Configuration
from volcenginesdkcore.signv4 import SignerV4
def get_generic_client(access_key: str, secret_key: str, region: str, endpoint: str):
"""创建通用API客户端(适用于任何服务)"""
try:
config = Configuration()
config.ak = access_key
config.sk = secret_key
config.region = region
config.host = endpoint
config.scheme = "https"
return ApiClient(config)
except Exception as e:
print(f"客户端初始化失败: {str(e)}")
return None
def call_aisearch_api(client: ApiClient, method: str, path: str, params: dict = None):
try:
# 设置服务名
service = "aisearch"
# 设置请求头
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"Host": client.configuration.host,
}
# 序列化请求体
body = json.dumps(params) if params else ""
# 手动签名请求
SignerV4.sign(
path=path,
method=method.upper(),
headers=headers,
body=body,
post_params={},
query={},
ak=client.configuration.ak,
sk=client.configuration.sk,
region=client.configuration.region,
service=service,
)
# 使用rest客户端发送请求
if method.upper() == "POST":
response = client.rest_client.POST(
url=f"https://{client.configuration.host}{path}",
headers=headers,
body=json.loads(body) if body else None,
_preload_content=True,
)
else:
response = client.rest_client.GET(
url=f"https://{client.configuration.host}{path}",
headers=headers,
_preload_content=True,
)
# 解析响应
response_data = json.loads(response.data)
# 打印状态和保存结果
print(f"API调用成功 (状态码: {response.status})")
return response_data
except ApiException as e:
print(f"API调用失败: {e.status} {e.reason}")
print(f"错误详情: {e.body}")
return None
except Exception as e:
print(f"调用异常: {str(e)}")
return None
if __name__ == "__main__":
ACCESS_KEY = "" # 配置信息(请替换为实际值)
SECRET_KEY = ""
REGION = "cn-beijing"
ENDPOINT = "aisearch.cn-beijing.volces.com" # AISearch服务端点
DATASET_ID = "" # 数据集ID
# 创建通用客户端
client = get_generic_client(ACCESS_KEY, SECRET_KEY, REGION, ENDPOINT)
if client is None:
print("客户端初始化失败,程序退出")
exit(1)
item_id = "" # 确保ID存在
get_path = f"/api/v1/dataset/{DATASET_ID}/get_item"
get_params = {"_id": item_id}
get_result = call_aisearch_api(client, "POST", get_path, get_params)
if get_result:
with open("get_item.json", "w", encoding="utf-8") as f:
json.dump(get_result, f, ensure_ascii=False, indent=2)
print("项目详情已保存到 get_item.json")
package com.example;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.*;
import java.nio.file.Files;
import java.nio.file.Paths;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonParser;
import com.google.gson.JsonElement;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.volcengine.auth.ISignerV4;
import com.volcengine.auth.impl.SignerV4Impl;
import com.volcengine.model.Credentials;
import com.volcengine.service.SignableRequest;
public class App {
private static final String AK = ""; // your ak
private static final String SK = ""; // your sk
private static final String HOST = "aisearch.cn-beijing.volces.com";
private static final String SERVICE = "aisearch";
private static final String REGION = "cn-beijing";
private static final String SCHEMA = "https";
public static class ApiClient {
private final String accessKey;
private final String secretKey;
private final String region;
private final String host;
private final String service;
private final HttpClient httpClient;
private final Gson gson;
public ApiClient(String accessKey, String secretKey, String region, String host, String service) {
this.accessKey = accessKey;
this.secretKey = secretKey;
this.region = region;
this.host = host;
this.service = service;
this.httpClient = HttpClients.createDefault();
this.gson = new GsonBuilder().setPrettyPrinting().create();
}
public String getHost() {
return host;
}
public Gson getGson() {
return gson;
}
}
public static class AISearchService {
private final ApiClient client;
public AISearchService(ApiClient client) {
this.client = client;
}
public String callApi(String method, String path, Map<String, Object> params) throws Exception {
try {
// 1. 构建请求体
String requestBody = params != null ? client.getGson().toJson(params) : "";
// 2. 准备签名请求
SignableRequest signableRequest = prepareRequest(
client.getHost(),
path,
method,
new ArrayList<>(),
requestBody,
client.accessKey,
client.secretKey
);
// 3. 构建最终的 HTTP 请求
URI uri = signableRequest.getUriBuilder().build();
HttpPost httpPost = new HttpPost(uri);
// 4. 设置请求头
httpPost.setHeader("Content-Type", "application/json");
httpPost.setHeader("Accept", "application/json");
httpPost.setHeader("Host", client.getHost());
// 5. 复制认证相关请求头
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. 设置请求体
httpPost.setEntity(new StringEntity(requestBody, StandardCharsets.UTF_8));
httpPost.setConfig(signableRequest.getConfig());
// 8. 发送请求
HttpResponse response = client.httpClient.execute(httpPost);
// 9. 处理响应
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<String, Object> 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<String, Object> params = new HashMap<>();
params.put("_id", itemId);
return callApi("POST", path, params);
}
}
public static void main(String[] args) {
// 配置信息(请替换为实际值)
String DATASET_ID = "";
int MAX_RESULTS = 3;
try {
// 创建通用客户端
ApiClient client = new ApiClient(AK, SK, REGION, HOST, SERVICE);
AISearchService service = new AISearchService(client);
String itemId = ""; // 确保ID存在
String getResult = service.getItem(DATASET_ID, itemId);
if (getResult != null) {
// 格式化并保存结果
JsonElement jsonElement = JsonParser.parseString(getResult);
String formattedJson = client.getGson().toJson(jsonElement);
Files.write(Paths.get("get_item.json"), formattedJson.getBytes(StandardCharsets.UTF_8));
System.out.println("项目详情已保存到 get_item.json");
}
} catch (Exception e) {
System.err.println("程序执行异常: " + e.getMessage());
e.printStackTrace();
}
}
public static SignableRequest prepareRequest(String host, String path, String method, List<NameValuePair> 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);
// 签名
ISignerV4 ISigner = new SignerV4Impl();
ISigner.sign(request, credentials);
return request;
}
}
响应示例
{
"request_id": "f0821969-7461-48bc-b5dd-beba75c01805",
"result": {
"item": {
"_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://ai-search-rec-video.byte-test.com/9ecc0045531947d4bd71ff6a890289e6/main.m3u8"
],
"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"
}
}
}