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

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

annotationsarray

Array of annotation objects containing source citations.

Annotation Object
typestring

Type of annotation. Currently supports url_citation.

url_citationobject

Citation information for web sources.

URL Citation Object
urlstring

The URL of the cited source.

titlestring

The title of the web page or article.

contentstring

Excerpt or summary of the content from the source (if available).

start_indexinteger

The character index where the citation begins in the message content.

end_indexinteger

The character index where the citation ends in the message content.

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

  1. Be Specific: Provide clear, specific queries for better search results
  2. Use System Messages: Set context about the type of information needed
  3. Handle Citations: Always check for and display source citations to users
  4. Rate Limiting: Be mindful of API rate limits when making frequent searches
  5. Verify Information: While web search provides current data, always encourage users to verify critical information

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.