@volcengine/search-sdk-js

Node.js SDK for Viking AI Search Open APIs.

Install

npm install @volcengine/search-sdk-js

The package supports both ESM and CommonJS.

Usage

import { createSearchClient } from "@volcengine/search-sdk-js";

const client = createSearchClient({
  apiKey: process.env.API_KEY!,
  region: "cn-beijing"
});

const result = await client.search({
  application: "76414365027",
  scene_id: "g0BAC4BM",
  dataset_id: "106265704",
  query: { text: "running shoes" },
  page_number: 1,
  page_size: 20
});

console.log(result.search_results);

Authentication

Use either an API key or AK/SK credentials. The two modes are mutually exclusive.

API key authentication sends a Bearer token:

const client = createSearchClient({
  apiKey: process.env.API_KEY!,
  region: "cn-beijing"
});

AK/SK authentication signs each request with Volcengine OpenAPI signing:

const client = createSearchClient({
  accessKeyId: process.env.VOLC_ACCESSKEY!,
  secretAccessKey: process.env.VOLC_SECRETKEY!,
  region: "cn-beijing"
});

baseUrl can override the region-derived endpoint:

const client = createSearchClient({
  apiKey: process.env.API_KEY!,
  baseUrl: "https://aisearch.cn-beijing.volces.com"
});

When overriding baseUrl to another region while using AK/SK credentials, pass the matching region as well so the signature scope is correct.

Timeout

Timeout is optional and measured in milliseconds.

• Set timeout on the client to use a default.
• Pass { timeout } as the second argument to override one request.
• Omit it to avoid SDK-level timeout handling.
• For chatSearch(), timeout only covers the initial request before response headers arrive.

const client = createSearchClient({
  apiKey: process.env.API_KEY!,
  region: "cn-beijing",
  timeout: 30_000
});

await client.search(searchParams, { timeout: 10_000 });

Chat Search

chatSearch() is streaming-only and returns an AsyncIterable.

for await (const chunk of client.chatSearch({
  application: "76414365027",
  session_id: "session_123",
  input_message: {
    content: [{ type: "text", text: "推荐几件外套" }]
  }
})) {
  process.stdout.write(chunk.content ?? "");
}

Data API

Dataset APIs use dataset_id for the path parameter and keep request body fields in the OpenAPI wire format.

await client.writeData({
  dataset_id: "106265704",
  fields: [
    {
      _id: "item_123",
      title: "running shoes",
      price: 129
    }
  ]
});

const item = await client.getItem({
  dataset_id: "106265704",
  _id: "item_123",
  output_fields: ["title", "price"]
});

console.log(item.item);

Methods

• search({ application, scene_id, ...body })
• recommend({ application, scene_id, version = "v1", ...body })
• chatSearch({ application, ...body })
• queryCompletion({ application, scene_id, ...body })
• queryRecommendation({ application, scene_id, ...body })
• rerank({ application, scene_id, version = "v1", ...body })
• deduplicate({ application, version = "v1", ...body })
• writeData({ dataset_id, version = "v1", ...body })
• deleteData({ dataset_id, version = "v1", ...body })
• getItem({ dataset_id, version = "v1", ...body })
• listItems({ dataset_id, version = "v1", ...body })
• createBatchImport({ dataset_id, version = "v1", ...body })
• batchImport({ dataset_id, version = "v1", ...body })
• completeBatchImportTask({ dataset_id, version = "v1", ...body })
• getBatchImportStatus({ dataset_id, version = "v1", ...body })

All methods accept an optional second argument for request options, including a per-request timeout override.

Request body fields use the OpenAPI wire format, including snake_case field names such as dataset_id, page_number, and input_message.

Errors

Non-2xx responses throw SearchApiError.

import { SearchApiError } from "@volcengine/search-sdk-js";

try {
  await client.search({
    application: "76414365027",
    scene_id: "g0BAC4BM",
    dataset_id: "106265704",
    query: { text: "running shoes" },
    page_number: 1,
    page_size: 20
  });
} catch (error) {
  if (error instanceof SearchApiError) {
    console.error(error.status, error.code, error.requestId, error.message);
  }
}

SDK timeouts throw SearchTimeoutError when timeout options are used.

Development

npm install
npm run gen:openapi
npm test

npm test is the full local verification gate. It runs type checking, unit tests, live API tests, the production build, and the package smoke test. Live API failures block release verification by default.

Useful test commands:

npm run test:unit      # Run the Vitest unit suite with mocked fetch responses.
npm run test:live      # Run the real API integration suite.
npm run test:watch     # Run Vitest in watch mode while developing.
npm run test:coverage  # Generate a coverage report for hand-written runtime code.
npm run test:pack      # Build and verify ESM/CJS exports, declarations, and package contents.
npm run verify         # Same verification sequence used by npm test.

Unit tests use mocked API responses and do not require a Volcengine API key or network access. Coverage reporting excludes generated OpenAPI code under src/generated and does not enforce a coverage threshold.

Live API tests

Live tests call real Viking AI Search APIs and are included in npm run verify and npm test. Configure them with shell environment variables or copy test/live/.env.example to test/live/.env.

Authentication values, choose one mode:

SEARCH_NODE_LIVE_API_KEY=
# Or:
# SEARCH_NODE_LIVE_ACCESS_KEY_ID=
# SEARCH_NODE_LIVE_SECRET_ACCESS_KEY=

Other required values:

SEARCH_NODE_LIVE_APPLICATION=
SEARCH_NODE_LIVE_SEARCH_SCENE_ID=
SEARCH_NODE_LIVE_RECOMMEND_SCENE_ID=
SEARCH_NODE_LIVE_DATASET_ID=
SEARCH_NODE_LIVE_ITEM_ID=
SEARCH_NODE_LIVE_QUERY=

Optional values:

SEARCH_NODE_LIVE_REGION=cn-beijing
SEARCH_NODE_LIVE_BASE_URL=
SEARCH_NODE_LIVE_TIMEOUT_MS=30000
SEARCH_NODE_LIVE_PAGE_SIZE=1
SEARCH_NODE_LIVE_LIST_MAX_RESULTS=1
SEARCH_NODE_LIVE_EXPECTED_MIN_RESULTS=1

The default live suite covers search, recommend, getItem, and listItems. It also runs queryCompletion, queryRecommendation, and chatSearch. recommend() uses SEARCH_NODE_LIVE_RECOMMEND_SCENE_ID; search-family APIs use SEARCH_NODE_LIVE_SEARCH_SCENE_ID.

To skip live tests explicitly when credentials, network, or quota are temporarily unavailable:

SEARCH_NODE_SKIP_LIVE_TESTS=1 npm run verify

The generated OpenAPI code lives under src/generated and should not be edited manually.

License

Apache-2.0