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
| Parameter | Description |
|---|---|
model | One of the four Shield model IDs. Defaults to shield. |
messages | 1 to 256 messages. Only the final user or tool message is scored. |
response_format | text or json_object. |
stream | Boolean. Defaults to false. |
stream_options.include_usage | Supported when stream is true. |
temperature | Only 0, if supplied. |
n | Only 1, if supplied. |
max_tokens, max_completion_tokens | Positive 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:
safeA flagged input returns:
unsafe
prompt_injectionThese 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.