Chat Completions

Generate AI chat completions using any supported model. This endpoint handles inference requests and returns AI-generated responses, with full OpenAI API compatibility including streaming.

Endpoint: https://apis.threatwinds.com/api/ai/v1/chat/completions

Method: POST

Parameters

Headers

Header Type Required Description
Authorization string Optional* Bearer token for session authentication
api-key string Optional* API key for key-based authentication
api-secret string Optional* API secret for key-based authentication
Content-Type string Yes Must be application/json
X-Session-Id string No Session affinity key — routes follow-up requests to the same backend instance for context continuity. Accepts any non-empty string; UUID format is not required
pentest-id string No UUID identifying the pentest engagement. Recorded per customer for usage reporting; pentests are not rate limited
pentest-targets string No Comma-separated list of pentest target addresses. Each unique target is recorded per customer for usage reporting; targets are not rate limited

Note: You must use either Authorization header OR API key/secret combination.

Request Body 

{
  "model": "silas-1.6",
  "messages": [
    {
      "role": "user",
      "content": "What is XDR in cybersecurity?"
    }
  ],
  "max_completion_tokens": 1024,
  "temperature": 1.0,
  "stream": false
}

Request Parameters

Parameter Type Required Description
model string Yes Model ID to use for inference (see Models)
messages array Yes Message history for context (minimum 1)
max_completion_tokens integer No Maximum tokens in response (defaults to the model’s configured default (see /models/{id} params))
max_tokens integer No Alias for max_completion_tokens (OpenAI compatibility)
temperature float No Sampling temperature (model-dependent range; check /models/{id} for valid bounds. Typical range: 0.0 to 2.0. Default: 1.0)
top_p float No Nucleus sampling (0.0 to 1.0, default: 1.0). Silently ignored for GPT-5-family models.
top_k integer No Number of top tokens to consider (-1 for all tokens). Limits the token pool before sampling
min_p float No Minimum probability relative to the top token (0.0 to 1.0, 0 disables). Dynamic cutoff that adapts to each token’s probability distribution
n integer No Number of completions to generate (1-128, default: 1). Some providers may restrict this value.
stop string/array No Stop sequences (max 4). Silently ignored for GPT-5-family models which enforce stop server-side
frequency_penalty float No Frequency penalty (-2.0 to 2.0, default: 0). Penalizes tokens based on their frequency in the generated text
presence_penalty float No Presence penalty (-2.0 to 2.0, default: 0). Penalizes tokens based on whether they appear in the generated text
repetition_penalty float No Repetition penalty (range: 0.0 to 2.0, default: 1.0). Penalizes tokens that appear in the prompt and generated text. Values > 1.0 discourage repetition, values < 1.0 encourage it
logprobs boolean No Return log probabilities of output tokens
top_logprobs integer No Number of top logprobs per token (0-5, requires logprobs=true)
logit_bias object No Token bias map (token_id: -100 to 100)
user string No Unique user identifier for tracking
stream boolean No Enable SSE streaming (default: false)
stream_options object No Streaming configuration
tools array No Tool/function definitions (max 128)
tool_choice string/object No Tool selection strategy
parallel_tool_calls boolean No Allow parallel tool calls
reasoning_effort string No Reasoning effort: minimal, low, medium, or high (minimal is treated as low). Only accepted on models with the reasoning capability (see Models); sending it to a model without this capability returns 400. An invalid value also returns 400. When omitted, the model’s configured default applies and reasoning stays enabled.
response_format object No Response format specification. Forwarded to both self-hosted and OpenAI backends.

Message Object

Field Type Required Description
role string Yes Message role: user, assistant, system, tool, developer
content string/array Yes Message content (string or array of content blocks: text, image_url, audio_url, video_url)
name string No Participant name
tool_calls array No Tool calls generated by the model (for assistant messages)
tool_call_id string No Tool call identifier (for tool messages)
reasoning string No Reasoning text (for assistant messages)

Control the structure of the model’s output:

JSON Object

Request JSON-formatted output:

{
  "response_format": {
    "type": "json_object"
  }
}

JSON Schema

Request output matching a specific schema. Follows the OpenAI Structured Outputs spec — type is "json_schema" and the schema lives under json_schema.schema. The name and strict fields are required by upstream:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "threat_record",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "threat_name": {"type": "string"},
          "severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
          "indicators": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["threat_name", "severity"],
        "additionalProperties": false
      }
    }
  }
}

