Model Management

Query available AI models and their capabilities across all supported providers.

List Models

Returns the list of available AI models across all providers (Claude, OpenAI, Gemini, Groq).

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

Method: GET

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

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

Request

To list all available models, use a GET request:

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

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

A successful response will return all available models across all providers.

Success Response (200 OK)

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4",
      "object": "model",
      "name": "Claude Sonnet 4",
      "provider": "claude",
      "owned_by": "Anthropic PBC",
      "created": 2025,
      "capabilities": [
        "chat",
        "tools-use",
        "reasoning",
        "code-generation"
      ],
      "limits": {
        "max_input_tokens": 64000,
        "max_completion_tokens": 64000,
        "max_total_tokens": 64000
      }
    },
    {
      "id": "claude-opus-4",
      "object": "model",
      "name": "Claude Opus 4",
      "provider": "claude",
      "owned_by": "Anthropic PBC",
      "created": 2025,
      "capabilities": [
        "chat",
        "tools-use",
        "reasoning",
        "code-generation"
      ],
      "limits": {
        "max_input_tokens": 32000,
        "max_completion_tokens": 32000,
        "max_total_tokens": 32000
      }
    },
    {
      "id": "gpt-oss-20b",
      "object": "model",
      "name": "GPT OSS 20B",
      "provider": "groq",
      "owned_by": "OpenAI",
      "created": 2025,
      "capabilities": [
        "chat",
        "code-generation",
        "tools-use",
        "reasoning"
      ],
      "limits": {
        "max_input_tokens": 131072,
        "max_completion_tokens": 65536,
        "max_total_tokens": 196608
      }
    },
    {
      "id": "qwen3-32b",
      "object": "model",
      "name": "Qwen 3 32B",
      "provider": "groq",
      "owned_by": "Qwen",
      "created": 2024,
      "capabilities": [
        "chat",
        "code-generation",
        "tools-use",
        "reasoning"
      ],
      "limits": {
        "max_input_tokens": 131072,
        "max_completion_tokens": 40960,
        "max_total_tokens": 172032
      }
    }
  ]
}

Response Schema

Field	Type	Description
object	string	Response type, always “list”
data	array	List of model details
data[].id	string	Model unique identifier
data[].object	string	Object type, always “model”
data[].name	string	Human-readable model name
data[].provider	string	Provider identifier: claude, openai, gemini, groq
data[].owned_by	string	Organization that owns the model
data[].created	integer	Unix timestamp of model creation
data[].capabilities	array	List of model capabilities
data[].limits	object	Token limit information
limits.max_input_tokens	integer	Maximum input tokens
limits.max_completion_tokens	integer	Maximum completion tokens
limits.max_total_tokens	integer	Maximum total tokens (input + completion)

Model Capabilities

Capability	Description
chat	Text-based conversation
text-generation	General text generation
code-generation	Code generation and completion
embeddings	Vector embeddings for semantic search
audio	Audio processing and transcription
image	Image understanding and generation
video	Video processing
tools-use	Function/tool calling support
vision	Image understanding in chat context
reasoning	Extended reasoning capabilities

Business Logic

• Retrieves models from in-memory provider registry
• Models aggregated across all registered providers
• No database queries - data from provider configuration
• Model list may change as providers update their offerings

Error Codes

Status Code	Description	Possible Cause
200	OK	Request successful
400	Bad Request	Invalid request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions

---

Get Model Details

Returns detailed information about a specific model.

Endpoint: https://apis.threatwinds.com/api/ai/v1/models/{id}

Method: GET

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

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

Path Parameters

Parameter	Type	Required	Description	Example
id	string	Yes	Model identifier	claude-3-5-sonnet-20241022

Request

To get details for a specific model, use a GET request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/ai/v1/models/claude-3-5-sonnet-20241022' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/ai/v1/models/gpt-4o' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

Success Response (200 OK)

{
  "id": "claude-sonnet-4",
  "object": "model",
  "name": "Claude Sonnet 4",
  "provider": "claude",
  "owned_by": "Anthropic PBC",
  "created": 2025,
  "capabilities": [
    "chat",
    "tools-use",
    "reasoning",
    "code-generation"
  ],
  "limits": {
    "max_input_tokens": 64000,
    "max_completion_tokens": 64000,
    "max_total_tokens": 64000
  }
}

Response Schema

