Skip to main content

Integration Guide

Connect to the QuilrAI gateway with your existing SDK. Change the base URL and the API key; keep everything else.

1. Choose Your Endpoint​

Region​

RegionBase URL
Globalhttps://guardrails.quilr.ai
USA (US Central West)https://guardrails-usa-1.quilr.ai
USA (US East)https://guardrails-usa-2.quilr.ai
India 1https://guardrails-india-1.quilr.ai
India 2https://guardrails-india-2.quilr.ai
Japanhttps://guardrails-jp-1.quilr.ai
Europehttps://guardrails-europe-1.quilr.ai

Configuration, keys and limits apply per region: use the regional host your organization uses for every call. The examples below use US East; replace the host with your region's.

API Format​

FormatPathAuth header
OpenAI-compatible/openai_compatible/Authorization: Bearer sk-quilr-xxx
Anthropic/anthropic_messages/x-api-key: sk-quilr-xxx
AWS Bedrock Runtime (boto3)/bedrock-runtime/AWS SigV4 using sk-quilr-xxx
Vertex AI/vertex_ai/Authorization: Bearer sk-quilr-xxx
OpenAI Responses/openai_responses/Authorization: Bearer sk-quilr-xxx
OpenAI Assistants/openai_assistants/Authorization: Bearer sk-quilr-xxx
OpenAI Realtime (wss)/openai_realtime/Authorization: Bearer sk-quilr-xxx
Sarvam (speech and text)/sarvam/Authorization: Bearer sk-quilr-xxx
TypeSafe System One (decision models)/typesafe/Authorization: Bearer sk-quilr-xxx
Mistral AI (OCR, fill-in-the-middle)/mistral/Authorization: Bearer sk-quilr-xxx
xAI (Responses with xAI tools, images, videos, batches)/xai/Authorization: Bearer sk-quilr-xxx
Copilot Studio/copilot_studio/{sk-quilr-xxx}Quilr key in the path
TrueFoundry custom guardrail/sdk/v1/check/truefoundryAuthorization: Bearer sk-quilr-xxx from a quilr_sdk app
Standalone SDK content check/sdk/v1/checkAuthorization: Bearer sk-quilr-xxx from a quilr_sdk app
Standalone SDK token savings/sdk/v1/token-savingsAuthorization: Bearer sk-quilr-xxx from a quilr_sdk app

Combine a region with a path, for example:

https://guardrails-usa-2.quilr.ai/openai_compatible/

Every path, its parameters, the headers the gateway adds and its error codes are in the Inference API reference, with an OpenAPI document you can import into your own API gateway.

Pick the path that matches your SDK, not your provider: every conversational path reaches every conversational provider on the app, natively when the provider speaks that format and by conversion when it does not. See any-to-any formats and the capability matrix.

The standalone SDK paths return content-check results or optimized text and token-savings estimates directly. Use them without a provider or model selection.

sk-quilr-xxx stands for your Quilr key. Copy it from the app's API Integration section (see Applications and Keys). The model you send must be enabled on the app.

2. Code Examples​

Send images and documents​

For a proxied model request, enable the app's attachment protections and the text or Image Risks data types you want to check. Use a model that accepts the files you send. Scanning does not extend the model's file support.

Send file bytes inline rather than a remote URL or provider file ID. The gateway recognizes native inline image/file blocks and supported data URLs embedded in text, including HTML, before converting the request for the selected provider. OCR reads image text; visual Image Risks are separate detections. The file and page limits, unreadable-file actions and scan coverage are described in Attachment scanning.

This OpenAI Chat Completions example sends a PNG and PDF. Encode the original bytes using standard base64; the MIME type describes the content, and the gateway also checks the bytes.

import base64
import os
from pathlib import Path

import requests

def data_url(path, mime):
encoded = base64.b64encode(Path(path).read_bytes()).decode("ascii")
return f"data:{mime};base64,{encoded}"

response = requests.post(
"https://guardrails-usa-2.quilr.ai/openai_compatible/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['QUILR_API_KEY']}"},
json={
"model": os.environ["QUILR_MODEL"],
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Summarize the allowed attachments."},
{"type": "image_url", "image_url": {
"url": data_url("sample.png", "image/png"),
}},
{"type": "file", "file": {
"filename": "sample.pdf",
"file_data": data_url("sample.pdf", "application/pdf"),
}},
],
}],
"stream": False,
},
timeout=60,
)
response.raise_for_status()
print(response.json())

