SDKs and clients

The inference API speaks OpenAI's Chat Completions format, so you do not need a Safeguard SDK. Any client that lets you set the base URL and the API key can call it.

Write the base URL as shown, without a trailing slash.

OpenAI Python SDK

pip install openai

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.safeguard.sh/gpt/v1",
    api_key=os.environ["SAFEGUARD_INFERENCE_KEY"],
)

response = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "List three ways to reduce dependency risk."}],
    max_tokens=300,
)

print(response.choices[0].message.content)
print("served by", response.provider, "for $", response.usage.cost)

provider and usage.cost are Safeguard's additions to OpenAI's response. The Python SDK keeps fields it does not know, so you can read them as attributes, as above.

OpenAI Node.js SDK

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.safeguard.sh/gpt/v1',
  apiKey: process.env.SAFEGUARD_INFERENCE_KEY,
});

const response = await client.chat.completions.create({
  model: 'MODEL_ID',
  messages: [{ role: 'user', content: 'List three ways to reduce dependency risk.' }],
  max_tokens: 300,
});

console.log(response.choices[0].message.content);
console.log('served by', response.provider, 'for $', response.usage.cost);

Run it as an ES module, for example saved as example.mjs. In TypeScript, provider and usage.cost are not in the SDK's types, so read them through a cast such as (response.usage as { cost?: number }).cost.

Configure with environment variables

Both OpenAI SDKs read OPENAI_BASE_URL and OPENAI_API_KEY when you create a client without arguments. That helps with tools built on the SDKs that let you set environment variables but not code:

export OPENAI_BASE_URL="https://api.safeguard.sh/gpt/v1"
export OPENAI_API_KEY="sg-api-..."

Set them only for the process that should use Safeguard, so they do not redirect other tools on the same machine.

curl and other HTTP clients

Any HTTP client works. Send JSON to POST /chat/completions with the two headers:

curl https://api.safeguard.sh/gpt/v1/chat/completions \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}'

For streaming, read the response as server-sent events: one data: line per chunk, ending with data: [DONE]. See Streaming.

Any OpenAI-compatible client

A library or tool that talks to OpenAI's Chat Completions API can work with Safeguard when:

• it lets you set the base URL to https://api.safeguard.sh/gpt/v1 and the API key to your sg-api- key;
• it uses /chat/completions, not OpenAI's other APIs;
• it sends text, one choice at a time.

What the API serves is POST /chat/completions, GET /models, GET /models/{id} and GET /key. Features that need other OpenAI endpoints, such as the Responses API, Assistants, embeddings, images, audio, files, batches or moderations, are not available. We have not tested other frameworks and tools, so check them against Chat completions before you rely on them.

Practical notes

• Keep the key on a server. Never call the API from browser code or a mobile app: anyone who can read the app can read the key. See Key management best practices.
• Newer parameters. Older SDK versions may not accept newer parameters such as stream_options or max_completion_tokens. Upgrade, or pass the field through extra_body in Python.
• Timeouts. The gateway waits up to 120 seconds for a provider, and a stream can run for up to 900 seconds. Give your client a timeout longer than you expect the model to take.
• Automatic retries. If your client retries failed requests on its own, each retry is a separate request, and one that gets an answer is billed. The OpenAI SDKs let you set this with max_retries (Python) and maxRetries (Node.js). See Errors.
• Request ids. Every chat response's id is its request id (gen-…), and the X-Generation-Id response header carries the same id, streamed or not. Log it with your own records. The separate X-Request-Id header is an internal id for Safeguard's audit trail.