Volcengine Fusion Information Search

Overview

Provide access to Volcengine's (ByteDance) Fusion Information Search API, enabling web searches, image searches, and AI-powered search summaries. The API returns structured results with rich metadata including authority levels, publish times, content snippets, and special card data (weather, stocks, travel info, etc.).

Core Capabilities

1. Web Search

Execute standard web searches with advanced filtering options:

Filter by time range (OneDay, OneWeek, OneMonth, OneYear, or custom date range)
Specify or block specific domains
Control authority level (only highly authoritative sources)
Get content snippets, summaries, or full text
Enable query rewriting for better results
Industry-specific searches (finance, gaming)

2. Web Search with AI Summary

Perform web searches and receive AI-generated summaries:

All features of standard web search
Additional AI-powered content summarization
Token usage statistics
Streaming or non-streaming response options

3. Image Search

Search for images with dimension and shape filters:

Filter by width/height ranges
Filter by shape (horizontal rectangle, vertical rectangle, square)
Get image metadata (dimensions, URLs, publish times)

4. Rich Card Data (火山如意)

Automatically receive structured card data when relevant:

Weather forecasts and air quality
Stock prices and financial data
Exchange rates and precious metals
Holiday schedules and calendars
Train/flight schedules
Concert information
And more (see references/api_reference.md for full list)

Quick Start

Prerequisites

Obtain an API Key from Volcengine console:

Visit https://console.volcengine.com/ask-echo/api-key
Navigate to "融合信息搜索" section
Create a new API Key
Store the key securely (use environment variable: VOLCENGINE_API_KEY)

Basic Usage Pattern

For simple searches, use the Python client script directly. For programmatic integration, import and use the VolcengineSearchClient class from scripts/volcengine_search.py.

Usage Examples

Example 1: Recent News Search

Search for recent news articles with high authority using the Python client.

Example 2: Domain-Specific Search

Search within specific trusted domains like stackoverflow.com, github.com.

Example 3: AI-Powered Summary

Get AI-generated summary of search results with token usage statistics.

Example 4: Image Search with Filters

Search for high-resolution landscape images with dimension filters.

Example 5: Financial Industry Search

Search with finance-specific optimization and query rewriting.

Working with Rich Card Data

When search results include structured card data (火山如意), extract it from the CardResults field. The API automatically returns relevant card types based on the query (weather, stocks, exchange rates, train schedules, etc.).

Refer to references/api_reference.md for complete card type specifications and data structures.

Error Handling

Handle common errors gracefully:

Status 403: Access denied - check API key and permissions
Status 429: Rate limit exceeded (default 5 QPS)
Empty results: Try enabling query_rewrite or broadening filters

Best Practices

API Key Security: Never hardcode API keys. Use environment variables or secure configuration files.
Rate Limiting: Default limit is 5 QPS per account. Implement retry logic with exponential backoff if needed.
Query Optimization:
- Keep queries concise (1-100 characters)
- Enable query_rewrite for complex queries
- Use industry-specific searches when applicable
Result Filtering:
- Use auth_info_level=1 for highly authoritative sources only
- Apply time ranges to get recent content
- Block low-quality domains with block_hosts
Content Retrieval:
- Set need_content=True only when full text is required (increases response size)
- Use need_summary=True for 300-500 character summaries
- Standard snippets (~100 chars) are included by default
Token Management (for summary mode):
- Monitor token usage via the Usage field
- Summary mode consumes tokens for AI processing
- Check TotalTokens, PromptTokens, and CompletionTokens

Command-Line Usage

The Python script supports direct command-line execution:

# Web search
python scripts/volcengine_search.py YOUR_API_KEY web "搜索关键词"

# Web search with summary
python scripts/volcengine_search.py YOUR_API_KEY summary "搜索关键词"

# Image search
python scripts/volcengine_search.py YOUR_API_KEY image "图片关键词"

Output is formatted as JSON for easy parsing.

Resources

scripts/volcengine_search.py

Python client library providing:

VolcengineSearchClient class with methods for all search types
Command-line interface for quick searches
Proper error handling and request formatting

references/api_reference.md

Comprehensive API documentation including:

Complete parameter specifications
Response structure details
All supported card types
Error codes and troubleshooting
Request/response examples

Limitations

Query Length: 1-100 characters (longer queries are truncated)
Result Limits:
- Web search: max 50 results per request
- Image search: max 5 results per request
Rate Limits: Default 5 QPS (can request increase via support ticket)
Free Quota: 5,000 free calls each for web search and web search summary
Domain Filters: Max 5 domains for sites or block_hosts

Troubleshooting

Error 100013 (AccessDenied):

Ensure API key is valid and active
For sub-accounts, grant TorchlightApiFullAccess permission in IAM console
Main account access is unrestricted

Empty Results:

Try enabling query_rewrite=True
Broaden time range or remove domain filters
Check if query is too specific or contains typos

Slow Response:

Disable query_rewrite if not needed (adds latency)
Reduce count parameter
Use standard search instead of summary mode

For detailed API specifications, authentication methods, and data structures, refer to references/api_reference.md.

volcengine-search