For native Anthropic Messages, the equivalent content blocks use type: "image" or "document" with a base64 source:

{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "<BASE64_IMAGE_BYTES>"
}
}

To inspect an embedded image in text, the message can contain a data URL such as HTML with an inline image. This is discovered for scanning, but it does not guarantee the selected model interprets that text as an image input:

{
"role": "user",
"content": "Inspect <img src=\"data:image/png;base64,<BASE64_IMAGE_BYTES>\">"
}

A bare base64 string in ordinary text is not inferred to be an image. Remote references are not downloaded. Request attachments can be scanned even when the model response streams; generated files in the response are not scanned by this feature.

For a standalone check before your own provider call, use an SDK app key with POST /sdk/v1/check, type: "request" and the same supported content. SDK request text/messages have the same attachment discovery, including embedded data URLs. Unlike a proxy call, your application must inspect the SDK action and forward its sanitized result. See SDK attachment results for coverage, whole-file removal and processed_body.

OpenAI-compatible chat​

from openai import OpenAI

# Point the client to QuilrAI's gateway
client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai_compatible/',
api_key='sk-openai-xxx'
api_key='sk-quilr-xxx'
)

# Everything below stays exactly the same
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)

# Embeddings work too
embedding = client.embeddings.create(
model='text-embedding-3-small',
input='The quick brown fox'
)
print(embedding.data[0].embedding[:5])

Bedrock, Vertex AI and Anthropic through OpenAI-compatible chat​

Keep the OpenAI client and send a provider-native model name. The gateway translates the request to Bedrock Converse, Vertex AI generateContent or Anthropic Messages. See Chat Completions adapters for supported parameters, content, tools and streaming. The same works from every other client format; see any-to-any formats.

App provider: bedrock. Send any selected Bedrock model ID or inference profile ID that supports Converse.

from openai import OpenAI

client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai_compatible/',
api_key='sk-quilr-xxx',
)

response = client.chat.completions.create(
model='amazon.nova-lite-v1:0',
messages=[{'role': 'user', 'content': 'Hello from an OpenAI client.'}],
max_tokens=256,
)
print(response.choices[0].message.content)

Embeddings​

Every embeddings provider (openai, azureopenai, bedrock_embeddings) takes the OpenAI embeddings shape. For Bedrock, the AWS credentials stay on the app's provider and the gateway makes the Bedrock call.

from openai import OpenAI

client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai_compatible/',
api_key='sk-quilr-xxx',
)

# Same call for OpenAI, Azure OpenAI, or AWS Bedrock embeddings providers.
# Use a model name enabled on your app
# (e.g. 'text-embedding-3-small', 'amazon.titan-embed-text-v2:0',
# 'cohere.embed-english-v3').
embedding = client.embeddings.create(
model='amazon.titan-embed-text-v2:0',
input='The quick brown fox',
)
print(embedding.data[0].embedding[:5])

Rerank​

Every rerank provider takes the Cohere-compatible shape. Point the Cohere SDK at https://guardrails-usa-2.quilr.ai/rerank; /rerank/rerank, /rerank/v1/rerank and /rerank/v2/rerank all work.

import cohere

co = cohere.ClientV2(
base_url='https://guardrails-usa-2.quilr.ai/rerank',
api_key='co-xxx',
api_key='sk-quilr-xxx',
)

# Same call for any configured rerank provider.
result = co.rerank(
model='rerank-english-v3.0',
query='What is the capital of France?',
documents=[
'Paris is the capital of France.',
'Berlin is the capital of Germany.',
'The Eiffel Tower is in Paris.',
],
top_n=2,
)
for r in result.results:
print(r.index, r.relevance_score)

Mistral and xAI APIs​

Mistral's and xAI's own APIs have their own routes, in each vendor's own format: /mistral/v1/ocr, /mistral/v1/fim/completions, /xai/v1/responses, /xai/v1/images/generations and more. Their chat goes through the OpenAI-compatible path like any provider. See Vendor routes.

from openai import OpenAI

client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/xai/v1',
api_key='xai-xxx',
api_key='sk-quilr-xxx',
)

# xAI's Responses API, including xAI's server-side tools
response = client.responses.create(
model='grok-4.20-0309-non-reasoning',
input='What is new at xAI?',
tools=[{'type': 'web_search'}],
)
print(response.output_text)

