Integration guide
Text models here speak the protocols your SDK already speaks: Chat Completions, the stateless Responses subset, Anthropic Messages and Google generateContent. The interesting question is what happens to a parameter the target model never declared.
The challenge
The classic failure is not a 500. It is a parameter your gateway accepted, dropped and never mentioned, so the model ran without your temperature, your tool definitions or your response format — and the output looked merely disappointing instead of broken.
01
messages, tools, tool_choice, response_format, max_tokens, temperature and top_p map onto the model's declared fields. Anything else is forwarded to the model's schema and returns 400 when the model does not declare it. Silence is never the answer.
02
On /v1 the body is an OpenAI or Anthropic error object, not the {code, msg, data, request_id} envelope used by /api/v1. Handle both if your product mixes the two surfaces.
03
stream: true returns chat.completion.chunk events terminated by data: [DONE]. Billing still follows measured usage, so an aborted stream is not a free request.
The approach
Change base_url and api_key, replace the model string with a value from GET /v1/models, and run the test suite you already have. Where a 400 comes back for a parameter, that parameter was never supported by the model you picked — which is information the silent version never gave you.
Any OpenAI-compatible client works. Only the base URL and the model value change.
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]Contract
| Field or header | Value or limit |
|---|---|
| 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 |
Swipe horizontally to see all columns.
Integration
Fit
Evidence
/v1/chat/completions, /v1/responses, /v1/messages and /v1beta/models/{model}:generateContent all authenticate with the same key. Authorization: Bearer, x-api-key and x-goog-api-key are each accepted where the SDK expects them.
GET /v1/models returns exactly the identifiers every /v1 and /api/v1 operation accepts, with the publisher in owned_by. Prices come from /api/v1/models, which is account-specific and therefore private.
The compatibility layer reuses the same authentication, rate limits, validation, pricing and hold logic as the native surface. Only the envelope differs.
Before launch
FAQ
Models
Each link opens that model family's own page: inputs, limits, content policy and the current price per unit.
Keep going
Point an existing OpenAI, Anthropic or Google client at SpicyAPI. What maps straight through, what is rejected on purpose, and how text is billed.
