HybridAI docs

Quick start

You need an API key from the HybridAI team (write to hello@hybridai.cloud). Then point any OpenAI-style client at this address:

Keep your key private. If it leaks, ask for it to be revoked and replaced.

Examples

curl

curl https://api.hybridai.cloud/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Say hi in 5 words"}]}' -i

The -i flag prints the response headers, so you can see which route answered.

Python

from openai import OpenAI

client = OpenAI(base_url="https://api.hybridai.cloud/v1", api_key="YOUR_KEY")

reply = client.chat.completions.create(
    model="hybridai-auto",
    messages=[{"role": "user", "content": "Say hi in 5 words"}],
)
print(reply.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hybridai.cloud/v1",
  apiKey: process.env.HYBRIDAI_KEY,
});

const reply = await client.chat.completions.create({
  model: "hybridai-auto",
  messages: [{ role: "user", content: "Say hi in 5 words" }],
});
console.log(reply.choices[0].message.content);

See which route answered (Python)

raw = client.chat.completions.with_raw_response.create(
    model="hybridai-auto",
    messages=[{"role": "user", "content": "Say hi in 5 words"}],
)
print(raw.headers.get("x-hybrid-route"), raw.headers.get("x-hybrid-model"))
reply = raw.parse()
print(reply.choices[0].message.content)

Streaming

Set stream: true and you get standard server-sent events ending with data: [DONE]. Add stream_options: {"include_usage": true} to receive a final usage chunk.

