API do BlackHub

Comece em 1 minuto

1. Assine um plano Dev (abaixo). Ele libera a API e os tokens.
2. Crie uma chave em Minha conta → Plano Dev e API. Ela começa com bh_live_ e aparece uma vez só.
3. Use o endereço https://blackhub.pro/api/v1 com o cabeçalho Authorization: Bearer sua_chave.

Exemplos

curl

curl https://blackhub.pro/api/v1/chat/completions \
  -H "Authorization: Bearer $BLACKHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [
      {"role": "system", "content": "Você é um engenheiro sênior."},
      {"role": "user", "content": "Escreva uma função em PHP que valide CPF."}
    ]
  }'

Python (SDK da OpenAI)

from openai import OpenAI

client = OpenAI(base_url="https://blackhub.pro/api/v1", api_key="bh_live_...")

stream = client.chat.completions.create(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Refatore esta função: ..."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

PHP

<?php
$ch = curl_init('https://blackhub.pro/api/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BLACKHUB_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'claude-opus-5-5',
        'messages' => [['role' => 'user', 'content' => 'Explique este erro: ...']],
    ]),
]);
$resp = json_decode(curl_exec($ch), true);
echo $resp['choices'][0]['message']['content'];

JavaScript

const resp = await fetch('https://blackhub.pro/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLACKHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-opus-5-5',
    messages: [{ role: 'user', content: 'Escreva testes para: ...' }],
  }),
});
const data = await resp.json();
console.log(data.choices[0].message.content);

No seu editor

Em qualquer ferramenta que aceite "OpenAI compatível" ou "OpenAI base URL", preencha:

• Cursor: Settings → Models → OpenAI API Key, ative "Override OpenAI Base URL" e adicione o modelo pelo nome.
• Cline / Roo: API Provider "OpenAI Compatible", com a Base URL, a chave e o Model ID.
• Continue: no config, provider "openai" com apiBase, apiKey e model.

O modo agente (que lê e edita arquivos e roda comandos) funciona nos três, porque a API aceita chamada de ferramentas.

Ferramentas (modo agente)

A API aceita chamada de ferramentas (function calling) no padrão da OpenAI. Nos editores não há nada a configurar; no seu código, funciona assim:

• Envie as ferramentas em tools: até 128, cada uma com "type": "function" e function com name, description e parameters (JSON Schema). Opcionais: tool_choice ("auto", "none", "required" ou {"type": "function", "function": {"name": "…"}}) e parallel_tool_calls.
• Quando o modelo quer usar uma, a resposta vem com finish_reason: "tool_calls" e message.tool_calls (id, nome e argumentos em JSON). No streaming, as partes chegam em delta.tool_calls, como na OpenAI.
• Devolva o resultado mandando de novo a mensagem do assistente com os tool_calls e, para cada chamada, uma mensagem {"role": "tool", "tool_call_id": "…", "content": "…"}. O modelo responde ou pede outra ferramenta.
• Tokens: as definições das ferramentas, os argumentos e os resultados contam como o resto da conversa.
• Escolha pelo nome em tool_choice depende do modelo: alguns usam a ferramenta que acharem melhor.

Python (laço de agente)

import json
from openai import OpenAI

client = OpenAI(base_url='https://blackhub.pro/api/v1', api_key='bh_live_...')
tools = [{
    'type': 'function',
    'function': {
        'name': 'ler_arquivo',
        'description': 'Lê um arquivo do projeto',
        'parameters': {
            'type': 'object',
            'properties': {'caminho': {'type': 'string'}},
            'required': ['caminho'],
        },
    },
}]
messages = [{'role': 'user', 'content': 'O que faz o arquivo src/app.php?'}]

while True:
    resp = client.chat.completions.create(model='claude-opus-5-5', messages=messages, tools=tools)
    msg = resp.choices[0].message
    if resp.choices[0].finish_reason != 'tool_calls':
        break
    messages.append(msg)  # a mensagem do assistente, com os tool_calls
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        messages.append({'role': 'tool', 'tool_call_id': call.id, 'content': open(args['caminho']).read()})

print(msg.content)

Modelos do plano

Cada token de entrada ou de saída conta 1 para 1 em qualquer um destes modelos. Com a sua chave de uma IA, os modelos dela (inclusive os de fora desta lista) não gastam tokens. A lista atualizada sai em GET https://blackhub.pro/api/v1/models.

Planos Dev

Tokens de texto por 30 dias, para a API e o Estúdio Dev, separados dos créditos do site (que ficam para as imagens). Renovar antes de acabar soma os tokens que sobraram.

Regras e limites

• Contagem: entrada + saída de cada pedido, no número que a IA informa. Pedido que não gera nada não conta.
• Acabaram os tokens: a API responde 402 tokens_esgotados até renovar ou trocar de plano. Os créditos do site não são usados.
• Limite: 60 pedidos por minuto por chave e até ~300 mil tokens de entrada por pedido.
• Streaming: "stream": true no padrão da OpenAI (com stream_options.include_usage, a última parte traz o uso).
• Parâmetros aceitos: model, messages (com texto e imagem), stream, max_tokens, temperature, top_p, stop, seed, tools, tool_choice e parallel_tool_calls.
• Privacidade: as suas chaves da API ficam guardadas só como impressão (hash), e as chaves próprias das IAs ficam criptografadas.

Erros