Skip to content

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 /health answers 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.