Request

To generate a chat completion, use a POST request:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "silas-1.6-pro",
  "messages": [
    {
      "role": "user",
      "content": "What is XDR in cybersecurity?"
    }
  ],
  "max_completion_tokens": 1024
}'

Or using API key and secret:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'api-secret: <YOUR_API_SECRET>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "gpt-5.4-nano",
  "messages": [
    {
      "role": "user",
      "content": "Explain threat intelligence"
    }
  ]
}'

Response

A successful response will return the AI-generated completion with usage statistics.

Success Response (200 OK) 

{
  "id": "msg_01AbCdEf123",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "silas-1.6",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "XDR (Extended Detection and Response) is a unified security platform that..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 150,
    "total_tokens": 162
  }
}

Response Schema

Field Type Description
id string Unique interaction identifier
object string Response type: "chat.completion" or "chat.completion.chunk"
created integer Unix timestamp of creation
model string Model used for inference
system_fingerprint string Backend configuration identifier (optional)
service_tier string Service tier used for request (optional)
choices array Generated response choices
choices[].index integer Choice index in array
choices[].finish_reason string How generation ended
choices[].message object Generated message (non-streaming)
choices[].delta object Incremental message (streaming)
choices[].logprobs object Log probabilities (when requested)
usage object Token usage statistics
usage.prompt_tokens integer Tokens in input messages
usage.completion_tokens integer Tokens in generated response
usage.total_tokens integer Sum of prompt and completion tokens
usage.prompt_tokens_details object Breakdown of prompt tokens (optional)
usage.prompt_tokens_details.audio_tokens integer Audio input tokens (for audio models)
usage.prompt_tokens_details.cached_tokens integer Cached prefix tokens reused from previous requests
usage.completion_tokens_details object Breakdown of completion tokens (optional)
usage.completion_tokens_details.reasoning_tokens integer Tokens used for reasoning/thinking
usage.completion_tokens_details.accepted_prediction_tokens integer Prefill tokens accepted by model (drafting)
usage.completion_tokens_details.rejected_prediction_tokens integer Prefill tokens rejected by model (drafting)

Message Object (Response)

Field Type Description
role string Always “assistant”
content string Generated response text
tool_calls array Tool calls requested by model (optional)
reasoning string Reasoning process (when reasoning enabled)
refusal string Model’s refusal message (optional)

Finish Reason Values

Reason Description
stop Model completed response naturally
length Response cut off due to max_completion_tokens limit
content_filter Content filtered by provider safety systems
tool_calls Model requested tool/function calls

Usage Weighting

This request is metered against chat_completions_per_day / chat_completions_per_week at a weight that depends on the requested model — not a flat 1 unit per request. Each model carries its own calibrated weight: for example silas-1.6 is 6, silas-1.6-pro is 13, gpt-6-luna is 12, gpt-6.1-sol is 230, and gpt-6-astra is 1150. The weight follows the model you asked for, never whichever backend ends up serving it, and a failed response is never charged. See Usage Weighting for the full model table and rules.

OpenAI Compatibility

This endpoint is designed for compatibility with OpenAI’s Chat Completions API.

Provider-Specific Parameter Support

Not all providers support every parameter – unsupported parameters are silently ignored unless noted otherwise.

Currently, the chat models served are the self-hosted ThreatWinds Silas models plus the third-party catalogues from OpenAI (GPT-6 tier and the gpt-5-nano / gpt-5.4-nano aliases), Anthropic (Claude 5 series), and Google (Gemini). See Usage Weighting for the full table and per-model weights.

Core Parameters

These parameters are used across the served chat providers, though support varies by provider. The OpenAI column reflects all five GPT-6 / GPT-5.4-nano models, which share the same wire-level constraints (temperature pinned to 1.0; top_p, stop, and most sampling knobs rejected by upstream and stripped by the adapter).

