Protocols & endpoints
Native Chat Completions, Responses, Anthropic Messages, Gemini generateContent, and media task endpoints supported by HopsAPI.
HopsAPI forwards requests through each model's native protocol. Discover model capabilities first, then select the advertised endpoint instead of sending every model to OpenAI Chat Completions.
1. Base configuration
| Setting | Value |
|---|---|
| API domain | https://hopsapi.com |
| OpenAI SDK base URL | https://hopsapi.com/v1 |
| Authentication | Authorization: Bearer sk-YOUR_KEY or x-api-key: sk-YOUR_KEY. Gemini native endpoints and GET /v1/models also accept x-goog-api-key and ?key= |
| Capability discovery | GET /v1/models |
/v1/modelsChoose an interface from the response's format, endpoint, and optional responses_endpoint.
LLM endpoints forward application end-to-end request headers to the upstream and return
application end-to-end upstream response headers. For GPT models, prompt-cache hits only require
the session-id header (optional, but recommended on every request): read it from the response
and send it unchanged with every LLM request in the same associated session. A/B testing verified
that session-id alone caches as reliably as all three headers; thread-id and conversation-id
remain optional for conversation tracking. The gateway replaces client Authorization, does not
forward x-api-key, x-goog-api-key, cookies, or ingress/proxy headers such as Forwarded,
Via, X-Real-IP, X-Forwarded-*, and CF-Connecting-IP, generates X-AIToken-Request-Id, and
returns the same value in the compatibility alias X-OneAPI-Request-Id; caller-supplied values
for either request ID header are not forwarded upstream. The gateway owns its X-Session-Id /
X-Call-Id response headers. Expect, hop-by-hop, proxy-authentication, Set-Cookie,
reverse-proxy control headers such as X-Accel-* and X-Sendfile, runtime transport, and
body-integrity headers that cannot survive proxy body processing are not copied. This rule applies
only to LLM endpoints, not media-task endpoints. Do not place secrets in arbitrary headers.
2. Protocol mapping
| Model family / capability | Native format | Request endpoint | Recommended SDK |
|---|---|---|---|
| GPT / Kimi / MiniMax / DeepSeek / Grok, plus Gemini text models that advertise compatibility | OpenAI Chat Completions | POST /v1/chat/completions | openai |
Text model with responses_endpoint | OpenAI Responses | POST /v1/responses | openai |
| Claude | Anthropic Messages | POST /v1/messages | @anthropic-ai/sdk |
| Gemini | Google generateContent | POST /v1/models/{model}:generateContent | @google/genai |
| Video / image models | HopsAPI async media tasks | POST /v1/router/task/create | HTTP client |
Claude is rejected at /v1/chat/completions. Gemini can use this endpoint only when its
model-list item explicitly includes openai-completions in supported_protocols; other models
continue to use native generateContent. /v1/responses accepts only enabled models that advertise
responses_endpoint. Always take protocol support from the model-list item, never from the model
name.
3. Streaming
| Protocol | How to enable it |
|---|---|
| Chat Completions | Send "stream":true in the request body |
| OpenAI Responses | Send "stream":true in the request body |
| Anthropic Messages | Send "stream":true in the request body |
| Gemini | Use :streamGenerateContent |
| Media models | No SSE; create a task and poll its status |
SDK base URLs differ: OpenAI uses https://hopsapi.com/v1; the Anthropic and Google Gen AI examples use the
bare domain https://hopsapi.com. Follow the complete example on each protocol page.