Web Search
Enable real-time web search capabilities in your AI applications
Overview
The BLACKBOX AI API provides powerful web search capabilities through the blackbox-search model. This feature allows your AI applications to access real-time information from the web, providing up-to-date answers with cited sources.
Key Features
- Real-time Information: Access current data from the web
- Source Citations: Get URLs and titles of sources used
- Seamless Integration: Works with the standard chat completions API
- Automatic Context: Web results are automatically incorporated into responses
Using Web Search
To enable web search, simply use the blackbox-search model in your chat completion requests:
# Public api users: use https://api.blackbox.ai/v1/chat/completions
curl --location 'https://enterprise.blackbox.ai/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "blackbox-search",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that provides accurate, up-to-date information."
},
{
"role": "user",
"content": "What are the latest developments in AI from OpenAI?"
}
],
}'from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ.get("BLACKBOX_API_KEY"),
# Public api users: use https://api.blackbox.ai
base_url="https://enterprise.blackbox.ai",
)
response = client.chat.completions.create(
model="blackbox-search",
messages=[
{
"role": "system",
"content": "You are a helpful assistant that provides accurate, up-to-date information."
},
{
"role": "user",
"content": "What are the latest developments in AI from OpenAI?"
}
],
stream=False
)
print(response.choices[0].message.content)
# Access citations if available
if hasattr(response.choices[0].message, 'annotations'):
for annotation in response.choices[0].message.annotations:
if annotation.type == 'url_citation':
print(f"\nSource: {annotation.url_citation.title}")
print(f"URL: {annotation.url_citation.url}")import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.BLACKBOX_API_KEY,
// Public api users: use https://api.blackbox.ai
baseURL: 'https://enterprise.blackbox.ai',
});
async function searchWeb() {
const response = await client.chat.completions.create({
model: 'blackbox-search',
messages: [
{
role: 'system',
content: 'You are a helpful assistant that provides accurate, up-to-date information.'
},
{
role: 'user',
content: 'What are the latest developments in AI from OpenAI?'
}
],
stream: false
});
console.log(response.choices[0].message.content);
// Access citations if available
if (response.choices[0].message.annotations) {
response.choices[0].message.annotations.forEach(annotation => {
if (annotation.type === 'url_citation') {
console.log(`\nSource: ${annotation.url_citation.title}`);
console.log(`URL: ${annotation.url_citation.url}`);
}
});
}
}
searchWeb();Response Format
When using web search, the response includes an annotations array containing URL citations:
{
"id": "gen-...",
"created": 1757140020,
"model": "blackbox-search",
"object": "chat.completion",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "Here's the latest news I found: OpenAI recently announced...",
"annotations": [
{
"type": "url_citation",
"url_citation": {
"url": "https://www.example.com/openai-news",
"title": "Latest OpenAI Developments",
"content": "Content of the web search result",
"start_index": 100,
"end_index": 200
}
}
]
}
}
],
"usage": {
"completion_tokens": 150,
"prompt_tokens": 25,
"total_tokens": 175
}
}Annotations Structure
annotationsarrayArray of annotation objects containing source citations.
Use Cases
News and Current Events
response = client.chat.completions.create(
model="blackbox-search",
messages=[
{"role": "user", "content": "What are today's top technology news?"}
]
)Research and Fact-Checking
response = client.chat.completions.create(
model="blackbox-search",
messages=[
{"role": "user", "content": "What is the current population of Tokyo?"}
]
)Product Information
response = client.chat.completions.create(
model="blackbox-search",
messages=[
{"role": "user", "content": "Compare the latest iPhone and Samsung Galaxy models"}
]
)Market Data
response = client.chat.completions.create(
model="blackbox-search",
messages=[
{"role": "user", "content": "What is the current price of Bitcoin?"}
]
)Best Practices
- Be Specific: Provide clear, specific queries for better search results
- Use System Messages: Set context about the type of information needed
- Handle Citations: Always check for and display source citations to users
- Rate Limiting: Be mindful of API rate limits when making frequent searches
- Verify Information: While web search provides current data, always encourage users to verify critical information
Streaming with Web Search
Web search works seamlessly with streaming responses:
stream = client.chat.completions.create(
model="blackbox-search",
messages=[
{"role": "user", "content": "Latest AI breakthroughs in 2025"}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)Pricing
The blackbox-search model includes web search capabilities at the following rates:
- Input: $0.0002 per 1K tokens
- Output: $0.0005 per 1K tokens
- Web Search: $0.03 for 1 search query (includes X/Twitter search)
See the Inference page for complete pricing information.