Quickstart with curl¶
One request, no SDK: the fastest way to prove the address and the key are right, and to see what the gateway adds to an answer. Everything an SDK does later is this request with nicer clothes.
What it is¶
Plain HTTP to the gateway. The gateway accepts three request formats (OpenAI, Anthropic and Gemini); curl can send any of them.
The two settings¶
| Setting | Value |
|---|---|
| Base address | https://<your-gateway> (the OpenAI and Anthropic paths start /v1, Gemini's /v1beta) |
| Key | Your Vidai key (starts vk_) in Authorization: Bearer, x-api-key or x-goog-api-key: all three are accepted |
The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. Issue a key in Keys › Issue a key; its secret is shown once.
export VIDAI_GATEWAY="https://<your-gateway>"
export VIDAI_KEY="vk_…"
Send one key header only: two different keys in two headers are refused (conflicting_auth_headers).
A minimal call¶
curl -i "$VIDAI_GATEWAY/v1/chat/completions" \
-H "Authorization: Bearer $VIDAI_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello in Dutch."}]}'
curl -i "$VIDAI_GATEWAY/v1/messages" \
-H "x-api-key: $VIDAI_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model": "claude-sonnet-4.5", "max_tokens": 200, "messages": [{"role": "user", "content": "Say hello in Dutch."}]}'
curl -i "$VIDAI_GATEWAY/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $VIDAI_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Say hello in Dutch."}]}]}'
Any of the three can name any approved model: send "model": "claude-sonnet-4.5" in the OpenAI format and the
gateway translates the call for Anthropic and the answer back into the OpenAI shape.
Streaming¶
curl -N "$VIDAI_GATEWAY/v1/chat/completions" \
-H "Authorization: Bearer $VIDAI_KEY" -H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "stream": true, "stream_options": {"include_usage": true},
"messages": [{"role": "user", "content": "Count to five."}]}'
curl -N "$VIDAI_GATEWAY/v1/messages" \
-H "x-api-key: $VIDAI_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" \
-d '{"model": "claude-sonnet-4.5", "max_tokens": 200, "stream": true,
"messages": [{"role": "user", "content": "Count to five."}]}'
curl -N "$VIDAI_GATEWAY/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $VIDAI_KEY" -H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Count to five."}]}]}'
A translated stream arrives in the format you asked in. If something fails after the stream has started, the connection closes.
Tool calls¶
Send tools in your format's own shape; the gateway carries tool definitions, tool calls and tool results across
providers. See Chat Completions, Messages and
generateContent for the shapes.
Reading what the gateway did¶
curl -i prints the headers. Look for:
x-vidai-request-id: 01J… the call's reference: quote it, or paste it into Request logs › Request reference
x-vidai-model: gpt-4o-mini the model that answered
x-vidai-translation-profile: default
and, when they apply, x-vidai-requested-model, x-vidai-routing-rule, x-vidai-provider-key, x-vidai-fallback,
x-vidai-adapted and x-vidai-pseudonymised. Every header is explained in
Headers and errors.
Errors¶
A refusal carries x-vidai-error-code (match on it), x-vidai-stage and a body in the format you called with:
HTTP/1.1 401 Unauthorized
x-vidai-error-code: invalid_api_key
x-vidai-stage: auth
{"error":{"code":"invalid_api_key","message":"…","param":null,"type":"authentication_error"}}
What goes through the gateway¶
Every path in Endpoints at a glance: chat, messages and generateContent translate across
providers; the rest (embeddings, audio, images, files, batches and more) go only to a provider of the same format.
The gateway answers GET /v1/models, GET /v1beta/models and GET /health itself.
Model names¶
curl -s "$VIDAI_GATEWAY/v1/models" -H "Authorization: Bearer $VIDAI_KEY"
lists exactly the models your key may call. See Model names.
Check it works in a minute¶
curl -s -o /dev/null -w "%{http_code}\n" "$VIDAI_GATEWAY/v1/models" -H "Authorization: Bearer $VIDAI_KEY"
200 means the address and the key are right (401 a wrong key). Then send the minimal call above; it shows in
Request logs within seconds.
Good to know¶
GET /healthanswers without a key, to check the gateway is up.- Cost is never in the answer: find the call in Request logs.
- Add
-H "x-request-id: <your id>"to keep your own reference with the call, and-H "x-trace: true"to keep this call's content in Request logs.