stream = client.chat.completions.create(
    model="hybridai-auto",
    messages=[{"role": "user", "content": "Write a haiku about rain"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

Routing and privacy

Each response includes these headers (the privacy headers are explained in the next section):

Which model answers

For prompts that go to the cloud, HybridAI looks at the task and sets x-hybrid-task. Easy prompts go to a small, quick model first; code and harder prompts go to a bigger one first. If the first choice fails, the other is tried.

The header is not sent on the private route, because only Cloudflare models answer there. This is a simple rule of thumb, not a guarantee that the best model is chosen.

When a key is in redact mode and values were replaced, the bigger model is tried first, because small models often refuse prompts that contain placeholders. x-hybrid-why then includes big-model-first.

The private route uses a stronger Cloudflare model (Gemma 4 26B) first, with smaller Cloudflare models as backups. Replies on that route are limited to 1,024 tokens unless you set max_tokens.

Free models are retired often. When the listed models for Groq or OpenRouter report that they no longer exist, HybridAI looks up the provider's current list and tries a few free text models instead. When that happens, x-hybrid-why includes discovered-model. Discovered models only receive what your key's privacy mode allows.

Private-route replies come from smaller models and use only your messages and max_tokens. Other settings such as temperature or tools are ignored there. On cloud routes, extra settings are passed through to the model.

Privacy modes and receipts

Every API key has a privacy mode. It is set when the key is created; ask for a different one if you need it.

In redact mode a prompt like the first line below reaches the cloud model as the second line. Repeated values get the same placeholder.

You send:  Draft a reply to jane@acme.com about invoice 4417
Cloud sees: Draft a reply to [EMAIL_1] about invoice 4417
You get:   ...a reply addressed to jane@acme.com...

Privacy headers

Saved answers

If you send the same plain prompt again (spacing, capitals and a final question mark do not matter) you may get the saved answer for up to 6 hours. That costs no provider quota. A short plain question that is only worded slightly differently also reuses it: polite openings and closings ("please", "can you tell me"), "the", "is" and "are", plural endings and common spelling variants or typos are ignored (so "wats the colour of sky" matches "What is the color of the sky?"), and the reply is marked cache-hit-similar in x-hybrid-why. Word order, numbers, names and "not" must still be the same, no AI guesses at meaning, and anything with code, links or earlier conversation differences uses the exact match only. Saved answers are kept separately for each privacy mode. They are never used for prompts that look private, requests with tools, a temperature above 0.5, or your own provider keys, and replies that look like refusals are not saved. Send the header x-hybrid-cache: off (or tick the box in the playground) to always get a fresh answer.

Route receipts

The receipt records the route, model, privacy result, how many values were redacted, every provider that received the request (seen_by, including providers that failed) and a SHA-256 hash of your request body. It never contains your prompt or the answer. Keep it as proof of where a request went. Anyone can check that a receipt is genuine and unchanged. In the playground, the receipt appears after each Send and the Verify receipt button checks it. Or use curl:

curl https://api.hybridai.cloud/api/receipt/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt":"PASTE_THE_x-hybrid-receipt_VALUE"}'

The answer is {"valid": true, ...} with the receipt contents, or {"valid": false}. Receipts stop verifying if the service's signing secret is ever changed, so save what you need to keep.

Bring your own key

You can use your own provider account for a single request by adding headers. HybridAI uses your key instead of its shared one, only for that call. It is never stored, logged or cached, so it is not in the usage records or the receipt (the receipt only lists provider names under byok). Your own limits and billing apply to those calls; your key's daily limit at HybridAI still applies.

curl https://api.hybridai.cloud/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-byok-deepseek: YOUR_DEEPSEEK_KEY" \
  -H "x-byok-model: deepseek-chat" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Say hi"}]}'

The response then includes byok:deepseek in x-hybrid-why, and the route is byok-deepseek. To try it without code, use the "Your own provider key" box in the playground. Privacy rules still apply first: a sensitive prompt on a private or edge-only key never leaves Cloudflare, even if you send a key. Send these headers only from your own server code, never from a web page.

If you used x-byok-only and your provider did not answer, the error includes provider_errors with what the provider said (for example "404 model not found"), so you can fix the key, address or model name. For NVIDIA the address is https://integrate.api.nvidia.com/v1 and model names look like meta/llama-3.1-8b-instruct (copy the exact name from the model's page on build.nvidia.com).

Any other OpenAI-compatible provider

If your provider is not listed but speaks the OpenAI request format, an owner-enabled key can send three headers: x-byok-custom-url (the base address, such as https://api.example.com/v1), x-byok-custom-key and x-byok-model (required). The route is byok-custom and the receipt lists the host name. This is off by default; the owner switches it on per key. Addresses must be public https addresses: no IP numbers, ports, query strings or internal names, and redirects are not followed. Providers with their own format, such as Anthropic's native one, are not supported yet.

Key tiers

Each key has a tier that sets its daily request limit: tester 100, beta 300, paid 1,000. A key can also have its own limit and an expiry date. An expired key answers 401 with "This key has expired."

Limits

These limits protect the free quotas behind the service and may change. Daily counters reset at 00:00 UTC.

Redact tool

A separate tool that works without any AI model. Send text, get it back with emails, phone-like numbers, card-like numbers, API keys and password-style values replaced by placeholders. You can use it before sending text to any AI service, then put the real values back afterwards. Nothing you send is stored or logged. It uses the same key as the gateway and allows 500 calls a day per key.

curl https://api.hybridai.cloud/v1/redact -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"text": "Email jane@acme.com or call 9876543210"}'

The answer has four parts: redacted (the safe text), found (how many of each kind), map (placeholder to original, shown only to you) and complete. If complete is false, something that still looks private was left, so do not send the text on without checking it.

{"redacted": "Email [EMAIL_1] or call [PHONE_1]", "found": {"email": 1, "phone": 1}, "map": {"[EMAIL_1]": "jane@acme.com", "[PHONE_1]": "9876543210"}, "complete": true}

To put the originals back into an answer, send the answer and the map to /v1/restore:

curl https://api.hybridai.cloud/v1/restore -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"text": "Reply to [EMAIL_1]", "map": {"[EMAIL_1]": "jane@acme.com"}}'

By default this finds patterns only: emails, phone-like and card-like numbers, API keys (well-known shapes and any long random-looking token), passwords and PIN-style values after words like "password is", and ID numbers (Aadhaar, PAN, US SSN, IBAN).

Add "strict": true to go further. Strict mode also turns spoken digits ("four two double zero") into numbers, hides whatever follows phrases such as "my password is", "my pin is", "the api key is", "my name is", "my address is", "I live at" and "account number is", and hides any spoken run of 4 or more digits. It may hide a few harmless words; that is on purpose. Voice transcripts and text to speech always use strict mode when you ask for redaction. Names and addresses written without such a phrase are still not found.

Dev kit

One-file clients for Python and JavaScript with no installs: chat, streaming chat (chat_stream), hide-and-restore chat (chat_private), redact, voice, approvals, webhooks, agent keys, a saved fallback endpoint and private memory in a few lines, under the MIT licence. See the Dev kit page.

Private memory

Small notes that only your key can read. Notes are encrypted in the gateway with a lock made from your key, which is never stored, so the saved text cannot be read from the database. If you lose or rotate the key, the notes are gone. Try it on the Memory page.

curl -X PUT https://api.hybridai.cloud/v1/memory/favourite-colour -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"value": "green", "expires_in_minutes": 1440}'
curl https://api.hybridai.cloud/v1/memory/favourite-colour -H "Authorization: Bearer YOUR_KEY"
curl https://api.hybridai.cloud/v1/memory -H "Authorization: Bearer YOUR_KEY"
curl -X DELETE https://api.hybridai.cloud/v1/memory/favourite-colour -H "Authorization: Bearer YOUR_KEY"

value can be text or any JSON. Titles are 1 to 64 characters, case sensitive, spaces and most characters are fine (put them in the address URL-encoded, for example my%20note; the dev kit does this for you). A note holds up to 16,384 bytes counted as JSON (a text note is two bytes less, for the quotes), a key holds up to 100 notes and 200 writes a day, and expires_in_minutes (1 to 525,600) is optional. There is no search inside the text of notes, because they are encrypted: you look them up by name or by tag, or list all names with GET /v1/memory. DELETE /v1/memory?all=yes erases every note for your key. To find notes later, add "tags": ["work", "ideas"] (up to 5 short words, saved lower-case) when you save, then call GET /v1/memory?tag=work. Tags are encrypted like the note and are exact matches only; the database holds a scrambled code that only your key can match. Saving a note replaces its value. Its tags are kept when you leave the tags field out, replaced when you send a new list, and cleared with "tags": []. The gateway can see a note while handling your request, like any other call, so do not store anything you could not afford to lose.

Approval inbox

For anything an AI or script should not do without a person saying yes: sending a message, spending money, deleting something. Your code creates a request, you open its link on any device and tap Approve or Reject, and your code reads the answer. Same key as the gateway. Try it on the Approve page.

curl https://api.hybridai.cloud/v1/approvals -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"title": "Send the refund email?", "details": "Refund 40 dollars to order 1182", "expires_in_minutes": 60}'

The answer has an id and a review_url. Open the link yourself or pass it to whoever should decide. Anyone holding the link can decide that one request, once, so treat it like a password. Poll GET /v1/approvals/ID until status is approved, rejected, expired or cancelled. A decided request also carries a signed receipt that the receipt checker accepts. POST /v1/approvals/ID/cancel withdraws a waiting request and GET /v1/approvals lists your latest 20. Titles and details are scanned first: emails, phone numbers, cards and keys are replaced with placeholders such as [EMAIL_1] before anything is stored, and you get the matching map back once. If something private might remain, you get a 422 and nothing is stored. Limits: title 120 characters, details 4,000, 20 new requests per key per day, 30 waiting at a time, expiry 5 minutes to 7 days (default 24 hours). Requests are deleted after 14 days. HybridAI does not send emails or messages, so your code delivers the link.

Webhooks

Instead of polling, your own server can be told when something happens. Today that means approval.decided (a person approved or rejected one of your requests) plus a test ping. The owner switches webhooks on for a key first; without that, the calls below answer 403. HybridAI posts to one https address per key and does not read anything back. Addresses must be https with a real domain name: no IP addresses, no ports, no query strings, no passwords and none of our own domains. Redirects are not followed, there is one attempt with a 5 second limit, and approval answers can always still be read with GET /v1/approvals/ID.

curl -X PUT https://api.hybridai.cloud/v1/webhook -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"url": "https://example.org/hooks/hybridai"}'
curl -X POST https://api.hybridai.cloud/v1/webhook/test -H "Authorization: Bearer YOUR_KEY"
curl https://api.hybridai.cloud/v1/webhook -H "Authorization: Bearer YOUR_KEY"
curl -X POST https://api.hybridai.cloud/v1/webhook/secret -H "Authorization: Bearer YOUR_KEY"
curl -X DELETE https://api.hybridai.cloud/v1/webhook -H "Authorization: Bearer YOUR_KEY"

The first PUT returns a signing secret once (whsec_...); keep it on your server. POST /v1/webhook/secret replaces it. Each delivery is a JSON body {"id", "type", "created", "data"} with the headers x-hybridai-event and x-hybridai-signature: t=UNIX_SECONDS,v1=HEX, where HEX is HMAC-SHA256 of t + "." + raw body using your secret. Check the signature and reject old timestamps (the dev kit has verify_webhook / verifyWebhook). For approval.decided, data is the same object as GET /v1/approvals/ID, receipt included. GET /v1/webhook shows the last delivery result. Test pings are limited to 20 a day.

Saved endpoint (last-resort fallback)

Save your own OpenAI-compatible endpoint once, and HybridAI tries it as the very last step when every free provider has failed, instead of returning an error. It is billed by your own provider, not by HybridAI. The owner must have switched custom endpoints on for your key (the same switch as the x-byok-custom-url headers); without that, the calls below answer 403. Admin keys and agent keys cannot save one.

curl -X PUT https://api.hybridai.cloud/v1/fallback -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"url": "https://api.example.com/v1", "key": "YOUR_PROVIDER_KEY", "model": "gpt-4o-mini"}'
curl https://api.hybridai.cloud/v1/fallback -H "Authorization: Bearer YOUR_KEY"
curl -X POST https://api.hybridai.cloud/v1/fallback/test -H "Authorization: Bearer YOUR_KEY"
curl -X DELETE https://api.hybridai.cloud/v1/fallback -H "Authorization: Bearer YOUR_KEY"

The address must be a public https address (no IP number, port, query string or password; redirects are not followed). Your provider key is stored encrypted with a key made from your HybridAI key, so it can only be opened while your HybridAI key is used, and it is never shown again: GET returns only the host, the model and the last four characters. The test call sends one tiny message ("Say ok.") and is limited to 10 a day; if your provider refuses it, the short error message it gave is shown in error. When the fallback answers, the route is saved-endpoint, the reason own-endpoint-fallback appears in x-hybrid-why, and the answer is never saved as a saved answer. The usual privacy rules still apply first: prompts with private-looking data on a private key stay on Cloudflare and never reach your endpoint, and redact-mode prompts are sent with the values hidden. A request with x-byok-only never uses it. The owner can switch the feature off with DISABLE_FEATURES=fallback.

Output guard

An optional check on the answer, the mirror image of the privacy check on the prompt. When it is on, emails, phone numbers, card numbers, ID numbers, keys and passwords that the model writes are hidden, or the whole answer is held back. Choose a mode: redact replaces each value with a placeholder such as [EMAIL_1]; block replaces the answer with a short notice and sets finish_reason to content_filter. Values you wrote in your own prompt are left alone, and 13 to 19 digit numbers that are not valid card numbers are left alone, but long plain numbers such as a 10 digit id can still be mistaken for a phone number, so use it where that is acceptable.

curl https://api.hybridai.cloud/v1/chat/completions -H "Authorization: Bearer YOUR_KEY" -H "x-output-guard: redact" -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"Write a sample customer record"}]}'

Send x-output-guard: redact or block per request (dev kit: output_guard="redact" / outputGuard: "redact"). The owner can also set a default for a key on the dashboard (the Guard button); the stricter of the two applies, so a request cannot switch off the owner's setting, and agent keys follow the key that made them. Guarded answers are always sent whole (streaming requests still get a stream, but it starts after the answer is checked), are never saved as saved answers, and show x-hybrid-output-guard with what was hidden (names only, never the values). GET /v1/usage shows your key's setting as output_guard. The owner can switch the feature off with DISABLE_FEATURES=outguard.

Agent keys

For scripts and autonomous agents. Give each one its own key so that a runaway loop only locks that key, not your main one. The owner switches agent keys on for your key first; without that, the calls below answer 403. An agent key has its own daily limit (never above yours), an optional expiry, and inherits your privacy mode and tier. Its requests also count against your own daily limit. An agent key cannot make other keys, use custom endpoints or set a webhook.

curl -X POST https://api.hybridai.cloud/v1/agents -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"name": "nightly-scraper", "daily_limit": 50, "burst_per_min": 10, "expires_in_minutes": 1440}'
curl https://api.hybridai.cloud/v1/agents -H "Authorization: Bearer YOUR_KEY"
curl -X POST https://api.hybridai.cloud/v1/agents/ID/unlock -H "Authorization: Bearer YOUR_KEY"
curl -X POST https://api.hybridai.cloud/v1/agents/ID/revoke -H "Authorization: Bearer YOUR_KEY"

The new key is shown once in key. daily_limit defaults to 100 or your own limit if lower. burst_per_min (1 to 120, default 30) is how many requests a minute the agent key may send; one more and it locks itself. It also locks after 5 blocked prompts within 10 minutes. A locked key answers 403 with code: "agent_locked" until you unlock it. You can have 20 active agent keys and make 30 a day. Revoking your own key stops all of its agent keys. GET /v1/agents shows each key's status, today's use and, if locked, why.

Voice

Speech to text and text to speech, running only on Cloudflare's own models. Audio and text are not stored. Same key as the gateway. Try it on the Voice page.

curl https://api.hybridai.cloud/v1/audio/transcriptions -H "Authorization: Bearer YOUR_KEY" -F file=@audio.mp3

The answer is {"text": "..."}. Add -F redact=true to also get a version with emails, phone numbers, cards and keys hidden (with the same found, map and complete fields as the redact tool). Audio can be up to about 3 minutes (3 MB). Add -F language=en if you know the language.

curl https://api.hybridai.cloud/v1/audio/speech -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"input": "Hello from HybridAI", "lang": "en"}' --output hello.mp3

Text can be up to 800 characters. lang can be en, es, fr, zh, jp or kr. The answer is an mp3 file. Add "redact": true and emails, phone numbers, cards and keys are spoken as "email address removed" and so on. If something private might remain, nothing is spoken and you get a 422. Limits per key per day: 20 transcriptions and 40 speech requests. All voice use also shares one small daily allowance across everyone, so it can run out before your own limit does.

Spoken emails are handled too: "jane at the rate gmail dot com" is understood as an email address when you use redact=true. Speech models sometimes write a different word for "rate", and spoken digits are not turned into numbers, so check the complete field.

Your own provider key works for voice too. Send x-byok-groq or x-byok-openai for transcription, or x-byok-openai for speech. Your audio or text then goes to that provider and uses your own quota. If it fails, the shared Cloudflare models answer instead, unless you also send x-byok-only: 1. Keys set to edge-only ignore these headers.

Usage and status

My usage shows how much of today's allowance your key has used, when it expires and your latest requests. Developers can call GET /v1/usage with the same key. Live model status is a public page showing which free models worked in real use over the last week.

Errors

Errors come back as JSON in this shape:

{"error": {"message": "Unauthorized. Send a valid key as 'Authorization: Bearer YOUR_KEY'.", "type": "hybridai_error"}}