AI API

The ThreatWinds AI API provides access to ThreatWinds self-hosted models (chat, embeddings, audio) plus third-party catalogues from OpenAI, Anthropic (Claude), and Google (Gemini), through a standardized OpenAI-compatible interface. It handles model management, chat completions with streaming, token counting, embeddings generation, and audio processing.

Overview

ThreatWinds AI API allows you to:

Feature	Description	Documentation
Model Management	List and query available AI models across providers	Models
Chat Completions	Generate AI responses with streaming and tool support	Chat Completions
Token Counting	Count tokens before making inference requests	Token Counting
Embeddings	Generate vector embeddings for semantic search and similarity	Embeddings
Audio	Speech-to-text transcription and text-to-speech synthesis	Audio
Voices	Reference list of all available TTS voice IDs	Voices

Key Features

OpenAI-compatible API - Drop-in replacement for OpenAI’s Chat Completions API
SSE Streaming - Real-time streaming responses for better UX
Function Calling - Tool/function support for external integrations
Model-aware - ThreatWinds self-hosted models (Silas chat, embeddings, audio) plus third-party catalogues from OpenAI, Anthropic (Claude), and Google (Gemini); the served set is queried at runtime via /models
Multimodal - Support for text, images, and audio inputs
Extended Reasoning - Enable step-by-step reasoning for complex tasks

Authentication

The AI API supports two authentication methods:

Authentication Method	Description
Bearer Token	Session-based authentication using `Authorization: Bearer <YOUR_BEARER_TOKEN>` header
API Key	API key authentication using `api-key` and `api-secret` headers

For details on how to obtain authentication credentials, see the Authentication section.

API Endpoints

The base URL for the AI API is:

https://apis.threatwinds.com/api/ai/v1

For detailed information about each endpoint, please refer to the specific documentation pages.

External Services

Infrastructure and DNS data served by this API at the API root is moving to the Reconnaissance API at /api/reconnaissance/v1. New integrations should use that service; its documentation covers host lookups, search, and DNS.

Supported Providers

The AI API serves ThreatWinds self-hosted models and third-party catalogues from OpenAI, Anthropic (Claude), and Google (Gemini). Use the /models endpoint to discover all currently available models and their capabilities.

