Skip to Content
ZeroLeaksDocs

Chat completions

Obtain a classification through OpenAI-compatible chat clients, including JSON and streaming.

POST https://api.zeroleaks.ai/v1/chat/completions

Shield uses the chat protocol to return a classification. It does not generate conversational answers or tool calls.

import OpenAI from "openai";

const shield = new OpenAI({
  apiKey: process.env.ZEROLEAKS_API_KEY,
  baseURL: "https://api.zeroleaks.ai/v1",
});

const response = await shield.chat.completions.create({
  model: "shield",
  messages: [{ role: "user", content: "Text to inspect" }],
});

const verdict = response.choices[0].message.content;

Request body

ParameterDescription
modelOne of the four Shield model IDs. Defaults to shield.
messages1 to 256 messages. Only the final user or tool message is scored.
response_formattext or json_object.
streamBoolean. Defaults to false.
stream_options.include_usageSupported when stream is true.
temperatureOnly 0, if supplied.
nOnly 1, if supplied.
max_tokens, max_completion_tokensPositive integers, accepted for client compatibility. They do not truncate the verdict.

Messages

The final message must have role user or tool. Its text is the entire classification input. Shield excludes earlier messages from the scored text and does not follow them as classifier instructions. To classify a whole transcript, format that transcript as text in the final message or use moderations.

content can be a string or an array of { "type": "text", "text": "..." } parts. Shield joins text parts with newlines.

Response

The response is a chat.completion object with one assistant choice and finish_reason: "stop". Its top-level shield object contains flagged, score, model_score, rules, and coverage.

An unflagged input returns:

safe

A flagged input returns:

unsafe
prompt_injection

These are protocol labels. safe means the classifier did not flag the scored text. Review coverage before treating it as a check of the full input.

JSON mode

Set response_format: { type: "json_object" }. The assistant message's content is a JSON string:

const response = await shield.chat.completions.create({
  model: "shield",
  messages: [{ role: "user", content: "Text to inspect" }],
  response_format: { type: "json_object" },
});

const verdict = JSON.parse(response.choices[0].message.content ?? "null");
// { flagged: false, score: 0.03, category: null }
// or { flagged: true, score: 0.93, category: "prompt_injection" }

The scores above are examples.

Streaming

const stream = await shield.chat.completions.create({
  model: "shield",
  messages: [{ role: "user", content: "Text to inspect" }],
  stream: true,
  stream_options: { include_usage: true },
});

let verdict = "";
for await (const chunk of stream) {
  verdict += chunk.choices[0]?.delta.content ?? "";
}

The server classifies first, then emits OpenAI-compatible server-sent events: a content chunk with Shield metadata, a finish chunk, an optional usage chunk, and data: [DONE]. Streaming does not progressively classify an unfinished input. Inference failures return an HTTP error before a verdict stream begins.

usage.prompt_tokens reports input token accounting. completion_tokens is zero because the classifier does not generate tokens. total_tokens equals prompt_tokens.

Limitations

  • Images, audio, and other modalities are unsupported.
  • Structured-output JSON schemas are not supported.
  • Tool calling, function calling, multiple choices, nonzero temperature, log probabilities, and custom stop sequences are unsupported.

The moderations input and request body limits, coverage semantics, and errors also apply.

On this page