Field	Type	Description
id	string	Model unique identifier
object	string	Object type, always “model”
name	string	Human-readable model name
provider	string	Provider identifier
owned_by	string	Organization that owns the model
created	integer	Unix timestamp of model creation
capabilities	array	List of model capabilities
limits	object	Token limit information
limits.max_input_tokens	integer	Maximum input tokens accepted
limits.max_completion_tokens	integer	Maximum tokens model can generate
limits.max_total_tokens	integer	Maximum combined tokens

Business Logic

• Retrieves model by ID from provider registry
• Returns 404 if model ID doesn’t exist
• No database queries - data from provider configuration

Error Codes

Status Code	Description	Possible Cause
200	OK	Model found and returned
404	Not Found	Model not found
400	Bad Request	Invalid request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions

---

Available Models

Claude Models (Anthropic)

Model ID	Name	Max Input	Max Output	Capabilities
claude-sonnet-4	Claude Sonnet 4	64,000	64,000	Chat, tools, reasoning, code-generation
claude-opus-4	Claude Opus 4	32,000	32,000	Chat, tools, reasoning, code-generation

Internal Mappings:

• claude-sonnet-4 → claude-sonnet-4-5-20250929
• claude-opus-4 → claude-opus-4-1-20250805

Best For:

• Sonnet 4: Balanced performance with extended reasoning support
• Opus 4: Highest quality reasoning and complex problem-solving

Groq Models

Model ID	Name	Max Input	Max Output	Capabilities
gpt-oss-20b	GPT OSS 20B	131,072	65,536	Chat, code, tools, reasoning
gpt-oss-120b	GPT OSS 120B	131,072	65,536	Chat, code, tools, reasoning
qwen3-32b	Qwen 3 32B	131,072	40,960	Chat, code, tools, reasoning*
llama4-maverick	LLaMA 4 Maverick 17B	131,072	8,192	Chat, code, tools
llama4-scout	LLaMA 4 Scout 17B	131,072	8,192	Chat, code, tools

Internal Mappings:

• gpt-oss-20b → openai/gpt-oss-20b
• gpt-oss-120b → openai/gpt-oss-120b
• qwen3-32b → qwen/qwen3-32b
• llama4-maverick → meta-llama/llama-4-maverick-17b-128e-instruct
• llama4-scout → meta-llama/llama-4-scout-17b-16e-instruct

Best For:

• Extremely fast inference (optimized hardware)
• Real-time applications
• Cost-effective at scale
• Large context windows (131K tokens)

Special Notes:

• *qwen3-32b only accepts “none” or “default” for reasoning_effort parameter
• Token counting not supported for Groq models

---

Choosing the Right Model

By Use Case

Use Case	Recommended Models
Simple Q&A	GPT-3.5 Turbo, Claude Haiku, Mixtral
Complex Reasoning	Claude Opus, O1, GPT-4o
Code Generation	GPT-4o, Claude Sonnet, O1
Long Context	Gemini Pro, Gemini Flash
Vision Tasks	GPT-4o, Claude Sonnet, Gemini
Real-time Chat	Groq models, Claude Haiku
Tool/Function Calling	Claude Sonnet, GPT-4o

By Performance Priority

Priority	Models
Speed	Groq (Llama, Mixtral), Claude Haiku, Gemini Flash
Quality	Claude Opus, O1 Preview, GPT-4o
Cost	GPT-3.5 Turbo, Claude Haiku, Groq models
Context Length	Gemini Pro (2M), Gemini Flash (1M), Claude/GPT-4 (200K/128K)

By Provider Strengths

Provider	Strengths
Claude	Instruction following, safety, reasoning
OpenAI	General purpose, tool use, vision
Gemini	Long context, multimodal, fast
Groq	Ultra-fast inference, low latency

---

Example: Filtering Models

List Only Claude Models

# Get all models
curl -X 'GET' 'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'Authorization: Bearer <token>' | \
  jq '.data[] | select(.provider == "claude")'

Find Models with Vision

# Get all models
curl -X 'GET' 'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'Authorization: Bearer <token>' | \
  jq '.data[] | select(.capabilities | contains(["vision"]))'

Find Models with Large Context

# Get all models
curl -X 'GET' 'https://apis.threatwinds.com/api/ai/v1/models' \
  -H 'Authorization: Bearer <token>' | \
  jq '.data[] | select(.limits.max_input_tokens > 100000)'

---

Model Selection Best Practices

1. Check Token Limits: Ensure model supports your required context length
2. Verify Capabilities: Confirm model has required features (vision, tools, etc.)
3. Consider Cost: Balance quality needs with token costs
4. Test Multiple Models: Compare results across models for your use case
5. Monitor Performance: Track response times and quality metrics
6. Stay Updated: Model list changes as providers release new versions