Media, image search and embeddings

The media operations put images into the same vector space as your text: upload an image, the platform writes a multilingual embedding into a document field, and a shopper can then search by photo or by meaning instead of keywords. createEmbeddings embeds plain text with the same model, for anything you want to compare against those vectors yourself.

Uploading and managing assets needs a full key. searchByImage and searchSemantic are search-scoped, so a storefront calls them with a search key like any other search (see keys and scopes). Every embedding call is billed from the credit wallet — see credits.

Upload an image

Small images go straight through uploadMedia — POST /media, multipart form data:

curl -X POST https://api.aacsearch.com/v1/media \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  -F "file=@drill.jpg" \
  -F "collection=products" -F "document_id=42" -F "vector_field=image_embedding"

For a file too large for one multipart request, start an upload instead:

const upload = await client.media.createMediaUpload({
  mime: "image/jpeg",
  collection: "products",
  document_id: "42",
  vector_field: "image_embedding",
});
// upload.media_id — then stream the bytes:

curl -X PUT "https://api.aacsearch.com/v1/media/$MEDIA_ID/content" \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: image/jpeg" \
  -H "Content-Length: $(stat -c%s drill.jpg)" \
  --data-binary @drill.jpg

createMediaUpload (POST /media/uploads) reserves the asset (uploaded: false); putMediaContent streams its bytes and requires Content-Length (411 without it, 413 over 100 MB — see errors). The embedding, and the caption if requested, are computed once the bytes are in.

Read and remove an asset

const asset = await client.media.getMedia({ mediaId });
// { media_id, mime, bytes, uploaded, caption, embedding, collection, document_id, vector_field, created_at }

await client.media.deleteMedia({ mediaId });

getMediaContent (GET /media/{mediaId}/content) streams the original bytes back. createMediaSignedUrl (POST /media/{mediaId}/signed_url) returns a time-limited url and expires_at for handing the image to something that can't send your API key — an email template, a third-party crawler.

Search by image or by meaning

Once documents carry an embedding, search past keywords:

curl -X POST https://api.aacsearch.com/v1/collections/products/documents/search/by_image \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" -F "file=@shopper-photo.jpg" -F "vector_field=image_embedding" -F "k=10"

Both return hits in the same shape as searchCollection. Reach for searchByImage when the shopper has a photo — their own, or one from your catalogue — and searchSemantic when they describe what they want in words but keyword search finds nothing close. Combine either with filter_by the way you would any search.

Embed text yourself

createEmbeddings — POST /embeddings — embeds up to 100 texts (about 500 tokens each) with the same model used for images, so a query and a product description land in one comparable space:

const { model, num_dim, data } = await client.embeddings.createEmbeddings({
  input: ["cordless drill", "impact driver"],
});
// data[0].length === num_dim

Use it when you want the raw vectors — comparing them yourself, storing them outside AACSearch, or building a custom ranking signal — rather than searching a collection directly.