Skip to content

Zapier

A Zap that summarises a form, drafts a reply or sorts a ticket can call your organisation's approved models through the gateway: checked against your policies, charged to the right team and recorded in Request logs, with Claude and Gemini as reachable as OpenAI's models.

What it is

Zapier connects apps with Zaps. Its built-in ChatGPT (OpenAI) app always calls OpenAI with an OpenAI key: it has no setting for another address, so it can't go through the gateway. Two of Zapier's own tools can:

  • Webhooks by Zapier, action Custom Request: sends any HTTP request. A premium app, on Zapier's paid plans.
  • Code by Zapier, Run Python (or Run JavaScript): a few lines of code that call the gateway. Python's requests library is built in.

Both call the gateway's chat endpoint, which reaches every provider your organisation has set up.

The two settings

Setting Value
Address https://<your-gateway>/v1/chat/completions
Key An Authorization header with the value Bearer vk_…: your Vidai key, never a provider's key

The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once. Zapier has no secret store for these steps, so anyone who can edit the Zap can read the key: issue one key for the Zap (or a group of Zaps) and never share the Zap as a template with the key in it.

A minimal call

  1. Add an action step: Webhooks by Zapier, event Custom Request.
  2. Method: POST. URL: https://<your-gateway>/v1/chat/completions.
  3. Data (sent exactly as typed, so keep it valid JSON):

    {
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "Say hello in Dutch."}]
    }
    
  4. Headers: Authorization = Bearer vk_…, and Content-Type = application/json.

  5. Test the step. The answer is in choices, first item, message › content.

Add an action step Code by Zapier, event Run Python. Under Input Data add prompt (mapped from an earlier step) and key (your Vidai key), then:

import requests

r = requests.post(
    "https://<your-gateway>/v1/chat/completions",
    headers={"Authorization": "Bearer " + input_data["key"]},
    json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": input_data["prompt"]}]},
    timeout=60,
)
output = {
    "status": r.status_code,
    "reply": r.json()["choices"][0]["message"]["content"] if r.ok else "",
    "error_code": r.headers.get("x-vidai-error-code", ""),
    "request_id": r.headers.get("x-vidai-request-id", ""),
}

Later steps can map reply, error_code and request_id.

The same step calls Claude or Gemini: put a name such as claude-sonnet-4.5 in model. The gateway translates the request for that provider and the answer back into the OpenAI shape.

Mapping text from an earlier step straight into the Data of a Custom Request breaks the JSON when that text has quotes or line breaks. The Code step builds the JSON for you, so prefer it for free text.

Reading what the gateway did

A Webhooks step doesn't show the response headers. The Code step above returns x-vidai-request-id, the call's reference: paste it into Request logs › Request reference. Or find the call in Request logs with the Key or Model filter under More filters. Cost is never in the answer; it's on the call in Request logs.

Errors

Status Gateway code What to do
401 invalid_api_key, missing_api_key Check the Authorization header: Bearer then the key
403 model_not_allowed, denied_by_routing_rule Use a model your key may call
403 content_guardrail_blocked A guardrail stopped the content
404 model_not_found Check the model name on Models
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded Slow the Zap down

Match on the x-vidai-error-code header (the Code step returns it), not on the message.

Model names

Use the names your organisation has approved, as listed under Models in the Control room. A GET to https://<your-gateway>/v1/models with the same header lists exactly the models your key may call.

What goes through the gateway

In Zapier Through the gateway
Webhooks by Zapier or Code by Zapier calling the gateway Yes, to every provider your organisation has set up
The ChatGPT (OpenAI) app, AI by Zapier and Zapier's other built-in AI features No: they use Zapier's or OpenAI's own connection
Streaming No: a Zap step waits for the whole answer

Check it works in a minute

Test the step in the Zap editor with the prompt "ping". A short answer means the address and key are right. The call shows in Request logs within seconds.

Good to know

  • The gateway must be reachable from the internet: Zapier runs every step in its own cloud.
  • One key per Zap, or per team of Zaps, keeps their spend apart: what the key acts for decides who pays.
  • The gateway's own 429 has no Retry-After header; Zapier's replay of failed runs is the simplest way to try again.
  • A Zap step times out on Zapier's side after a while; keep prompts and answers short, and set max_tokens.