完成第一次查询

完成本页后，你将使用平台分配给接入应用的订阅和应用密钥执行一次关键词检索。

接入前提

平台已为你的组织开通 Portal 账号。
组织下已有接入应用。
平台已给该应用分配有效订阅。
组织 owner/admin 已在 Portal「接入应用 → 应用密钥」创建 Consumer API Key，并安全交付给你。
本机有 Bash、curl（支持 --fail-with-body）和 jq。

本页只查询已有数据，不发起新采集。

生产 Base URL：

https://www.marsyoo.com

第一次查询

Bash

export WHALE_BASE_URL="${WHALE_BASE_URL:-https://www.marsyoo.com}"
: "${WHALE_API_KEY:?Set the Consumer API Key from Portal}"
 
search_response="$(curl -sS --fail-with-body --request POST "$WHALE_BASE_URL/v1/search" \
  --header "Authorization: Bearer $WHALE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "keyword",
    "query": "人工智能",
    "limit": 10
  }')"
printf '%s' "$search_response" | jq .
DOCUMENT_ID="$(printf '%s' "$search_response" | jq -r '.results[0].document_id // empty')"

响应结构（字段完整说明见关键词与语义检索）：

JSON

{
  "mode": "keyword",
  "results": [
    {
      "document_id": "doc_01J...",
      "source_platform": "weibo",
      "title": "...",
      "body": "最佳命中分块摘要",
      "score": 0.87,
      "published_at": "2026-09-10T12:00:00Z"
    }
  ],
  "total": 342,
  "cursor": "eyJv..."
}

验证：请求成功，响应有 results 数组。results=[] 仍可能是正常结果，先确认关键词、已有数据和订阅范围，不要因此自动发起实时采集。

本例不传平台过滤，使用应用已有的授权范围。需要限定平台时，添加合法的 platforms 枚举；过滤不能扩大订阅权限。/v1/contents/search 是旧兼容入口，新接入使用 /v1/search。

读取详情

只有结果非空才执行下一步；这里使用上一步自动取得的 document_id：

Bash

: "${DOCUMENT_ID:?No matches; check the query and subscription before reading details}"
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID" \
  --header "Authorization: Bearer $WHALE_API_KEY"

返回文档元数据和当前版本信息；字段说明见读取内容与历史。

完整正文：

Bash

curl -sS --fail-with-body "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID/content" \
  --header "Authorization: Bearer $WHALE_API_KEY"

请求失败时

401 查 Key 是否有效；403 查订阅和字段权限；429 按限流策略退避。错误处理见限流、重试与排错。不要把 Key 放进日志或 Agent 对话。

查询和正文读取成功后，进入关键词与语义检索，选择适合实际需求的检索模式与筛选条件。

完成标准： 查询得到 document_id，并成功读取对应正文；空结果时先检查关键词和订阅，不自动发起采集。