runningz1 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.