Conecte a DevHub ao seu fluxo.
Crie uma chave no console, escolha um modelo do catálogo e configure sua
ferramenta. Para clientes OpenAI, use
https://api.devhubbrasil.com/v1. Para Claude Code, use a
URL raiz https://api.devhubbrasil.com.
As três informações da conexão
| Campo | Valor de exemplo |
|---|---|
| Base URL · OpenAI | https://api.devhubbrasil.com/v1 |
| API key | dh_SUA_CHAVE |
| Model ID | O ID exato mostrado no catálogo do console |
-
Entre no console e abra Chaves de API. Crie uma
chave com
inferenceemodels:read. - Copie e guarde a chave completa. Novas chaves podem ser consultadas em “Ver chave”; chaves antigas armazenadas apenas como hash não são recuperáveis.
- Abra DevHub Chat. Escolha Automático ou um modelo e faça uma chamada curta.
- Confira a resposta, o consumo e seu saldo antes de configurar uma ferramenta que executa muitas chamadas.
O modelo devhub-echo, quando habilitado, serve para
testar a integração e retorna texto simulado. Para usar IA real,
escolha um modelo de um provedor configurado no catálogo.
Qual Model ID devo usar?
Use o ID exato que aparece no Catálogo de modelos ou em GET /v1/models. O nome exibido no seletor é o rótulo para pessoas; o Model ID é o valor que vai no campo model da chamada. Exemplos que podem aparecer no catálogo: claude-sonnet-5, claude-fable-5.1 e gpt-5.5. A lista do seu console é a referência atual; nomes e disponibilidade podem mudar.
O ID seleciona uma entrada do catálogo DevHub. O gateway decide qual provedor configurado atende a chamada e pode usar uma rota de contingência. Portanto, o nome do catálogo, sozinho, não comprova que a chamada foi atendida pela API oficial da empresa que dá nome ao modelo. Uma chave de API DevHub também não é uma assinatura oficial de Claude, ChatGPT ou outro aplicativo.
Os recursos dependem do modelo e da rota: texto, imagens, áudio, ferramentas e contexto podem variar. Confira as capacidades indicadas no catálogo e faça um teste pequeno antes de usar arquivos ou fluxos longos.
Consultar os IDs disponíveis
curl https://api.devhubbrasil.com/v1/models \ -H "Authorization: Bearer dh_SUA_CHAVE"
Instalar o Gateway no Windows
- Abra a página inicial da DevHub e baixe o instalador do Gateway para Windows. Confira a versão mostrada no botão de download.
- Abra o arquivo baixado e siga as etapas do instalador. Se o Windows exibir um aviso, confira a origem e a assinatura do arquivo. Se não conseguir confirmar o editor, não ignore o bloqueio e fale com o suporte.
- Abra o Gateway, conecte com uma chave criada em Chaves de API e escolha um Model ID disponível no catálogo.
- Faça uma pergunta curta. Se a conexão falhar, confira a URL-base exibida pelo Gateway, a chave, o passe ativo e o Model ID. Não cole a chave em conversas, capturas ou chamados públicos.
O instalador do Gateway é para Windows. No macOS, siga o tutorial de API/Claude Code abaixo; no Linux, escolha o pacote compatível com sua distribuição e arquitetura. Use sempre a versão indicada na página de downloads.
Cline
- Abra a extensão Cline no VS Code e clique nas configurações.
- Em API Provider, selecione OpenAI Compatible.
-
Informe a Base URL terminada em
/v1e sua chavedh_.... - Preencha Model ID com o ID do catálogo DevHub.
- Se a extensão pedir janela de contexto e limite de saída, use valores suportados pelo modelo. Comece com uma tarefa pequena e confirme o consumo.
Ative recursos como imagens ou ferramentas somente para modelos que os suportem. Fluxos de agente dependem também do comportamento do modelo e da versão da extensão.
Referência: configuração oficial do Cline.
Continue
Na configuração YAML do Continue, adicione um modelo com
provider: openai e sua URL em apiBase. O
gateway expõe Chat Completions; configure
useResponsesApi: false quando necessário.
name: DevHub AI
version: 1.0.0
schema: v1
models:
- name: Meu modelo DevHub
provider: openai
model: ID_DO_MODELO
apiBase: https://api.devhubbrasil.com/v1
apiKey: dh_SUA_CHAVE
useResponsesApi: false
Guarde essa configuração em um arquivo local privado ou use o mecanismo de segredos da sua versão do Continue. Não envie a chave para um repositório.
Referência: provedores OpenAI compatíveis no Continue.
Cursor
- Em Settings → Models, procure as opções de chaves de API próprias.
-
Se sua versão oferecer Override OpenAI Base URL,
habilite e informe
https://api.devhubbrasil.com/v1. - Configure a chave DevHub na conexão OpenAI e habilite seu uso.
- Selecione ou adicione um Model ID que corresponda exatamente ao catálogo do gateway.
- Teste um chat curto e confira se a requisição apareceu no histórico DevHub.
A disponibilidade de Base URL personalizada e os recursos que usam a chave dependem da versão e do plano do Cursor. Recursos próprios, modelos vinculados a outros protocolos e Tab Completion podem usar infraestrutura do Cursor. A conexão não substitui a assinatura da ferramenta nem garante suporte a todos os modelos ou recursos.
Referência: documentação oficial do Cursor. Consulte as opções de modelos e API Keys da versão instalada.
Claude Code
Claude Code usa o protocolo Anthropic. A DevHub expõe
/v1/messages; configure a URL raiz, pois
o cliente acrescenta /v1/messages. Não acrescente
/v1 à variável abaixo.
PowerShell:
$env:ANTHROPIC_BASE_URL="https://api.devhubbrasil.com" $env:ANTHROPIC_AUTH_TOKEN="dh_SUA_CHAVE" $env:ANTHROPIC_MODEL="ID_DO_MODELO" claude
macOS / Linux:
export ANTHROPIC_BASE_URL="https://api.devhubbrasil.com" export ANTHROPIC_AUTH_TOKEN="dh_SUA_CHAVE" export ANTHROPIC_MODEL="ID_DO_MODELO" claude
A compatibilidade Anthropic desta instalação é experimental: inclui texto, streaming e tradução de ferramentas (tool use / tool result) para modelos que as suportem. O endpoint de contagem de tokens retorna uma estimativa local. Thinking, ferramentas nativas de servidor, documentos/PDFs e cache de prompt avançado não estão implementados. A configuração acima não equivale a uma certificação de funcionamento integral do agente. A Anthropic não oferece suporte ao uso do Claude Code com modelos não Claude.
Use uma chave específica para esse cliente e faça um teste completo de leitura, edição e execução em um projeto descartável antes de adotar em trabalho real.
Referência: guia oficial de gateways do Claude Code.
Usar a API DevHub no Mac
Este tutorial configura o Claude Code CLI no macOS para enviar chamadas à API DevHub. No momento, esta documentação não oferece um instalador macOS do aplicativo Gateway; a conexão do Mac é feita pelo terminal.
- Entre no console DevHub, crie uma chave de API com permissão de inferência e guarde-a em local privado. Não a envie por mensagem ou captura de tela.
- Abra o app Terminal. Instale o Claude Code usando o instalador oficial da Anthropic e confirme a instalação:
curl -fsSL https://claude.ai/install.sh | bash claude --version
Para testar primeiro nesta janela do Terminal, configure a URL raiz (sem /v1) e a chave. Depois inicie o Claude Code:
export ANTHROPIC_BASE_URL="https://api.devhubbrasil.com" export ANTHROPIC_AUTH_TOKEN="dh_SUA_CHAVE" claude
Dentro do Claude Code, rode /status e confirme que a URL base mostra https://api.devhubbrasil.com. Escolha um Model ID que apareça no catálogo DevHub e teste uma pergunta curta. As variáveis acima valem para essa janela do Terminal.
Para manter a conexão em novas janelas, crie a pasta e abra o arquivo pessoal de configurações:
mkdir -p ~/.claude nano ~/.claude/settings.json
Coloque este conteúdo no arquivo, substituindo dh_SUA_CHAVE pela sua chave privada:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.devhubbrasil.com",
"ANTHROPIC_AUTH_TOKEN": "dh_SUA_CHAVE"
}
}
Salve e feche o editor, depois proteja a chave: chmod 600 ~/.claude/settings.json. Evite salvar a chave em arquivos do projeto ou repositórios. Se usar a extensão do VS Code, configure também as variáveis nas configurações de ambiente da extensão; ela pode não herdar valores do Terminal.
A integração Anthropic com o Claude Code é experimental. Texto, streaming e algumas ferramentas podem funcionar; recursos dependentes de extensões próprias do protocolo podem não estar disponíveis. O uso de modelos que não sejam Claude não é suportado pela Anthropic. Se algo falhar, confira /status, a chave/permissão no console e o ID exato do modelo.
Referências: instalação oficial do Claude Code · conexão oficial com um gateway.
Instalar e abrir o Gateway no Linux
O site disponibiliza o Gateway Linux para amd64/x86-64. Em Ubuntu/Debian, prefira o pacote .deb, que instala as dependências do sistema. Baixe o arquivo pela página inicial e confira se a versão no nome do arquivo corresponde à versão mostrada no botão de download. Abra o Terminal na pasta Downloads:
cd ~/Downloads sudo apt update sudo apt install ./DevHub-Brasil-Gateway-VERSAO-linux.deb
Depois, abra DevHub Brasil Gateway pelo menu de aplicativos. No primeiro uso, conecte com a chave DevHub e selecione o modelo do catálogo. A versão AppImage pode ser iniciada com:
chmod +x ~/Downloads/DevHub-Brasil-Gateway-VERSAO-linux.AppImage ~/Downloads/DevHub-Brasil-Gateway-VERSAO-linux.AppImage
Substitua VERSAO pelo número que aparece no arquivo baixado. Em Ubuntu/Debian, o comando abaixo também funciona se você estiver na pasta Downloads:
sudo apt install ./NOME_EXATO_DO_ARQUIVO.deb
Se o sistema disser “dependência não satisfeita”, atualize a lista com sudo apt update e repita sudo apt install ./arquivo.deb; não use dpkg -i sozinho, pois ele não baixa dependências automaticamente. Se o aplicativo não abrir, envie ao suporte a distribuição/versão do Linux e a mensagem completa do Terminal. O pacote é para sistemas x86-64, não ARM.
SDK OpenAI e HTTP
Use Chat Completions com a Base URL DevHub. Mantenha a chave no servidor ou em variáveis de ambiente de uma aplicação local.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEVHUB_API_KEY"],
base_url="https://api.devhubbrasil.com/v1",
)
response = client.chat.completions.create(
model="ID_DO_MODELO",
messages=[{"role": "user", "content": "Olá"}],
max_tokens=512,
)
print(response.choices[0].message.content)
Streaming:
stream = client.chat.completions.create(
model="ID_DO_MODELO",
messages=[{"role": "user", "content": "Olá"}],
max_tokens=512,
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="")
cURL (macOS/Linux; troque curl por
curl.exe no Windows e adapte a continuação de linhas ao
seu terminal):
curl https://api.devhubbrasil.com/v1/models \
-H "Authorization: Bearer $DEVHUB_API_KEY"
curl https://api.devhubbrasil.com/v1/chat/completions \
-H "Authorization: Bearer $DEVHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"ID_DO_MODELO","messages":[{"role":"user","content":"Olá"}],"max_tokens":512,"stream":true}'
PowerShell, sem depender do escape de aspas do cURL:
$body = @{
model = "ID_DO_MODELO"
messages = @(@{ role = "user"; content = "Olá" })
max_tokens = 512
} | ConvertTo-Json -Depth 10
Invoke-RestMethod -Method Post `
-Uri "https://api.devhubbrasil.com/v1/chat/completions" `
-Headers @{ Authorization = "Bearer $env:DEVHUB_API_KEY" } `
-ContentType "application/json" -Body $body
O gateway também oferece POST /v1/responses em modo de
compatibilidade parcial: texto de entrada, resposta básica e uma
conversão limitada de ferramentas. Esse adaptador não preserva imagens
enviadas nessa rota e não equivale a toda a API Responses da OpenAI.
POST /v1/messages/count_tokens retorna uma estimativa local,
não uma contagem nativa do provedor. Embeddings e endpoints dedicados
de áudio/imagem não estão incluídos nesta referência. Ferramentas e
formatos de saída dependem do modelo e do adaptador configurado.
Passes, limites e respostas de erro
O passe ativo dá acesso à API durante o período contratado, dentro do teto diário de tokens do passe. Ao atingir o teto diário, a API responde 429 e o uso volta no dia seguinte. Não há janela de 5 horas nem limite semanal. O gateway mede o uso para segurança e operação. Continuam valendo os limites técnicos de taxa/contexto, disponibilidade e políticas dos provedores.
| Código | O que verificar |
|---|---|
| 400 / 422 | Campos, conteúdo e parâmetros da chamada. |
| 401 / 403 | Chave válida, permissões e situação da conta. |
| 402 | Passe ativo ou saldo legado disponível. |
| 404 | URL do endpoint e Model ID do catálogo. |
| 429 | Limite de requisições; respeite o cabeçalho Retry-After. |
| 502 / 503 | Disponibilidade do serviço ou provedor. Aguarde e tente com intervalos progressivos. |
Guarde o X-Request-ID retornado para localizar a chamada
no histórico. Interromper streaming pode gerar consumo pelos tokens já
processados. Um modelo simulado não valida os recursos de um provedor
real.
Boas práticas para suas chaves
- Use uma chave por projeto ou ferramenta e conceda só as permissões necessárias.
- Não coloque chaves em sites públicos, capturas de tela, logs ou repositórios.
- Rotacione uma chave exposta e atualize sua configuração. A chave antiga deixa de funcionar imediatamente.
- Use HTTPS no ambiente publicado e consulte o histórico quando houver dúvidas sobre consumo.
Pagamento e liberação automática
Escolha um passe no console e conclua o pagamento pelo meio disponível. O passe é ativado automaticamente assim que o provedor confirma o pagamento. Enquanto o pedido aparecer como pendente ou em revisão, a confirmação ainda não chegou; atualize o status e não faça outro pagamento para o mesmo pedido.
API OpenAI-compatible e Gateway Anthropic
Use uma chave de API DevHub com permissão de inferência. O passe precisa estar ativo. Envie a chave no header indicado abaixo; não exponha chaves no código de páginas públicas.
Acesso por passe ativo: o uso é limitado pelo teto diário de tokens do passe (o valor de cada passe está em /precos e no console). Ao atingir o teto, a API responde 429 e o uso volta no dia seguinte. Passe ativo e chave válida continuam obrigatórios. Contexto e saída máxima por chamada, limites de taxa, disponibilidade e políticas do provedor continuam aplicáveis.
| Método | Endpoint | Uso |
|---|---|---|
| GET | /v1/models | Consultar modelos disponíveis para a sua chave |
| POST | /v1/chat/completions | Conversas no formato OpenAI, com streaming opcional |
| POST | /v1/messages | Gateway no formato Anthropic |
| POST | /v1/messages/count_tokens | Estimativa local de tokens de entrada |
| POST | /v1/responses | Compatibilidade parcial com a API Responses |
Chat Completions
curl https://api.devhubbrasil.com/v1/chat/completions \
-H "Authorization: Bearer dh_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Olá!"}],"max_tokens":512,"stream":false}'A resposta segue o formato choices[0].message.content. Com stream: true, leia os eventos SSE data: até [DONE].
Anthropic Messages
curl https://api.devhubbrasil.com/v1/messages \
-H "x-api-key: dh_SUA_CHAVE" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-5","max_tokens":512,"messages":[{"role":"user","content":"Olá!"}]}'Erros e limites
401: confira a chave. 403: confira permissões e acesso. 429: limite técnico, aguarde a janela indicada. 502/503: falha ou indisponibilidade temporária do upstream. Consulte as seções de integração e erros para detalhes.
Esta é a referência pública de integração. O Swagger interno não é exposto em produção. Todas as chamadas e limites continuam nas rotas existentes.