Decision models​

Decision models answer typed questions with probabilities: Microsoft-Decision-1 deployments on an Azure provider, and TypeSafe Jev models on a TypeSafe provider. Send the OpenAI Decisions format to /openai_compatible/v1/decisions or the System One format to /typesafe/v1/systemone; model is your Azure deployment name or a Jev model such as jev-latest. See Decision models.

import requests

response = requests.post(
'https://guardrails-usa-2.quilr.ai/openai_compatible/v1/decisions',
headers={'Authorization': 'Bearer sk-quilr-xxx'},
json={
'model': 'decision-1',
'input': 'I was charged twice for my plan.',
'questions': [
{'type': 'predicate', 'name': 'billing', 'instructions': 'Is this about billing?'},
{'type': 'choice', 'name': 'team', 'instructions': 'Which team should handle it?',
'choices': [{'value': 'billing'}, {'value': 'engineering'}]},
],
},
)
for answer in response.json()['answers']:
print(answer)

Anthropic​

import anthropic

# Point the client to QuilrAI's gateway
client = anthropic.Anthropic(
# uses default base URL
base_url='https://guardrails-usa-2.quilr.ai/anthropic_messages/',
api_key='sk-ant-xxx'
api_key='sk-quilr-xxx'
)

# Everything below stays exactly the same
message = client.messages.create(
model='claude-sonnet-4-20250514',
max_tokens=1024,
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(message.content[0].text)

Vertex AI​

Pass the Quilr key as a Bearer token. project and location should match the GCP project ID and region on the app's vertex_ai provider.

from google import genai
from google.genai.types import HttpOptions
from google.oauth2 import service_account
from google.auth import credentials as auth_credentials


class APIKeyCredentials(auth_credentials.Credentials):
"""Pass the QuilrAI API key as a Bearer token."""

def __init__(self, api_key):
super().__init__()
self.api_key = api_key
self.token = api_key

def refresh(self, request):
self.token = self.api_key

@property
def valid(self):
return True


credentials = service_account.Credentials.from_service_account_file(
'service.json',
scopes=['https://www.googleapis.com/auth/cloud-platform']
)
credentials = APIKeyCredentials('sk-quilr-xxx')

client = genai.Client(
vertexai=True,
project='your-gcp-project',
location='us-central1',
credentials=credentials,
# uses default Vertex AI endpoint
http_options=HttpOptions(base_url='https://guardrails-usa-2.quilr.ai/vertex_ai'),
)

# Everything below stays exactly the same
response = client.models.generate_content(
model='gemini-2.5-flash',
contents='Hello!'
)
print(response.text)

AWS Bedrock Runtime - boto3​

App provider: bedrock. Point the Bedrock Runtime client at the gateway and sign with the Quilr key.

import boto3
from botocore.config import Config

QUILR_KEY = "sk-quilr-xxx"

bedrock = boto3.client(
"bedrock-runtime",
region_name="us-east-1",
endpoint_url="https://guardrails-usa-2.quilr.ai/bedrock-runtime",
aws_access_key_id="AKIA...",
aws_access_key_id=QUILR_KEY,
aws_secret_access_key="aws-secret",
aws_secret_access_key=QUILR_KEY,
config=Config(read_timeout=300),
)

response = bedrock.converse(
modelId="amazon.nova-lite-v1:0",
messages=[
{
"role": "user",
"content": [{"text": "Hello!"}],
}
],
inferenceConfig={"maxTokens": 256},
)

print(response["output"]["message"]["content"][0]["text"])

converse, converse_stream and invoke_model are supported. See AWS Bedrock - boto3 Runtime for coverage and troubleshooting.

OpenAI Responses​

App provider: openai, azureopenai, openai_responses or openai_responses_azure natively, or any other conversational provider through any-to-any formats (for example Claude on Bedrock). For Azure, send the deployment name as model.

from openai import OpenAI

# Point the client to QuilrAI's gateway
client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai_responses/v1',
api_key='sk-openai-xxx'
api_key='sk-quilr-xxx'
)

# Everything below stays exactly the same
response = client.responses.create(
model='gpt-5',
input=[{'role': 'user', 'content': 'Hello!'}],
instructions='You are a helpful assistant.'
)
print(response.output_text)

OpenAI Realtime​

App provider: openai_realtime or openai_realtime_azure. Sessions are a websocket passthrough; guardrails are not yet applied to live events (see Realtime API).

