Vectors API

The Vectors API lets you create collections, embed images/text/audio into a shared vector space, and run similarity searches across modalities.

Embedding Models

Endpoint: GET /v1/vectors/models

Lists available embedding models for creating collections.

Response:

json

{
  "models": [
    {
      "id": "multimodal-embedding-v1",
      "name": "Multimodal Embedding v1",
      "types": ["image", "text", "audio"],
      "dimensions": 1024,
      "metric": "COSINE"
    }
  ]
}

Collections

Create a Collection

Endpoint: POST /v1/vectors/collections

Parameter	Type	Required	Description
`name`	string	yes	Collection name (unique within project, max 100 chars)
`description`	string	no	Collection description (max 500 chars)
`model_id`	string	no	Embedding model ID (default: `multimodal-embedding-v1`)

json

{
  "name": "product-images",
  "description": "Product catalog for visual search",
  "model_id": "multimodal-embedding-v1"
}

List / Get / Delete

Endpoint	Method	Description
`/v1/vectors/collections`	GET	List collections in the current project
`/v1/vectors/collections/:id`	GET	Get collection details
`/v1/vectors/collections/:id`	DELETE	Delete collection and its items

Indexing

Add Items to a Collection

Endpoint: POST /v1/vectors/collections/:id/index

Each item may carry an image, image_base64, text, or audio input — all land in the same vector space for cross-modal search. Up to 100 items per request.

json

{
  "items": [
    {
      "image": "https://example.com/shoe.jpg",
      "metadata": { "category": "footwear", "sku": "SH-001" }
    },
    {
      "text": "Red leather running shoes with white soles",
      "metadata": { "category": "footwear", "sku": "SH-002" }
    }
  ]
}

Response:

json

{
  "indexed": 2,
  "model": "multimodal-embedding-v1",
  "usage": { "input_tokens": 1250 }
}

List Items

Endpoint: GET /v1/vectors/collections/:id/items?limit=20&offset=0

Returns up to 100 items per page with metadata and (for media) presigned content URLs.

Delete Items

Endpoint: DELETE /v1/vectors/collections/:id/items

json

{ "ids": ["item_abc123", "item_def456"] }

Search

Similarity Search

Endpoint: POST /v1/vectors/collections/:id/search

Provide exactly one of image, image_base64, text, or audio as the query.

Parameter	Type	Description
`image`	string	Query image URL
`image_base64`	string	Base64-encoded query image
`text`	string	Query text
`audio`	string	Query audio URL
`top_k`	number	Max results (1–100, default: 10)
`threshold`	number	Minimum similarity score (0–1)

json

{
  "text": "white running shoes",
  "top_k": 5,
  "threshold": 0.5
}

Response:

json

{
  "results": [
    {
      "id": "item_abc123",
      "score": 0.952,
      "content_type": "image",
      "metadata": { "category": "footwear", "sku": "SH-001" },
      "content_url": "https://storage.visowork.com/..."
    },
    {
      "id": "item_def456",
      "score": 0.871,
      "content_type": "text",
      "metadata": { "category": "footwear", "sku": "SH-002" },
      "content_url": null
    }
  ],
  "model": "multimodal-embedding-v1",
  "usage": { "input_tokens": 50 }
}

Video API Authentication