Parameter Description ThreatWinds (Silas) OpenAI (GPT-6 ladder, GPT-5.4-nano)
model Model ID to use Yes Yes
messages Message history array Yes Yes
temperature Sampling temperature (0.0-2.0, default: 1.0) Yes Pinned to 1.0
top_p Nucleus sampling (0.0-1.0, default: 1.0) Yes Silently ignored
top_k Top-k sampling (-1 for all tokens) Yes No
min_p Minimum probability vs top token (0.0-1.0) Yes No
n Number of completions (1-128) Forwarded Yes
stop Stop sequences (max 4) Yes Silently ignored (enforced server-side)
frequency_penalty Penalize frequent tokens (-2.0 to 2.0) Yes Yes
presence_penalty Penalize repeated tokens (-2.0 to 2.0) Yes Yes
repetition_penalty Penalize tokens appearing in prompt Yes No
user User identifier for tracking Yes Yes

Token Limits

Parameter Description ThreatWinds (Silas) OpenAI (GPT-6 ladder, GPT-5.4-nano)
max_completion_tokens Maximum output tokens Yes Yes
max_tokens Alias for max_completion_tokens (compatibility) Yes Yes

Advanced Features

Parameter Description ThreatWinds (Silas) OpenAI (GPT-6 ladder, GPT-5.4-nano)
logprobs Return token log probabilities Forwarded Yes
top_logprobs Number of top logprobs per token (0-5) Forwarded Yes
logit_bias Token bias map (token_id: -100 to 100) Forwarded Yes
tools Tool/function definitions (max 128) Yes Yes (luna tier only; astra/sol reject tools on /v1/chat/completions)
tool_choice Tool selection strategy Yes Yes (luna tier only)
parallel_tool_calls Allow calling multiple tools simultaneously Yes Yes (luna tier only)
reasoning_effort Reasoning depth Yes Yes (clamped per-model to the upstream ceiling)
response_format Force JSON or structured output format Yes Yes
stream Enable Server-Sent Events streaming Yes Yes
stream_options Streaming configuration (include_usage) Yes Yes

“Forwarded” means the parameter is passed to the backend verbatim; whether the backend honours it is backend-dependent.

Error Responses

Queue Timeout (503)

When the server is at capacity and the request times out waiting in the request queue:

{
  "error": {
    "message": "server is at capacity; please retry after 15s.",
    "type": "service_unavailable",
    "code": "queue_timeout"
  }
}

The response includes a Retry-After header (in seconds) indicating how long to wait before retrying. This error is safe to retry — the request never reached a backend.

Model Warming (503)

When a self-hosted model is loading and not yet ready:

{
  "error": {
    "message": "model \"silas-1.6\" is temporarily unavailable (warming up). Retry after 60s.",
    "type": "service_unavailable",
    "param": "silas-1.6",
    "code": "model_warming_up"
  }
}

The response includes a Retry-After header (in seconds). This error is safe to retry — the model will be ready after the warmup period.

Server Overloaded (503)

When the instance has too many requests already in flight (admission bound reached), the request is rejected at the door before it enters the queue:

{
  "error": {
    "message": "server is overloaded; please retry after 15s.",
    "type": "service_unavailable",
    "code": "server_overloaded"
  }
}

The response includes a Retry-After header (in seconds). This error is safe to retry — no work was started.

Streaming Errors

If an error occurs during streaming (after headers are sent), the error is delivered as an SSE event rather than an HTTP error:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"finish_reason":"error","delta":{},"error":{"message":"...","type":"proxy_error","code":"upstream_failure"}}]}

Error Codes

Status Code Description Possible Cause
200 OK Request successful
400 Bad Request Invalid JSON, empty messages, invalid role, parameter out of range, token limit exceeded
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions or model not allowed
429 Too Many Requests Rate limit exceeded; check Retry-After header
500 Internal Server Error Provider error, model unavailable
503 Service Unavailable Server at capacity (queue_timeout), model warming up (model_warming_up), or instance admission bound hit (server_overloaded); check Retry-After header
504 Gateway Timeout Backend provider did not respond in time; safe to retry with backoff

Examples

Example 1: Simple Question 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.6",
    "messages": [
      {"role": "user", "content": "What is 2+2?"}
    ],
    "max_completion_tokens": 100
  }'

Response:

{
  "id": "msg_123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "2 + 2 = 4"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 5,
    "total_tokens": 13
  }
}

Example 2: Multi-turn Conversation 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.6",
    "messages": [
      {"role": "system", "content": "You are a cybersecurity expert"},
      {"role": "user", "content": "What is a zero-day vulnerability?"},
      {"role": "assistant", "content": "A zero-day vulnerability is a software security flaw that is unknown to the vendor..."},
      {"role": "user", "content": "How can organizations protect against them?"}
    ],
    "max_completion_tokens": 500
  }'