import asyncio
from openai import AsyncOpenAI


async def main():
client = AsyncOpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai/v1',
api_key='sk-openai-xxx',
api_key='sk-quilr-xxx',
)

# Everything below stays exactly the same
async with client.realtime.connect(model='gpt-realtime') as conn:
await conn.session.update(session={'modalities': ['text']})
await conn.conversation.item.create(item={
'type': 'message',
'role': 'user',
'content': [{'type': 'input_text', 'text': 'Hello!'}],
})
await conn.response.create()
async for event in conn:
if event.type == 'response.output_text.delta':
print(event.delta, end='', flush=True)
elif event.type == 'response.done':
break


asyncio.run(main())

Sarvam speech and text​

App provider: sarvam. Chat goes through the OpenAI-compatible client:

from openai import OpenAI

client = OpenAI(
base_url='https://guardrails-usa-2.quilr.ai/openai_compatible/',
api_key='sk-quilr-xxx'
)

resp = client.chat.completions.create(
model='sarvam-105b',
messages=[{'role': 'user', 'content': 'Hello!'}]
)

Speech uses the OpenAI audio methods. voice is a Sarvam speaker and language_code is required:

speech = client.audio.speech.create(
model='bulbul:v3',
input='Hello world',
voice='shubh',
response_format='wav',
extra_body={'language_code': 'en-IN'}
)
with open('hello.wav', 'wb') as out:
out.write(speech.content)

with open('audio.wav', 'rb') as audio:
transcript = client.audio.transcriptions.create(model='saaras:v4', file=audio)

The native /sarvam/ routes take Sarvam's own fields. Translation, transliteration and language detection are only here:

# Speech synthesis - returns {"request_id": "...", "audios": ["<base64>"]}
curl https://guardrails-usa-2.quilr.ai/sarvam/text-to-speech \
-H "Authorization: Bearer sk-quilr-xxx" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello world",
"model": "bulbul:v3",
"speaker": "shubh",
"language_code": "en-IN",
"output_audio_codec": "wav"
}'

# Transcription - multipart, one file field
curl https://guardrails-usa-2.quilr.ai/sarvam/speech-to-text \
-H "Authorization: Bearer sk-quilr-xxx" \
-F file=@audio.wav \
-F model=saaras:v4 \
-F mode=transcribe \
-F language_code=hi-IN

# Text translation
curl https://guardrails-usa-2.quilr.ai/sarvam/translate \
-H "Authorization: Bearer sk-quilr-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "mayura:v1",
"input": "Hello",
"source_language_code": "en-IN",
"target_language_code": "hi-IN"
}'

See Sarvam Speech and Text for every endpoint, model and limit.

Microsoft Copilot Studio​

App provider: copilot_studio. Register this endpoint base in Power Platform admin center:

https://guardrails-usa-2.quilr.ai/copilot_studio/sk-quilr-xxx

See Copilot Studio for setup.

TrueFoundry custom guardrails​

Add QuilrAI as a TrueFoundry custom input/output guardrail: URL = your regional base plus /sdk/v1/check/truefoundry, mode Mutate, Custom Bearer Auth with a Quilr key from a quilr_sdk app. See TrueFoundry Integration.

3. Optional Headers​

HeaderPurpose
X-User-EmailIdentifies the end user behind the request. See Identity Aware.
X-Conversation-IdGroups related requests into one conversation. See Conversation Grouping.
X-Provider-Name / X-Provider-LabelSelects a provider on apps with several (see section 5).
X-Prompt-VariablesSupplies {{variable}} values for stored prompts. See Prompt Store.

4. Using Routing Groups​

Send a routing group name as model. The gateway load-balances and fails over across the group's models.

response = client.chat.completions.create(
model='Group1', # your routing group name
messages=[{'role': 'user', 'content': 'Hello!'}]
)

5. Selecting a Provider​

On an app with several providers, pick one per request by provider type or label. The fields for each endpoint are in Selecting a Provider on Multi-Provider Apps.

# Responses: pick a specific additional provider
response = client.responses.create(
model='gpt-5',
input=[{'role': 'user', 'content': 'Hello!'}],
extra_body={'provider_label': 'azure-westus'},
)
# Realtime: select via query string (headers also work)
async with client.realtime.connect(
model='gpt-realtime',
extra_query={'provider_label': 'azure-westus'},
) as conn:
...