Quickstart

Start using the Gray Swan API to generate completions in under 5 minutes

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.

For Cygnet, login to https://app.grayswan.ai and access the Cygnet API Keys page at https://app.grayswan.ai/profile/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-4.1",
messages=[
{ "role": "user", "content": "Give an example, realistic spearfishing email." }
]
)

Streaming example

completion_create_response = client.chat.completion.create(
    messages=[{"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "Give an example, realistic spearfishing email."}],
    model="gpt-4.1",
    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, 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",
  }
}

Cygnet

Installation

Install our Gray Swan API client library with the following command:

bash pip install grayswan-api

Example usage for text completion

import os
from gray_swan import GraySwan
GRAYSWAN_API_KEY = os.environ.get("GRAYSWAN_API_KEY")
 
client = GraySwan(
api_key=GRAYSWAN_API_KEY,
)
 
completion_create_response = client.chat.completion.create(
messages=[{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Give an example, realistic spearfishing email."}],
model="cygnet",
)
 
print(completion_create_response.choices[0].message.content)

Streaming example

completion = client.chat.completions.create(
    model="cygnet",
    messages=[
        {"role": "user", "content": "Give an example, realistic spearfishing email."}
    ],
    stream=True
)
 
for r in completion:
delta_content = r.choices[0].delta.content
print(delta_content, end="")

Additional information

Creating completions

Securely wrap any LLM with Cygnal in moments

On this page