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 three types of embedding models. The ThreatWinds-hosted models are reported under the threatwinds provider on the unified /models API; the owned_by field identifies the original model maintainer. External models are reported under their respective provider.

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)
Text + Vision	gemini-embedding-2	gemini	Google	Text or image	Multimodal embeddings with dimension truncation support

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 pod

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`. Only honored by self-hosted `qwen3` embedding models (vLLM backend); `gemini-embedding-2` always returns float arrays regardless of this setting
dimensions	int64	No	Output vector dimensions (optional). Must be ≤ the model’s default dimension count. For `gemini-embedding-2`, valid range is 128–3,072 using MRL dimension truncation.

Available Models

Model	Max Input Tokens	Capabilities	Description
qwen3-embedding-8b	32,768	Text embeddings	High-performance multilingual text embedding model by Qwen
qwen3-vl-embedding-8b	32,768	Vision embeddings	Multimodal embedding model supporting text and images
gemini-embedding-2	8,192	Text + vision embeddings	Gemini multimodal embedding model with MRL dimension truncation (128–3,072; default 3,072)

Example

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: 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).

Multimodal Content Blocks (gemini-embedding-2)

For gemini-embedding-2, you can embed images using OpenAI-style content block arrays:

{
  "model": "gemini-embedding-2",
  "input": [
    {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
  ]
}

The input field accepts an array of map[string]any content blocks with type: "image_url" for vision embedding models. This allows embedding text and image content blocks in a single request for gemini-embedding-2.

Note: Combined text-plus-image embedding in a single request is not supported. Send separate requests for the text and the image, then combine the resulting vectors at the application layer if needed.

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 <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 (only for `qwen3` embedding models — `gemini-embedding-2` always returns float arrays).
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: The embedding vector dimensions depend on the model: qwen3-embedding-8b produces 4,096 dimensions; qwen3-vl-embedding-8b produces 4,096 dimensions; gemini-embedding-2 produces up to 3,072 dimensions (configurable via the dimensions parameter).

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

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 <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 <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 admission queue timeout; check `Retry-After` header