# Blackbox API

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

- Skill: `webrenew/blackbox-api` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add webrenew/blackbox-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/blackbox-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/blackbox-api

---


# 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](https://app.blackbox.ai/dashboard).

### Python (OpenAI SDK)

```python
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)

```typescript
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

```bash
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:

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

### Streaming

```python
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.

```python
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

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

### Video Generation

```python
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:

```python
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:

```python
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

```typescript
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

```python
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**
```bash
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