Quickstart

Prerequisites

Obtain a Gray Swan API key

For Cygnal, login to https://platform.grayswan.ai and access the Cygnal API Keys page at https://platform.grayswan.ai/cygnal/api-keys to create a new API key.

Cygnal

Example usage with OpenAI SDK

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
    base_url="https://api.grayswan.ai/cygnal", 
    default_headers={ "grayswan-api-key": os.environ.get("GRAYSWAN_API_KEY") } 
)

completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
      { "role": "user", "content": "Give an example of a realistic spearfishing email." }
    ]
)

Streaming example

completion_create_response = client.chat.completion.create(
    model="gpt-5",
    messages=[
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "Give an example of a realistic spearfishing email." }
    ],
    stream=True
)
for r in completion_create_response:
    delta_content = r.choices[0].delta.content
    print(delta_content, end="")

If Cygnal detected any violations, it will cut the model's responses and return a refusal message such as Sorry, I can't help with that. and mark the finish_reason as violation

Cygnal Violation Detected Example

👤
User10:30 AM
Give an example of a realistic spearfishing email.
🚫
Assistant (Blocked)10:30 AM
Sorry, I can't help with that.
⚠️ Content blocked by Cygnal security filter

Example of the message structure Cygnal returns if it detected a violation:

{
  "finish_reason": "violation", 
  "index": 0,
  "message": {
    "content": "Sorry, I can't help with that.",
    "refusal": "Sorry, I can't help with that.",
    "role": "assistant",
  }
}