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:

Parameter	Type	Default	Description
model	string	—	Model ID (e.g., blackbox-ai, gpt-4o, claude-sonnet-4)
messages	array	—	Conversation messages with role and content
temperature	float	1.0	Randomness (0.0–2.0)
max_tokens	integer	—	Max output tokens
top_p	float	1.0	Nucleus sampling (0.0–1.0)
stream	boolean	false	Enable streaming
response_format	object	—	{"type": "json_object"} for JSON mode
tools	array	—	Function/tool definitions
stop	array	—	Stop sequences

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

Error	Cause	Fix
400	Invalid params or CORS	Check request body format
401	Invalid/expired API key	Regenerate key at dashboard
402	Insufficient credits	Add credits to your account
403	Content flagged by moderation	Review input content
408	Request timeout	Reduce prompt size or use streaming
429	Rate limited	Implement exponential backoff
502	Model provider down	Use allow_fallbacks: true
503	No provider matches routing	Relax provider constraints

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