Choose by contract, not by brand name
Section titled “Choose by contract, not by brand name”The gateway exposes native LLM protocols. Use /v1/models for public model IDs, protocol labels and declared capabilities; it does not provide an endpoint list. Before choosing an SDK or changing its base URL, consult the selected model’s current guide for supported endpoints and request parameters. Do not infer endpoint compatibility from the protocol label alone. Switching the model string does not translate a Chat Completions request into a Claude or Gemini request.
| Protocol | Request endpoint | Authentication | Input shape |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions | Authorization: Bearer API_KEY | model, messages |
| OpenAI Responses | /v1/responses | Authorization: Bearer API_KEY | model, input |
| Claude Messages | /v1/messages | x-api-key: API_KEY, anthropic-version: 2023-06-01 | model, messages, max_tokens |
| Gemini content | /v1beta/models/{model}:generateContent | x-goog-api-key: API_KEY | contents with parts |
These are gateway endpoint families, not a claim that every model supports every row. Use the platform origin shown in the model’s request example; do not send the platform key to an upstream provider’s hostname.
Map both sides of an integration
Section titled “Map both sides of an integration”Chat Completions commonly returns text under choices[].message, Claude returns content blocks, and Gemini returns candidates containing parts. Responses uses output items. Preserve the native usage object and finish/stop information; do not force all of these into a media task schema.
Tool calls are structured instructions for your application, not proof that a tool executed. Keep tool execution behind your own validation and permission boundary. Enable tools, structured outputs, images or reasoning only where the exact route declares support. An omitted capability is not an affirmative guarantee.
Migrate one layer at a time
Section titled “Migrate one layer at a time”- Record the current endpoint, model ID, role layout, output-limit field and parser.
- Select an active target route and inspect its model guide.
- Translate the request and response adapters together. Keep optional parameters out of the first request.
- Test a small approved sample including empty output, refusal, truncation and errors.
- Compare task quality and total usage using the evaluation worksheet, before changing production traffic.
SDKs may append /v1 themselves, retry automatically or default to another endpoint. Inspect the final URL and retry configuration without logging the key. A successful SDK initialization does not test protocol compatibility.
Where to continue
Section titled “Where to continue”Use first request for a minimal Chat Completions example, Claude Opus 5.5 for Messages, or Gemini 3.6 Flash for native content requests. Check current availability before running any example. Streaming has separate event formats; follow the streaming guide.