Resposta direta
O caminho recomendado pelos guias da API compatível com OpenAI vai do contrato HTTP básico até a validação: URL e endpoint, autenticação Bearer, campos essenciais da requisição, catálogo de modelos, streaming, tool calling, clientes HTTP em várias linguagens e os limites da compatibilidade. Cada guia do mapa cobre uma etapa e pode ser lido de forma independente.
Passo 1: entender o contrato
Antes da primeira chamada, vale entender o que a compatibilidade cobre e o que ela não garante:
- O que significa API compativel com OpenAI
- API OpenAI-compatible: o que e compatibilidade real
- Quando separar um guia de quickstart
Passo 2: montar a requisição base
O contrato base tem três peças: a URL com o endpoint, o header de autenticação Bearer e o corpo JSON mínimo:
- Base URL e endpoint de Chat Completions
- Autenticacao Bearer no protocolo OpenAI
- Chat Completions: campos essenciais
Depois da primeira resposta, dois guias ajudam a fechar o contrato: Como comparar contrato e resposta real e Como lidar com campos desconhecidos.
Passo 3: escolher o modelo
Passo 4: validar capacidades
- Streaming SSE em uma API compativel
- Como testar streaming antes de producao
- Tool calling: o que foi verificado
- Como testar tool calling antes de producao
Passo 5: escolher o cliente HTTP
- Exemplo generico com cliente HTTP
- Exemplo Python com requests
- Exemplo JavaScript com fetch
- Exemplo Go com net/http
Passo 6: respeitar os limites
- Limite do protocolo compativel com OpenAI
- Por que nao afirmar suporte a SDK oficial
- Anthropic Messages e Chat Completions: limite da comparacao
Exemplo copiável
Para conferir que você está no contrato certo antes de seguir o mapa, faça uma chamada mínima e observe as três peças (URL com endpoint, header Bearer, corpo JSON):
curl -sS https://api.mandapi.com/v1/chat/completions \
-H "Authorization: Bearer $MANDAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"ping"}]}'
Se essa chamada responder com um objeto de Chat Completions, os guias dos passos 2 a 4 se aplicam diretamente ao seu fluxo.
Como conferir o resultado
Um mapa bem usado termina com uma chamada validada de ponta a ponta: requisição mínima com Bearer, model escolhido a partir do catálogo, resposta lida como Chat Completions e nenhuma afirmação além do comportamento capturado. Se algum passo falhar, volte ao guia específico daquele passo em vez de alterar várias peças ao mesmo tempo.