blackbox-api

name: blackbox-api description: > Guides usage of the Blackbox AI API, including OpenAI-compatible endpoints, model routing, web search API, image generation, video generation, function calling, streaming responses, and multi-agent task orchestration via REST API. Activates when working with Blackbox API calls, provider routing, or SDK integration. metadata: author: tradecraft version: "1.0.0"

Blackbox AI API

Blackbox AI provides an OpenAI-compatible REST API for chat completions, image generation, video generation, web search, function calling, and multi-agent task orchestration. Use your existing OpenAI SDK by swapping the base URL.

When to Use This Skill

• Making API calls to Blackbox AI endpoints
• Using OpenAI SDK with Blackbox as a drop-in replacement
• Configuring provider routing for cost, latency, or throughput optimization
• Implementing function/tool calling with Blackbox models
• Generating images (Flux, DALL-E) or videos (Veo) via API
• Using web search model (blackbox-search) with citations
• Building multi-agent workflows via the cloud API
• Handling streaming responses
• Debugging API errors (400-503)

Quick Start

Authentication

Get your API key from app.blackbox.ai/dashboard.

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="your-blackbox-api-key",
    base_url="https://api.blackbox.ai/api/chat/completions"
)

response = client.chat.completions.create(
    model="blackbox-ai",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

JavaScript/TypeScript (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-blackbox-api-key",
  baseURL: "https://api.blackbox.ai/api/chat/completions",
});

const response = await client.chat.completions.create({
  model: "blackbox-ai",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

cURL

curl https://api.blackbox.ai/api/chat/completions \
  -H "Authorization: Bearer your-blackbox-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "blackbox-ai",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Core Concepts

Chat Completions

Endpoint: POST https://api.blackbox.ai/api/chat/completions

Key Parameters:

See references/api-reference.md for the full parameter list.

Web Search

Use model blackbox-search for web-grounded responses with citations:

response = client.chat.completions.create(
    model="blackbox-search",
    messages=[{"role": "user", "content": "What are the latest Next.js features?"}]
)
# Response includes inline citations

Streaming

stream = client.chat.completions.create(
    model="blackbox-ai",
    messages=[{"role": "user", "content": "Write a poem"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Function/Tool Calling

Three-step flow: define tools → send request → handle tool calls.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
}]

# Step 1: Send with tools
response = client.chat.completions.create(
    model="blackbox-ai",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto"
)

# Step 2: Check for tool calls
tool_call = response.choices[0].message.tool_calls[0]

# Step 3: Send tool result back
messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": '{"temperature": "22°C", "condition": "Sunny"}'
})
final = client.chat.completions.create(model="blackbox-ai", messages=messages, tools=tools)

Image Generation

response = client.images.generate(
    model="flux-pro",
    prompt="A serene mountain landscape at sunset",
    n=1
)
image_url = response.data[0].url

Video Generation

response = client.chat.completions.create(
    model="veo-2",
    messages=[{"role": "user", "content": "Generate a 5-second video of ocean waves"}]
)

Provider Routing

Control which AI providers serve your requests:

response = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {
            "sort": "latency",           # Optimize for speed
            "only": ["anthropic"],       # Restrict to Anthropic
            "allow_fallbacks": True,     # Enable fallback providers
            "data_collection": "deny"    # Zero data retention
        }
    }
)

See references/provider-routing.md for all routing options.

Multi-Agent Tasks

Run tasks across multiple AI agents (Claude, Blackbox, Codex, Gemini) in parallel:

import requests

response = requests.post(
    "https://cloud.blackbox.ai/api/tasks",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Add authentication to the Express app",
        "selectedAgents": [
            {"agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5"},
            {"agent": "blackbox", "model": "blackboxai/blackbox-pro"},
            {"agent": "codex", "model": "gpt-5.2-codex"}
        ],
        "repoUrl": "https://github.com/user/repo",
        "selectedBranch": "main"
    }
)
task = response.json()
# Poll GET https://cloud.blackbox.ai/api/tasks/{task_id} for results

Common Patterns

Retry with Fallback Provider

async function chatWithFallback(messages: any[], primaryProvider: string) {
  try {
    return await client.chat.completions.create({
      model: "claude-sonnet-4",
      messages,
      extra_body: { provider: { only: [primaryProvider] } },
    });
  } catch (error) {
    // Fallback to any available provider
    return await client.chat.completions.create({
      model: "claude-sonnet-4",
      messages,
      extra_body: { provider: { ignore: [primaryProvider] } },
    });
  }
}

JSON Mode

response = client.chat.completions.create(
    model="blackbox-ai",
    messages=[{"role": "user", "content": "List 3 colors as JSON"}],
    response_format={"type": "json_object"}
)

Workflows

API Integration Setup

Copy this checklist and track your progress:

API Integration Progress:
- [ ] Step 1: Get API key from dashboard
- [ ] Step 2: Make first test request
- [ ] Step 3: Verify response format
- [ ] Step 4: Add error handling
- [ ] Step 5: Configure provider routing (if needed)
- [ ] Step 6: Enable streaming (if needed)
- [ ] Step 7: Test in production environment

Step 1: Get API key Generate a key at https://www.blackbox.ai/settings/api-keys.

Step 2: Make first test request

curl https://api.blackbox.ai/api/chat/completions \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"blackbox-ai","messages":[{"role":"user","content":"Hello"}]}'

Step 3: Verify response format Confirm the response has choices[0].message.content. If not, check the model name and request format.

Step 4: Add error handling Implement retry logic with exponential backoff for 429/502/503 errors. See references/error-codes.md.

Step 5: Configure provider routing If using multiple providers, set provider in extra_body. See references/provider-routing.md.

Step 6: Enable streaming Set stream: true and handle text/event-stream responses.

Step 7: Test in production Verify rate limits, error handling, and fallback behavior under load.

Provider Routing Configuration

Routing Setup Progress:
- [ ] Step 1: Choose sort strategy (price, latency, throughput)
- [ ] Step 2: Select providers (order, only, or ignore)
- [ ] Step 3: Test with a sample request
- [ ] Step 4: Verify fallback behavior
- [ ] Step 5: Set performance thresholds (if needed)

Step 1: Pick a strategy — price (default), latency, or throughput. See references/provider-routing.md.

Step 2: Configure provider selection. Use order for preferences, only for restrictions, or ignore for exclusions.

Step 3: Send a test request and check the x-provider response header to confirm routing.

Step 4: Test with allow_fallbacks: true (default). Intentionally use an unavailable provider to verify fallback works.

Step 5: Optionally set min_throughput or max_latency thresholds to filter slow providers.

Troubleshooting

See references/error-codes.md for detailed error handling.

References

• See references/api-reference.md for complete endpoint and parameter documentation
• See references/models.md for available models with capabilities
• See references/error-codes.md for error codes and troubleshooting
• See references/provider-routing.md for provider routing configuration