Example 3: Streaming Response 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.6-pro",
    "messages": [
      {"role": "user", "content": "Explain the MITRE ATT&CK framework"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Example 4: JSON Response Format 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "silas-1.6",
  "messages": [
    {
      "role": "user",
      "content": "What is XDR in cybersecurity?"
    }
  ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "threat_record",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "severity": {"type": "string"}
          },
          "required": ["name", "severity"],
          "additionalProperties": false
        }
      }
    }
  }'

Response:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "{\"name\": \"Apache Log4j\", \"severity\": \"Critical\"}"
    },
    "finish_reason": "stop"
  }]
}

Example 5: Extended Reasoning 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.6-pro",
    "messages": [
      {
        "role": "user",
        "content": "Design a zero-trust network architecture for a financial institution"
      }
    ],
    "reasoning_effort": "high",
    "max_completion_tokens": 4000
  }'

Example 6: Vision (Image Analysis) 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.7-pro",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What security issues do you see in this network topology?"},
          {"type": "image_url", "image_url": {"url": "https://example.com/network.png", "detail": "high"}}
        ]
      }
    ]
  }'

Example 7: Function Calling 

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/completions' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.4-nano",
    "messages": [
      {"role": "user", "content": "Scan the domain threatwinds.com for vulnerabilities"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "vulnerability_scan",
          "description": "Perform a vulnerability scan on a domain",
          "parameters": {
            "type": "object",
            "properties": {
              "domain": {"type": "string", "description": "Domain to scan"},
              "scan_type": {"type": "string", "enum": ["quick", "full", "stealth"]}
            },
            "required": ["domain"]
          }
        }
      }
    ]
  }'

Best Practices

Message Construction

  1. System Messages: Use system messages to set behavior and context
  2. Message History: Include relevant conversation history for context
  3. Clear Prompts: Be specific and clear in user messages
  4. Role Consistency: Maintain proper role alternation

Token Management

  1. Set Max Tokens: Always set max_completion_tokens to control costs
  2. Count First: Use token counting endpoint for large requests
  3. Monitor Usage: Track token usage via response usage field
  4. Truncate History: Remove old messages to stay within limits

Streaming

  1. Use for Long Responses: Enable streaming for better UX on long responses
  2. Handle Chunks: Process each chunk as it arrives
  3. Check for [DONE]: Always check for the [DONE] marker
  4. Include Usage: Set include_usage: true for token tracking

Error Handling

  1. Validate Before Send: Check message count and roles before sending
  2. Handle Provider Errors: Be prepared for provider-specific errors
  3. Implement Retries: Add exponential backoff for transient errors; handle Retry-After headers on 503 responses for queue_timeout and model_warming_up
  4. Log Interaction IDs: Save interaction IDs for debugging

Long-Running Requests

AI API requests can take a significant amount of time to complete. The server-side request deadline is 55 minutes. A client timeout shorter than this will cause premature failures on valid requests.

Recommended client timeout: 45–55 minutes (2700–3300 seconds).

Requests may take long due to:

  • Admission Queue: Under load, requests are queued and dispatched as backend capacity becomes available. If the queue deadline is exceeded before a slot opens, the API returns 503 Service Unavailable with error code queue_timeout and a Retry-After header. The request did not reach a backend — it is safe to retry.
  • Internal Reasoning: Self-hosted chat models (Silas) perform advanced multi-step processing. This adds processing time beyond standard generation.
  • Extended Generation: Large max_completion_tokens values, reasoning models with reasoning_effort: high, or multi-tool-calling workflows produce longer responses.

Performance

  1. Choose Appropriate Models: Use faster models for simple tasks
  2. Minimize Context: Send only necessary message history
  3. Parallel Requests: Process multiple items concurrently when possible
  4. Cache Results: Cache frequent queries to reduce API calls

Security

  1. Validate Input: Sanitize user input before sending to AI
  2. Filter Output: Validate and sanitize AI responses
  3. Monitor Usage: Track unusual patterns via logs
  4. Rotate Keys: Regularly rotate API credentials

Cost Optimization

  1. Model Selection: Use smaller/faster models when quality permits
  2. Token Limits: Set appropriate max_completion_tokens
  3. Batch Processing: Group similar requests
  4. Response Caching: Cache responses for repeated queries