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:

cURL

# 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

annotations · array

Array of annotation objects containing source citations.

Show Annotation Object

type · string

Type of annotation. Currently supports url_citation.

url_citation · object

Citation information for web sources.

Show URL Citation Object

url · string

The URL of the cited source.

title · string

The title of the web page or article.

content · string

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

start_index · integer

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

end_index · integer

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

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.

Related Resources

Chat Completions

Learn about the chat completions API

Chat Models

Explore all available chat models

Sample Usage

See more API usage examples

CLI Web Search

Use web search in BLACKBOX CLI