Embeddings

Generate vector embeddings for text and images using ThreatWinds-hosted embedding models. This endpoint is OpenAI-compatible and returns dense float vectors suitable for semantic search, clustering, and similarity comparisons.

ThreatWinds supports two embedding models, reported under the threatwinds provider on the unified /models API; the owned_by field identifies the original model maintainer.

Type	Model	Provider	Owned By	Input Types	Description
Text Embeddings	`qwen3-embedding-8b`	threatwinds	Alibaba	Text	High-performance multilingual embeddings
Vision Embeddings	`qwen3-vl-embedding-8b`	threatwinds	Alibaba	Text or image	Same model embeds either a text string OR an image (one input per request)

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

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 requests to the same backend instance

Note: You must use either the Authorization header OR the api-key/api-secret combination.

Request Body

{
  "model": "qwen3-embedding-8b",
  "input": "Analyze this threat intelligence report",
  "encoding_format": "float"
}

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID to use for embedding generation
input	string \| array	Yes	A text string, an array of text strings (batch), or — for `qwen3-vl-embedding-8b` — a base64 image data URL string. See Input Formats.
encoding_format	string	No	Format for the embedding values. `float` (default) or `base64`
dimensions	int64	No	Output vector dimensions. The `qwen3` embedding models produce a fixed 4,096-dimensional vector and do not truncate; the field is accepted but ignored for them.

Available Models

Model	Max Input Tokens	Capabilities	Description
qwen3-embedding-8b	32,768	Text embeddings	High-performance multilingual text embedding model
qwen3-vl-embedding-8b	32,768	Vision embeddings	Multimodal embedding model supporting text and images

Example

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen3-embedding-8b",
  "input": "CVE-2024-1234 is a critical remote code execution vulnerability"
}'

Input Formats

Plain Text (all models)

Pass a single string:

{
  "model": "qwen3-embedding-8b",
  "input": "A text string to embed"
}

Array of Strings (text models)

Batch-embed multiple texts:

{
  "model": "qwen3-embedding-8b",
  "input": ["Text one", "Text two", "Text three"]
}

Image Input (vision model only)

For qwen3-vl-embedding-8b, pass the image as a base64 data URL string in the input field:

{
  "model": "qwen3-vl-embedding-8b",
  "input": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

The same model also accepts plain text — pass a regular string and it embeds the text into the same multimodal space, useful for cross-modal similarity (e.g. comparing a text query against image embeddings).

Note: The text-only model (qwen3-embedding-8b) does not understand image data URLs. Pass image inputs only to qwen3-vl-embedding-8b.

Batch Embedding

Embed multiple texts in a single request:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen3-embedding-8b",
  "input": [
    "Ransomware attack targeting healthcare sector",
    "DDoS amplification using DNS reflection",
    "SQL injection in login form"
  ]
}'

Returns

A successful response returns a JSON object with an array of embedding vectors:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789, 0.0321, 0.0654],
      "index": 0
    }
  ],
  "model": "qwen3-embedding-8b",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

Response Schema

Field	Type	Description
object	string	Always `"list"`
data	array	Array of embedding objects, one per input text
data[].object	string	Always `"embedding"`
data[].embedding	array	Vector of floating-point numbers representing the text. When `encoding_format` is `base64`, this field is a base64-encoded string instead of a float array.
data[].index	integer	Zero-based index corresponding to the input array position
model	string	Model ID used for the request
usage.prompt_tokens	integer	Number of tokens in the input
usage.total_tokens	integer	Total tokens processed (same as prompt_tokens for embeddings)

Note: Both models produce 4,096-dimensional vectors.

Note: The example embedding array above is truncated for readability.

Usage Weighting

Embedding requests are metered against embeddings_per_day / embeddings_per_week. Each embedding model carries its own calibrated weight — the two self-hosted models are qwen3-embedding-8b (5) and qwen3-vl-embedding-8b (12), and the third-party gemini-embedding-2 is 20. The weight follows the model you asked for, and a failed response is never charged. See Usage Weighting for the full model table (including chat completions) and rules.

Vision Embeddings

The qwen3-vl-embedding-8b model embeds either an image OR a text string into a shared multimodal space, allowing cross-modal similarity search (e.g. finding images similar to a text description, or finding text similar to an image). One input per request.

Image Embedding

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen3-vl-embedding-8b",
  "input": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}'

Text Embedding (Same Vision Model)

The vision model also embeds plain text into the same space — use it whenever you want to compare a text query against image embeddings:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen3-vl-embedding-8b",
  "input": "A screenshot showing suspicious network traffic"
}'

Combining Text and Image

The endpoint does not accept a combined text+image input in a single request. To produce a “text+image” embedding, send two separate requests (one for the text, one for the image) and combine the resulting vectors at the application layer (e.g. mean-pool or concatenate).

Use Cases

Use Case	Description
Visual threat detection	Embed screenshots of phishing emails, malicious websites, or logs
Cross-modal search	Find images matching a text description, or text matching an image
Multimodal RAG	Index text and images in the same embedding space for retrieval
Visual similarity	Find visually similar screenshots, diagrams, or UI elements

Error Response Headers

Header	Description
x-error	Human-readable error message
x-error-id	Unique identifier for error tracking

Error Codes

Status Code	Description	Possible Cause
400	Bad Request	Missing `model`, missing `input`, empty input, invalid `encoding_format`, or an `input` shape the backend does not accept (e.g. content-block arrays sent to non-vision models like `qwen3-embedding-8b`)
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Insufficient permissions for AI API access
429	Too Many Requests	Rate limit exceeded; check `Retry-After` header
500	Internal Server Error	Embedding service unavailable or server-side error
503	Service Unavailable	Model warming up or request queue timeout; check `Retry-After` header