user

User

是

见下：User

用户信息，可上传用户 pseudo ID（需通过用户系统获取并确保唯一），用于明确是哪一位具体的用户触发了本次 API 调用。用户信息对象，包含用户唯一标识（_user_id）

page_size

Integer

否

10

最高返回数量：决定返回的推荐物品数量。如未传入，则使用当前场景在控制台中配置的返回数量。不支持分页，返回结果为单批次。

parent_items

Array<Item>

部分场景必须

见下：Item

在「详情页推荐」场景中，必须传入当前详情页物品的唯一标识（需从物品数据集中获取，即物品的_id字段值）。

session_id

String

否

"GrrZCRhlYyxQOiSf0qG6MgJX3qb7Jgm6s8e1"

用户会话的唯一标识，用于判断推荐场景中置顶推荐物品的 24 小时内重复生效情况。当推荐场景配置并生效了置顶推荐物品配置且关闭了**「每次刷新时重复推荐」**时，产品通过session_id判断是否当天已经置顶过。若未提供此参数，则不做24小时内的重复置顶判断。如果session_id已经在24小时内出现，skipped = true，详情请见

filter

Object<Filter>

否

见下：Filter

如果您在推荐范围中配置了「动态参数过滤」且该过滤条件为必填，则必须通过这个字段传入参数值。平台会自动利用值来填充参数的过滤条件，并自动忽略缺失的动态过滤条件。

output_fields

Array

否

["title", "price", "category"]

指定推荐物品列表的'display_fields'返回中，选择物品数据集数据中的哪些字段来返回展示，如果不传则返回所有字段。

如果数据集中存在嵌套的对象(Object或Array

context

Object<Context>

否

见下：Context

支持配置请求上下文（context），影响推荐物品召回处理逻辑和返回物品的结果

_user_id

String

是

"user_199432"

代表最终用户的唯一标识符。
该字段用于精确标识触发本次 API 调用的具体用户，对于区分同一组织下的不同使用者至关重要。
例如，它有助于记录详细操作日志、提供个性化推荐，或分析不同用户的行为模式。建议为每位最终用户分配并传递唯一 ID。

_id

String

是

"item_1001"

在「详情页推荐」场景中，必须传入当前详情页物品的唯一标识。该唯一标识需存在于物品数据集中，否则召回过程将自动忽略该物品。

配置的参数

{
    "category": ["shoes"],
    "max_price": 100.50
}

了解更多： 动态推荐范围配置

1. 用于传入与平台配置一致的动态过滤条件参数，参数名称必须和平台配置对齐。
2. 平台会自动忽略缺失的动态过滤条件。
3. 如果过滤字段数据格式为字符串 (String)，输入必须是数组 (Array)

location

{
    "latitude": "12.1243",
    "longitude": "-012.1223"
}

1. 支持传入用户位置，用于用户地理位置提权与降权物品配置。传入数据格式必须是字符串
2. 若输入不合法，平台会自动忽略 LBS 配置。
3. 依赖控制台配置，详情请查看： 用户地理位置提权与降权

request_id

String

"25ee998a-5462-9385-9f18-035f1da7a6e5"

用于唯一标识一次请求，可根据 request_id 快速定位一次请求的执行。

rec_results

Array<RecommendResults>

见下： RecommendResults

推荐物品列表。

extra_info

Object<ExtraInfo>

见下： ExtraInfo

单次请求中携带的额外信息对象，用于指定生效的业务逻辑（如示例中的个性化推荐），帮助理解返回推荐物品列表的生成逻辑

_id

String

"item_1003"

该物品在物品数据集中的主键来源于您在上传物品数据集时指定为唯一标识字段的值。

display_fields

Object

"display_fields": {
      "allow_search": "1",
      "inner_item_count":  1234,
      "update_time": 1752238692193,
      "item_id": "item_1003",
      "main_sku": "default",
      "sale_rule": "1,2",
      "item_category": [
        "3","5","12"
      ],
      "sku_id": "default"
}

返回中的字段与您导入数据时的字段一致。您可以在请求中指定要返回的字段，若未指定，则默认返回所有字段。

forced_item_info

Object<ForcedItems>

见下： ForcedItems

当推荐场景配置并生效了置顶推荐物品配置，参数会返回置顶物品 ID 和生效状态，以便您检查是否符合预期。

omitted_params

Array

["category", "max_price"]

为确保推荐接口总能返回结果，当动态过滤条件不合法或为空时，平台会自动忽略该条件。此参数会列出本次请求中所有被忽略的 Filter 参数名。

item_ids

Array

["60493", "52937"]

成功置顶的物品 ID

skipped

Boolean

false

置顶是否生效：true 表示 session_id已在24小时内出现，置顶不生效；false表示session_id未在24小时内出现，置顶生效。
session_id 参数配置，请查看 请求体。