Skip to main content

​
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: 
curl --location 'https://api.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?"
    }
  ],
}'

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

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

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