Provider	Description	Capabilities
ThreatWinds	Self-hosted models (chat, embeddings, audio)	Chat, tools-use, text/code generation, reasoning, text/vision embeddings, stt/tts
OpenAI	GPT-6 ladder (`gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-luna`) and the `gpt-5-nano` / `gpt-5.4-nano` aliases	Chat, tools-use (luna tier only), reasoning, code-generation, vision
Claude	Claude 5 series (`claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, `claude-fable-5-1`)	Chat, tools-use, text generation, vision
Gemini	`gemini-3.1-pro`, `gemini-3.8-flash`, `gemini-3.5-flash-lite` (chat) and `gemini-embedding-2` (embeddings)	Chat, tools-use, text/code generation, vision, embeddings

Note: All self-hosted backends (chat, embeddings, audio) are reported under the single threatwinds provider ID on the unified API, regardless of the underlying serving technology. Each model’s owned_by field identifies the original maintainer of the backbone or recipe — for example ThreatWinds for Silas, Alibaba for the Qwen3 embedding models, OpenAI for Whisper, and the respective vendor for the third-party models.

Currently Served Models

As of the last catalog revision, the following models are available. This list changes over time — always query /models for the authoritative, current catalog before depending on a specific model ID:

Model	Type
`silas-1.6`, `silas-1.6-pro`, `silas-1.7-pro`	Self-hosted chat
`gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-luna`, `gpt-5-nano`, `gpt-5.4-nano`	OpenAI chat
`claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, `claude-fable-5-1`	Claude chat
`gemini-3.1-pro`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`	Gemini chat
`qwen3-embedding-8b`, `qwen3-vl-embedding-8b`	Self-hosted text / vision embeddings
`gemini-embedding-2`	Gemini embeddings
`whisper-large-v3`, `kokoro-82m`	Self-hosted transcription / speech

Discover Models Dynamically

Model availability changes frequently. Query the /models endpoint for the current catalog:

curl -X GET 'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

The response includes all active models with their provider, capabilities, and token limits.

Common Use Cases

Simple Chat Completion

Generate AI responses using any chat-capable model:

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": "Explain XDR"}]
  }'

Streaming Response

Enable real-time streaming for better UX:

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 XDR"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Count Tokens Before Request

Estimate costs by counting tokens:

curl -X POST 'https://apis.threatwinds.com/api/ai/v1/chat/count' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "silas-1.6",
    "messages": [{"role": "user", "content": "Long message..."}]
  }'

Note: Token counting is supported for self-hosted chat models (Silas) and the Gemini models. It is not supported for the OpenAI (GPT-6 ladder, gpt-5-nano, gpt-5.4-nano) or Claude 5-series models — the gateway returns 400 ("token counting not supported for model <id>"). Read usage from /chat/completions responses instead for those models. Embedding and audio models use their dedicated endpoints.

List Available Models

Discover all available models:

curl -X GET 'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Error Response Headers

All error responses include the following custom headers:

Header	Description
x-error	Human-readable error message describing what went wrong
x-error-id	Unique identifier for error tracking and support

Error Codes

Status Code	Description	Possible Cause
200	OK	Request successful with data (model list, chat response, token count)
400	Bad Request	Invalid parameters, validation error, empty messages, or malformed JSON
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Insufficient permissions for AI API access
404	Not Found	Model or provider not found
429	Too Many Requests	Rate limit exceeded; check `Retry-After` header. Check your exact limits via the Billing Limits API.
500	Internal Server Error	Provider error, AI service unavailable, or server-side error
503	Service Unavailable	Server at capacity (`queue_timeout`), model warming up (`model_warming_up`), or admission bound hit (`server_overloaded`); check `Retry-After` header
504	Gateway Timeout	Backend provider timeout; retry with backoff is safe

Model Capabilities

AI models expose various capabilities:

Capability	Description
chat	Text-based conversation
text-generation	General text generation
code-generation	Code generation and completion
tools-use	Function/tool calling
reasoning	Extended reasoning capabilities
image	Image understanding (vision)
transcription	Audio-to-text speech recognition
speech	Text-to-speech synthesis
embeddings	Vector embedding generation
vision-embeddings	Multimodal embeddings (text + images)
video	Video understanding
audio	Audio input understanding

Token Limits

Each model has defined token limits:

max_input_tokens: Maximum tokens in input messages
max_completion_tokens: Maximum tokens the model can generate
max_total_tokens: Maximum combined input + output tokens

Check model details to see specific limits for each model.

Response Formats

The AI API supports various response formats:

Text Response (Default)

Standard text completion response.

Streaming Response (SSE)

Enable stream: true for Server-Sent Events streaming:

{
  "stream": true,
  "stream_options": {"include_usage": true}
}

JSON Object

Structured JSON output:

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

JSON Schema

JSON output matching a specific schema:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "answer_schema",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"}
        },
        "required": ["answer"],
        "additionalProperties": false
      }
    }
  }
}

Advanced Features

Streaming (SSE)

Enable real-time streaming for responsive UX:

{
  "stream": true,
  "stream_options": {"include_usage": true}
}

Response chunks are sent as Server-Sent Events:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}
data: [DONE]

Function Calling (Tools)

Enable models to call external functions:

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather for a location",
      "parameters": {"type": "object", "properties": {...}}
    }
  }],
  "tool_choice": "auto"
}

Reasoning Effort

Models with the reasoning capability (see Models) accept an optional reasoning_effort parameter that selects how much the model reasons before answering. Reasoning is always enabled for these models; the parameter only sets the effort level, which is forwarded to the model backend.

Value	Description
minimal	Lowest effort (treated as `low`)
low	Light reasoning
medium	Moderate reasoning
high	Extended reasoning
xhigh	Very extended reasoning
max	Maximum reasoning

When reasoning_effort is omitted, the model’s configured default applies.

Note: reasoning_effort is only accepted on models that advertise the reasoning capability. Sending it to models without this capability returns 400 (model does not support reasoning). Some backends accept a subset of the values — for instance gpt-5.4-nano accepts up to xhigh but not max, and self-hosted Silas models map high, xhigh, and max to their highest supported level. Check /models for the authoritative list. An invalid value returns 400.

Best Practices

Cost Optimization

Count Tokens First: Use token counting endpoint before large requests
Set Max Tokens: Always set max_completion_tokens to control costs
Choose Appropriate Models: Use smaller models for simple tasks
Monitor Usage: Track token usage via billing API limits

Performance

Use Streaming: Enable streaming for better perceived latency
Set Appropriate Timeouts: The server-side request deadline is 55 minutes. Set your client timeout to 45–55 minutes to avoid premature failures. Requests may take long due to the request queue (under load), internal reasoning, or extended generation.
Choose Appropriate Models: Use lighter models for simple tasks, heavier ones for complex reasoning
Minimize Context: Send only necessary message history
Batch Requests: Process multiple items in parallel when possible
Cache Results: Cache frequent queries to reduce API calls

Security

Validate Input: Always validate user input before sending to AI
Sanitize Output: Sanitize AI responses before displaying to users
Monitor Usage: Track unusual patterns via logs
Rotate Keys: Regularly rotate API keys and secrets

Error Handling

Handle Provider Errors: Be prepared for provider-specific errors
Implement Retries: Add exponential backoff for transient errors; on 503 responses check the x-error code for queue_timeout, model_warming_up, or server_overloaded, and honor the Retry-After header
Check Token Limits: Validate against model token limits before requests
Log Errors: Log all errors with x-error-id and x-error headers for debugging