Image Embeddings

Generate high-dimensional vector embeddings for images to enable semantic search, similarity matching, and content discovery in your applications. Embeddings capture the semantic meaning of images, allowing you to find visually similar content or search by meaning rather than exact matches.

Interactive Demo

Try it out ↓

Endpoint

POST /api/ai/embeddings

Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes
`x-api-key`	Your API key	Yes

Request Body

Field	Type	Required	Description
`image`	string	Yes	URL of the image to generate embeddings for
`model`	string	No	Embedding model to use (default: "default")

Example Request

curl -X POST https://lab.coreviz.io/api/ai/embeddings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image": "https://example.com/input.jpg"
  }'

Response

Status Code: 200 OK

Response Body:

{
  "embedding": [0.123, -0.456, 0.789, ...],
  "dimensions": 768,
  "model": "default"
}

Response Fields

Field	Type	Description
`embedding`	number[]	Vector embedding of the image (array of floating-point numbers)
`dimensions`	number	Number of dimensions in the embedding vector
`model`	string	The model used to generate the embedding

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

400 Bad Request

Invalid request parameters:

{
  "error": "Bad Request",
  "message": "Invalid image URL or missing required fields"
}

422 Unprocessable Entity

Image could not be processed:

{
  "error": "Unprocessable Entity",
  "message": "Unable to process the provided image"
}

Example Usage

JavaScript/TypeScript

const apiKey = 'YOUR_API_KEY';
const imageUrl = 'https://example.com/input.jpg';

const response = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    image: imageUrl,
  }),
});

const data = await response.json();
console.log('Embedding dimensions:', data.dimensions);
console.log('Embedding vector:', data.embedding);

Python

import requests
import numpy as np

api_key = 'YOUR_API_KEY'
image_url = 'https://example.com/input.jpg'

response = requests.post(
    'https://lab.coreviz.io/api/ai/embeddings',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key,
    },
    json={
        'image': image_url,
    }
)

data = response.json()
embedding = np.array(data['embedding'])
print(f'Embedding shape: {embedding.shape}')
print(f'Dimensions: {data["dimensions"]}')

Node.js

const fetch = require('node-fetch');

const apiKey = 'YOUR_API_KEY';
const imageUrl = 'https://example.com/input.jpg';

fetch('https://lab.coreviz.io/api/ai/embeddings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    image: imageUrl,
  }),
})
  .then((res) => res.json())
  .then((data) => {
    console.log('Embedding dimensions:', data.dimensions);
    console.log('Embedding vector length:', data.embedding.length);
  });

Use Cases

Semantic Search

Build a search system that finds images by meaning:

async function searchSimilarImages(queryImageUrl, imageDatabase) {
  // Get embedding for query image
  const queryResponse = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({ image: queryImageUrl }),
  });
  
  const { embedding: queryEmbedding } = await queryResponse.json();
  
  // Find similar images using cosine similarity
  const results = imageDatabase.map(image => {
    const similarity = cosineSimilarity(queryEmbedding, image.embedding);
    return { ...image, similarity };
  });
  
  // Sort by similarity
  return results.sort((a, b) => b.similarity - a.similarity);
}

function cosineSimilarity(vecA, vecB) {
  const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
  const magnitudeA = Math.sqrt(vecA.reduce((sum, a) => sum + a * a, 0));
  const magnitudeB = Math.sqrt(vecB.reduce((sum, b) => sum + b * b, 0));
  return dotProduct / (magnitudeA * magnitudeB);
}

Content Recommendation

Recommend similar content to users:

async function recommendSimilarContent(userImageUrl, contentLibrary) {
  const response = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({ image: userImageUrl }),
  });
  
  const { embedding } = await response.json();
  
  // Find top 5 similar items
  const recommendations = contentLibrary
    .map(item => ({
      ...item,
      similarity: cosineSimilarity(embedding, item.embedding),
    }))
    .sort((a, b) => b.similarity - a.similarity)
    .slice(0, 5);
  
  return recommendations;
}

Duplicate Detection

Find duplicate or near-duplicate images:

async function findDuplicates(imageUrl, imageCollection) {
  const response = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({ image: imageUrl }),
  });
  
  const { embedding } = await response.json();
  
  // Find images with high similarity (potential duplicates)
  const duplicates = imageCollection
    .map(image => ({
      ...image,
      similarity: cosineSimilarity(embedding, image.embedding),
    }))
    .filter(item => item.similarity > 0.95); // Threshold for duplicates
  
  return duplicates;
}

Image Clustering

Group similar images together:

async function clusterImages(imageUrls) {
  // Generate embeddings for all images
  const embeddings = await Promise.all(
    imageUrls.map(async (url) => {
      const response = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey,
        },
        body: JSON.stringify({ image: url }),
      });
      const data = await response.json();
      return { url, embedding: data.embedding };
    })
  );
  
  // Simple clustering using similarity threshold
  const clusters = [];
  const processed = new Set();
  
  embeddings.forEach((item, i) => {
    if (processed.has(i)) return;
    
    const cluster = [item.url];
    processed.add(i);
    
    embeddings.forEach((other, j) => {
      if (i !== j && !processed.has(j)) {
        const similarity = cosineSimilarity(item.embedding, other.embedding);
        if (similarity > 0.85) {
          cluster.push(other.url);
          processed.add(j);
        }
      }
    });
    
    clusters.push(cluster);
  });
  
  return clusters;
}

Storing Embeddings

For production applications, you'll want to store embeddings in a vector database:

Using a Vector Database

// Example with a vector database (pseudo-code)
async function indexImage(imageUrl) {
  // Generate embedding
  const response = await fetch('https://lab.coreviz.io/api/ai/embeddings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({ image: imageUrl }),
  });
  
  const { embedding } = await response.json();
  
  // Store in vector database
  await vectorDB.insert({
    id: imageUrl,
    embedding: embedding,
    metadata: { url: imageUrl, timestamp: Date.now() },
  });
}

Popular vector databases that work well with embeddings:

Pinecone: Managed vector database
Weaviate: Open-source vector database
Qdrant: High-performance vector database
Milvus: Scalable vector database
Chroma: Embedded vector database

Supported Image Formats

The API supports common image formats:

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
GIF (.gif)

Image URL Requirements

The image URL must be publicly accessible
HTTPS URLs are recommended
The image must be a valid image file
Maximum file size limits may apply (check your plan)

Embedding Dimensions

The default embedding model produces vectors with 768 dimensions. This provides a good balance between:

Representation quality: Captures rich semantic information
Storage efficiency: Reasonable size for most applications
Search performance: Fast similarity calculations

Notes

Embeddings are deterministic for the same image and model
Higher similarity scores indicate more similar images
Cosine similarity is the recommended distance metric
Embeddings can be stored and reused for faster searches
Processing time varies based on image complexity
Embeddings are normalized for optimal similarity calculations

Learn More

Try the Image Embeddings Tool to test the API interactively
Explore Image Description for generating descriptions
Check out Image Tagging for classification
Visit CoreViz Studio for bulk processing

Image Embeddings

On this page