Guia de integração
Os modelos de texto aqui falam os protocolos que o seu SDK já fala: Chat Completions, o subconjunto sem estado de Responses, Anthropic Messages e Google generateContent. O interessante é o que acontece com um parâmetro que o modelo de destino nunca declarou.
O desafio
A falha clássica não é um 500. É um parâmetro que o seu gateway aceitou, descartou e nunca mencionou: o modelo rodou sem a sua temperature, sem as definições de ferramentas ou sem o formato de resposta, e a saída pareceu só decepcionante em vez de quebrada.
01
messages, tools, tool_choice, response_format, max_tokens, temperature e top_p mapeiam para os campos declarados do modelo. O resto é repassado ao esquema do modelo e devolve 400 quando ele não declara. Silêncio nunca é resposta.
02
Em /v1 o corpo é um objeto de erro do OpenAI ou da Anthropic, não o envelope {code, msg, data, request_id} de /api/v1. Se o seu produto mistura as duas superfícies, trate as duas formas.
03
stream: true devolve eventos chat.completion.chunk encerrados por data: [DONE]. A cobrança continua seguindo o uso medido, então um fluxo interrompido não é uma requisição grátis.
A abordagem
Mude base_url e api_key, troque a string de modelo por um valor de GET /v1/models e rode a bateria de testes que você já tem. Se um parâmetro devolver 400, o modelo escolhido nunca o suportou — informação que a versão silenciosa nunca dava.
Qualquer cliente compatível com OpenAI serve. Mudam só a URL base e o valor model.
POST /v1/chat/completions
from openai import OpenAI
client = OpenAI(
base_url="https://api.spicyapi.ai/v1",
api_key=os.environ["SPICY_API_KEY"],
)
stream = client.chat.completions.create(
model="<publisher>/<model>/chat", # exact value from GET /v1/models
messages=[{"role": "user", "content": "Summarise these notes in three bullets."}],
temperature=0.7,
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")text/event-stream
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"- "}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Ships"}}]}
data: [DONE]Contrato
| Campo ou cabeçalho | Valor ou limite |
|---|---|
| POST /v1/chat/completions | chat.completion · SSE with stream: true |
| GET /v1/models | every callable model value |
| Authorization: Bearer · x-api-key · x-goog-api-key | accepted on /v1 |
| undeclared parameter | 400 · never silently dropped |
Deslize horizontalmente para ver todas as colunas.
Integração
Adequação
Evidências
/v1/chat/completions, /v1/responses, /v1/messages e /v1beta/models/{model}:generateContent autenticam com a mesma chave. Authorization: Bearer, x-api-key e x-goog-api-key são aceitos onde o SDK os espera.
GET /v1/models devolve exatamente os identificadores que toda operação /v1 e /api/v1 aceita, com o criador em owned_by. Os preços vêm de /api/v1/models, específico da conta e portanto privado.
A camada de compatibilidade usa a mesma autenticação, os mesmos limites de taxa, a mesma validação, o mesmo cálculo de preço e a mesma reserva da superfície nativa. Só o envelope muda.
Antes de lançar
Perguntas frequentes
Modelos
Cada link abre a página daquela família de modelos: entradas, limites, política de conteúdo e o preço atual por unidade.
A seguir
Aponte um cliente OpenAI, Anthropic ou Google para a SpicyAPI. O que passa direto, o que é recusado de propósito e como o texto é cobrado.
